From 597a1119ea2d8430ade31c7501f2a493c62a6388 Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Thu, 18 Apr 2024 09:44:03 +0200 Subject: [PATCH 1/6] docs: add components overview --- README.md | 57 --------------- docs/docs/architecture/components/index.md | 71 +++++++++++++++++++ .../architecture/components/init-container.md | 0 .../components/{cli.md => podvm-image.md} | 0 .../{coordinator.md => service-mesh.md} | 0 5 files changed, 71 insertions(+), 57 deletions(-) create mode 100644 docs/docs/architecture/components/index.md delete mode 100644 docs/docs/architecture/components/init-container.md rename docs/docs/architecture/components/{cli.md => podvm-image.md} (100%) rename docs/docs/architecture/components/{coordinator.md => service-mesh.md} (100%) diff --git a/README.md b/README.md index ce59354f4..52a253436 100644 --- a/README.md +++ b/README.md @@ -52,64 +52,7 @@ Contrast integrates fluently with the existing Kubernetes workflows. It's compat * Minimal DevOps involvement. * Simple CLI tool to get started. -## Components -### The Contrast Coordinator - -The Contrast Coordinator is the central remote attestation service of a Contrast deployment. -It runs inside a confidential container inside your cluster. -The Coordinator can be verified via remote attestation, and a Contrast deployment is self-contained. -The Coordinator is configured with a *manifest*, a configuration file containing the reference attestation values of your deployment. -It ensures that your deployment's topology adheres to your specified manifest by verifying the identity and integrity of all confidential pods inside the deployment. -The Coordinator is also a certificate authority and issues certificates for your workload pods during the attestation procedure. -Your workload pods can establish secure, encrypted communication channels between themselves based on these certificates and the Coordinator as the root CA. -As your app needs to scale, the Coordinator transparently verifies new instances and then provides them with their certificates to join the deployment. - -To verify your deployment, the Coordinator's remote attestation statement combined with the manifest offers a concise single remote attestation statement for your entire deployment. -A third party can use this to verify the integrity of your distributed app, making it easy to assure stakeholders of your app's identity and integrity. - -### The Manifest - -The manifest is the configuration file for the Coordinator, defining your confidential deployment. -It's automatically generated from your deployment by the Contrast CLI. -It currently consists of the following parts: - -* *Policies*: The identities of your Pods, represented by the hashes of their respective runtime policies. -* *Reference Values*: The remote attestation reference values for the Kata confidential micro-VM that's the runtime environment of your Pods. -* *WorkloadOwnerKeyDigest*: The workload owner's public key digest. Used for authenticating subsequent manifest updates. - -### Runtime Policies - -Runtime Policies are a mechanism to enable the use of the untrusted Kubernetes API for orchestration while ensuring the confidentiality and integrity of your confidential containers. -They allow us to enforce the integrity of your containers' runtime environment as defined in your deployment files. -The runtime policy mechanism is based on the Open Policy Agent (OPA) and translates the Kubernetes deployment YAML into the Rego policy language of OPA. -The Kata Agent inside the confidential micro-VM then enforces the policy by only acting on permitted requests. -The Contrast CLI provides the tooling for automatically translating Kubernetes deployment YAML into the Rego policy language of OPA. - -The trust chain goes as follows: - -1. The Contrast CLI generates a policy and attaches it to the pod definition. -2. Kubernetes schedules the pod on a node with the confidential computing runtime. -3. Containerd takes the node, starts the Kata Shim and creates the pod sandbox. -4. The Kata runtime starts a CVM with the policy's digest as `HOSTDATA`. -5. The Kata runtime sets the policy using the `SetPolicy` method. -6. The Kata agent verifies that the incoming policy's digest matches `HOSTDATA`. -7. The CLI sets a manifest in the Contrast Coordinator, including a list of permitted policies. -8. The Contrast Coordinator verifies that the started pod has a permitted policy hash in its `HOSTDATA` field. - -After the last step, we know that the policy hasn't been tampered with and, thus, that the workload is as intended. - -### The Contrast Initializer - -Contrast provides an Initializer that handles the remote attestation on the workload side transparently and -fetches the workload certificate. The Initializer runs as an init container before your workload is started. - -### The Contrast runtime - -Contrast depends on a Kubernetes [runtime class](https://kubernetes.io/docs/concepts/containers/runtime-class/), which is installed -by the `node-installer` DaemonSet. -This runtime consists of a containerd runtime plugin, a virtual machine manager (cloud-hypervisor), and a podvm image (IGVM and rootFS). -The installer takes care of provisioning every node in the cluster so it provides this runtime class. ## Current limitations diff --git a/docs/docs/architecture/components/index.md b/docs/docs/architecture/components/index.md new file mode 100644 index 000000000..ef4a198b7 --- /dev/null +++ b/docs/docs/architecture/components/index.md @@ -0,0 +1,71 @@ +# Components + +Contrast is composed of several key components that work together to manage and scale confidential containers effectively within Kubernetes environments. +This page provides an overview of the core components essential for deploying and managing Contrast. + +## The CLI (Command Line Interface) + +The CLI serves as the primary management tool for Contrast deployments. It is designed to streamline the configuration and operation of Contrast in several ways: + +* Installation and Setup: The CLI facilitates the installation of the necessary runtime classes required for Contrast to function within a Kubernetes cluster. +* Policy Generation: It allows users to generate runtime policies and generating the deployment manifest. +* Configuration Management: Through the CLI, users can configure the Contrast Coordinator with the generated manifest. +* Verification and Attestation: The CLI provides tools to verify the integrity and authenticity of the Coordinator and the entire deployment via remote attestation. + +## The Coordinator + +The Contrast Coordinator is the central remote attestation service of a Contrast deployment. +It runs inside a confidential container inside your cluster. +The Coordinator can be verified via remote attestation, and a Contrast deployment is self-contained. +The Coordinator is configured with a *manifest*, a configuration file containing the reference attestation values of your deployment. +It ensures that your deployment's topology adheres to your specified manifest by verifying the identity and integrity of all confidential pods inside the deployment. +The Coordinator is also a certificate authority and issues certificates for your workload pods during the attestation procedure. +Your workload pods can establish secure, encrypted communication channels between themselves based on these certificates and the Coordinator as the root CA. +As your app needs to scale, the Coordinator transparently verifies new instances and then provides them with their certificates to join the deployment. + +To verify your deployment, the Coordinator's remote attestation statement combined with the manifest offers a concise single remote attestation statement for your entire deployment. +A third party can use this to verify the integrity of your distributed app, making it easy to assure stakeholders of your app's identity and integrity. + +## The Manifest + +The manifest is the configuration file for the Coordinator, defining your confidential deployment. +It's automatically generated from your deployment by the Contrast CLI. +It currently consists of the following parts: + +* *Policies*: The identities of your Pods, represented by the hashes of their respective runtime policies. +* *Reference Values*: The remote attestation reference values for the Kata confidential micro-VM that's the runtime environment of your Pods. +* *WorkloadOwnerKeyDigest*: The workload owner's public key digest. Used for authenticating subsequent manifest updates. + +## Runtime Policies + +Runtime Policies are a mechanism to enable the use of the untrusted Kubernetes API for orchestration while ensuring the confidentiality and integrity of your confidential containers. +They allow us to enforce the integrity of your containers' runtime environment as defined in your deployment files. +The runtime policy mechanism is based on the Open Policy Agent (OPA) and translates the Kubernetes deployment YAML into the Rego policy language of OPA. +The Kata Agent inside the confidential micro-VM then enforces the policy by only acting on permitted requests. +The Contrast CLI provides the tooling for automatically translating Kubernetes deployment YAML into the Rego policy language of OPA. + +The trust chain goes as follows: + +1. The Contrast CLI generates a policy and attaches it to the pod definition. +2. Kubernetes schedules the pod on a node with the confidential computing runtime. +3. Containerd takes the node, starts the Kata Shim and creates the pod sandbox. +4. The Kata runtime starts a CVM with the policy's digest as `HOSTDATA`. +5. The Kata runtime sets the policy using the `SetPolicy` method. +6. The Kata agent verifies that the incoming policy's digest matches `HOSTDATA`. +7. The CLI sets a manifest in the Contrast Coordinator, including a list of permitted policies. +8. The Contrast Coordinator verifies that the started pod has a permitted policy hash in its `HOSTDATA` field. + +After the last step, we know that the policy hasn't been tampered with and, thus, that the workload is as intended. + +## The Initializer + +Contrast provides an Initializer that handles the remote attestation on the workload side transparently and +fetches the workload certificate. The Initializer runs as an init container before your workload is started. +It provides the workload container and the [service mesh sidecar](service-mesh.md) with the workload certificates. + +## The Contrast runtime + +Contrast depends on a Kubernetes [runtime class](https://kubernetes.io/docs/concepts/containers/runtime-class/), which is installed +by the `node-installer` DaemonSet. +This runtime consists of a containerd runtime plugin, a virtual machine manager (cloud-hypervisor), and a podvm image (IGVM and rootFS). +The installer takes care of provisioning every node in the cluster so it provides this runtime class. diff --git a/docs/docs/architecture/components/init-container.md b/docs/docs/architecture/components/init-container.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/docs/architecture/components/cli.md b/docs/docs/architecture/components/podvm-image.md similarity index 100% rename from docs/docs/architecture/components/cli.md rename to docs/docs/architecture/components/podvm-image.md diff --git a/docs/docs/architecture/components/coordinator.md b/docs/docs/architecture/components/service-mesh.md similarity index 100% rename from docs/docs/architecture/components/coordinator.md rename to docs/docs/architecture/components/service-mesh.md From ed0173dd925a6e3bc0e6c8819361fe3c9ee6e576 Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Thu, 18 Apr 2024 10:00:29 +0200 Subject: [PATCH 2/6] refactor components and architecture section --- .../architecture/confidential-containers.md | 0 .../network-encryption/protocols-and-keys.md | 0 .../network-encryption/sidecar.md | 0 .../{architecture => }/components/index.md | 0 .../components/podvm-image.md | 0 .../components/service-mesh.md | 0 docs/sidebars.js | 62 +++++-------------- 7 files changed, 17 insertions(+), 45 deletions(-) delete mode 100644 docs/docs/architecture/confidential-containers.md delete mode 100644 docs/docs/architecture/network-encryption/protocols-and-keys.md delete mode 100644 docs/docs/architecture/network-encryption/sidecar.md rename docs/docs/{architecture => }/components/index.md (100%) rename docs/docs/{architecture => }/components/podvm-image.md (100%) rename docs/docs/{architecture => }/components/service-mesh.md (100%) diff --git a/docs/docs/architecture/confidential-containers.md b/docs/docs/architecture/confidential-containers.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/docs/architecture/network-encryption/protocols-and-keys.md b/docs/docs/architecture/network-encryption/protocols-and-keys.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/docs/architecture/network-encryption/sidecar.md b/docs/docs/architecture/network-encryption/sidecar.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/docs/architecture/components/index.md b/docs/docs/components/index.md similarity index 100% rename from docs/docs/architecture/components/index.md rename to docs/docs/components/index.md diff --git a/docs/docs/architecture/components/podvm-image.md b/docs/docs/components/podvm-image.md similarity index 100% rename from docs/docs/architecture/components/podvm-image.md rename to docs/docs/components/podvm-image.md diff --git a/docs/docs/architecture/components/service-mesh.md b/docs/docs/components/service-mesh.md similarity index 100% rename from docs/docs/architecture/components/service-mesh.md rename to docs/docs/components/service-mesh.md diff --git a/docs/sidebars.js b/docs/sidebars.js index c34fd6ade..d85cfaf79 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -89,41 +89,32 @@ const sidebars = { }, { type: 'category', - label: 'Architecture', + label: 'Components', link: { type: 'doc', - id: 'architecture/index' + id: 'components/index' }, items: [ { - type: 'category', - label: 'Components', - link: { - type: 'generated-index', - }, - items: [ - { - type: 'doc', - label: 'Coordinator', - id: 'architecture/components/coordinator', - }, - { - type: 'doc', - label: 'Init container', - id: 'architecture/components/init-container', - }, - { - type: 'doc', - label: 'CLI', - id: 'architecture/components/cli', - }, - ] + type: 'doc', + label: 'Service Mesh', + id: 'components/service-mesh', }, { type: 'doc', - label: 'Confidential Containers', - id: 'architecture/confidential-containers', + label: 'Pod VM image', + id: 'components/podvm-image', }, + ] + }, + { + type: 'category', + label: 'Architecture', + link: { + type: 'doc', + id: 'architecture/index' + }, + items: [ { type: 'category', label: 'Attestation', @@ -172,25 +163,6 @@ const sidebars = { }, ] }, - { - type: 'category', - label: 'Network Encryption', - link: { - type: 'generated-index', - }, - items: [ - { - type: 'doc', - label: 'Sidecar', - id: 'architecture/network-encryption/sidecar', - }, - { - type: 'doc', - label: 'Protocols and Keys', - id: 'architecture/network-encryption/protocols-and-keys', - }, - ] - } ] }, ], From 5a1749c050e5b23bde90342cd7c6de7774123409 Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Thu, 18 Apr 2024 10:01:44 +0200 Subject: [PATCH 3/6] add components graphic --- docs/docs/_media/components.svg | 798 ++++++++++++++++++++++++++++++++ docs/docs/components/index.md | 4 +- 2 files changed, 801 insertions(+), 1 deletion(-) create mode 100644 docs/docs/_media/components.svg diff --git a/docs/docs/_media/components.svg b/docs/docs/_media/components.svg new file mode 100644 index 000000000..33f1df422 --- /dev/null +++ b/docs/docs/_media/components.svg @@ -0,0 +1,798 @@ + + diff --git a/docs/docs/components/index.md b/docs/docs/components/index.md index ef4a198b7..f26c032ea 100644 --- a/docs/docs/components/index.md +++ b/docs/docs/components/index.md @@ -3,12 +3,14 @@ Contrast is composed of several key components that work together to manage and scale confidential containers effectively within Kubernetes environments. This page provides an overview of the core components essential for deploying and managing Contrast. +![components overview](../_media/components.svg) + ## The CLI (Command Line Interface) The CLI serves as the primary management tool for Contrast deployments. It is designed to streamline the configuration and operation of Contrast in several ways: * Installation and Setup: The CLI facilitates the installation of the necessary runtime classes required for Contrast to function within a Kubernetes cluster. -* Policy Generation: It allows users to generate runtime policies and generating the deployment manifest. +* Policy Generation: It allows users to generate runtime policies, adapt the deployment files, and generate the Contrast manifest. * Configuration Management: Through the CLI, users can configure the Contrast Coordinator with the generated manifest. * Verification and Attestation: The CLI provides tools to verify the integrity and authenticity of the Coordinator and the entire deployment via remote attestation. From f538f6915a49e1e5e4041c293b504b9485d7efd2 Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Thu, 18 Apr 2024 10:10:50 +0200 Subject: [PATCH 4/6] fix spelling --- docs/docs/components/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/components/index.md b/docs/docs/components/index.md index f26c032ea..b100ab05d 100644 --- a/docs/docs/components/index.md +++ b/docs/docs/components/index.md @@ -7,7 +7,7 @@ This page provides an overview of the core components essential for deploying an ## The CLI (Command Line Interface) -The CLI serves as the primary management tool for Contrast deployments. It is designed to streamline the configuration and operation of Contrast in several ways: +The CLI serves as the primary management tool for Contrast deployments. It's designed to streamline the configuration and operation of Contrast in several ways: * Installation and Setup: The CLI facilitates the installation of the necessary runtime classes required for Contrast to function within a Kubernetes cluster. * Policy Generation: It allows users to generate runtime policies, adapt the deployment files, and generate the Contrast manifest. From 4eb2649f920cf94024d1744be4d1fe2132b864c1 Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Thu, 18 Apr 2024 11:25:50 +0200 Subject: [PATCH 5/6] rename podvm-image -> runtime --- docs/docs/components/{podvm-image.md => runtime.md} | 0 docs/sidebars.js | 8 ++++---- 2 files changed, 4 insertions(+), 4 deletions(-) rename docs/docs/components/{podvm-image.md => runtime.md} (100%) diff --git a/docs/docs/components/podvm-image.md b/docs/docs/components/runtime.md similarity index 100% rename from docs/docs/components/podvm-image.md rename to docs/docs/components/runtime.md diff --git a/docs/sidebars.js b/docs/sidebars.js index d85cfaf79..74dc45b8c 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -97,13 +97,13 @@ const sidebars = { items: [ { type: 'doc', - label: 'Service Mesh', - id: 'components/service-mesh', + label: 'Runtime', + id: 'components/runtime', }, { type: 'doc', - label: 'Pod VM image', - id: 'components/podvm-image', + label: 'Service Mesh', + id: 'components/service-mesh', }, ] }, From 8349374d4b335d7c61036ab01d2bd65cda5e23d2 Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Fri, 19 Apr 2024 09:58:04 +0200 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Paul Meyer <49727155+katexochen@users.noreply.github.com> --- docs/docs/components/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/components/index.md b/docs/docs/components/index.md index b100ab05d..bed40a2f8 100644 --- a/docs/docs/components/index.md +++ b/docs/docs/components/index.md @@ -9,10 +9,10 @@ This page provides an overview of the core components essential for deploying an The CLI serves as the primary management tool for Contrast deployments. It's designed to streamline the configuration and operation of Contrast in several ways: -* Installation and Setup: The CLI facilitates the installation of the necessary runtime classes required for Contrast to function within a Kubernetes cluster. -* Policy Generation: It allows users to generate runtime policies, adapt the deployment files, and generate the Contrast manifest. -* Configuration Management: Through the CLI, users can configure the Contrast Coordinator with the generated manifest. -* Verification and Attestation: The CLI provides tools to verify the integrity and authenticity of the Coordinator and the entire deployment via remote attestation. +* Installation and setup: The CLI facilitates the installation of the necessary runtime classes required for Contrast to function within a Kubernetes cluster. +* Policy generation: It allows users to generate runtime policies, adapt the deployment files, and generate the Contrast manifest. +* Configuration management: Through the CLI, users can configure the Contrast Coordinator with the generated manifest. +* Verification and attestation: The CLI provides tools to verify the integrity and authenticity of the Coordinator and the entire deployment via remote attestation. ## The Coordinator @@ -38,7 +38,7 @@ It currently consists of the following parts: * *Reference Values*: The remote attestation reference values for the Kata confidential micro-VM that's the runtime environment of your Pods. * *WorkloadOwnerKeyDigest*: The workload owner's public key digest. Used for authenticating subsequent manifest updates. -## Runtime Policies +## Runtime policies Runtime Policies are a mechanism to enable the use of the untrusted Kubernetes API for orchestration while ensuring the confidentiality and integrity of your confidential containers. They allow us to enforce the integrity of your containers' runtime environment as defined in your deployment files.