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/_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/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/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/components/index.md b/docs/docs/components/index.md new file mode 100644 index 000000000..bed40a2f8 --- /dev/null +++ b/docs/docs/components/index.md @@ -0,0 +1,73 @@ +# 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. + +![components overview](../_media/components.svg) + +## The CLI (Command Line Interface) + +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. + +## 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/cli.md b/docs/docs/components/runtime.md similarity index 100% rename from docs/docs/architecture/components/cli.md rename to docs/docs/components/runtime.md diff --git a/docs/docs/architecture/components/coordinator.md b/docs/docs/components/service-mesh.md similarity index 100% rename from docs/docs/architecture/components/coordinator.md rename to docs/docs/components/service-mesh.md diff --git a/docs/sidebars.js b/docs/sidebars.js index c34fd6ade..74dc45b8c 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: 'Runtime', + id: 'components/runtime', }, { type: 'doc', - label: 'Confidential Containers', - id: 'architecture/confidential-containers', + label: 'Service Mesh', + id: 'components/service-mesh', }, + ] + }, + { + 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', - }, - ] - } ] }, ],