diff --git a/docs/versioned_docs/version-0.5/_media/emoijvoto.png b/docs/versioned_docs/version-0.5/_media/emoijvoto.png deleted file mode 100644 index 9779306e04..0000000000 Binary files a/docs/versioned_docs/version-0.5/_media/emoijvoto.png and /dev/null differ diff --git a/docs/versioned_docs/version-0.5/architecture/attestation/coordinator.md b/docs/versioned_docs/version-0.5/architecture/attestation/coordinator.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/versioned_docs/version-0.5/architecture/attestation/hardware.md b/docs/versioned_docs/version-0.5/architecture/attestation/hardware.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/versioned_docs/version-0.5/architecture/attestation/manifest.md b/docs/versioned_docs/version-0.5/architecture/attestation/manifest.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/versioned_docs/version-0.5/architecture/attestation/pod-vm.md b/docs/versioned_docs/version-0.5/architecture/attestation/pod-vm.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/versioned_docs/version-0.5/architecture/attestation/runtime-policies.md b/docs/versioned_docs/version-0.5/architecture/attestation/runtime-policies.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/versioned_docs/version-0.5/architecture/certificates-and-identities/pki.md b/docs/versioned_docs/version-0.5/architecture/certificates-and-identities/pki.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/versioned_docs/version-0.5/architecture/components/cli.md b/docs/versioned_docs/version-0.5/architecture/components/cli.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/versioned_docs/version-0.5/architecture/components/coordinator.md b/docs/versioned_docs/version-0.5/architecture/components/coordinator.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/versioned_docs/version-0.5/architecture/components/init-container.md b/docs/versioned_docs/version-0.5/architecture/components/init-container.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/versioned_docs/version-0.5/architecture/confidential-containers.md b/docs/versioned_docs/version-0.5/architecture/confidential-containers.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/versioned_docs/version-0.5/architecture/index.md b/docs/versioned_docs/version-0.5/architecture/index.md deleted file mode 100644 index d2bb21f55a..0000000000 --- a/docs/versioned_docs/version-0.5/architecture/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# Architecture - -import DocCardList from '@theme/DocCardList'; - - diff --git a/docs/versioned_docs/version-0.5/architecture/network-encryption/protocols-and-keys.md b/docs/versioned_docs/version-0.5/architecture/network-encryption/protocols-and-keys.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/versioned_docs/version-0.5/architecture/network-encryption/sidecar.md b/docs/versioned_docs/version-0.5/architecture/network-encryption/sidecar.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/versioned_docs/version-0.5/basics/confidential-containers.md b/docs/versioned_docs/version-0.5/basics/confidential-containers.md deleted file mode 100644 index 21ab3f01cd..0000000000 --- a/docs/versioned_docs/version-0.5/basics/confidential-containers.md +++ /dev/null @@ -1,32 +0,0 @@ -# Confidential Containers - -Contrast uses some building blocks from [Confidential Containers](https://confidentialcontainers.org) (CoCo), a [CNCF Sandbox project](https://www.cncf.io/projects/confidential-containers/) that aims to standardize confidential computing at the pod level. -The project is under active development and many of the high-level features are still in flux. -Contrast uses the more stable, core primitive provided by CoCo: its Kubernetes runtime. - -## Kubernetes RuntimeClass - -Kubernetes can be extended to use more than one container runtime with [`RuntimeClass`](https://kubernetes.io/docs/concepts/containers/runtime-class/) objects. -The [Container Runtime Interface](https://kubernetes.io/docs/concepts/architecture/cri/) (CRI) implementation, for example containerd, dispatches pod management API calls to the appropriate `RuntimeClass`. -`RuntimeClass` implementations are usually based on an [OCI runtime](https://github.com/opencontainers/runtime-spec), such as `runc`, `runsc` or `crun`. -In CoCo's case, the runtime is Kata Containers with added confidential computing capabilities. - -## Kata Containers - -[Kata Containers](https://katacontainers.io/) is an OCI runtime that runs pods in VMs. -The guest VM spawns an agent process that accepts management commands from the Kata runtime running on the host. -There are two options for creating pod VMs: local to the Kubernetes node, or remote VMs created with cloud provider APIs. -Using local VMs requires either bare-metal servers or VMs with support for nested virtualization. -Local VMs communicate with the host over a virtual socket. -For remote VMs, host-to-agent communication is tunnelled through the cloud provider's network. - -Kata Containers was originally designed to isolate the guest from the host, but it can also run pods in confidential VMs (CVMs) to shield pods from their underlying infrastructure. -In confidential mode, the guest agent is configured with an [Open Policy Agent](https://www.openpolicyagent.org/) (OPA) policy to authorize API calls from the host. -This policy also contains checksums for the expected container images. -It's derived from Kubernetes resource definitions and its checksum is included in the attestation report. - -## AKS CoCo Preview - -[Azure Kubernetes Service](https://learn.microsoft.com/en-us/azure/aks/) (AKS) provides CoCo-enabled node pools as a [preview offering](https://learn.microsoft.com/en-us/azure/aks/confidential-containers-overview). -These node pools leverage Azure VM types capable of nested virtualization (CVM-in-VM) and the CoCo stack is pre-installed. -Contrast can be deployed directly into a CoCo-enabled AKS cluster. diff --git a/docs/versioned_docs/version-0.5/basics/features.md b/docs/versioned_docs/version-0.5/basics/features.md deleted file mode 100644 index fcd5b1a90d..0000000000 --- a/docs/versioned_docs/version-0.5/basics/features.md +++ /dev/null @@ -1,15 +0,0 @@ -# Product Features - -Contrast simplifies the deployment and management of Confidential Containers, offering optimal data security for your workloads while integrating seamlessly with your existing Kubernetes environment. - -From a security perspective, Contrast employs the [Confidential Containers](confidential-containers.md) concept and provides [security benefits](security-benefits.md) that go beyond individual containers, shielding your entire deployment from the underlying infrastructure. - -From an operational perspective, Contrast provides the following key features: - -* **Managed Kubernetes Compatibility**: Initially compatible with Azure Kubernetes Service (AKS), Contrast is designed to support additional platforms such as AWS EKS and Google Cloud GKE as they begin to accommodate confidential containers. - -* **Lightweight Installation**: Contrast can be integrated as a [day-2 operation](../deployment.md) within existing clusters, adding minimal [components](../architecture) to your setup. This facilitates straightforward deployments using your existing YAML configurations, Helm charts, or Kustomization, enabling native Kubernetes orchestration of your applications. - -* **Remote Attestation**: Contrast generates a concise attestation statement that verifies the identity, authenticity, and integrity of your deployment both internally and to external parties. This architecture ensures that updates or scaling of the application don't compromise the attestation’s validity. - -* **Service Mesh**: Contrast securely manages a Public Key Infrastructure (PKI) for your deployments, issues workload-specific certificates, and establishes transparent mutual TLS (mTLS) connections across pods. This is done by harnessing the [envoy proxy](https://www.envoyproxy.io/) to ensure secure communications within your Kubernetes cluster. diff --git a/docs/versioned_docs/version-0.5/basics/security-benefits.md b/docs/versioned_docs/version-0.5/basics/security-benefits.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/versioned_docs/version-0.5/deployment.md b/docs/versioned_docs/version-0.5/deployment.md deleted file mode 100644 index fd77935043..0000000000 --- a/docs/versioned_docs/version-0.5/deployment.md +++ /dev/null @@ -1,161 +0,0 @@ -# Workload deployment - -The following instructions will guide you through the process of making an existing Kubernetes deployment -confidential and deploying it together with Contrast. - -A running CoCo-enabled cluster is required for these steps, see the [setup guide](./getting-started/cluster-setup.md) on how to set it up. - -## Deploy the Contrast Coordinator - -Install the latest Contrast Coordinator release, comprising a single replica deployment and a -LoadBalancer service, into your cluster. - -```sh -kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/download/coordinator.yml -``` - -## Prepare your Kubernetes resources - -Contrast will add annotations to your Kubernetes YAML files. If you want to keep the original files -unchanged, you can copy the files into a separate local directory. -You can also generate files from a Helm chart or from a Kustomization. - - - - -```sh -mkdir resources -kustomize build $MY_RESOURCE_DIR > resources/all.yml -``` - - - - -```sh -mkdir resources -helm template $RELEASE_NAME $CHART_NAME > resources/all.yml -``` - - - - -```sh -cp -R $MY_RESOURCE_DIR resources/ -``` - - - - -To specify that a workload (pod, deployment, etc.) should be deployed as confidential containers, -add `runtimeClassName: kata-cc-isolation` to the pod spec (pod definition or template). -In addition, add the Contrast Initializer as `initContainers` to these workloads and configure the -workload to use the certificates written to a `volumeMount` named `tls-certs`. - -```yaml -spec: # v1.PodSpec - runtimeClassName: kata-cc-isolation - initContainers: - - name: initializer - image: "ghcr.io/edgelesssys/contrast/initializer:latest" - env: - - name: COORDINATOR_HOST - value: coordinator - volumeMounts: - - name: tls-certs - mountPath: /tls-config - volumes: - - name: tls-certs - emptyDir: {} -``` - -## Generate policy annotations and manifest - -Run the `generate` command to generate the execution policies and add them as annotations to your -deployment files. A `manifest.json` with the reference values of your deployment will be created. - -```sh -contrast generate resources/ -``` - -## Apply the resources - -Apply the resources to the cluster. Your workloads will block in the initialization phase until a -manifest is set at the Coordinator. - -```sh -kubectl apply -f resources/ -``` - -## Connect to the Contrast Coordinator - -For the next steps, we will need to connect to the Coordinator. The released Coordinator resource -includes a LoadBalancer definition we can use. - -```sh -coordinator=$(kubectl get svc coordinator -o=jsonpath='{.status.loadBalancer.ingress[0].ip}') -``` - -:::info[Port-forwarding of Confidential Containers] - -`kubectl port-forward` uses a Container Runtime Interface (CRI) method that isn't supported by the Kata shim. -If you can't use a public load balancer, you can deploy a [port-forwarder](https://github.com/edgelesssys/contrast/blob/main/deployments/emojivoto/portforwarder.yml). -The port-forwarder relays traffic from a CoCo pod and can be accessed via `kubectl port-forward`. - -Upstream tracking issue: https://github.com/kata-containers/kata-containers/issues/1693. - -::: - -## Set the manifest - -Attest the Coordinator and set the manifest: - -```sh -contrast set -c "${coordinator}:1313" resources/ -``` - -After this step, the Coordinator will start issuing TLS certs to the workloads. The init container -will fetch a certificate for the workload and the workload is started. - -## Verify the Coordinator - -An end user (data owner) can verify the Contrast deployment using the `verify` command. - -```sh -contrast verify -c "${coordinator}:1313" -``` - -The CLI will attest the Coordinator using embedded reference values. The CLI will write the service mesh -root certificate and the history of manifests into the `verify/` directory. In addition, the policies referenced -in the manifest are also written to the directory. - -## Communicate with workloads - -You can securely connect to the workloads using the Coordinator's `mesh-root.pem` as a trusted CA certificate. -First, expose the service on a public IP address via a LoadBalancer service: - -```sh -kubectl patch svc ${MY_SERVICE} -p '{"spec": {"type": "LoadBalancer"}}' -timeout 30s bash -c 'until kubectl get service/${MY_SERVICE} --output=jsonpath='{.status.loadBalancer}' | grep "ingress"; do sleep 2 ; done' -lbip=$(kubectl get svc ${MY_SERVICE} -o=jsonpath='{.status.loadBalancer.ingress[0].ip}') -echo $lbip -``` - -:::info[Subject alternative names and LoadBalancer IP] - -By default, mesh certificates are issued with a wildcard DNS entry. The web frontend is accessed -via load balancer IP in this demo. Tools like curl check the certificate for IP entries in the SAN field. -Validation fails since the certificate contains no IP entries as a subject alternative name (SAN). -For example, a connection attempt using the curl and the mesh root certificate with throw the following error: - -```sh -$ curl --cacert ./verify/mesh-root.pem "https://${frontendIP}:443" -curl: (60) SSL: no alternative certificate subject name matches target host name '203.0.113.34' -``` - -::: - -Using `openssl`, the certificate of the service can be validated with the `mesh-root.pem`: - -```sh -openssl s_client -CAfile verify/mesh-root.pem -verify_return_error -connect ${frontendIP}:443 < /dev/null -``` diff --git a/docs/versioned_docs/version-0.5/examples/emojivoto.md b/docs/versioned_docs/version-0.5/examples/emojivoto.md deleted file mode 100644 index 863b213519..0000000000 --- a/docs/versioned_docs/version-0.5/examples/emojivoto.md +++ /dev/null @@ -1,214 +0,0 @@ -# Confidential emoji voting - - -![screenshot of the emojivoto UI](../_media/emoijvoto.png) - -**This tutorial guides you through deploying [emojivoto](https://github.com/BuoyantIO/emojivoto) as a -confidential Contrast deployment and validating the deployment from a voters perspective.** - - -Emojivoto is an example app allowing users to vote for different emojis and view votes -on a leader board. It has a microservice architecture consisting of a -web frontend (`web`), a gRPC backend for listing available emojis (`emoji`), and a backend for -the voting and leader board logic (`voting`). The `vote-bot` simulates user traffic by submitting -votes to the frontend. - - -![emojivoto components topology](https://raw.githubusercontent.com/BuoyantIO/emojivoto/e490d5789086e75933a474b22f9723fbfa0b29ba/assets/emojivoto-topology.png) - -### Motivation - -Using a voting service, users' votes are considered highly sensitive data, as we require -a secret ballot. Also, users are likely interested in the fairness of the ballot. For -both requirements, we can use Confidential Computing and, specifically, workload attestation -to prove to those interested in voting that the app is running in a protected environment -where their votes are processed without leaking to the platform provider or workload owner. - -## Prerequisites - -- **Installed Contrast CLI.** - See the [installation instructions](./../getting-started/install.md) on how to get it. -- **Running cluster with Confidential Containers support.** - Please follow the [cluster setup instructions](./../getting-started/cluster-setup.md) - to create a cluster. -- **Get the deployment.** This is currently available as part of the preview bundle. - -## Steps to deploy emojivoto with Contrast - -### Deploy the Contrast Coordinator - -Deploy the Contrast Coordinator, comprising a single replica deployment and a -LoadBalancer service, into your cluster: - -```sh -kubectl apply -f coordinator.yml -``` - -### Generate policy annotations and manifest - -Run the `generate` command to generate the execution policies and add them as -annotations to your deployment files. A `manifest.json` file with the reference values -of your deployment will be created: - -```sh -contrast generate deployment/ -``` - -:::note[Runtime class and Initializer] - -The deployment YAML shipped for this demo is already configured to be used with Contrast. -A runtime class `kata-cc-isolation` was added to the pods to signal they should be run -as Confidential Containers. In addition, the Contrast Initializer was added -as an init container to these workloads to facilitate the attestation and certificate pulling -before the actual workload is started. - -::: - -### Set the manifest - -Configure the coordinator with a manifest. It might take up to a few minutes -for the load balancer to be created and the Coordinator being available. - -```sh -coordinator=$(kubectl get svc coordinator -o=jsonpath='{.status.loadBalancer.ingress[0].ip}') -echo "The user API of your Contrast Coordinator is available at $coordinator:1313" -contrast set -c "${coordinator}:1313" deployment/ -``` - -The CLI will use the embedded reference values to attest the Coordinator deployment -during the TLS handshake. If the connection succeeds, we're ensured that the Coordinator -deployment hasn't been tampered with. - -### Deploy emojivoto - -Now that the coordinator has a manifest set, which defines the emojivoto deployment as an allowed workload, -we can deploy the application: - -```sh -kubectl apply -f deployment/ -``` - -:::note[Inter-deployment communication] - -The Contrast Coordinator issues mesh certificates after successfully validating workloads. -These certificates can be used for secure inter-deployment communication. The Initializer -sends an attestation report to the Coordinator, retrieves certificates and a private key in return -and writes them to a `volumeMount`. The emojivoto version we're using is patched to only communicate -via mTLS (the original app talks plain HTTP). The different parts of the workload are configured -to use the credentials from the `volumeMount` when communicating with each other. - -::: - -## Voter's perspective: Verifying the ballot - -As voters, we want to verify the fairness and confidentiality of the deployment before -deciding to vote. Regardless of the scale of our distributed deployment, Contrast only -needs a single remote attestation step to verify the deployment. By doing remote attestation -of the Coordinator, we transitively verify those systems the Coordinator has already attested -or will attest in the future. Successful verification of the Coordinator means that -we can be sure it will enforce the configured manifest. - -### Attest the Coordinator - -A potential voter can verify the Contrast deployment using the verify -command: - -```sh -contrast verify -c "${coordinator}:1313" -``` - -The CLI will attest the Coordinator using embedded reference values. If the command succeeds, -the Coordinator deployment was successfully verified to be running in the expected Confidential -Computing environment with the expected code version. The Coordinator will then return its -configuration over the established TLS channel. The CLI will store this information, namely the root -certificate of the mesh (`mesh-root.pem`) and the history of manifests, into the `verify/` directory. -In addition, the policies referenced in the manifest history are also written into the same directory. - -### Manifest history and artifact audit - -In the next step, the Coordinator configuration that was written by the `verify` command needs to be audited. -A potential voter should inspect the manifest and the referenced policies. They could delegate -this task to an entity they trust. - -### Confidential connection to the attested workload - -After ensuring the configuration of the Coordinator fits the expectation, you can securely connect -to the workloads using the Coordinator's `mesh-root.pem` as a trusted CA certificate. - -To access the web frontend, expose the service on a public IP address via a LoadBalancer service: - -```sh -frontendIP=$(kubectl get svc web-svc -o=jsonpath='{.status.loadBalancer.ingress[0].ip}') -echo "Frontend is available at https://$frontendIP, you can visit it in your browser." -``` - -Using `openssl`, the certificate of the service can be validated with the `mesh-root.pem`: - -```sh -openssl s_client -CAfile verify/mesh-root.pem -verify_return_error -connect ${frontendIP}:443 < /dev/null -``` - -## Certificate SAN and manifest update (optional) - -By default, mesh certificates are issued with a wildcard DNS entry. The web frontend is accessed -via load balancer IP in this demo. Tools like curl check the certificate for IP entries in the SAN field. -Validation fails since the certificate contains no IP entries as a subject alternative name (SAN). -For example, a connection attempt using the curl and the mesh root certificate with throw the following error: - -```sh -$ curl --cacert ./verify/mesh-root.pem "https://${frontendIP}:443" -curl: (60) SSL: no alternative certificate subject name matches target host name '203.0.113.34' -``` - -### Configure the service SAN in the manifest - -The `Policies` section of the manifest maps policy hashes to a list of SANs. To enable certificate verification -of the web frontend with tools like curl, edit the policy with your favorite editor and add the `frontendIP` to -the list that already contains the `"web"` DNS entry: - -```diff - "Policies": { - ... - "99dd77cbd7fe2c4e1f29511014c14054a21a376f7d58a48d50e9e036f4522f6b": [ - "web", -- "*" -+ "*", -+ "203.0.113.34" - ], -``` - -### Update the manifest - -Next, set the changed manifest at the coordinator with: - -```sh -contrast set -c "${coordinator}:1313" deployment/ -``` - -The Contrast Coordinator will rotate the mesh root certificate on the manifest update. Workload certificates issued -after the manifest are thus issued by another certificate authority and services receiving the new CA certificate chain -won't trust parts of the deployment that got their certificate issued before the update. This way, Contrast ensures -that parts of the deployment that received a security update won't be infected by parts of the deployment at an older -patch level that may have been compromised. The `mesh-root.pem` is updated with the new CA certificate chain. - -### Rolling out the update - -The Coordinator has the new manifest set, but the different containers of the app are still -using the older certificate authority. The Contrast Initializer terminates after the initial attestation -flow and won't pull new certificates on manifest updates. - -To roll out the update, use: - -```sh -kubectl rollout restart deployment/emoji -kubectl rollout restart deployment/vote-bot -kubectl rollout restart deployment/voting -kubectl rollout restart deployment/web -``` - -After the update has been rolled out, connecting to the frontend using curl will successfully validate -the service certificate and return the HTML document of the voting site: - -```sh -curl --cacert ./mesh-root.pem "https://${frontendIP}:443" -``` diff --git a/docs/versioned_docs/version-0.5/examples/index.md b/docs/versioned_docs/version-0.5/examples/index.md deleted file mode 100644 index 252c82c820..0000000000 --- a/docs/versioned_docs/version-0.5/examples/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# Examples - -import DocCardList from '@theme/DocCardList'; - - diff --git a/docs/versioned_docs/version-0.5/getting-started/cluster-setup.md b/docs/versioned_docs/version-0.5/getting-started/cluster-setup.md deleted file mode 100644 index 3d7d080861..0000000000 --- a/docs/versioned_docs/version-0.5/getting-started/cluster-setup.md +++ /dev/null @@ -1,157 +0,0 @@ -# Create a cluster - -## Prerequisites - -Install the latest version of the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/). - -[Login to your account](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli), which has -the permissions to create an AKS cluster, by executing: - -```bash -az login -``` - -## Prepare using the AKS preview - -CoCo on AKS is currently in preview. An extension for the `az` CLI is needed to create such a cluster. -Add the extension with the following commands: - -```bash -az extension add \ - --name aks-preview \ - --allow-preview true -az extension update \ - --name aks-preview \ - --allow-preview true -``` - -Then register the required feature flags in your subscription to allow access to the public preview: - -```bash -az feature register \ - --namespace "Microsoft.ContainerService" \ - --name "KataCcIsolationPreview" -``` - -The registration can take a few minutes. The status of the operation can be checked with the following -command, which should show the registration state as `Registered`: - -```sh -az feature show \ - --namespace "Microsoft.ContainerService" \ - --name "KataCcIsolationPreview" \ - --output table -``` - -Afterward, refresh the registration of the ContainerService provider: - -```sh -az provider register \ - --namespace "Microsoft.ContainerService" -``` - -## Create resource group - -The AKS with CoCo preview is currently available in the following locations: - -``` -CentralIndia -eastus -EastUS2EUAP -GermanyWestCentral -japaneast -northeurope -SwitzerlandNorth -UAENorth -westeurope -westus -``` - -Set the name of the resource group you want to use: - -```bash -azResourceGroup="ContrastDemo" -``` - -You can either use an existing one or create a new resource group with the following command: - -```bash -azLocation="westus" # Select a location from the list above - -az group create \ - --name "$azResourceGroup" \ - --location "$azLocation" -``` - -## Create AKS cluster - -First create an AKS cluster: - -```sh -# Select the name for your AKS cluster -azClusterName="ContrastDemo" - -az aks create \ - --resource-group "$azResourceGroup" \ - --name "$azClusterName" \ - --kubernetes-version 1.29 \ - --os-sku AzureLinux \ - --node-vm-size Standard_DC4as_cc_v5 \ - --node-count 1 \ - --generate-ssh-keys -``` - -We then add a second node pool with CoCo support: - -```bash -az aks nodepool add \ - --resource-group "$azResourceGroup" \ - --name nodepool2 \ - --cluster-name "$azClusterName" \ - --node-count 1 \ - --os-sku AzureLinux \ - --node-vm-size Standard_DC4as_cc_v5 \ - --workload-runtime KataCcIsolation -``` - -Finally, update your kubeconfig with the credentials to access the cluster: - -```bash -az aks get-credentials \ - --resource-group "$azResourceGroup" \ - --name "$azClusterName" -``` - -For validation, list the available nodes using kubectl: - -```bash -kubectl get nodes -``` - -It should show two nodes: - -```bash -NAME STATUS ROLES AGE VERSION -aks-nodepool1-32049705-vmss000000 Ready 9m47s v1.29.0 -aks-nodepool2-32238657-vmss000000 Ready 45s v1.29.0 -``` - -## Cleanup - -After trying out Contrast, you might want to clean up the cloud resources created in this step. -In case you've created a new resource group, you can just delete that group with - -```sh -az group delete \ - --name "$azResourceGroup" -``` - -Deleting the resource group will also delete the cluster and all other related resources. - -To only cleanup the AKS cluster and node pools, run - -```sh -az aks delete \ - --resource-group "$azResourceGroup" \ - --name "$azClusterName" -``` diff --git a/docs/versioned_docs/version-0.5/getting-started/first-steps.md b/docs/versioned_docs/version-0.5/getting-started/first-steps.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/versioned_docs/version-0.5/getting-started/index.md b/docs/versioned_docs/version-0.5/getting-started/index.md deleted file mode 100644 index 71e5bd4233..0000000000 --- a/docs/versioned_docs/version-0.5/getting-started/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# Getting started - -import DocCardList from '@theme/DocCardList'; - - diff --git a/docs/versioned_docs/version-0.5/getting-started/install.md b/docs/versioned_docs/version-0.5/getting-started/install.md deleted file mode 100644 index 4d53c30d1a..0000000000 --- a/docs/versioned_docs/version-0.5/getting-started/install.md +++ /dev/null @@ -1,35 +0,0 @@ -# Installation - - - - -Download the bundle from the URL you received: - -```bash -curl -fLO -``` - -Then unpack the unpack the downloaded archive: - -```bash -unzip contrast.zip -``` - - - - -Download the Contrast CLI from the latest release: - -```bash -curl -fLo contrast https://github.com/edgelesssys/contrast/releases/latest/download/contrast -``` - - - - - -Install the Contrast CLI in your PATH, e.g.: - -```bash -mv contrast /usr/local/bin/contrast -``` diff --git a/docs/versioned_docs/version-0.5/intro.md b/docs/versioned_docs/version-0.5/intro.md deleted file mode 100644 index 31ae9696ef..0000000000 --- a/docs/versioned_docs/version-0.5/intro.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -slug: / -id: intro ---- - -# Contrast - -Welcome to the documentation of Contrast! Contrast runs confidential container deployments on Kubernetes at scale. - -Contrast is based on the [Kata Containers](https://github.com/kata-containers/kata-containers) and -[Confidential Containers](https://github.com/confidential-containers) projects. -Confidential Containers are Kubernetes pods that are executed inside a confidential micro-VM and provide strong hardware-based isolation from the surrounding environment. -This works with unmodified containers in a lift-and-shift approach. -Contrast currently targets the [CoCo preview on AKS](https://learn.microsoft.com/en-us/azure/confidential-computing/confidential-containers-on-aks-preview). - -:::tip -See the 📄[whitepaper](https://content.edgeless.systems/hubfs/Confidential%20Computing%20Whitepaper.pdf) for more information on confidential computing. -::: - -## Goal - -Contrast is designed to keep all data always encrypted and to prevent access from the infrastructure layer. It removes the infrastructure provider from the trusted computing base (TCB). This includes access from datacenter employees, privileged cloud admins, own cluster administrators, and attackers coming through the infrastructure, for example, malicious co-tenants escalating their privileges. - -Contrast integrates fluently with the existing Kubernetes workflows. It's compatible with managed Kubernetes, can be installed as a day-2 operation and imposes only minimal changes to your deployment flow. - -## Use Cases - -Contrast provides unique security [features](basics/features.md) and [benefits](basics/security-benefits.md). The core use cases are: - -* Increasing the security of your containers -* Moving sensitive workloads from on-prem to the cloud with Confidential Computing -* Shielding the code and data even from the own cluster administrators -* Increasing the trustworthiness of your SaaS offerings -* Simplifying regulatory compliance -* Multi-party computation for data collaboration - -## Next steps - -You can learn more about the concept of [Confidential Containers](basics/confidential-containers.md), [features](basics/features.md), and [security benefits](basics/security-benefits.md) of Contrast in this section. To jump right into the action head to [*Getting started*](getting-started/index.md). diff --git a/docs/versioned_docs/version-0.6/_media/attestation-composite-device.svg b/docs/versioned_docs/version-0.6/_media/attestation-composite-device.svg deleted file mode 100644 index f76b674710..0000000000 --- a/docs/versioned_docs/version-0.6/_media/attestation-composite-device.svg +++ /dev/null @@ -1,1127 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/versioned_docs/version-0.6/_media/attestation-composite-device.txt b/docs/versioned_docs/version-0.6/_media/attestation-composite-device.txt deleted file mode 100644 index 7fae1031d2..0000000000 --- a/docs/versioned_docs/version-0.6/_media/attestation-composite-device.txt +++ /dev/null @@ -1,24 +0,0 @@ - .-----------------------------. - | Verifier | - '-----------------------------' - ^ - | - | Evidence of - | Composite Device - | - .----------------------------------|-------------------------------. - | .--------------------------------|-----. .------------. | - | | Collect .---------+--. | | | | - | | Claims .--------->| Attesting |<--------+ Pod A +-. | - | | | |Environment | | '-+----------' | | - | | .--------+-------. | |<----------+ Pod B +-. | - | | | Runtime Target | | | | '-+----------' | | - | | | Environment | | |<------------+ ... | | - | | | | '------------' | Evidence '------------' | - | | '----------------' | of | - | | | Pods | - | | Coordinator | (via Pod network) | - | '--------------------------------------' | - | | - | Composite Device | - '------------------------------------------------------------------' diff --git a/docs/versioned_docs/version-0.6/_media/attestation-pod.svg b/docs/versioned_docs/version-0.6/_media/attestation-pod.svg deleted file mode 100644 index 4149941117..0000000000 --- a/docs/versioned_docs/version-0.6/_media/attestation-pod.svg +++ /dev/null @@ -1,1737 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/versioned_docs/version-0.6/_media/attestation-pod.txt b/docs/versioned_docs/version-0.6/_media/attestation-pod.txt deleted file mode 100644 index 10a7c6135e..0000000000 --- a/docs/versioned_docs/version-0.6/_media/attestation-pod.txt +++ /dev/null @@ -1,43 +0,0 @@ - .-------------. - | CPU | Endorsement for CPU - | Vendor +-----------------------. - '-------------' | - v - .-------------. Reference .-------------. - | CLI + | Values for | | - | Edgeless +----------------->| Coordinator | - | Systems | Runtime Env and | | - '-------------' Runtime Policy '-------------' - ^ - .------------------------------------. | - | | | - | | | - | .---------------------------. | | Evidence for - | | Guest Agent(C) | | | Runtime Environment - | | | | | and - | | Target | | | Runtime Policy - | | Environment | | | - | | | | | - | | | | | - | | | | | - | '-----------+-------+-------' | | - | Part of | | Evidence | | - | v | for | | - | .-----------------. | Runtime | | - | | Runtime Env(B) | | Policy | | - | | | | | | - | | Target | | | | - | | Environment | | | | - | | ^ | | | | - | '-----------|-----' | | | - | Measure | | | | - | | | | | - | | | | | - | .-----------+-------|-------. | | - | | CPU(A): AMD SEV, v | | | - | | Intel TDX | | | - | | Attesting | | | - | | Environment +---------' - | '---------------------------' | - | | - '------------------------------------' diff --git a/docs/versioned_docs/version-0.6/_media/attestation-rats-architecture.svg b/docs/versioned_docs/version-0.6/_media/attestation-rats-architecture.svg deleted file mode 100644 index 7e291b4696..0000000000 --- a/docs/versioned_docs/version-0.6/_media/attestation-rats-architecture.svg +++ /dev/null @@ -1,1417 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/versioned_docs/version-0.6/_media/attestation-rats-architecture.txt b/docs/versioned_docs/version-0.6/_media/attestation-rats-architecture.txt deleted file mode 100644 index f0d1a68491..0000000000 --- a/docs/versioned_docs/version-0.6/_media/attestation-rats-architecture.txt +++ /dev/null @@ -1,23 +0,0 @@ - .--------. .---------. .--------. .-------------. - | Endorser | | Reference | | Verifier | | Relying Party | - '-+------' | Value | | Owner | | Owner | - | | Provider | '---+----' '----+--------' - | '-----+---' | | - | | | | - | Endorsements | Reference | Appraisal | Appraisal - | | Values | Policy for | Policy for - | | | Evidence | Attestation - '-----------. | | | Results - | | | | - v v v | - .-------------------------. | - .------>| Verifier +-----. | - | '-------------------------' | | - | | | - | Evidence Attestation | | - | Results | | - | | | - | v v - .-----+----. .---------------. - | Attester | | Relying Party | - '----------' '---------------' diff --git a/docs/versioned_docs/version-0.6/_media/components.svg b/docs/versioned_docs/version-0.6/_media/components.svg deleted file mode 100644 index 33f1df4223..0000000000 --- a/docs/versioned_docs/version-0.6/_media/components.svg +++ /dev/null @@ -1,798 +0,0 @@ - - diff --git a/docs/versioned_docs/version-0.6/_media/contrast_pki.drawio.svg b/docs/versioned_docs/version-0.6/_media/contrast_pki.drawio.svg deleted file mode 100644 index 386d2215c2..0000000000 --- a/docs/versioned_docs/version-0.6/_media/contrast_pki.drawio.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - -
Root CA








Root CA Certificate
Root CA
Private Key
Intermediate CA








Intermediate CA
Certificate
Intermediate CA
Private Key
Mesh CA
Certificate
Mesh








Mesh Certificate
Mesh Private Key
signs
signs
signs
signs
 diff --git a/docs/versioned_docs/version-0.6/_media/emoijvoto.png b/docs/versioned_docs/version-0.6/_media/emoijvoto.png deleted file mode 100644 index 9779306e04..0000000000 Binary files a/docs/versioned_docs/version-0.6/_media/emoijvoto.png and /dev/null differ diff --git a/docs/versioned_docs/version-0.6/_media/personas.svg b/docs/versioned_docs/version-0.6/_media/personas.svg deleted file mode 100644 index 19988f631c..0000000000 --- a/docs/versioned_docs/version-0.6/_media/personas.svg +++ /dev/null @@ -1,573 +0,0 @@ - - diff --git a/docs/versioned_docs/version-0.6/_media/runtime.svg b/docs/versioned_docs/version-0.6/_media/runtime.svg deleted file mode 100644 index b13d79e3ae..0000000000 --- a/docs/versioned_docs/version-0.6/_media/runtime.svg +++ /dev/null @@ -1,1376 +0,0 @@ - - diff --git a/docs/versioned_docs/version-0.6/_media/tcb.svg b/docs/versioned_docs/version-0.6/_media/tcb.svg deleted file mode 100644 index b20ac5284c..0000000000 --- a/docs/versioned_docs/version-0.6/_media/tcb.svg +++ /dev/null @@ -1,547 +0,0 @@ - - diff --git a/docs/versioned_docs/version-0.6/about/index.md b/docs/versioned_docs/version-0.6/about/index.md deleted file mode 100644 index 92b6b7d53b..0000000000 --- a/docs/versioned_docs/version-0.6/about/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# About - -import DocCardList from '@theme/DocCardList'; - - diff --git a/docs/versioned_docs/version-0.6/about/telemetry.md b/docs/versioned_docs/version-0.6/about/telemetry.md deleted file mode 100644 index 074754c78e..0000000000 --- a/docs/versioned_docs/version-0.6/about/telemetry.md +++ /dev/null @@ -1,20 +0,0 @@ -# CLI telemetry - -The Contrast CLI sends telemetry data to Edgeless Systems when you use CLI commands. -This allows to understand how Contrast is used and to improve it. - -The CLI sends the following data: - -* The CLI version -* The CLI target OS and architecture (GOOS and GOARCH) -* The command that was run -* The kind of error that occurred (if any) - -The CLI *doesn't* collect sensitive information. -The implementation is open-source and can be reviewed. - -IP addresses may be processed or stored for security purposes. - -The data that the CLI collects adheres to the Edgeless Systems [privacy policy](https://www.edgeless.systems/privacy). - -You can disable telemetry by setting the environment variable `DO_NOT_TRACK=1` before running the CLI. diff --git a/docs/versioned_docs/version-0.6/architecture/attestation.md b/docs/versioned_docs/version-0.6/architecture/attestation.md deleted file mode 100644 index 35564aad28..0000000000 --- a/docs/versioned_docs/version-0.6/architecture/attestation.md +++ /dev/null @@ -1,119 +0,0 @@ -# Attestation in Contrast - -This document describes the attestation architecture of Contrast, adhering to the definitions of Remote ATtestation procedureS (RATS) in [RFC 9334](https://www.rfc-editor.org/rfc/rfc9334.html). -The following gives a detailed description of Contrast's attestation architecture. -At the end of this document, we included an [FAQ](#frequently-asked-questions-about-attestation-in-contrast) that answers the most common questions regarding attestation in hindsight of the [security benefits](../basics/security-benefits.md). - -## Attestation architecture - -Contrast integrates with the RATS architecture, leveraging their definition of roles and processes including *Attesters*, *Verifiers*, and *Relying Parties*. - -![Conceptual attestation architecture](../_media/attestation-rats-architecture.svg) - -Figure 1: Conceptual attestation architecture. Taken from [RFC 9334](https://www.rfc-editor.org/rfc/rfc9334.html#figure-1). - -- **Attester**: Assigned to entities that are responsible for creating *Evidence* which is then sent to a *Verifier*. -- **Verifier**: These entities utilize the *Evidence*, *Reference Values*, and *Endorsements*. They assess the trustworthiness of the *Attester* by applying an *Appraisal Policy* for *Evidence*. Following this assessment, *Verifiers* generate *Attestation Results* for use by *Relying Parties*. The *Appraisal Policy* for *Evidence* may be provided by the *Verifier Owner*, programmed into the *Verifier*, or acquired through other means. -- **Relying Party**: Assigned to entities that utilize *Attestation Results*, applying their own appraisal policies to make specific decisions, such as authorization decisions. This process is referred to as the "appraisal of Attestation Results." The *Appraisal Policy* for *Attestation Results* might be sourced from the *Relying Party Owner*, configured by the owner, embedded in the *Relying Party*, or obtained through other protocols or mechanisms. - -## Components of Contrast's attestation - -The key components involved in the attestation process of Contrast are detailed below: - -### Attester: Application Pods - -This includes all Pods of the Contrast deployment that run inside Confidential Containers and generate cryptographic evidence reflecting their current configuration and state. -Their evidence is rooted in the [hardware measurements](../basics/confidential-containers.md) from the CPU and their [confidential VM environment](../components/runtime.md). -The details of this evidence are given below in the section on [evidence generation and appraisal](#evidence-generation-and-appraisal). - -![Attestation flow of a confidential pod](../_media/attestation-pod.svg) - -Figure 2: Attestation flow of a confidential pod. Based on the layered attester graphic in [RFC 9334](https://www.rfc-editor.org/rfc/rfc9334.html#figure-3). - -Pods run in Contrast's [runtime environment](../components/runtime.md) (B), effectively within a confidential VM. -During launch, the CPU (A) measures the initial memory content of the confidential VM that contains Contrast's pod-VM image and generates the corresponding attestation evidence. -The image is in [IGVM format](https://github.com/microsoft/igvm), encapsulating all information required to launch a virtual machine, including the kernel, the initramfs, and kernel cmdline. -The kernel cmdline contains the root hash for [dm-verity](https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/verity.html) that ensures the integrity of the root filesystem. -The root filesystem contains all components of the container's runtime environment including the [guest agent](../basics/confidential-containers.md#kata-containers) (C). - -In the userland, the guest agent takes care of enforcing the [runtime policy](../components/index.md#runtime-policies) of the pod. -While the policy is passed in during the initialization procedure via the host, the evidence for the runtime policy is part of the CPU measurements. -During the [deployment](../deployment.md#generate-policy-annotations-and-manifest) the policy is annotated to the Kubernetes Pod resources. -On AMD SEV-SNP the hash of the policy is then added to the attestation report via the `HOSTDATA` field by the hypervisor. -When provided with the policy from the Kata host, the guest agent verifies that the policy's hash matches the one in the `HOSTDATA` field. - -In summary a Pod's evidence is the attestation report of the CPU that provides evidence for runtime environment and the runtime policy. - -### Verifier: Coordinator and CLI - -The [Coordinator](../components/index.md#the-coordinator) acts as a verifier within the Contrast deployment, configured with a [Manifest](../components/index.md#the-manifest) that defines the reference values and serves as an appraisal policy for all pods in the deployment. -It also pulls endorsements from hardware vendors to verify the hardware claims. -The Coordinator operates within the cluster as a confidential container and provides similar evidence as any other Pod when it acts as an attester. -In RATS terminology, the Coordinator's dual role is defined as a lead attester in a composite device which spans the entire deployment: Coordinator and the workload pods. -It collects evidence from other attesters and conveys it to a verifier, generating evidence about the layout of the whole composite device based on the Manifest as the appraisal policy. - -![Deployment attestation as a composite device](../_media/attestation-composite-device.svg) - -Figure 3: Contrast deployment as a composite device. Based on the composite device in [RFC 9334](https://www.rfc-editor.org/rfc/rfc9334.html#figure-4). - -The [CLI](../components/index.md#the-cli-command-line-interface) serves as the verifier for the Coordinator and the entire Contrast deployment, containing the reference values for the Coordinator and the endorsements from hardware vendors. -These reference values are built into the CLI during our release process and can be reproduced offline via reproducible builds. - -### Relying Party: Data owner - -A relying party in the Contrast scenario could be, for example, the [data owner](../basics/security-benefits.md) that interacts with the application. -The relying party can use the CLI to obtain the attestation results and Contrast's [CA certificates](certificates.md) bound to these results. -The CA certificates can then be used by the relying party to authenticate the application, for example through TLS connections. - -## Evidence generation and appraisal - -### Evidence types and formats - -In Contrast, attestation evidence revolves around a hardware-generated attestation report, which contains several critical pieces of information: - -- **The hardware attestation report**: This report includes details such as the chip identifier, platform information, microcode versions, and comprehensive guest measurements. The entire report is signed by the CPU's private key, ensuring the authenticity and integrity of the data provided. -- **The launch measurements**: Included within the hardware attestation report, this is a digest generated by the CPU that represents a hash of all initial guest memory pages. This includes essential components like the kernel, initramfs, and the kernel command line. Notably, it incorporates the root filesystem's dm-verity root hash, verifying the integrity of the root filesystem. -- **The runtime policy hash**: Also part of the hardware attestation report, this field contains the hash of the Rego policy which dictates all expected API commands and their values from the host to the Kata guest agent. It encompasses crucial settings such as dm-verity hashes for the container image layers, environment variables, and mount points. - -### Appraisal policies for evidence - -The appraisal of this evidence in Contrast is governed by two main components: - -- **The Manifest**: A JSON file used by the Coordinator to align with reference values. It sets the expectations for runtime policy hashes for each pod and includes what should be reported in the hardware attestation report for each component of the deployment. -- **The CLI's appraisal policy**: This policy encompasses expected values of the Coordinator’s guest measurements and its runtime policy. It's embedded into the CLI during the build process and ensures that any discrepancy between the built-in values and those reported by the hardware attestation can be identified and addressed. The integrity of this policy is safeguardable through reproducible builds, allowing verification against the source code reference. - -## Frequently asked questions about attestation in Contrast - -### What's the purpose of remote attestation in Contrast? - -Remote attestation in Contrast ensures that software runs within a secure, isolated confidential computing environment. -This process certifies that the memory is encrypted and confirms the integrity and authenticity of the software running within the deployment. -By validating the runtime environment and the policies enforced on it, Contrast ensures that the system operates in a trustworthy state and hasn't been tampered with. - -### How does Contrast ensure the security of the attestation process? - -Contrast leverages hardware-rooted security features such as AMD SEV-SNP to generate cryptographic evidence of a pod’s current state and configuration. -This evidence is checked against pre-defined appraisal policies to guarantee that only verified and authorized pods are part of a Contrast deployment. - -### What security benefits does attestation provide? - -Attestation confirms the integrity of the runtime environment and the identity of the workloads. -It plays a critical role in preventing unauthorized changes and detecting potential modifications at runtime. -The attestation provides integrity and authenticity guarantees, enabling relying parties—such as workload operators or data owners—to confirm the effective protection against potential threats, including malicious cloud insiders, co-tenants, or compromised workload operators. -More details on the specific security benefits can be found [here](../basics/security-benefits.md). - -### How can you verify the authenticity of attestation results? - -Attestation results in Contrast are tied to cryptographic proofs generated and signed by the hardware itself. -These proofs are then verified using public keys from trusted hardware vendors, ensuring that the results aren't only accurate but also resistant to tampering. -For further authenticity verification, all of Contrast's code is reproducibly built, and the attestation evidence can be verified locally from the source code. - -### How are attestation results used by relying parties? - -Relying parties use attestation results to make informed security decisions, such as allowing access to sensitive data or resources only if the attestation verifies the system's integrity. -Thereafter, the use of Contrast's [CA certificates in TLS connections](certificates.md) provides a practical approach to communicate securely with the application. - -## Summary - -In summary, Contrast's attestation strategy adheres to the RATS guidelines and consists of robust verification mechanisms that ensure each component of the deployment is secure and trustworthy. -This comprehensive approach allows Contrast to provide a high level of security assurance to its users. diff --git a/docs/versioned_docs/version-0.6/architecture/certificates.md b/docs/versioned_docs/version-0.6/architecture/certificates.md deleted file mode 100644 index d6c2b8ef73..0000000000 --- a/docs/versioned_docs/version-0.6/architecture/certificates.md +++ /dev/null @@ -1,70 +0,0 @@ -# Certificate authority - -The Coordinator acts as a certificate authority (CA) for the workloads -defined in the manifest. -After a workload pod's attestation has been verified by the Coordinator, -it receives a mesh certificate and the mesh CA certificate. -The mesh certificate can be used for example in a TLS connection as the server or -client certificate to proof to the other party that the workload has been -verified by the Coordinator. The other party can verify the mesh certificate -with the mesh CA certificate. While the certificates can be used by the workload -developer in different ways, they're automatically used in Contrast's service -mesh to establish mTLS connections between workloads in the same deployment. - -## Public key infrastructure - -The Coordinator establishes a public key infrastructure (PKI) for all workloads -contained in the manifest. The Coordinator holds three certificates: the root CA -certificate, the intermediate CA certificate, and the mesh CA certificate. -The root CA certificate is a long-lasting certificate and its private key signs -the intermediate CA certificate. The intermediate CA certificate and the mesh CA -certificate share the same private key. This intermediate private key is used -to sign the mesh certificates. Moreover, the intermediate private key and -therefore the intermediate CA certificate and the mesh CA certificate are -rotated when setting a new manifest. - -![PKI certificate chain](../_media/contrast_pki.drawio.svg) - -## Certificate rotation - -Depending on the configuration of the first manifest, it allows the workload -owner to update the manifest and, therefore, the deployment. -Workload owners and data owners can be mutually untrusted parties. -To protect against the workload owner silently introducing malicious containers, -the Coordinator rotates the intermediate private key every time the manifest is -updated and, therefore, the -intermediate CA certificate and mesh CA certificate. If the user doesn't -trust the workload owner, they use the mesh CA certificate obtained when they -verified the Coordinator and the manifest. This ensures that the user only -connects to workloads defined in the manifest they verified since only those -workloads' certificates are signed with this intermediate private key. - -Similarly, the service mesh also uses the mesh CA certificate obtained when the -workload was started, so the workload only trusts endpoints that have been -verified by the Coordinator based on the same manifest. Consequently, a -manifest update requires a fresh rollout of the services in the service mesh. - -## Usage of the different certificates - -- The **root CA certificate** is returned when verifying the Coordinator. -The data owner can use it to verify the mesh certificates of the workloads. -This should only be used if the data owner trusts all future updates to the -manifest and workloads. This is, for instance, the case when the workload owner is -the same entity as the data owner. -- The **mesh CA certificate** is returned when verifying the Coordinator. -The data owner can use it to verify the mesh certificates of the workloads. -This certificate is bound to the manifest set when the Coordinator is verified. -If the manifest is updated, the mesh CA certificate changes. -New workloads will receive mesh certificates signed by the _new_ mesh CA certificate. -The Coordinator with the new manifest needs to be verified to retrieve the new mesh CA certificate. -The service mesh also uses the mesh CA certificate to verify the mesh certificates. -- The **intermediate CA certificate** links the root CA certificate to the -mesh certificate so that the mesh certificate can be verified with the root CA -certificate. It's part of the certificate chain handed out by -endpoints in the service mesh. -- The **mesh certificate** is part of the certificate chain handed out by -endpoints in the service mesh. During the startup of a pod, the Initializer -requests a certificate from the Coordinator. This mesh certificate will be returned if the Coordinator successfully -verifies the workload. The mesh certificate -contains X.509 extensions with information from the workloads attestation -document. diff --git a/docs/versioned_docs/version-0.6/architecture/index.md b/docs/versioned_docs/version-0.6/architecture/index.md deleted file mode 100644 index d2bb21f55a..0000000000 --- a/docs/versioned_docs/version-0.6/architecture/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# Architecture - -import DocCardList from '@theme/DocCardList'; - - diff --git a/docs/versioned_docs/version-0.6/basics/confidential-containers.md b/docs/versioned_docs/version-0.6/basics/confidential-containers.md deleted file mode 100644 index 6f3f48f5bb..0000000000 --- a/docs/versioned_docs/version-0.6/basics/confidential-containers.md +++ /dev/null @@ -1,32 +0,0 @@ -# Confidential Containers - -Contrast uses some building blocks from [Confidential Containers](https://confidentialcontainers.org) (CoCo), a [CNCF Sandbox project](https://www.cncf.io/projects/confidential-containers/) that aims to standardize confidential computing at the pod level. -The project is under active development and many of the high-level features are still in flux. -Contrast uses the more stable core primitive provided by CoCo: its Kubernetes runtime. - -## Kubernetes RuntimeClass - -Kubernetes can be extended to use more than one container runtime with [`RuntimeClass`](https://kubernetes.io/docs/concepts/containers/runtime-class/) objects. -The [Container Runtime Interface](https://kubernetes.io/docs/concepts/architecture/cri/) (CRI) implementation, for example containerd, dispatches pod management API calls to the appropriate `RuntimeClass`. -`RuntimeClass` implementations are usually based on an [OCI runtime](https://github.com/opencontainers/runtime-spec), such as `runc`, `runsc` or `crun`. -In CoCo's case, the runtime is Kata Containers with added confidential computing capabilities. - -## Kata Containers - -[Kata Containers](https://katacontainers.io/) is an OCI runtime that runs pods in VMs. -The pod VM spawns an agent process that accepts management commands from the Kata runtime running on the host. -There are two options for creating pod VMs: local to the Kubernetes node, or remote VMs created with cloud provider APIs. -Using local VMs requires either bare-metal servers or VMs with support for nested virtualization. -Local VMs communicate with the host over a virtual socket. -For remote VMs, host-to-agent communication is tunnelled through the cloud provider's network. - -Kata Containers was originally designed to isolate the guest from the host, but it can also run pods in confidential VMs (CVMs) to shield pods from their underlying infrastructure. -In confidential mode, the guest agent is configured with an [Open Policy Agent](https://www.openpolicyagent.org/) (OPA) policy to authorize API calls from the host. -This policy also contains checksums for the expected container images. -It's derived from Kubernetes resource definitions and its checksum is included in the attestation report. - -## AKS CoCo preview - -[Azure Kubernetes Service](https://learn.microsoft.com/en-us/azure/aks/) (AKS) provides CoCo-enabled node pools as a [preview offering](https://learn.microsoft.com/en-us/azure/aks/confidential-containers-overview). -These node pools leverage Azure VM types capable of nested virtualization (CVM-in-VM) and the CoCo stack is pre-installed. -Contrast can be deployed directly into a CoCo-enabled AKS cluster. diff --git a/docs/versioned_docs/version-0.6/basics/features.md b/docs/versioned_docs/version-0.6/basics/features.md deleted file mode 100644 index 1139ae0f0d..0000000000 --- a/docs/versioned_docs/version-0.6/basics/features.md +++ /dev/null @@ -1,15 +0,0 @@ -# Product features - -Contrast simplifies the deployment and management of Confidential Containers, offering optimal data security for your workloads while integrating seamlessly with your existing Kubernetes environment. - -From a security perspective, Contrast employs the [Confidential Containers](confidential-containers.md) concept and provides [security benefits](security-benefits.md) that go beyond individual containers, shielding your entire deployment from the underlying infrastructure. - -From an operational perspective, Contrast provides the following key features: - -* **Managed Kubernetes compatibility**: Initially compatible with Azure Kubernetes Service (AKS), Contrast is designed to support additional platforms such as AWS EKS and Google Cloud GKE as they begin to accommodate confidential containers. - -* **Lightweight installation**: Contrast can be integrated as a [day-2 operation](../deployment.md) within existing clusters, adding minimal [components](../architecture) to your setup. This facilitates straightforward deployments using your existing YAML configurations, Helm charts, or Kustomization, enabling native Kubernetes orchestration of your applications. - -* **Remote attestation**: Contrast generates a concise attestation statement that verifies the identity, authenticity, and integrity of your deployment both internally and to external parties. This architecture ensures that updates or scaling of the application don't compromise the attestation’s validity. - -* **Service mesh**: Contrast securely manages a Public Key Infrastructure (PKI) for your deployments, issues workload-specific certificates, and establishes transparent mutual TLS (mTLS) connections across pods. This is done by harnessing the [envoy proxy](https://www.envoyproxy.io/) to ensure secure communications within your Kubernetes cluster. diff --git a/docs/versioned_docs/version-0.6/basics/security-benefits.md b/docs/versioned_docs/version-0.6/basics/security-benefits.md deleted file mode 100644 index c56b23178f..0000000000 --- a/docs/versioned_docs/version-0.6/basics/security-benefits.md +++ /dev/null @@ -1,159 +0,0 @@ -# Contrast security overview - -This document outlines the security measures of Contrast and its capability to counter various threats. -Contrast is designed to shield entire Kubernetes deployments from the infrastructure, enabling entities to manage sensitive information (such as regulated or personally identifiable information (PII)) in the public cloud, while maintaining data confidentiality and ownership. - -Contrast is applicable in situations where establishing trust with the workload operator or the underlying infrastructure is challenging. -This is particularly beneficial for regulated sectors looking to transition sensitive activities to the cloud, without sacrificing security or compliance. -It allows for cloud adoption by maintaining a hardware-based separation from the cloud service provider. - -## Confidential computing foundation - -Leveraging Confidential Computing technology, Contrast provides three defining security properties: - -- **Encryption of data in use**: Contrast ensures that all data processed in memory is encrypted, making it inaccessible to unauthorized users or systems, even if they have physical access to the hardware. -- **Workload isolation**: Each pod runs in its isolated runtime environment, preventing any cross-contamination between workloads, which is critical for multi-tenant infrastructures. -- **Remote attestation**: This feature allows data owners and workload operators to verify that the Contrast environment executing their workloads hasn't been tampered with and is running in a secure, pre-approved configuration. - -The runtime encryption is transparently provided by the confidential computing hardware during the workload's lifetime. -The workload isolation and remote attestation involves two phases: - -* An attestation process detects modifications to the workload image or its runtime environment during the initialization. This protects the workload's integrity pre-attestation. -* A protected runtime environment and a policy mechanism prevents the platform operator from accessing or compromising the instance at runtime. This protects a workload's integrity and confidentiality post-attestation. - -For more details on confidential computing see our [whitepaper](https://content.edgeless.systems/hubfs/Confidential%20Computing%20Whitepaper.pdf). -The [attestation architecture](../architecture/attestation.md) describes Contrast's attestation process and the resulting chain of trust in detail. - -## Components of a Contrast deployment - -Contrast uses the Kubernetes runtime of the [Confidential Containers](confidential-containers.md) project. -Confidential Containers significantly decrease the size of the trusted computing base (TCB) of a Kubernetes deployment, by isolating each pod within its own confidential micro-VM environment. -The TCB is the totality of elements in a computing environment that must be trusted not to be compromised. -A smaller TCB results in a smaller attack surface. The following diagram shows how Confidential Containers remove the *cloud & datacenter infrastructure* and the *physical hosts*, including the hypervisor, the host OS, the Kubernetes control plane, and other components, from the TCB (red). -In the confidential context, depicted in green, only the workload containers along with their confidential micro-VM environment are included within the TCB. -Their integrity is [verifiable through remote attestation](../architecture/attestation.md). - -Contrast uses [hardware-based mechanisms](confidential-containers.md), specifically leveraging CPU features, such as AMD SEV or Intel TDX, to provide the isolation of the workload. -This implies that both the CPU and its microcode are integral components of the TCB. -However, it should be noted that the CPU microcode aspects aren't depicted in the accompanying graphic. - -![TCB comparison](../_media/tcb.svg) - -Contrast adds the following components to a deployment that become part of the TCB. -The components that are part of the TCB are: - -* **The workload containers**: Container images that run the actual application. -* **[The runtime environment](../components/runtime.md)**: The confidential micro-VM that acts as the container runtime. -* **[The sidecar containers](../components/service-mesh.md)**: Containers that provide additional functionality such as [initialization](../components/index.md#the-initializer) and [service mesh](../components/service-mesh.md). -* **[The runtime policies](../components/policies.md)**: Policies that enforce the runtime environments for the workload containers during their lifetime. -* **[The manifest](../components/index.md#the-manifest)**: A manifest file defining the reference values of an entire confidential deployment. It contains the policy hashes for all pods of the deployment and the expected hardware reference values for the Confidential Container runtime. -* **[The Coordinator](../components/index.md#the-coordinator)**: An attestation service that runs in a Confidential Container in the Kubernetes cluster. The Coordinator is configured with the manifest. User-facing, you can verify this service and the effective manifest using remote attestation, providing you with a concise attestation for the entire deployment. Cluster-facing, it verifies all pods and their policies based on remote attestation procedures and the manifest. - -## Personas in a Contrast deployment - -In a Contrast deployment, there are three parties: - -* **The container image provider**, who creates the container images that represent the application that has access to the protected data. - -* **The workload operator**, who runs the workload in a Kubernetes cluster. The operator typically has full administrative privileges to the deployment. The operator can manage cluster resources such as nodes, volumes, and networking rules, and the operator can interact with any Kubernetes or underlying cloud API. - -* **The data owner**, who owns the protected data. A data owner can verify the deployment using the Coordinator attestation service. The verification includes the identity, integrity, and confidentiality of the workloads, the runtime environment and the access permissions. - -Contrast supports a trust model where the container image provider, workload operator, and data owner are separate, mutually distrusting parties. - -The following diagram shows the system components and parties. - -![Components and parties](../_media/personas.svg) - -## Threat model and mitigations - -This section describes the threat vectors that Contrast helps to mitigate. - -The following attacks are out of scope for this document: - -* Attacks on the application code itself, such as insufficient access controls. -* Attacks on the Confidential Computing hardware directly, such as side-channel attacks. -* Attacks on the availability, such as denial-of-service (DOS) attacks. - - -### Possible attacks - -Contrast is designed to defend against five possible attacks: - -* **A malicious cloud insider**: malicious employees or third-party contractors of cloud service providers (CSPs) potentially have full access to various layers of the cloud infrastructure. That goes from the physical datacenter up to the hypervisor and Kubernetes layer. For example, they can access the physical memory of the machines, modify the hypervisor, modify disk contents, intercept network communications, and attempt to compromise the confidential container at runtime. A malicious insider can expand the attack surface or restrict the runtime environment. For example, a malicious operator can add a storage device to introduce new attack vectors. As another example, a malicious operator can constrain resources such as limiting a guest's memory size, changing its disk space, or changing firewall rules. -* **A malicious cloud co-tenant**: malicious cloud user ("hackers") may break out of their tenancy and access other tenants' data. Advanced attackers may even be able to establish a permanent foothold within the infrastructure and access data over a longer period. The threats are analogous to the *cloud insider access* scenario, without the physical access. -* **A malicious workload operator**: malicious workload operators, for example Kubernetes administrators, have full access to the workload deployment and the underlying Kubernetes platform. The threats are analogously to the *cloud insider access* scenario, with access to everything that's above the hypervisor level. -* **A malicious attestation client**: this attacker connects to the attestation service and sends malformed request. -* **A malicious container image provider**: a malicious container image provider has full control over the application development itself. This attacker might release a malicious version of the workload containing harmful operations. - -### Attack surfaces - -The following table describes the attack surfaces that are available to attackers. - -| Attacker | Target | Attack surface | Risks | -|------------------------------------------------|----------------------------------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| -| Cloud insider | Confidential Container, Workload | Physical memory | Attacker can dump the physical memory of the workloads. | -| Cloud insider, cloud hacker, workload operator | Confidential Container, Workload | Disk reads | Anything read from the disk is within the attacker's control. | -| Cloud insider, cloud hacker, workload operator | Confidential Container, Workload | Disk writes | Anything written to disk is visible to an attacker. | -| Cloud insider, cloud hacker, workload operator | Confidential Container, Workload | Kubernetes Control Plane | Instance attributes read from the Kubernetes control plane, including mount points and environment variables, are within the attacker's control. | -| Cloud insider, cloud hacker, workload operator | Confidential Container, Workload | Container Runtime | The attacker can use container runtime APIs (for example "kubectl exec") to perform operations on the workload container. | -| Cloud insider, cloud hacker, workload operator | Confidential Container, Workload | Network | Intra-deployment (between containers) as well as external network connections to the image repository or attestation service can be intercepted. | -| Attestation client | Coordinator attestation service | Attestation requests | The attestation service has complex, crypto-heavy logic that's challenging to write defensively. | -| Container image provider | Workload | Workload | This attacker might release an upgrade to the workload containing harmful changes, such as a backdoor. | | - -### Threats and mitigations - -Contrast shields a workload from the aforementioned threats with three main components: - -1. The [runtime environment](../components/runtime.md) safeguards against the physical memory and disk attack surface. -2. The [runtime policies](../components/policies.md) safeguard against the Kubernetes control plane and container runtime attack surface. -3. The [service mesh](../components/service-mesh.md) safeguards against the network attack surface. - -The following tables describe concrete threats and how they're mitigated in Contrast grouped by these categories: - -* Attacks on the confidential container environment -* Attacks on the attestation service -* Attacks on workloads - -#### Attacks on the confidential container environment - -This table describes potential threats and mitigation strategies related to the confidential container environment. - -| Threat | Mitigation | Mitigation implementation | -|----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------| -| An attacker intercepts the network connection of the launcher or image repository. | An attacker can change the image URL and control the workload binary. However these actions are reflected in the attestation report. The image repository isn't controlled using an access list, therefore the image is assumed to be viewable by everyone. You must ensure that the workload container image doesn't contain any secrets. | Within the [runtime policies](../components/policies.md) and [attestation](../architecture/attestation.md) | -| An attacker modifies the workload image on disk after it was downloaded and measured. | This threat is mitigated by a read-only partition that's integrity-protected. The workload image is protected by dm-verity. | Within the Contrast [runtime environment](../components/runtime.md) | -| An attacker modifies a container's runtime environment configuration in the Kubernetes control plane. | The attestation process and the runtime policies detects unsafe configurations that load non-authentic images or perform any other modification to the expected runtime environment. | Within the [runtime policies](../components/policies.md) and [attestation](../architecture/attestation.md) | - -#### Attacks on the Coordinator attestation service - -This table describes potential threats and mitigation strategies to the attestation service. - -| Threat | Mitigation | Mitigation implementation | -|-----------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------| -| An attacker intercepts the Coordinator deployment and modifies the image or hijacks the runtime environment. | This threat is mitigated by having an attestation procedure and attested, encrypted TLS connections to the Coordinator. The attestation evidence for the Coordinator image is distributed with our releases, protected by supply chain security, and fully reproducible. | Within the [attestation](../architecture/attestation.md) | -| An attacker intercepts the network connection between the workload and the Coordinator and reads secret keys from the wire. | This threat is mitigated by having an attested, encrypted TLS connection. This connection helps protect the secrets from passive eavesdropping. The attacker can't create valid workload certificates that would be accepted in Contrast's service mesh. An attacker can't impersonate a valid workload container because the container's identity is guaranteed by the attestation protocol. | Within the network between your workload and the Coordinator. | -| An attacker exploits parsing discrepancies, which leads to undetected changes in the attestation process. | This risk is mitigated by having a parsing engine written in memory-safe Go that's tested against the attestation specification of the hardware vendor. The runtime policies are available as an attestation artifact for further inspection and audits to verify their effectiveness. | Within the [Coordinator](../components/index.md#the-coordinator) | -| An attacker uses all service resources, which brings the Coordinator down in a denial of service (DoS) attack. | In the future, this reliability risk is mitigated by having a distributed Coordinator service that can be easily replicated and scaled out as needed. | Within the [Coordinator](../components/index.md#the-coordinator) | -#### Attacks on workloads - -This table describes potential threats and mitigation strategies related to workloads. - -| Threat | Mitigation | Mitigation implementation | -|--------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------| -| An attacker intercepts the network connection between two workload containers. | This threat is mitigated by having transparently encrypted TLS connections between the containers in your deployment. | Within the [service mesh](../components/service-mesh.md) | -| An attacker reads or modifies data written to disk via persistent volumes. | Currently, persistent volumes aren't supported in Contrast. In the future, this threat is mitigated by encrypted and integrity-protected volume mounts. | Within the Contrast [runtime environment](../components/runtime.md)| -| An attacker publishes a new image version containing malicious code. | The attestation process and the runtime policies require a data owner to accept a specific version of the workload and any update to the workload needs to be explicitly acknowledged. | Within the [attestation](../architecture/attestation.md) | - -## Examples of Contrast's threat model in practice - - -The following table describes three example use cases and how they map to the defined threat model in this document: - -| Use Case | Example Scenario | -|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Migrate sensitive workloads to the cloud | TechSolve Inc., a software development firm, aimed to enhance its defense-in-depth strategy for its cloud-based development environment, especially for projects involving proprietary algorithms and client data. TechSolve acts as the image provider, workload operator, and data owner, combining all three personas in this scenario. In our [attestation terminology](../architecture/attestation.md), they're the workload operator and relying party in one entity. Their threat model includes a malicious cloud insider and cloud co-tenant. | -| Make your SaaS more trustworthy | SaaSProviderX, a company offering cloud-based project management tools, sought to enhance its platform's trustworthiness amidst growing concerns about data breaches and privacy. Here, the [relying party](../architecture/attestation.md) is the SaaS customer as the data owner. The goal is to achieve a form of operator exclusion and only allow selective operations on the deployment. Hence, their threat model includes a malicious workload operator. | -| Simplify regulatory compliance | HealthSecure Inc. has been managing a significant volume of sensitive patient data on-premises. With the increasing demand for advanced data analytics and the need for scalable infrastructure, the firm decides to migrate its data analytics operations to the cloud. However, the primary concern is maintaining the confidentiality and security of patient data during and after the migration, in compliance with healthcare regulations. In this compliance scenario, the regulator serves as an additional relying party. HealthSecure must implement a mechanism that ensures the isolation of patient data can be verifiably guaranteed to the regulator. | - -In each scenario, Contrast ensures exclusive data access and processing capabilities are confined to the designated workloads. It achieves this by effectively isolating the workload from the infrastructure and other components of the stack. Data owners are granted the capability to audit and approve the deployment environment before submitting their data, ensuring a secure handover. Meanwhile, workload operators are equipped to manage and operate the application seamlessly, without requiring direct access to either the workload or its associated data. diff --git a/docs/versioned_docs/version-0.6/components/index.md b/docs/versioned_docs/version-0.6/components/index.md deleted file mode 100644 index 7acb319da3..0000000000 --- a/docs/versioned_docs/version-0.6/components/index.md +++ /dev/null @@ -1,60 +0,0 @@ -# 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 using 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 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/versioned_docs/version-0.6/components/policies.md b/docs/versioned_docs/version-0.6/components/policies.md deleted file mode 100644 index 20596667ea..0000000000 --- a/docs/versioned_docs/version-0.6/components/policies.md +++ /dev/null @@ -1,76 +0,0 @@ -# Policies - -Kata runtime policies are an integral part of the Confidential Containers preview on AKS. -They prescribe how a Kubernetes pod must be configured to launch successfully in a confidential VM. -In Contrast, policies act as a workload identifier: only pods with a policy registered in the manifest receive workload certificates and may participate in the confidential deployment. -Verification of the Contrast Coordinator and its manifest transitively guarantees that all workloads meet the owner's expectations. - -## Structure - -The Kata agent running in the confidential micro-VM exposes an RPC service [`AgentService`] to the Kata runtime. -This service handles potentially untrustworthy requests from outside the TCB, which need to be checked against a policy. - -Kata runtime policies are written in the policy language [Rego]. -They specify what `AgentService` methods can be called, and the permissible parameters for each call. - -Policies consist of two parts: a list of rules and a data section. -While the list of rules is static, the data section is populated with information from the `PodSpec` and other sources. - -[`AgentService`]: https://github.com/kata-containers/kata-containers/blob/e5e0983/src/libs/protocols/protos/agent.proto#L21-L76 -[Rego]: https://www.openpolicyagent.org/docs/latest/policy-language/ - -## Generation - -Runtime policies are programmatically generated from Kubernetes manifests by the Contrast CLI. -The `generate` subcommand inspects pod definitions and derives rules for validating the pod at the Kata agent. -There are two important integrity checks: container image checksums and OCI runtime parameters. - -For each of the container images used in a pod, the CLI downloads all image layers and produces a cryptographic [dm-verity] checksum. -These checksums are the basis for the policy's *storage data*. - -The CLI combines information from the `PodSpec`, `ConfigMaps`, and `Secrets` in the provided Kubernetes manifests to derive a permissible set of command-line arguments and environment variables. -These constitute the policy's *OCI data*. - -[dm-verity]: https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/verity.html - -## Evaluation - -The generated policy document is annotated to the pod definitions in Base64 encoding. -This annotation is propagated to the Kata runtime, which calculates the SHA256 checksum for the policy and uses that as SNP `HOSTDATA` for the confidential micro-VM. - -After the VM launched, the runtime calls the agent's `SetPolicy` method with the full policy document. -If the policy doesn't match the checksum in `HOSTDATA`, the agent rejects the policy. -Otherwise, it applies the policy to all future `AgentService` requests. - -## Guarantees - -The policy evaluation provides the following guarantees for pods launched with the correct generated policy: - -* Command and its arguments are set as specified in the resources. -* There are no unexpected additional environment variables. -* The container image layers correspond to the layers observed at policy generation time. - Thus, only the expected workload image can be instantiated. -* Executing additional processes in a container is prohibited. -* Sending data to a container's standard input is prohibited. - -The current implementation of policy checking has some blind spots: - -* Containers can be started in any order, or be omitted entirely. -* Environment variables may be missing. -* Volumes other than the container root volume don't have integrity checks (particularly relevant for mounted `ConfigMaps` and `Secrets`). - -## Trust - -Contrast verifies its confidential containers following these steps: - -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 invokes the Kata runtime to create 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 Initializer sends an attestation report to the Contrast Coordinator, asking for a mesh certificate. -9. 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 matches expectations and may receive mesh certificates. diff --git a/docs/versioned_docs/version-0.6/components/runtime.md b/docs/versioned_docs/version-0.6/components/runtime.md deleted file mode 100644 index 62c072ff47..0000000000 --- a/docs/versioned_docs/version-0.6/components/runtime.md +++ /dev/null @@ -1,84 +0,0 @@ -# Contrast Runtime - -The Contrast runtime is responsible for starting pods as confidential virtual machines. -This works by specifying the runtime class to be used in a pod spec and by registering the runtime class with the apiserver. -The `RuntimeClass` resource defines a name for referencing the class and -a handler used by the container runtime (`containerd`) to identify the class. - -```yaml -apiVersion: node.k8s.io/v1 -kind: RuntimeClass -metadata: - # This name is used by pods in the runtimeClassName field - name: contrast-cc-abcdef -# This name is used by the -# container runtime interface implementation (containerd) -handler: contrast-cc-abcdef -``` - -Confidential pods that are part of a Contrast deployment need to specify the -same runtime class in the `runtimeClassName` field, so Kubernetes uses the -Contrast runtime instead of the default `containerd` / `runc` handler. - -```yaml -apiVersion: v1 -kind: Pod -spec: - runtimeClassName: contrast-cc-abcdef - # ... -``` - -## Node-level components - -The runtime consists of additional software components that need to be installed -and configured on every SEV-SNP-enabled worker node. -This installation is performed automatically by the [`node-installer` DaemonSet](#node-installer-daemonset). - -![Runtime components](../_media/runtime.svg) - -### Containerd shim - -The `handler` field in the Kubernetes `RuntimeClass` instructs containerd not to use the default `runc` implementation. -Instead, containerd invokes a custom plugin called `containerd-shim-contrast-cc-v2`. -This shim is described in more detail in the [upstream source repository](https://github.com/kata-containers/kata-containers/tree/3.4.0/src/runtime) and in the [containerd documentation](https://github.com/containerd/containerd/blob/main/core/runtime/v2/README.md). - -### `cloud-hypervisor` virtual machine manager (VMM) - -The `containerd` shim uses [`cloud-hypervisor`](https://www.cloudhypervisor.org) to create a confidential virtual machine for every pod. -This requires the `cloud-hypervisor` binary to be installed on every node (responsibility of the [`node-installer`](#node-installer-daemonset)). - -### `Tardev snapshotter` - -Contrast uses a special [`containerd` snapshotter](https://github.com/containerd/containerd/tree/v1.7.16/docs/snapshotters/README.md) ([`tardev`](https://github.com/kata-containers/tardev-snapshotter)) to provide container images as block devices to the pod-VM. This snapshotter consists of a host component that pulls container images and a guest component (kernel module) used to mount container images. -The `tardev` snapshotter uses [`dm-verity`](https://docs.kernel.org/admin-guide/device-mapper/verity.html) to protect the integrity of container images. -Expected `dm-verity` container image hashes are part of Contrast runtime policies and are enforced by the kata-agent. -This enables workload attestation by specifying the allowed container image as part of the policy. Read [the chapter on policies](policies.md) for more information. - -### Pod-VM image - -Every pod-VM starts with the same guest image. It consists of an IGVM file and a root filesystem. -The IGVM file describes the initial memory contents of a pod-VM and consists of: - -- Linux kernel image -- `initrd` -- `kernel commandline` - -Additionally, a root filesystem image is used that contains a read-only partition with the user space of the pod-VM and a verity partition to guarantee the integrity of the root filesystem. -The root filesystem contains systemd as the init system, and the kata agent for managing the pod. - -This pod-VM image isn't specific to any pod workload. Instead, container images are mounted at runtime. - -## Node installer DaemonSet - -The `RuntimeClass` resource above registers the runtime with the Kubernetes api. -The node-level installation is carried out by the Contrast node-installer -`DaemonSet` that ships with every Contrast release. - -After deploying the installer, it performs the following steps on each node: - -- Install the Contrast containerd shim (`containerd-shim-contrast-cc-v2`) -- Install `cloud-hypervisor` as the virtual machine manager (VMM) -- Install an IGVM file for pod-VMs of this class -- Install a read only root filesystem disk image for the pod-VMs of this class -- Reconfigure `containerd` by adding a runtime plugin that corresponds to the `handler` field of the Kubernetes `RuntimeClass` -- Restart `containerd` to make it aware of the new plugin diff --git a/docs/versioned_docs/version-0.6/components/service-mesh.md b/docs/versioned_docs/version-0.6/components/service-mesh.md deleted file mode 100644 index 749a14992f..0000000000 --- a/docs/versioned_docs/version-0.6/components/service-mesh.md +++ /dev/null @@ -1,162 +0,0 @@ -# Service Mesh - -The Contrast service mesh secures the communication of the workload by automatically -wrapping the network traffic inside mutual TLS (mTLS) connections. The -verification of the endpoints in the connection establishment is based on -certificates that are part of the -[PKI of the Coordinator](../architecture/certificates.md). - -The service mesh can be enabled on a per-pod basis by adding the `service-mesh` -container as a [sidecar container](https://kubernetes.io/docs/concepts/workloads/pods/sidecar-containers/). -The service mesh container first sets up `iptables` -rules based on its configuration and then starts [Envoy](https://www.envoyproxy.io/) -for TLS origination and termination. - -## Configuring the Proxy - -The service mesh container can be configured using the `EDG_INGRESS_PROXY_CONFIG` -and `EDG_EGRESS_PROXY_CONFIG` environment variables. - -### Ingress - -All TCP ingress traffic is routed over Envoy by default. Since we use -[TPROXY](https://docs.kernel.org/networking/tproxy.html), the destination address -remains the same throughout the packet handling. - -Any incoming connection is required to present a client certificate signed by the -[mesh CA certificate](../architecture/certificates.md#usage-of-the-different-certificates). -Envoy presents a certificate chain of the mesh -certificate of the workload and the intermediate CA certificate as the server certificate. - -If the deployment contains workloads which should be reachable from outside the -Service Mesh, while still handing out the certificate chain, disable client -authentication by setting the environment variable `EDG_INGRESS_PROXY_CONFIG` as -`##false`. Separate multiple entries with `##`. You can choose any -descriptive string identifying the service on the given port for the -informational-only field ``. - -Disable redirection and TLS termination altogether by specifying -`##true`. This can be beneficial if the workload itself handles TLS -on that port or if the information exposed on this port is non-sensitive. - -The following example workload exposes a web service on port 8080 and metrics on -port 7890. The web server is exposed to a 3rd party end-user which wants to -verify the deployment, therefore it's still required that the server hands out -it certificate chain signed by the mesh CA certificate. The metrics should be -exposed via TCP without TLS. - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: web -spec: - replicas: 1 - template: - spec: - runtimeClassName: contrast-cc - initContainers: - - name: initializer - image: "ghcr.io/edgelesssys/contrast/initializer@sha256:..." - env: - - name: COORDINATOR_HOST - value: coordinator - volumeMounts: - - name: tls-certs - mountPath: /tls-config - - name: sidecar - image: "ghcr.io/edgelesssys/contrast/service-mesh-proxy@sha256:..." - restartPolicy: Always - volumeMounts: - - name: tls-certs - mountPath: /tls-config - env: - - name: EDG_INGRESS_PROXY_CONFIG - value: "web#8080#false##metrics#7890#true" - securityContext: - privileged: true - capabilities: - add: - - NET_ADMIN - containers: - - name: web-svc - image: ghcr.io/edgelesssys/frontend:v1.2.3@... - ports: - - containerPort: 8080 - name: web - - containerPort: 7890 - name: metrics - volumeMounts: - - name: tls-certs - mountPath: /tls-config - volumes: - - name: tls-certs - emptyDir: {} -``` - -### Egress - -To be able to route the egress traffic of the workload through Envoy, the remote -endpoints' IP address and port must be configurable. - -* Choose an IP address inside the `127.0.0.0/8` CIDR and a port not yet in use -by the pod. -* Configure the workload to connect to this IP address and port. -* Set `#:#:` -as `EDG_EGRESS_PROXY_CONFIG`. Separate multiple entries with `##`. Choose any -string identifying the service on the given port as ``. - -This redirects the traffic over Envoy. The endpoint must present a valid -certificate chain which must be verifiable with the -[mesh CA certificate](../architecture/certificates.md#usage-of-the-different-certificates). -Furthermore, Envoy uses a certificate chain with the mesh certificate of the workload -and the intermediate CA certificate as the client certificate. - -The following example workload has no ingress connections and two egress -connection to different microservices. The microservices are themselves part -of the confidential deployment. One is reachable under `billing-svc:8080` and -the other under `cart-svc:8080`. - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: web -spec: - replicas: 1 - template: - spec: - runtimeClassName: contrast-cc - initContainers: - - name: initializer - image: "ghcr.io/edgelesssys/contrast/initializer@sha256:..." - env: - - name: COORDINATOR_HOST - value: coordinator - volumeMounts: - - name: tls-certs - mountPath: /tls-config - - name: sidecar - image: "ghcr.io/edgelesssys/contrast/service-mesh-proxy@sha256:..." - restartPolicy: Always - volumeMounts: - - name: tls-certs - mountPath: /tls-config - env: - - name: EDG_EGRESS_PROXY_CONFIG - value: "billing#127.137.0.1:8081#billing-svc:8080##cart#127.137.0.2:8081#cart-svc:8080" - securityContext: - privileged: true - capabilities: - add: - - NET_ADMIN - containers: - - name: currency-conversion - image: ghcr.io/edgelesssys/conversion:v1.2.3@... - volumeMounts: - - name: tls-certs - mountPath: /tls-config - volumes: - - name: tls-certs - emptyDir: {} -``` diff --git a/docs/versioned_docs/version-0.6/deployment.md b/docs/versioned_docs/version-0.6/deployment.md deleted file mode 100644 index 24d471ce1f..0000000000 --- a/docs/versioned_docs/version-0.6/deployment.md +++ /dev/null @@ -1,271 +0,0 @@ -# Workload deployment - -The following instructions will guide you through the process of making an existing Kubernetes deployment -confidential and deploying it together with Contrast. - -A running CoCo-enabled cluster is required for these steps, see the [setup guide](./getting-started/cluster-setup.md) on how to set it up. - -## Deploy the Contrast runtime - -Contrast depends on a [custom Kubernetes `RuntimeClass` (`contrast-cc`)](./components/runtime.md), -which needs to be installed in the cluster prior to the Coordinator or any confidential workloads. -This consists of a `RuntimeClass` resource and a `DaemonSet` that performs installation on worker nodes. -This step is only required once for each version of the runtime. -It can be shared between Contrast deployments. - -```sh -kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/download/runtime.yml -``` - -## Deploy the Contrast Coordinator - -Install the latest Contrast Coordinator release, comprising a single replica deployment and a -LoadBalancer service, into your cluster. - -```sh -kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/download/coordinator.yml -``` - -## Prepare your Kubernetes resources - -Your Kubernetes resources need some modifications to run as Confidential Containers. -This section guides you through the process and outlines the necessary changes. - -### RuntimeClass and Initializer - -Contrast will add annotations to your Kubernetes YAML files. If you want to keep the original files -unchanged, you can copy the files into a separate local directory. -You can also generate files from a Helm chart or from a Kustomization. - - - - -```sh -mkdir resources -kustomize build $MY_RESOURCE_DIR > resources/all.yml -``` - - - - -```sh -mkdir resources -helm template $RELEASE_NAME $CHART_NAME > resources/all.yml -``` - - - - -```sh -cp -R $MY_RESOURCE_DIR resources/ -``` - - - - -To specify that a workload (pod, deployment, etc.) should be deployed as confidential containers, -add `runtimeClassName: contrast-cc` to the pod spec (pod definition or template). -This is a placeholder name that will be replaced by a versioned `runtimeClassName` when generating policies. -In addition, add the Contrast Initializer as `initContainers` to these workloads and configure the -workload to use the certificates written to a `volumeMount` named `tls-certs`. - -```yaml -spec: # v1.PodSpec - runtimeClassName: contrast-cc - initContainers: - - name: initializer - image: "ghcr.io/edgelesssys/contrast/initializer:latest" - env: - - name: COORDINATOR_HOST - value: coordinator - volumeMounts: - - name: tls-certs - mountPath: /tls-config - volumes: - - name: tls-certs - emptyDir: {} -``` - -### Handling TLS - -The initializer populates the shared volume with X.509 certificates for your workload. -These certificates are used by the [Contrast Service Mesh](components/service-mesh.md), but can also be used by your application directly. -The following tab group explains the setup for both scenarios. - - - - -Contrast can be configured to handle TLS in a sidecar container. -This is useful for workloads that are hard to configure with custom certificates, like Java applications. - -Configuration of the sidecar depends heavily on the application. -The following example is for an application with these properties: - -* The app has a main application at TCP port 8001, which should be TLS-wrapped and doesn't require client authentication. -* The app has a metrics endpoint at TCP port 8080, which should be accessible in plain text. -* All other endpoints require client authentication. -* The app connects to a Kubernetes service `backend.default:4001`, which requires client authentication. - -Add the following sidecar definition to your workload: - -```yaml -spec: # v1.PodSpec - initContainers: - - name: tls-sidecar - image: "ghcr.io/edgelesssys/contrast/service-mesh-proxy:latest" - restartPolicy: Always - env: - - name: EDG_INGRESS_PROXY_CONFIG - value: "main#8001#false##metrics#8080#true" - - name: EDG_EGRESS_PROXY_CONFIG - value: "backend#127.0.0.2:4001#backend.default:4001" - volumeMounts: - - name: tls-certs - mountPath: /tls-config -``` - -The only change required to the app itself is to let it connect to `127.0.0.2:4001` to reach the backend service. -You can find more detailed documentation in the [Service Mesh chapter](components/service-mesh.md). - - - - - -The mesh certificate contained in `certChain.pem` authenticates this workload, while the mesh CA certificate `mesh-ca.pem` authenticates its peers. -Your app should turn on client authentication to ensure peers are running as confidential containers, too. -See the [Certificate Authority](architecture/certificates.md) section for detailed information about these certificates. - -The following example shows how to configure a Golang app, with error handling omitted for clarity. - - - - -```go -caCerts := x509.NewCertPool() -caCert, _ := os.ReadFile("/tls-config/mesh-ca.pem") -caCerts.AppendCertsFromPEM(caCert) -cert, _ := tls.LoadX509KeyPair("/tls-config/certChain.pem", "/tls-config/key.pem") -cfg := &tls.Config{ - Certificates: []tls.Certificate{cert}, - RootCAs: caCerts, -} -``` - - - - -```go -caCerts := x509.NewCertPool() -caCert, _ := os.ReadFile("/tls-config/mesh-ca.pem") -caCerts.AppendCertsFromPEM(caCert) -cert, _ := tls.LoadX509KeyPair("/tls-config/certChain.pem", "/tls-config/key.pem") -cfg := &tls.Config{ - Certificates: []tls.Certificate{cert}, - ClientAuth: tls.RequireAndVerifyClientCert, - ClientCAs: caCerts, -} -``` - - - - - - - -## Generate policy annotations and manifest - -Run the `generate` command to generate the execution policies and add them as annotations to your -deployment files. A `manifest.json` with the reference values of your deployment will be created. - -```sh -contrast generate resources/ -``` - -:::warning -Please be aware that runtime policies currently have some blind spots. For example, they can't guarantee the starting order of containers. See the [current limitations](known-limitations.md#runtime-policies) for more details. -::: - -## Apply the resources - -Apply the resources to the cluster. Your workloads will block in the initialization phase until a -manifest is set at the Coordinator. - -```sh -kubectl apply -f resources/ -``` - -## Connect to the Contrast Coordinator - -For the next steps, we will need to connect to the Coordinator. The released Coordinator resource -includes a LoadBalancer definition we can use. - -```sh -coordinator=$(kubectl get svc coordinator -o=jsonpath='{.status.loadBalancer.ingress[0].ip}') -``` - -:::info[Port-forwarding of Confidential Containers] - -`kubectl port-forward` uses a Container Runtime Interface (CRI) method that isn't supported by the Kata shim. -If you can't use a public load balancer, you can deploy a [port-forwarder](https://github.com/edgelesssys/contrast/blob/ddc371b/deployments/emojivoto/portforwarder.yml). -The port-forwarder relays traffic from a CoCo pod and can be accessed via `kubectl port-forward`. - - - -Upstream tracking issue: https://github.com/kata-containers/kata-containers/issues/1693. - -::: - -## Set the manifest - -Attest the Coordinator and set the manifest: - -```sh -contrast set -c "${coordinator}:1313" resources/ -``` - -After this step, the Coordinator will start issuing TLS certs to the workloads. The init container -will fetch a certificate for the workload and the workload is started. - -## Verify the Coordinator - -An end user (data owner) can verify the Contrast deployment using the `verify` command. - -```sh -contrast verify -c "${coordinator}:1313" -``` - -The CLI will attest the Coordinator using embedded reference values. The CLI will write the service mesh -root certificate and the history of manifests into the `verify/` directory. In addition, the policies referenced -in the manifest are also written to the directory. - -## Communicate with workloads - -You can securely connect to the workloads using the Coordinator's `mesh-ca.pem` as a trusted CA certificate. -First, expose the service on a public IP address via a LoadBalancer service: - -```sh -kubectl patch svc ${MY_SERVICE} -p '{"spec": {"type": "LoadBalancer"}}' -kubectl wait --timeout=30s --for=jsonpath='{.status.loadBalancer.ingress}' service/${MY_SERVICE} -lbip=$(kubectl get svc ${MY_SERVICE} -o=jsonpath='{.status.loadBalancer.ingress[0].ip}') -echo $lbip -``` - -:::info[Subject alternative names and LoadBalancer IP] - -By default, mesh certificates are issued with a wildcard DNS entry. The web frontend is accessed -via load balancer IP in this demo. Tools like curl check the certificate for IP entries in the SAN field. -Validation fails since the certificate contains no IP entries as a subject alternative name (SAN). -For example, a connection attempt using the curl and the mesh CA certificate with throw the following error: - -```sh -$ curl --cacert ./verify/mesh-ca.pem "https://${frontendIP}:443" -curl: (60) SSL: no alternative certificate subject name matches target host name '203.0.113.34' -``` - -::: - -Using `openssl`, the certificate of the service can be validated with the `mesh-ca.pem`: - -```sh -openssl s_client -CAfile verify/mesh-ca.pem -verify_return_error -connect ${frontendIP}:443 < /dev/null -``` diff --git a/docs/versioned_docs/version-0.6/examples/emojivoto.md b/docs/versioned_docs/version-0.6/examples/emojivoto.md deleted file mode 100644 index 46ce268908..0000000000 --- a/docs/versioned_docs/version-0.6/examples/emojivoto.md +++ /dev/null @@ -1,243 +0,0 @@ -# Confidential emoji voting - - -![screenshot of the emojivoto UI](../_media/emoijvoto.png) - -**This tutorial guides you through deploying [emojivoto](https://github.com/BuoyantIO/emojivoto) as a -confidential Contrast deployment and validating the deployment from a voters perspective.** - -Emojivoto is an example app allowing users to vote for different emojis and view votes -on a leader board. It has a microservice architecture consisting of a -web frontend (`web`), a gRPC backend for listing available emojis (`emoji`), and a backend for -the voting and leader board logic (`voting`). The `vote-bot` simulates user traffic by submitting -votes to the frontend. - - -![emojivoto components topology](https://raw.githubusercontent.com/BuoyantIO/emojivoto/e490d5789086e75933a474b22f9723fbfa0b29ba/assets/emojivoto-topology.png) - -### Motivation - -Using a voting service, users' votes are considered highly sensitive data, as we require -a secret ballot. Also, users are likely interested in the fairness of the ballot. For -both requirements, we can use Confidential Computing and, specifically, workload attestation -to prove to those interested in voting that the app is running in a protected environment -where their votes are processed without leaking to the platform provider or workload owner. - -## Prerequisites - -- **Installed Contrast CLI.** - See the [installation instructions](./../getting-started/install.md) on how to get it. -- **Running cluster with Confidential Containers support.** - Please follow the [cluster setup instructions](./../getting-started/cluster-setup.md) - to create a cluster. - -## Steps to deploy emojivoto with Contrast - -### Downloading the deployment - -The emojivoto deployment files are part of a zip file in the Contrast release. You can download the -latest deployment by running: - -```sh -curl -fLO https://github.com/edgelesssys/contrast/releases/latest/download/emojivoto-demo.zip -``` - -After that, unzip the `emojivoto-demo.zip` file to extract the `deployment/` directory. - -```sh -unzip emojivoto-demo.zip -``` - -### Deploy the Contrast runtime - -Contrast depends on a [custom Kubernetes `RuntimeClass` (`contrast-cc`)](../components/runtime.md), -which needs to be installed in the cluster prior to the Coordinator or any confidential workloads. -This consists of a `RuntimeClass` resource and a `DaemonSet` that performs installation on worker nodes. -This step is only required once for each version of the runtime. -It can be shared between Contrast deployments. - -```sh -kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/download/runtime.yml -``` - -### Deploy the Contrast Coordinator - -Deploy the Contrast Coordinator, comprising a single replica deployment and a -LoadBalancer service, into your cluster: - -```sh -kubectl apply -f https://github.com/edgelesssys/contrast/releases/latest/download/coordinator.yml -``` - -### Generate policy annotations and manifest - -Run the `generate` command to generate the execution policies and add them as -annotations to your deployment files. A `manifest.json` file with the reference values -of your deployment will be created: - -```sh -contrast generate deployment/ -``` - -:::note[Runtime class and Initializer] - -The deployment YAML shipped for this demo is already configured to be used with Contrast. -A [runtime class](https://docs.edgeless.systems/contrast/components/runtime) `contrast-cc-` -was added to the pods to signal they should be run as Confidential Containers. In addition, the Contrast -[Initializer](../components/index.md#the-initializer) was added as an init container to these workloads to -facilitate the attestation and certificate pulling before the actual workload is started. - -Further, the deployment YAML is also configured with the Contrast [service mesh](../components/service-mesh.md). -The configured service mesh proxy provides transparent protection for the communication between -the different components of emojivoto. - -::: - -### Set the manifest - -Configure the coordinator with a manifest. It might take up to a few minutes -for the load balancer to be created and the Coordinator being available. - -```sh -coordinator=$(kubectl get svc coordinator -o=jsonpath='{.status.loadBalancer.ingress[0].ip}') -echo "The user API of your Contrast Coordinator is available at $coordinator:1313" -contrast set -c "${coordinator}:1313" deployment/ -``` - -The CLI will use the embedded reference values to attest the Coordinator deployment -during the TLS handshake. If the connection succeeds, we're ensured that the Coordinator -deployment hasn't been tampered with. - -### Deploy emojivoto - -Now that the coordinator has a manifest set, which defines the emojivoto deployment as an allowed workload, -we can deploy the application: - -```sh -kubectl apply -f deployment/ -``` - -:::note[Inter-deployment communication] - -The Contrast Coordinator issues mesh certificates after successfully validating workloads. -These certificates can be used for secure inter-deployment communication. The Initializer -sends an attestation report to the Coordinator, retrieves certificates and a private key in return -and writes them to a `volumeMount`. The service mesh sidecar is configured to use the credentials -from the `volumeMount` when communicating with other parts of the deployment over mTLS. -The public facing frontend for voting uses the mesh certificate without client authentication. - -::: - -## Voter's perspective: Verifying the ballot - -As voters, we want to verify the fairness and confidentiality of the deployment before -deciding to vote. Regardless of the scale of our distributed deployment, Contrast only -needs a single remote attestation step to verify the deployment. By doing remote attestation -of the Coordinator, we transitively verify those systems the Coordinator has already attested -or will attest in the future. Successful verification of the Coordinator means that -we can be sure it will enforce the configured manifest. - -### Attest the Coordinator - -A potential voter can verify the Contrast deployment using the verify -command: - -```sh -contrast verify -c "${coordinator}:1313" -``` - -The CLI will attest the Coordinator using embedded reference values. If the command succeeds, -the Coordinator deployment was successfully verified to be running in the expected Confidential -Computing environment with the expected code version. The Coordinator will then return its -configuration over the established TLS channel. The CLI will store this information, namely the root -certificate of the mesh (`mesh-ca.pem`) and the history of manifests, into the `verify/` directory. -In addition, the policies referenced in the manifest history are also written into the same directory. - -### Manifest history and artifact audit - -In the next step, the Coordinator configuration that was written by the `verify` command needs to be audited. -A potential voter should inspect the manifest and the referenced policies. They could delegate -this task to an entity they trust. - -### Confidential connection to the attested workload - -After ensuring the configuration of the Coordinator fits the expectation, you can securely connect -to the workloads using the Coordinator's `mesh-ca.pem` as a trusted CA certificate. - -To access the web frontend, expose the service on a public IP address via a LoadBalancer service: - -```sh -frontendIP=$(kubectl get svc web-svc -o=jsonpath='{.status.loadBalancer.ingress[0].ip}') -echo "Frontend is available at https://$frontendIP, you can visit it in your browser." -``` - -Using `openssl`, the certificate of the service can be validated with the `mesh-ca.pem`: - -```sh -openssl s_client -CAfile verify/mesh-ca.pem -verify_return_error -connect ${frontendIP}:443 < /dev/null -``` - -## Certificate SAN and manifest update (optional) - -By default, mesh certificates are issued with a wildcard DNS entry. The web frontend is accessed -via load balancer IP in this demo. Tools like curl check the certificate for IP entries in the SAN field. -Validation fails since the certificate contains no IP entries as a subject alternative name (SAN). -For example, a connection attempt using the curl and the mesh CA certificate with throw the following error: - -```sh -$ curl --cacert ./verify/mesh-ca.pem "https://${frontendIP}:443" -curl: (60) SSL: no alternative certificate subject name matches target host name '203.0.113.34' -``` - -### Configure the service SAN in the manifest - -The `Policies` section of the manifest maps policy hashes to a list of SANs. To enable certificate verification -of the web frontend with tools like curl, edit the policy with your favorite editor and add the `frontendIP` to -the list that already contains the `"web"` DNS entry: - -```diff - "Policies": { - ... - "99dd77cbd7fe2c4e1f29511014c14054a21a376f7d58a48d50e9e036f4522f6b": [ - "web", -- "*" -+ "*", -+ "203.0.113.34" - ], -``` - -### Update the manifest - -Next, set the changed manifest at the coordinator with: - -```sh -contrast set -c "${coordinator}:1313" deployment/ -``` - -The Contrast Coordinator will rotate the mesh ca certificate on the manifest update. Workload certificates issued -after the manifest are thus issued by another certificate authority and services receiving the new CA certificate chain -won't trust parts of the deployment that got their certificate issued before the update. This way, Contrast ensures -that parts of the deployment that received a security update won't be infected by parts of the deployment at an older -patch level that may have been compromised. The `mesh-ca.pem` is updated with the new CA certificate chain. - -### Rolling out the update - -The Coordinator has the new manifest set, but the different containers of the app are still -using the older certificate authority. The Contrast Initializer terminates after the initial attestation -flow and won't pull new certificates on manifest updates. - -To roll out the update, use: - -```sh -kubectl rollout restart deployment/emoji -kubectl rollout restart deployment/vote-bot -kubectl rollout restart deployment/voting -kubectl rollout restart deployment/web -``` - -After the update has been rolled out, connecting to the frontend using curl will successfully validate -the service certificate and return the HTML document of the voting site: - -```sh -curl --cacert ./mesh-ca.pem "https://${frontendIP}:443" -``` diff --git a/docs/versioned_docs/version-0.6/examples/index.md b/docs/versioned_docs/version-0.6/examples/index.md deleted file mode 100644 index 252c82c820..0000000000 --- a/docs/versioned_docs/version-0.6/examples/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# Examples - -import DocCardList from '@theme/DocCardList'; - - diff --git a/docs/versioned_docs/version-0.6/getting-started/cluster-setup.md b/docs/versioned_docs/version-0.6/getting-started/cluster-setup.md deleted file mode 100644 index ea238261fb..0000000000 --- a/docs/versioned_docs/version-0.6/getting-started/cluster-setup.md +++ /dev/null @@ -1,157 +0,0 @@ -# Create a cluster - -## Prerequisites - -Install the latest version of the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/). - -[Login to your account](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli), which needs -to have the permissions to create an AKS cluster, by executing: - -```bash -az login -``` - -## Prepare using the AKS preview - -CoCo on AKS is currently in preview. An extension for the `az` CLI is needed to create such a cluster. -Add the extension with the following commands: - -```bash -az extension add \ - --name aks-preview \ - --allow-preview true -az extension update \ - --name aks-preview \ - --allow-preview true -``` - -Then register the required feature flags in your subscription to allow access to the public preview: - -```bash -az feature register \ - --namespace "Microsoft.ContainerService" \ - --name "KataCcIsolationPreview" -``` - -The registration can take a few minutes. The status of the operation can be checked with the following -command, which should show the registration state as `Registered`: - -```sh -az feature show \ - --namespace "Microsoft.ContainerService" \ - --name "KataCcIsolationPreview" \ - --output table -``` - -Afterward, refresh the registration of the ContainerService provider: - -```sh -az provider register \ - --namespace "Microsoft.ContainerService" -``` - -## Create resource group - -The AKS with CoCo preview is currently available in the following locations: - -``` -CentralIndia -eastus -EastUS2EUAP -GermanyWestCentral -japaneast -northeurope -SwitzerlandNorth -UAENorth -westeurope -westus -``` - -Set the name of the resource group you want to use: - -```bash -azResourceGroup="ContrastDemo" -``` - -You can either use an existing one or create a new resource group with the following command: - -```bash -azLocation="westus" # Select a location from the list above - -az group create \ - --name "${azResourceGroup:?}" \ - --location "${azLocation:?}" -``` - -## Create AKS cluster - -First create an AKS cluster: - -```sh -# Select the name for your AKS cluster -azClusterName="ContrastDemo" - -az aks create \ - --resource-group "${azResourceGroup:?}" \ - --name "${azClusterName:?}" \ - --kubernetes-version 1.29 \ - --os-sku AzureLinux \ - --node-vm-size Standard_DC4as_cc_v5 \ - --node-count 1 \ - --generate-ssh-keys -``` - -We then add a second node pool with CoCo support: - -```bash -az aks nodepool add \ - --resource-group "${azResourceGroup:?}" \ - --name nodepool2 \ - --cluster-name "${azClusterName:?}" \ - --node-count 1 \ - --os-sku AzureLinux \ - --node-vm-size Standard_DC4as_cc_v5 \ - --workload-runtime KataCcIsolation -``` - -Finally, update your kubeconfig with the credentials to access the cluster: - -```bash -az aks get-credentials \ - --resource-group "${azResourceGroup:?}" \ - --name "${azClusterName:?}" -``` - -For validation, list the available nodes using kubectl: - -```bash -kubectl get nodes -``` - -It should show two nodes: - -```bash -NAME STATUS ROLES AGE VERSION -aks-nodepool1-32049705-vmss000000 Ready 9m47s v1.29.0 -aks-nodepool2-32238657-vmss000000 Ready 45s v1.29.0 -``` - -## Cleanup - -After trying out Contrast, you might want to clean up the cloud resources created in this step. -In case you've created a new resource group, you can just delete that group with - -```sh -az group delete \ - --name "${azResourceGroup:?}" -``` - -Deleting the resource group will also delete the cluster and all other related resources. - -To only cleanup the AKS cluster and node pools, run - -```sh -az aks delete \ - --resource-group "${azResourceGroup:?}" \ - --name "${azClusterName:?}" -``` diff --git a/docs/versioned_docs/version-0.6/getting-started/index.md b/docs/versioned_docs/version-0.6/getting-started/index.md deleted file mode 100644 index 71e5bd4233..0000000000 --- a/docs/versioned_docs/version-0.6/getting-started/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# Getting started - -import DocCardList from '@theme/DocCardList'; - - diff --git a/docs/versioned_docs/version-0.6/getting-started/install.md b/docs/versioned_docs/version-0.6/getting-started/install.md deleted file mode 100644 index 43aeb46d32..0000000000 --- a/docs/versioned_docs/version-0.6/getting-started/install.md +++ /dev/null @@ -1,13 +0,0 @@ -# Installation - -Download the Contrast CLI from the latest release: - -```bash -curl --proto '=https' --tlsv1.2 -fLo contrast https://github.com/edgelesssys/contrast/releases/latest/download/contrast -``` - -After that, install the Contrast CLI in your PATH, e.g.: - -```bash -sudo install contrast /usr/local/bin/contrast -``` diff --git a/docs/versioned_docs/version-0.6/intro.md b/docs/versioned_docs/version-0.6/intro.md deleted file mode 100644 index 31ae9696ef..0000000000 --- a/docs/versioned_docs/version-0.6/intro.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -slug: / -id: intro ---- - -# Contrast - -Welcome to the documentation of Contrast! Contrast runs confidential container deployments on Kubernetes at scale. - -Contrast is based on the [Kata Containers](https://github.com/kata-containers/kata-containers) and -[Confidential Containers](https://github.com/confidential-containers) projects. -Confidential Containers are Kubernetes pods that are executed inside a confidential micro-VM and provide strong hardware-based isolation from the surrounding environment. -This works with unmodified containers in a lift-and-shift approach. -Contrast currently targets the [CoCo preview on AKS](https://learn.microsoft.com/en-us/azure/confidential-computing/confidential-containers-on-aks-preview). - -:::tip -See the 📄[whitepaper](https://content.edgeless.systems/hubfs/Confidential%20Computing%20Whitepaper.pdf) for more information on confidential computing. -::: - -## Goal - -Contrast is designed to keep all data always encrypted and to prevent access from the infrastructure layer. It removes the infrastructure provider from the trusted computing base (TCB). This includes access from datacenter employees, privileged cloud admins, own cluster administrators, and attackers coming through the infrastructure, for example, malicious co-tenants escalating their privileges. - -Contrast integrates fluently with the existing Kubernetes workflows. It's compatible with managed Kubernetes, can be installed as a day-2 operation and imposes only minimal changes to your deployment flow. - -## Use Cases - -Contrast provides unique security [features](basics/features.md) and [benefits](basics/security-benefits.md). The core use cases are: - -* Increasing the security of your containers -* Moving sensitive workloads from on-prem to the cloud with Confidential Computing -* Shielding the code and data even from the own cluster administrators -* Increasing the trustworthiness of your SaaS offerings -* Simplifying regulatory compliance -* Multi-party computation for data collaboration - -## Next steps - -You can learn more about the concept of [Confidential Containers](basics/confidential-containers.md), [features](basics/features.md), and [security benefits](basics/security-benefits.md) of Contrast in this section. To jump right into the action head to [*Getting started*](getting-started/index.md). diff --git a/docs/versioned_docs/version-0.6/known-limitations.md b/docs/versioned_docs/version-0.6/known-limitations.md deleted file mode 100644 index 27cf2a1664..0000000000 --- a/docs/versioned_docs/version-0.6/known-limitations.md +++ /dev/null @@ -1,29 +0,0 @@ -# Known Limitations - -As Contrast is currently in an early development stage, it's built on several projects that are also under active development. -This section outlines the most significant known limitations, providing stakeholders with clear expectations and understanding of the current state. - -## Availability - -- **Platform Support**: At present, Contrast is exclusively available on Azure AKS, supported by the [Confidential Container preview for AKS](https://learn.microsoft.com/en-us/azure/confidential-computing/confidential-containers-on-aks-preview). Expansion to other cloud platforms is planned, pending the availability of necessary infrastructure enhancements. - -## Kubernetes Features - -- **Persistent Volumes**: Not currently supported within Confidential Containers. -- **Port-Forwarding**: This feature [isn't yet supported by Kata Containers](https://github.com/kata-containers/kata-containers/issues/1693). You can [deploy a port-forwarder](https://docs.edgeless.systems/contrast/deployment#connect-to-the-contrast-coordinator) as a workaround. -- **Resource Limits**: There is an existing bug on AKS where container memory limits are incorrectly applied. The current workaround involves using only memory requests instead of limits. - -## Runtime Policies - -- **Coverage**: While the enforcement of workload policies generally functions well, [there are scenarios not yet fully covered](https://github.com/microsoft/kata-containers/releases/tag/3.2.0.azl0.genpolicy). It's crucial to review deployments specifically for these edge cases. -- **Order of events**: The current policy evaluation mechanism on API requests isn't stateful, so it can't ensure a prescribed order of events. Consequently, there's no guaranteed enforcement that the [service mesh sidecar](components/service-mesh.md) container runs *before* the workload container. This order ensures that all traffic between pods is securely encapsulated within TLS connections. -- **Absence of events**: Policies can't ensure certain events have happened. A container, such as the [service mesh sidecar](components/service-mesh.md), can be omitted entirely. Environment variables may be missing. -- **Volume integrity checks**: While persistent volumes aren't supported yet, integrity checks don't currently cover other objects such as `ConfigMaps` and `Secrets`. - -:::warning -The policy limitations, in particular the missing guarantee that our service mesh sidecar has been started before the workload container affects the service mesh implementation of Contrast. Currently, this requires inspecting the iptables rules on startup or terminating TLS connections in the workload directly. -::: - -## Tooling Integration - -- **CLI Availability**: The CLI tool is currently only available for Linux. This limitation arises because certain upstream dependencies haven't yet been ported to other platforms. diff --git a/docs/versioned_docs/version-0.7/_media/attestation-composite-device.svg b/docs/versioned_docs/version-0.7/_media/attestation-composite-device.svg deleted file mode 100644 index f76b674710..0000000000 --- a/docs/versioned_docs/version-0.7/_media/attestation-composite-device.svg +++ /dev/null @@ -1,1127 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/versioned_docs/version-0.7/_media/attestation-composite-device.txt b/docs/versioned_docs/version-0.7/_media/attestation-composite-device.txt deleted file mode 100644 index 7fae1031d2..0000000000 --- a/docs/versioned_docs/version-0.7/_media/attestation-composite-device.txt +++ /dev/null @@ -1,24 +0,0 @@ - .-----------------------------. - | Verifier | - '-----------------------------' - ^ - | - | Evidence of - | Composite Device - | - .----------------------------------|-------------------------------. - | .--------------------------------|-----. .------------. | - | | Collect .---------+--. | | | | - | | Claims .--------->| Attesting |<--------+ Pod A +-. | - | | | |Environment | | '-+----------' | | - | | .--------+-------. | |<----------+ Pod B +-. | - | | | Runtime Target | | | | '-+----------' | | - | | | Environment | | |<------------+ ... | | - | | | | '------------' | Evidence '------------' | - | | '----------------' | of | - | | | Pods | - | | Coordinator | (via Pod network) | - | '--------------------------------------' | - | | - | Composite Device | - '------------------------------------------------------------------' diff --git a/docs/versioned_docs/version-0.7/_media/attestation-pod.svg b/docs/versioned_docs/version-0.7/_media/attestation-pod.svg deleted file mode 100644 index 4149941117..0000000000 --- a/docs/versioned_docs/version-0.7/_media/attestation-pod.svg +++ /dev/null @@ -1,1737 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/versioned_docs/version-0.7/_media/attestation-pod.txt b/docs/versioned_docs/version-0.7/_media/attestation-pod.txt deleted file mode 100644 index 10a7c6135e..0000000000 --- a/docs/versioned_docs/version-0.7/_media/attestation-pod.txt +++ /dev/null @@ -1,43 +0,0 @@ - .-------------. - | CPU | Endorsement for CPU - | Vendor +-----------------------. - '-------------' | - v - .-------------. Reference .-------------. - | CLI + | Values for | | - | Edgeless +----------------->| Coordinator | - | Systems | Runtime Env and | | - '-------------' Runtime Policy '-------------' - ^ - .------------------------------------. | - | | | - | | | - | .---------------------------. | | Evidence for - | | Guest Agent(C) | | | Runtime Environment - | | | | | and - | | Target | | | Runtime Policy - | | Environment | | | - | | | | | - | | | | | - | | | | | - | '-----------+-------+-------' | | - | Part of | | Evidence | | - | v | for | | - | .-----------------. | Runtime | | - | | Runtime Env(B) | | Policy | | - | | | | | | - | | Target | | | | - | | Environment | | | | - | | ^ | | | | - | '-----------|-----' | | | - | Measure | | | | - | | | | | - | | | | | - | .-----------+-------|-------. | | - | | CPU(A): AMD SEV, v | | | - | | Intel TDX | | | - | | Attesting | | | - | | Environment +---------' - | '---------------------------' | - | | - '------------------------------------' diff --git a/docs/versioned_docs/version-0.7/_media/attestation-rats-architecture.svg b/docs/versioned_docs/version-0.7/_media/attestation-rats-architecture.svg deleted file mode 100644 index 7e291b4696..0000000000 --- a/docs/versioned_docs/version-0.7/_media/attestation-rats-architecture.svg +++ /dev/null @@ -1,1417 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/versioned_docs/version-0.7/_media/attestation-rats-architecture.txt b/docs/versioned_docs/version-0.7/_media/attestation-rats-architecture.txt deleted file mode 100644 index f0d1a68491..0000000000 --- a/docs/versioned_docs/version-0.7/_media/attestation-rats-architecture.txt +++ /dev/null @@ -1,23 +0,0 @@ - .--------. .---------. .--------. .-------------. - | Endorser | | Reference | | Verifier | | Relying Party | - '-+------' | Value | | Owner | | Owner | - | | Provider | '---+----' '----+--------' - | '-----+---' | | - | | | | - | Endorsements | Reference | Appraisal | Appraisal - | | Values | Policy for | Policy for - | | | Evidence | Attestation - '-----------. | | | Results - | | | | - v v v | - .-------------------------. | - .------>| Verifier +-----. | - | '-------------------------' | | - | | | - | Evidence Attestation | | - | Results | | - | | | - | v v - .-----+----. .---------------. - | Attester | | Relying Party | - '----------' '---------------' diff --git a/docs/versioned_docs/version-0.7/_media/components.svg b/docs/versioned_docs/version-0.7/_media/components.svg deleted file mode 100644 index bd65c768ef..0000000000 --- a/docs/versioned_docs/version-0.7/_media/components.svg +++ /dev/null @@ -1,766 +0,0 @@ - - diff --git a/docs/versioned_docs/version-0.7/_media/contrast_pki.drawio.svg b/docs/versioned_docs/version-0.7/_media/contrast_pki.drawio.svg deleted file mode 100644 index 386d2215c2..0000000000 --- a/docs/versioned_docs/version-0.7/_media/contrast_pki.drawio.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - -
Root CA








Root CA Certificate
Root CA
Private Key
Intermediate CA








Intermediate CA
Certificate
Intermediate CA
Private Key
Mesh CA
Certificate
Mesh








Mesh Certificate
Mesh Private Key
signs
signs
signs
signs
 diff --git a/docs/versioned_docs/version-0.7/_media/emoijvoto.png b/docs/versioned_docs/version-0.7/_media/emoijvoto.png deleted file mode 100644 index 9779306e04..0000000000 Binary files a/docs/versioned_docs/version-0.7/_media/emoijvoto.png and /dev/null differ diff --git a/docs/versioned_docs/version-0.7/_media/personas.svg b/docs/versioned_docs/version-0.7/_media/personas.svg deleted file mode 100644 index c14341047f..0000000000 --- a/docs/versioned_docs/version-0.7/_media/personas.svg +++ /dev/null @@ -1,568 +0,0 @@ - - diff --git a/docs/versioned_docs/version-0.7/_media/runtime.svg b/docs/versioned_docs/version-0.7/_media/runtime.svg deleted file mode 100644 index b13d79e3ae..0000000000 --- a/docs/versioned_docs/version-0.7/_media/runtime.svg +++ /dev/null @@ -1,1376 +0,0 @@ - - diff --git a/docs/versioned_docs/version-0.7/_media/tcb.svg b/docs/versioned_docs/version-0.7/_media/tcb.svg deleted file mode 100644 index b20ac5284c..0000000000 --- a/docs/versioned_docs/version-0.7/_media/tcb.svg +++ /dev/null @@ -1,547 +0,0 @@ - - diff --git a/docs/versioned_docs/version-0.7/about/index.md b/docs/versioned_docs/version-0.7/about/index.md deleted file mode 100644 index 92b6b7d53b..0000000000 --- a/docs/versioned_docs/version-0.7/about/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# About - -import DocCardList from '@theme/DocCardList'; - - diff --git a/docs/versioned_docs/version-0.7/about/telemetry.md b/docs/versioned_docs/version-0.7/about/telemetry.md deleted file mode 100644 index 074754c78e..0000000000 --- a/docs/versioned_docs/version-0.7/about/telemetry.md +++ /dev/null @@ -1,20 +0,0 @@ -# CLI telemetry - -The Contrast CLI sends telemetry data to Edgeless Systems when you use CLI commands. -This allows to understand how Contrast is used and to improve it. - -The CLI sends the following data: - -* The CLI version -* The CLI target OS and architecture (GOOS and GOARCH) -* The command that was run -* The kind of error that occurred (if any) - -The CLI *doesn't* collect sensitive information. -The implementation is open-source and can be reviewed. - -IP addresses may be processed or stored for security purposes. - -The data that the CLI collects adheres to the Edgeless Systems [privacy policy](https://www.edgeless.systems/privacy). - -You can disable telemetry by setting the environment variable `DO_NOT_TRACK=1` before running the CLI. diff --git a/docs/versioned_docs/version-0.7/architecture/attestation.md b/docs/versioned_docs/version-0.7/architecture/attestation.md deleted file mode 100644 index 35564aad28..0000000000 --- a/docs/versioned_docs/version-0.7/architecture/attestation.md +++ /dev/null @@ -1,119 +0,0 @@ -# Attestation in Contrast - -This document describes the attestation architecture of Contrast, adhering to the definitions of Remote ATtestation procedureS (RATS) in [RFC 9334](https://www.rfc-editor.org/rfc/rfc9334.html). -The following gives a detailed description of Contrast's attestation architecture. -At the end of this document, we included an [FAQ](#frequently-asked-questions-about-attestation-in-contrast) that answers the most common questions regarding attestation in hindsight of the [security benefits](../basics/security-benefits.md). - -## Attestation architecture - -Contrast integrates with the RATS architecture, leveraging their definition of roles and processes including *Attesters*, *Verifiers*, and *Relying Parties*. - -![Conceptual attestation architecture](../_media/attestation-rats-architecture.svg) - -Figure 1: Conceptual attestation architecture. Taken from [RFC 9334](https://www.rfc-editor.org/rfc/rfc9334.html#figure-1). - -- **Attester**: Assigned to entities that are responsible for creating *Evidence* which is then sent to a *Verifier*. -- **Verifier**: These entities utilize the *Evidence*, *Reference Values*, and *Endorsements*. They assess the trustworthiness of the *Attester* by applying an *Appraisal Policy* for *Evidence*. Following this assessment, *Verifiers* generate *Attestation Results* for use by *Relying Parties*. The *Appraisal Policy* for *Evidence* may be provided by the *Verifier Owner*, programmed into the *Verifier*, or acquired through other means. -- **Relying Party**: Assigned to entities that utilize *Attestation Results*, applying their own appraisal policies to make specific decisions, such as authorization decisions. This process is referred to as the "appraisal of Attestation Results." The *Appraisal Policy* for *Attestation Results* might be sourced from the *Relying Party Owner*, configured by the owner, embedded in the *Relying Party*, or obtained through other protocols or mechanisms. - -## Components of Contrast's attestation - -The key components involved in the attestation process of Contrast are detailed below: - -### Attester: Application Pods - -This includes all Pods of the Contrast deployment that run inside Confidential Containers and generate cryptographic evidence reflecting their current configuration and state. -Their evidence is rooted in the [hardware measurements](../basics/confidential-containers.md) from the CPU and their [confidential VM environment](../components/runtime.md). -The details of this evidence are given below in the section on [evidence generation and appraisal](#evidence-generation-and-appraisal). - -![Attestation flow of a confidential pod](../_media/attestation-pod.svg) - -Figure 2: Attestation flow of a confidential pod. Based on the layered attester graphic in [RFC 9334](https://www.rfc-editor.org/rfc/rfc9334.html#figure-3). - -Pods run in Contrast's [runtime environment](../components/runtime.md) (B), effectively within a confidential VM. -During launch, the CPU (A) measures the initial memory content of the confidential VM that contains Contrast's pod-VM image and generates the corresponding attestation evidence. -The image is in [IGVM format](https://github.com/microsoft/igvm), encapsulating all information required to launch a virtual machine, including the kernel, the initramfs, and kernel cmdline. -The kernel cmdline contains the root hash for [dm-verity](https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/verity.html) that ensures the integrity of the root filesystem. -The root filesystem contains all components of the container's runtime environment including the [guest agent](../basics/confidential-containers.md#kata-containers) (C). - -In the userland, the guest agent takes care of enforcing the [runtime policy](../components/index.md#runtime-policies) of the pod. -While the policy is passed in during the initialization procedure via the host, the evidence for the runtime policy is part of the CPU measurements. -During the [deployment](../deployment.md#generate-policy-annotations-and-manifest) the policy is annotated to the Kubernetes Pod resources. -On AMD SEV-SNP the hash of the policy is then added to the attestation report via the `HOSTDATA` field by the hypervisor. -When provided with the policy from the Kata host, the guest agent verifies that the policy's hash matches the one in the `HOSTDATA` field. - -In summary a Pod's evidence is the attestation report of the CPU that provides evidence for runtime environment and the runtime policy. - -### Verifier: Coordinator and CLI - -The [Coordinator](../components/index.md#the-coordinator) acts as a verifier within the Contrast deployment, configured with a [Manifest](../components/index.md#the-manifest) that defines the reference values and serves as an appraisal policy for all pods in the deployment. -It also pulls endorsements from hardware vendors to verify the hardware claims. -The Coordinator operates within the cluster as a confidential container and provides similar evidence as any other Pod when it acts as an attester. -In RATS terminology, the Coordinator's dual role is defined as a lead attester in a composite device which spans the entire deployment: Coordinator and the workload pods. -It collects evidence from other attesters and conveys it to a verifier, generating evidence about the layout of the whole composite device based on the Manifest as the appraisal policy. - -![Deployment attestation as a composite device](../_media/attestation-composite-device.svg) - -Figure 3: Contrast deployment as a composite device. Based on the composite device in [RFC 9334](https://www.rfc-editor.org/rfc/rfc9334.html#figure-4). - -The [CLI](../components/index.md#the-cli-command-line-interface) serves as the verifier for the Coordinator and the entire Contrast deployment, containing the reference values for the Coordinator and the endorsements from hardware vendors. -These reference values are built into the CLI during our release process and can be reproduced offline via reproducible builds. - -### Relying Party: Data owner - -A relying party in the Contrast scenario could be, for example, the [data owner](../basics/security-benefits.md) that interacts with the application. -The relying party can use the CLI to obtain the attestation results and Contrast's [CA certificates](certificates.md) bound to these results. -The CA certificates can then be used by the relying party to authenticate the application, for example through TLS connections. - -## Evidence generation and appraisal - -### Evidence types and formats - -In Contrast, attestation evidence revolves around a hardware-generated attestation report, which contains several critical pieces of information: - -- **The hardware attestation report**: This report includes details such as the chip identifier, platform information, microcode versions, and comprehensive guest measurements. The entire report is signed by the CPU's private key, ensuring the authenticity and integrity of the data provided. -- **The launch measurements**: Included within the hardware attestation report, this is a digest generated by the CPU that represents a hash of all initial guest memory pages. This includes essential components like the kernel, initramfs, and the kernel command line. Notably, it incorporates the root filesystem's dm-verity root hash, verifying the integrity of the root filesystem. -- **The runtime policy hash**: Also part of the hardware attestation report, this field contains the hash of the Rego policy which dictates all expected API commands and their values from the host to the Kata guest agent. It encompasses crucial settings such as dm-verity hashes for the container image layers, environment variables, and mount points. - -### Appraisal policies for evidence - -The appraisal of this evidence in Contrast is governed by two main components: - -- **The Manifest**: A JSON file used by the Coordinator to align with reference values. It sets the expectations for runtime policy hashes for each pod and includes what should be reported in the hardware attestation report for each component of the deployment. -- **The CLI's appraisal policy**: This policy encompasses expected values of the Coordinator’s guest measurements and its runtime policy. It's embedded into the CLI during the build process and ensures that any discrepancy between the built-in values and those reported by the hardware attestation can be identified and addressed. The integrity of this policy is safeguardable through reproducible builds, allowing verification against the source code reference. - -## Frequently asked questions about attestation in Contrast - -### What's the purpose of remote attestation in Contrast? - -Remote attestation in Contrast ensures that software runs within a secure, isolated confidential computing environment. -This process certifies that the memory is encrypted and confirms the integrity and authenticity of the software running within the deployment. -By validating the runtime environment and the policies enforced on it, Contrast ensures that the system operates in a trustworthy state and hasn't been tampered with. - -### How does Contrast ensure the security of the attestation process? - -Contrast leverages hardware-rooted security features such as AMD SEV-SNP to generate cryptographic evidence of a pod’s current state and configuration. -This evidence is checked against pre-defined appraisal policies to guarantee that only verified and authorized pods are part of a Contrast deployment. - -### What security benefits does attestation provide? - -Attestation confirms the integrity of the runtime environment and the identity of the workloads. -It plays a critical role in preventing unauthorized changes and detecting potential modifications at runtime. -The attestation provides integrity and authenticity guarantees, enabling relying parties—such as workload operators or data owners—to confirm the effective protection against potential threats, including malicious cloud insiders, co-tenants, or compromised workload operators. -More details on the specific security benefits can be found [here](../basics/security-benefits.md). - -### How can you verify the authenticity of attestation results? - -Attestation results in Contrast are tied to cryptographic proofs generated and signed by the hardware itself. -These proofs are then verified using public keys from trusted hardware vendors, ensuring that the results aren't only accurate but also resistant to tampering. -For further authenticity verification, all of Contrast's code is reproducibly built, and the attestation evidence can be verified locally from the source code. - -### How are attestation results used by relying parties? - -Relying parties use attestation results to make informed security decisions, such as allowing access to sensitive data or resources only if the attestation verifies the system's integrity. -Thereafter, the use of Contrast's [CA certificates in TLS connections](certificates.md) provides a practical approach to communicate securely with the application. - -## Summary - -In summary, Contrast's attestation strategy adheres to the RATS guidelines and consists of robust verification mechanisms that ensure each component of the deployment is secure and trustworthy. -This comprehensive approach allows Contrast to provide a high level of security assurance to its users. diff --git a/docs/versioned_docs/version-0.7/architecture/certificates.md b/docs/versioned_docs/version-0.7/architecture/certificates.md deleted file mode 100644 index d6c2b8ef73..0000000000 --- a/docs/versioned_docs/version-0.7/architecture/certificates.md +++ /dev/null @@ -1,70 +0,0 @@ -# Certificate authority - -The Coordinator acts as a certificate authority (CA) for the workloads -defined in the manifest. -After a workload pod's attestation has been verified by the Coordinator, -it receives a mesh certificate and the mesh CA certificate. -The mesh certificate can be used for example in a TLS connection as the server or -client certificate to proof to the other party that the workload has been -verified by the Coordinator. The other party can verify the mesh certificate -with the mesh CA certificate. While the certificates can be used by the workload -developer in different ways, they're automatically used in Contrast's service -mesh to establish mTLS connections between workloads in the same deployment. - -## Public key infrastructure - -The Coordinator establishes a public key infrastructure (PKI) for all workloads -contained in the manifest. The Coordinator holds three certificates: the root CA -certificate, the intermediate CA certificate, and the mesh CA certificate. -The root CA certificate is a long-lasting certificate and its private key signs -the intermediate CA certificate. The intermediate CA certificate and the mesh CA -certificate share the same private key. This intermediate private key is used -to sign the mesh certificates. Moreover, the intermediate private key and -therefore the intermediate CA certificate and the mesh CA certificate are -rotated when setting a new manifest. - -![PKI certificate chain](../_media/contrast_pki.drawio.svg) - -## Certificate rotation - -Depending on the configuration of the first manifest, it allows the workload -owner to update the manifest and, therefore, the deployment. -Workload owners and data owners can be mutually untrusted parties. -To protect against the workload owner silently introducing malicious containers, -the Coordinator rotates the intermediate private key every time the manifest is -updated and, therefore, the -intermediate CA certificate and mesh CA certificate. If the user doesn't -trust the workload owner, they use the mesh CA certificate obtained when they -verified the Coordinator and the manifest. This ensures that the user only -connects to workloads defined in the manifest they verified since only those -workloads' certificates are signed with this intermediate private key. - -Similarly, the service mesh also uses the mesh CA certificate obtained when the -workload was started, so the workload only trusts endpoints that have been -verified by the Coordinator based on the same manifest. Consequently, a -manifest update requires a fresh rollout of the services in the service mesh. - -## Usage of the different certificates - -- The **root CA certificate** is returned when verifying the Coordinator. -The data owner can use it to verify the mesh certificates of the workloads. -This should only be used if the data owner trusts all future updates to the -manifest and workloads. This is, for instance, the case when the workload owner is -the same entity as the data owner. -- The **mesh CA certificate** is returned when verifying the Coordinator. -The data owner can use it to verify the mesh certificates of the workloads. -This certificate is bound to the manifest set when the Coordinator is verified. -If the manifest is updated, the mesh CA certificate changes. -New workloads will receive mesh certificates signed by the _new_ mesh CA certificate. -The Coordinator with the new manifest needs to be verified to retrieve the new mesh CA certificate. -The service mesh also uses the mesh CA certificate to verify the mesh certificates. -- The **intermediate CA certificate** links the root CA certificate to the -mesh certificate so that the mesh certificate can be verified with the root CA -certificate. It's part of the certificate chain handed out by -endpoints in the service mesh. -- The **mesh certificate** is part of the certificate chain handed out by -endpoints in the service mesh. During the startup of a pod, the Initializer -requests a certificate from the Coordinator. This mesh certificate will be returned if the Coordinator successfully -verifies the workload. The mesh certificate -contains X.509 extensions with information from the workloads attestation -document. diff --git a/docs/versioned_docs/version-0.7/architecture/index.md b/docs/versioned_docs/version-0.7/architecture/index.md deleted file mode 100644 index d2bb21f55a..0000000000 --- a/docs/versioned_docs/version-0.7/architecture/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# Architecture - -import DocCardList from '@theme/DocCardList'; - - diff --git a/docs/versioned_docs/version-0.7/architecture/observability.md b/docs/versioned_docs/version-0.7/architecture/observability.md deleted file mode 100644 index c55ac24726..0000000000 --- a/docs/versioned_docs/version-0.7/architecture/observability.md +++ /dev/null @@ -1,55 +0,0 @@ -# Observability - -The Contrast Coordinator can expose metrics in the -[Prometheus](https://prometheus.io/) format. These can be monitored to quickly -identify problems in the gRPC layer or attestation errors. Prometheus metrics -are numerical values associated with a name and additional key/values pairs, -called labels. - -## Exposed metrics - -The metrics can be accessed at the Coordinator pod at the port specified in the -`CONTRAST_METRICS_PORT` environment variable under the `/metrics` endpoint. By -default, this environment variable isn't specified, hence no metrics will be -exposed. - -The Coordinator starts two gRPC servers, one for the user API on port `1313` and -one for the mesh API on port `7777`. Metrics for both servers can be accessed -using different prefixes. - -All metric names for the user API are prefixed with `contrast_userapi_grpc_server_`. -Exposed metrics include the number of handled requests of the methods -`SetManifest` and `GetManifest`, which get called when [setting the -manifest](../deployment#set-the-manifest) and [verifying the -Coordinator](../deployment#verify-the-coordinator) respectively. For each method -you can see the gRPC status code indicating whether the request succeeded or -not and the request latency. - -For the mesh API, the metric names are prefixed with `contrast_meshapi_grpc_server_`. The -metrics include similar data to the user API for the method `NewMeshCert` which -gets called by the [Initializer](../components#the-initializer) when starting a -new workload. Attestation failures from workloads to the Coordinator can be -tracked with the counter `contrast_meshapi_attestation_failures`. - -The current manifest generation is exposed as a -[gauge](https://prometheus.io/docs/concepts/metric_types/#gauge) with the metric -name `contrast_coordinator_manifest_generation`. If no manifest is set at the -Coordinator, this counter will be zero. - -## Service mesh metrics - -The [Service Mesh](../components/service-mesh.md) can be configured to expose -metrics via its [Envoy admin -interface](https://www.envoyproxy.io/docs/envoy/latest/operations/admin). Be -aware that the admin interface can expose private information and allows -destructive operations to be performed. To enable the admin interface for the -Service Mesh, set the annotation -`contrast.edgeless.systems/servicemesh-admin-interface-port` in the configuration -of your workload. If this annotation is set, the admin interface will be started -on this port. - -To access the admin interface, the ingress settings of the Service Mesh have to -be configured to allow access to the specified port (see [Configuring the -Proxy](../components/service-mesh#configuring-the-proxy)). All metrics will be -exposed under the `/stats` endpoint. Metrics in Prometheus format can be scraped -from the `/stats/prometheus` endpoint. diff --git a/docs/versioned_docs/version-0.7/basics/confidential-containers.md b/docs/versioned_docs/version-0.7/basics/confidential-containers.md deleted file mode 100644 index 6f3f48f5bb..0000000000 --- a/docs/versioned_docs/version-0.7/basics/confidential-containers.md +++ /dev/null @@ -1,32 +0,0 @@ -# Confidential Containers - -Contrast uses some building blocks from [Confidential Containers](https://confidentialcontainers.org) (CoCo), a [CNCF Sandbox project](https://www.cncf.io/projects/confidential-containers/) that aims to standardize confidential computing at the pod level. -The project is under active development and many of the high-level features are still in flux. -Contrast uses the more stable core primitive provided by CoCo: its Kubernetes runtime. - -## Kubernetes RuntimeClass - -Kubernetes can be extended to use more than one container runtime with [`RuntimeClass`](https://kubernetes.io/docs/concepts/containers/runtime-class/) objects. -The [Container Runtime Interface](https://kubernetes.io/docs/concepts/architecture/cri/) (CRI) implementation, for example containerd, dispatches pod management API calls to the appropriate `RuntimeClass`. -`RuntimeClass` implementations are usually based on an [OCI runtime](https://github.com/opencontainers/runtime-spec), such as `runc`, `runsc` or `crun`. -In CoCo's case, the runtime is Kata Containers with added confidential computing capabilities. - -## Kata Containers - -[Kata Containers](https://katacontainers.io/) is an OCI runtime that runs pods in VMs. -The pod VM spawns an agent process that accepts management commands from the Kata runtime running on the host. -There are two options for creating pod VMs: local to the Kubernetes node, or remote VMs created with cloud provider APIs. -Using local VMs requires either bare-metal servers or VMs with support for nested virtualization. -Local VMs communicate with the host over a virtual socket. -For remote VMs, host-to-agent communication is tunnelled through the cloud provider's network. - -Kata Containers was originally designed to isolate the guest from the host, but it can also run pods in confidential VMs (CVMs) to shield pods from their underlying infrastructure. -In confidential mode, the guest agent is configured with an [Open Policy Agent](https://www.openpolicyagent.org/) (OPA) policy to authorize API calls from the host. -This policy also contains checksums for the expected container images. -It's derived from Kubernetes resource definitions and its checksum is included in the attestation report. - -## AKS CoCo preview - -[Azure Kubernetes Service](https://learn.microsoft.com/en-us/azure/aks/) (AKS) provides CoCo-enabled node pools as a [preview offering](https://learn.microsoft.com/en-us/azure/aks/confidential-containers-overview). -These node pools leverage Azure VM types capable of nested virtualization (CVM-in-VM) and the CoCo stack is pre-installed. -Contrast can be deployed directly into a CoCo-enabled AKS cluster. diff --git a/docs/versioned_docs/version-0.7/basics/features.md b/docs/versioned_docs/version-0.7/basics/features.md deleted file mode 100644 index 1139ae0f0d..0000000000 --- a/docs/versioned_docs/version-0.7/basics/features.md +++ /dev/null @@ -1,15 +0,0 @@ -# Product features - -Contrast simplifies the deployment and management of Confidential Containers, offering optimal data security for your workloads while integrating seamlessly with your existing Kubernetes environment. - -From a security perspective, Contrast employs the [Confidential Containers](confidential-containers.md) concept and provides [security benefits](security-benefits.md) that go beyond individual containers, shielding your entire deployment from the underlying infrastructure. - -From an operational perspective, Contrast provides the following key features: - -* **Managed Kubernetes compatibility**: Initially compatible with Azure Kubernetes Service (AKS), Contrast is designed to support additional platforms such as AWS EKS and Google Cloud GKE as they begin to accommodate confidential containers. - -* **Lightweight installation**: Contrast can be integrated as a [day-2 operation](../deployment.md) within existing clusters, adding minimal [components](../architecture) to your setup. This facilitates straightforward deployments using your existing YAML configurations, Helm charts, or Kustomization, enabling native Kubernetes orchestration of your applications. - -* **Remote attestation**: Contrast generates a concise attestation statement that verifies the identity, authenticity, and integrity of your deployment both internally and to external parties. This architecture ensures that updates or scaling of the application don't compromise the attestation’s validity. - -* **Service mesh**: Contrast securely manages a Public Key Infrastructure (PKI) for your deployments, issues workload-specific certificates, and establishes transparent mutual TLS (mTLS) connections across pods. This is done by harnessing the [envoy proxy](https://www.envoyproxy.io/) to ensure secure communications within your Kubernetes cluster. diff --git a/docs/versioned_docs/version-0.7/basics/security-benefits.md b/docs/versioned_docs/version-0.7/basics/security-benefits.md deleted file mode 100644 index c56b23178f..0000000000 --- a/docs/versioned_docs/version-0.7/basics/security-benefits.md +++ /dev/null @@ -1,159 +0,0 @@ -# Contrast security overview - -This document outlines the security measures of Contrast and its capability to counter various threats. -Contrast is designed to shield entire Kubernetes deployments from the infrastructure, enabling entities to manage sensitive information (such as regulated or personally identifiable information (PII)) in the public cloud, while maintaining data confidentiality and ownership. - -Contrast is applicable in situations where establishing trust with the workload operator or the underlying infrastructure is challenging. -This is particularly beneficial for regulated sectors looking to transition sensitive activities to the cloud, without sacrificing security or compliance. -It allows for cloud adoption by maintaining a hardware-based separation from the cloud service provider. - -## Confidential computing foundation - -Leveraging Confidential Computing technology, Contrast provides three defining security properties: - -- **Encryption of data in use**: Contrast ensures that all data processed in memory is encrypted, making it inaccessible to unauthorized users or systems, even if they have physical access to the hardware. -- **Workload isolation**: Each pod runs in its isolated runtime environment, preventing any cross-contamination between workloads, which is critical for multi-tenant infrastructures. -- **Remote attestation**: This feature allows data owners and workload operators to verify that the Contrast environment executing their workloads hasn't been tampered with and is running in a secure, pre-approved configuration. - -The runtime encryption is transparently provided by the confidential computing hardware during the workload's lifetime. -The workload isolation and remote attestation involves two phases: - -* An attestation process detects modifications to the workload image or its runtime environment during the initialization. This protects the workload's integrity pre-attestation. -* A protected runtime environment and a policy mechanism prevents the platform operator from accessing or compromising the instance at runtime. This protects a workload's integrity and confidentiality post-attestation. - -For more details on confidential computing see our [whitepaper](https://content.edgeless.systems/hubfs/Confidential%20Computing%20Whitepaper.pdf). -The [attestation architecture](../architecture/attestation.md) describes Contrast's attestation process and the resulting chain of trust in detail. - -## Components of a Contrast deployment - -Contrast uses the Kubernetes runtime of the [Confidential Containers](confidential-containers.md) project. -Confidential Containers significantly decrease the size of the trusted computing base (TCB) of a Kubernetes deployment, by isolating each pod within its own confidential micro-VM environment. -The TCB is the totality of elements in a computing environment that must be trusted not to be compromised. -A smaller TCB results in a smaller attack surface. The following diagram shows how Confidential Containers remove the *cloud & datacenter infrastructure* and the *physical hosts*, including the hypervisor, the host OS, the Kubernetes control plane, and other components, from the TCB (red). -In the confidential context, depicted in green, only the workload containers along with their confidential micro-VM environment are included within the TCB. -Their integrity is [verifiable through remote attestation](../architecture/attestation.md). - -Contrast uses [hardware-based mechanisms](confidential-containers.md), specifically leveraging CPU features, such as AMD SEV or Intel TDX, to provide the isolation of the workload. -This implies that both the CPU and its microcode are integral components of the TCB. -However, it should be noted that the CPU microcode aspects aren't depicted in the accompanying graphic. - -![TCB comparison](../_media/tcb.svg) - -Contrast adds the following components to a deployment that become part of the TCB. -The components that are part of the TCB are: - -* **The workload containers**: Container images that run the actual application. -* **[The runtime environment](../components/runtime.md)**: The confidential micro-VM that acts as the container runtime. -* **[The sidecar containers](../components/service-mesh.md)**: Containers that provide additional functionality such as [initialization](../components/index.md#the-initializer) and [service mesh](../components/service-mesh.md). -* **[The runtime policies](../components/policies.md)**: Policies that enforce the runtime environments for the workload containers during their lifetime. -* **[The manifest](../components/index.md#the-manifest)**: A manifest file defining the reference values of an entire confidential deployment. It contains the policy hashes for all pods of the deployment and the expected hardware reference values for the Confidential Container runtime. -* **[The Coordinator](../components/index.md#the-coordinator)**: An attestation service that runs in a Confidential Container in the Kubernetes cluster. The Coordinator is configured with the manifest. User-facing, you can verify this service and the effective manifest using remote attestation, providing you with a concise attestation for the entire deployment. Cluster-facing, it verifies all pods and their policies based on remote attestation procedures and the manifest. - -## Personas in a Contrast deployment - -In a Contrast deployment, there are three parties: - -* **The container image provider**, who creates the container images that represent the application that has access to the protected data. - -* **The workload operator**, who runs the workload in a Kubernetes cluster. The operator typically has full administrative privileges to the deployment. The operator can manage cluster resources such as nodes, volumes, and networking rules, and the operator can interact with any Kubernetes or underlying cloud API. - -* **The data owner**, who owns the protected data. A data owner can verify the deployment using the Coordinator attestation service. The verification includes the identity, integrity, and confidentiality of the workloads, the runtime environment and the access permissions. - -Contrast supports a trust model where the container image provider, workload operator, and data owner are separate, mutually distrusting parties. - -The following diagram shows the system components and parties. - -![Components and parties](../_media/personas.svg) - -## Threat model and mitigations - -This section describes the threat vectors that Contrast helps to mitigate. - -The following attacks are out of scope for this document: - -* Attacks on the application code itself, such as insufficient access controls. -* Attacks on the Confidential Computing hardware directly, such as side-channel attacks. -* Attacks on the availability, such as denial-of-service (DOS) attacks. - - -### Possible attacks - -Contrast is designed to defend against five possible attacks: - -* **A malicious cloud insider**: malicious employees or third-party contractors of cloud service providers (CSPs) potentially have full access to various layers of the cloud infrastructure. That goes from the physical datacenter up to the hypervisor and Kubernetes layer. For example, they can access the physical memory of the machines, modify the hypervisor, modify disk contents, intercept network communications, and attempt to compromise the confidential container at runtime. A malicious insider can expand the attack surface or restrict the runtime environment. For example, a malicious operator can add a storage device to introduce new attack vectors. As another example, a malicious operator can constrain resources such as limiting a guest's memory size, changing its disk space, or changing firewall rules. -* **A malicious cloud co-tenant**: malicious cloud user ("hackers") may break out of their tenancy and access other tenants' data. Advanced attackers may even be able to establish a permanent foothold within the infrastructure and access data over a longer period. The threats are analogous to the *cloud insider access* scenario, without the physical access. -* **A malicious workload operator**: malicious workload operators, for example Kubernetes administrators, have full access to the workload deployment and the underlying Kubernetes platform. The threats are analogously to the *cloud insider access* scenario, with access to everything that's above the hypervisor level. -* **A malicious attestation client**: this attacker connects to the attestation service and sends malformed request. -* **A malicious container image provider**: a malicious container image provider has full control over the application development itself. This attacker might release a malicious version of the workload containing harmful operations. - -### Attack surfaces - -The following table describes the attack surfaces that are available to attackers. - -| Attacker | Target | Attack surface | Risks | -|------------------------------------------------|----------------------------------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| -| Cloud insider | Confidential Container, Workload | Physical memory | Attacker can dump the physical memory of the workloads. | -| Cloud insider, cloud hacker, workload operator | Confidential Container, Workload | Disk reads | Anything read from the disk is within the attacker's control. | -| Cloud insider, cloud hacker, workload operator | Confidential Container, Workload | Disk writes | Anything written to disk is visible to an attacker. | -| Cloud insider, cloud hacker, workload operator | Confidential Container, Workload | Kubernetes Control Plane | Instance attributes read from the Kubernetes control plane, including mount points and environment variables, are within the attacker's control. | -| Cloud insider, cloud hacker, workload operator | Confidential Container, Workload | Container Runtime | The attacker can use container runtime APIs (for example "kubectl exec") to perform operations on the workload container. | -| Cloud insider, cloud hacker, workload operator | Confidential Container, Workload | Network | Intra-deployment (between containers) as well as external network connections to the image repository or attestation service can be intercepted. | -| Attestation client | Coordinator attestation service | Attestation requests | The attestation service has complex, crypto-heavy logic that's challenging to write defensively. | -| Container image provider | Workload | Workload | This attacker might release an upgrade to the workload containing harmful changes, such as a backdoor. | | - -### Threats and mitigations - -Contrast shields a workload from the aforementioned threats with three main components: - -1. The [runtime environment](../components/runtime.md) safeguards against the physical memory and disk attack surface. -2. The [runtime policies](../components/policies.md) safeguard against the Kubernetes control plane and container runtime attack surface. -3. The [service mesh](../components/service-mesh.md) safeguards against the network attack surface. - -The following tables describe concrete threats and how they're mitigated in Contrast grouped by these categories: - -* Attacks on the confidential container environment -* Attacks on the attestation service -* Attacks on workloads - -#### Attacks on the confidential container environment - -This table describes potential threats and mitigation strategies related to the confidential container environment. - -| Threat | Mitigation | Mitigation implementation | -|----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------| -| An attacker intercepts the network connection of the launcher or image repository. | An attacker can change the image URL and control the workload binary. However these actions are reflected in the attestation report. The image repository isn't controlled using an access list, therefore the image is assumed to be viewable by everyone. You must ensure that the workload container image doesn't contain any secrets. | Within the [runtime policies](../components/policies.md) and [attestation](../architecture/attestation.md) | -| An attacker modifies the workload image on disk after it was downloaded and measured. | This threat is mitigated by a read-only partition that's integrity-protected. The workload image is protected by dm-verity. | Within the Contrast [runtime environment](../components/runtime.md) | -| An attacker modifies a container's runtime environment configuration in the Kubernetes control plane. | The attestation process and the runtime policies detects unsafe configurations that load non-authentic images or perform any other modification to the expected runtime environment. | Within the [runtime policies](../components/policies.md) and [attestation](../architecture/attestation.md) | - -#### Attacks on the Coordinator attestation service - -This table describes potential threats and mitigation strategies to the attestation service. - -| Threat | Mitigation | Mitigation implementation | -|-----------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------| -| An attacker intercepts the Coordinator deployment and modifies the image or hijacks the runtime environment. | This threat is mitigated by having an attestation procedure and attested, encrypted TLS connections to the Coordinator. The attestation evidence for the Coordinator image is distributed with our releases, protected by supply chain security, and fully reproducible. | Within the [attestation](../architecture/attestation.md) | -| An attacker intercepts the network connection between the workload and the Coordinator and reads secret keys from the wire. | This threat is mitigated by having an attested, encrypted TLS connection. This connection helps protect the secrets from passive eavesdropping. The attacker can't create valid workload certificates that would be accepted in Contrast's service mesh. An attacker can't impersonate a valid workload container because the container's identity is guaranteed by the attestation protocol. | Within the network between your workload and the Coordinator. | -| An attacker exploits parsing discrepancies, which leads to undetected changes in the attestation process. | This risk is mitigated by having a parsing engine written in memory-safe Go that's tested against the attestation specification of the hardware vendor. The runtime policies are available as an attestation artifact for further inspection and audits to verify their effectiveness. | Within the [Coordinator](../components/index.md#the-coordinator) | -| An attacker uses all service resources, which brings the Coordinator down in a denial of service (DoS) attack. | In the future, this reliability risk is mitigated by having a distributed Coordinator service that can be easily replicated and scaled out as needed. | Within the [Coordinator](../components/index.md#the-coordinator) | -#### Attacks on workloads - -This table describes potential threats and mitigation strategies related to workloads. - -| Threat | Mitigation | Mitigation implementation | -|--------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------| -| An attacker intercepts the network connection between two workload containers. | This threat is mitigated by having transparently encrypted TLS connections between the containers in your deployment. | Within the [service mesh](../components/service-mesh.md) | -| An attacker reads or modifies data written to disk via persistent volumes. | Currently, persistent volumes aren't supported in Contrast. In the future, this threat is mitigated by encrypted and integrity-protected volume mounts. | Within the Contrast [runtime environment](../components/runtime.md)| -| An attacker publishes a new image version containing malicious code. | The attestation process and the runtime policies require a data owner to accept a specific version of the workload and any update to the workload needs to be explicitly acknowledged. | Within the [attestation](../architecture/attestation.md) | - -## Examples of Contrast's threat model in practice - - -The following table describes three example use cases and how they map to the defined threat model in this document: - -| Use Case | Example Scenario | -|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Migrate sensitive workloads to the cloud | TechSolve Inc., a software development firm, aimed to enhance its defense-in-depth strategy for its cloud-based development environment, especially for projects involving proprietary algorithms and client data. TechSolve acts as the image provider, workload operator, and data owner, combining all three personas in this scenario. In our [attestation terminology](../architecture/attestation.md), they're the workload operator and relying party in one entity. Their threat model includes a malicious cloud insider and cloud co-tenant. | -| Make your SaaS more trustworthy | SaaSProviderX, a company offering cloud-based project management tools, sought to enhance its platform's trustworthiness amidst growing concerns about data breaches and privacy. Here, the [relying party](../architecture/attestation.md) is the SaaS customer as the data owner. The goal is to achieve a form of operator exclusion and only allow selective operations on the deployment. Hence, their threat model includes a malicious workload operator. | -| Simplify regulatory compliance | HealthSecure Inc. has been managing a significant volume of sensitive patient data on-premises. With the increasing demand for advanced data analytics and the need for scalable infrastructure, the firm decides to migrate its data analytics operations to the cloud. However, the primary concern is maintaining the confidentiality and security of patient data during and after the migration, in compliance with healthcare regulations. In this compliance scenario, the regulator serves as an additional relying party. HealthSecure must implement a mechanism that ensures the isolation of patient data can be verifiably guaranteed to the regulator. | - -In each scenario, Contrast ensures exclusive data access and processing capabilities are confined to the designated workloads. It achieves this by effectively isolating the workload from the infrastructure and other components of the stack. Data owners are granted the capability to audit and approve the deployment environment before submitting their data, ensuring a secure handover. Meanwhile, workload operators are equipped to manage and operate the application seamlessly, without requiring direct access to either the workload or its associated data. diff --git a/docs/versioned_docs/version-0.7/components/index.md b/docs/versioned_docs/version-0.7/components/index.md deleted file mode 100644 index 7acb319da3..0000000000 --- a/docs/versioned_docs/version-0.7/components/index.md +++ /dev/null @@ -1,60 +0,0 @@ -# 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 using 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 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/versioned_docs/version-0.7/components/policies.md b/docs/versioned_docs/version-0.7/components/policies.md deleted file mode 100644 index 20596667ea..0000000000 --- a/docs/versioned_docs/version-0.7/components/policies.md +++ /dev/null @@ -1,76 +0,0 @@ -# Policies - -Kata runtime policies are an integral part of the Confidential Containers preview on AKS. -They prescribe how a Kubernetes pod must be configured to launch successfully in a confidential VM. -In Contrast, policies act as a workload identifier: only pods with a policy registered in the manifest receive workload certificates and may participate in the confidential deployment. -Verification of the Contrast Coordinator and its manifest transitively guarantees that all workloads meet the owner's expectations. - -## Structure - -The Kata agent running in the confidential micro-VM exposes an RPC service [`AgentService`] to the Kata runtime. -This service handles potentially untrustworthy requests from outside the TCB, which need to be checked against a policy. - -Kata runtime policies are written in the policy language [Rego]. -They specify what `AgentService` methods can be called, and the permissible parameters for each call. - -Policies consist of two parts: a list of rules and a data section. -While the list of rules is static, the data section is populated with information from the `PodSpec` and other sources. - -[`AgentService`]: https://github.com/kata-containers/kata-containers/blob/e5e0983/src/libs/protocols/protos/agent.proto#L21-L76 -[Rego]: https://www.openpolicyagent.org/docs/latest/policy-language/ - -## Generation - -Runtime policies are programmatically generated from Kubernetes manifests by the Contrast CLI. -The `generate` subcommand inspects pod definitions and derives rules for validating the pod at the Kata agent. -There are two important integrity checks: container image checksums and OCI runtime parameters. - -For each of the container images used in a pod, the CLI downloads all image layers and produces a cryptographic [dm-verity] checksum. -These checksums are the basis for the policy's *storage data*. - -The CLI combines information from the `PodSpec`, `ConfigMaps`, and `Secrets` in the provided Kubernetes manifests to derive a permissible set of command-line arguments and environment variables. -These constitute the policy's *OCI data*. - -[dm-verity]: https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/verity.html - -## Evaluation - -The generated policy document is annotated to the pod definitions in Base64 encoding. -This annotation is propagated to the Kata runtime, which calculates the SHA256 checksum for the policy and uses that as SNP `HOSTDATA` for the confidential micro-VM. - -After the VM launched, the runtime calls the agent's `SetPolicy` method with the full policy document. -If the policy doesn't match the checksum in `HOSTDATA`, the agent rejects the policy. -Otherwise, it applies the policy to all future `AgentService` requests. - -## Guarantees - -The policy evaluation provides the following guarantees for pods launched with the correct generated policy: - -* Command and its arguments are set as specified in the resources. -* There are no unexpected additional environment variables. -* The container image layers correspond to the layers observed at policy generation time. - Thus, only the expected workload image can be instantiated. -* Executing additional processes in a container is prohibited. -* Sending data to a container's standard input is prohibited. - -The current implementation of policy checking has some blind spots: - -* Containers can be started in any order, or be omitted entirely. -* Environment variables may be missing. -* Volumes other than the container root volume don't have integrity checks (particularly relevant for mounted `ConfigMaps` and `Secrets`). - -## Trust - -Contrast verifies its confidential containers following these steps: - -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 invokes the Kata runtime to create 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 Initializer sends an attestation report to the Contrast Coordinator, asking for a mesh certificate. -9. 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 matches expectations and may receive mesh certificates. diff --git a/docs/versioned_docs/version-0.7/components/runtime.md b/docs/versioned_docs/version-0.7/components/runtime.md deleted file mode 100644 index 62c072ff47..0000000000 --- a/docs/versioned_docs/version-0.7/components/runtime.md +++ /dev/null @@ -1,84 +0,0 @@ -# Contrast Runtime - -The Contrast runtime is responsible for starting pods as confidential virtual machines. -This works by specifying the runtime class to be used in a pod spec and by registering the runtime class with the apiserver. -The `RuntimeClass` resource defines a name for referencing the class and -a handler used by the container runtime (`containerd`) to identify the class. - -```yaml -apiVersion: node.k8s.io/v1 -kind: RuntimeClass -metadata: - # This name is used by pods in the runtimeClassName field - name: contrast-cc-abcdef -# This name is used by the -# container runtime interface implementation (containerd) -handler: contrast-cc-abcdef -``` - -Confidential pods that are part of a Contrast deployment need to specify the -same runtime class in the `runtimeClassName` field, so Kubernetes uses the -Contrast runtime instead of the default `containerd` / `runc` handler. - -```yaml -apiVersion: v1 -kind: Pod -spec: - runtimeClassName: contrast-cc-abcdef - # ... -``` - -## Node-level components - -The runtime consists of additional software components that need to be installed -and configured on every SEV-SNP-enabled worker node. -This installation is performed automatically by the [`node-installer` DaemonSet](#node-installer-daemonset). - -![Runtime components](../_media/runtime.svg) - -### Containerd shim - -The `handler` field in the Kubernetes `RuntimeClass` instructs containerd not to use the default `runc` implementation. -Instead, containerd invokes a custom plugin called `containerd-shim-contrast-cc-v2`. -This shim is described in more detail in the [upstream source repository](https://github.com/kata-containers/kata-containers/tree/3.4.0/src/runtime) and in the [containerd documentation](https://github.com/containerd/containerd/blob/main/core/runtime/v2/README.md). - -### `cloud-hypervisor` virtual machine manager (VMM) - -The `containerd` shim uses [`cloud-hypervisor`](https://www.cloudhypervisor.org) to create a confidential virtual machine for every pod. -This requires the `cloud-hypervisor` binary to be installed on every node (responsibility of the [`node-installer`](#node-installer-daemonset)). - -### `Tardev snapshotter` - -Contrast uses a special [`containerd` snapshotter](https://github.com/containerd/containerd/tree/v1.7.16/docs/snapshotters/README.md) ([`tardev`](https://github.com/kata-containers/tardev-snapshotter)) to provide container images as block devices to the pod-VM. This snapshotter consists of a host component that pulls container images and a guest component (kernel module) used to mount container images. -The `tardev` snapshotter uses [`dm-verity`](https://docs.kernel.org/admin-guide/device-mapper/verity.html) to protect the integrity of container images. -Expected `dm-verity` container image hashes are part of Contrast runtime policies and are enforced by the kata-agent. -This enables workload attestation by specifying the allowed container image as part of the policy. Read [the chapter on policies](policies.md) for more information. - -### Pod-VM image - -Every pod-VM starts with the same guest image. It consists of an IGVM file and a root filesystem. -The IGVM file describes the initial memory contents of a pod-VM and consists of: - -- Linux kernel image -- `initrd` -- `kernel commandline` - -Additionally, a root filesystem image is used that contains a read-only partition with the user space of the pod-VM and a verity partition to guarantee the integrity of the root filesystem. -The root filesystem contains systemd as the init system, and the kata agent for managing the pod. - -This pod-VM image isn't specific to any pod workload. Instead, container images are mounted at runtime. - -## Node installer DaemonSet - -The `RuntimeClass` resource above registers the runtime with the Kubernetes api. -The node-level installation is carried out by the Contrast node-installer -`DaemonSet` that ships with every Contrast release. - -After deploying the installer, it performs the following steps on each node: - -- Install the Contrast containerd shim (`containerd-shim-contrast-cc-v2`) -- Install `cloud-hypervisor` as the virtual machine manager (VMM) -- Install an IGVM file for pod-VMs of this class -- Install a read only root filesystem disk image for the pod-VMs of this class -- Reconfigure `containerd` by adding a runtime plugin that corresponds to the `handler` field of the Kubernetes `RuntimeClass` -- Restart `containerd` to make it aware of the new plugin diff --git a/docs/versioned_docs/version-0.7/components/service-mesh.md b/docs/versioned_docs/version-0.7/components/service-mesh.md deleted file mode 100644 index a14ca6adfb..0000000000 --- a/docs/versioned_docs/version-0.7/components/service-mesh.md +++ /dev/null @@ -1,146 +0,0 @@ -# Service mesh - -The Contrast service mesh secures the communication of the workload by automatically -wrapping the network traffic inside mutual TLS (mTLS) connections. The -verification of the endpoints in the connection establishment is based on -certificates that are part of the -[PKI of the Coordinator](../architecture/certificates.md). - -The service mesh can be enabled on a per-workload basis by adding a service mesh -configuration to the workload's object annotations. During the `contrast generate` -step, the service mesh is added as a [sidecar -container](https://kubernetes.io/docs/concepts/workloads/pods/sidecar-containers/) to -all workloads which have a specified configuration. The service mesh container first -sets up `iptables` rules based on its configuration and then starts -[Envoy](https://www.envoyproxy.io/) for TLS origination and termination. - -## Configuring the proxy - -The service mesh container can be configured using the following object annotations: - -* `contrast.edgeless.systems/servicemesh-ingress` to configure ingress. -* `contrast.edgeless.systems/servicemesh-egress` to configure egress. -* `contrast.edgeless.systems/servicemesh-admin-interface-port` to configure the Envoy - admin interface. If not specified, no admin interface will be started. - -If you aren't using the automatic service mesh injection and want to configure the -service mesh manually, set the environment variables `EDG_INGRESS_PROXY_CONFIG`, -`EDG_EGRESS_PROXY_CONFIG` and `EDG_ADMIN_PORT` in the service mesh sidecar directly. - -### Ingress - -All TCP ingress traffic is routed over Envoy by default. Since we use -[TPROXY](https://docs.kernel.org/networking/tproxy.html), the destination address -remains the same throughout the packet handling. - -Any incoming connection is required to present a client certificate signed by the -[mesh CA certificate](../architecture/certificates.md#usage-of-the-different-certificates). -Envoy presents a certificate chain of the mesh -certificate of the workload and the intermediate CA certificate as the server certificate. - -If the deployment contains workloads which should be reachable from outside the -Service Mesh, while still handing out the certificate chain, disable client -authentication by setting the annotation `contrast.edgeless.systems/servicemesh-ingress` as -`##false`. Separate multiple entries with `##`. You can choose any -descriptive string identifying the service on the given port for the `` field, -as it's only informational. - -Disable redirection and TLS termination altogether by specifying -`##true`. This can be beneficial if the workload itself handles TLS -on that port or if the information exposed on this port is non-sensitive. - -The following example workload exposes a web service on port 8080 and metrics on -port 7890. The web server is exposed to a 3rd party end-user which wants to -verify the deployment, therefore it's still required that the server hands out -it certificate chain signed by the mesh CA certificate. The metrics should be -exposed via TCP without TLS. - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: web - annotations: - contrast.edgeless.systems/servicemesh-ingress: "web#8080#false##metrics#7890#true" -spec: - replicas: 1 - template: - spec: - runtimeClassName: contrast-cc - containers: - - name: web-svc - image: ghcr.io/edgelesssys/frontend:v1.2.3@... - ports: - - containerPort: 8080 - name: web - - containerPort: 7890 - name: metrics -``` - -When invoking `contrast generate`, the resulting deployment will be injected with the -Contrast service mesh as an init container. - -```yaml -# ... - initContainers: - - env: - - name: EDG_INGRESS_PROXY_CONFIG - value: "web#8080#false##metrics#7890#true" - image: "ghcr.io/edgelesssys/contrast/service-mesh-proxy:v0.7.3@sha256:e297e9db93744445608f229d44479359313bc187a7f31e1a9c3c9b1d5407b5f6" - name: contrast-service-mesh - restartPolicy: Always - securityContext: - capabilities: - add: - - NET_ADMIN - privileged: true - volumeMounts: - - name: contrast-tls-certs - mountPath: /tls-config -``` - -Note, that changing the environment variables of the sidecar container directly will -only have an effect if the workload isn't configured to automatically generate a -service mesh component on `contrast generate`. Otherwise, the service mesh sidecar -container will be regenerated on every invocation of the command. - -### Egress - -To be able to route the egress traffic of the workload through Envoy, the remote -endpoints' IP address and port must be configurable. - -* Choose an IP address inside the `127.0.0.0/8` CIDR and a port not yet in use -by the pod. -* Configure the workload to connect to this IP address and port. -* Set `#:#:` -as the `contrast.edgeless.systems/servicemesh-egress` workload annotation. Separate multiple -entries with `##`. Choose any string identifying the service on the given port as -``. - -This redirects the traffic over Envoy. The endpoint must present a valid -certificate chain which must be verifiable with the -[mesh CA certificate](../architecture/certificates.md#usage-of-the-different-certificates). -Furthermore, Envoy uses a certificate chain with the mesh certificate of the workload -and the intermediate CA certificate as the client certificate. - -The following example workload has no ingress connections and two egress -connection to different microservices. The microservices are part -of the confidential deployment. One is reachable under `billing-svc:8080` and -the other under `cart-svc:8080`. - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: web - annotations: - contrast.edgeless.systems/servicemesh-egress: "billing#127.137.0.1:8081#billing-svc:8080##cart#127.137.0.2:8081#cart-svc:8080" -spec: - replicas: 1 - template: - spec: - runtimeClassName: contrast-cc - containers: - - name: currency-conversion - image: ghcr.io/edgelesssys/conversion:v1.2.3@... -``` diff --git a/docs/versioned_docs/version-0.7/deployment.md b/docs/versioned_docs/version-0.7/deployment.md deleted file mode 100644 index 2d0465675d..0000000000 --- a/docs/versioned_docs/version-0.7/deployment.md +++ /dev/null @@ -1,304 +0,0 @@ -# Workload deployment - -The following instructions will guide you through the process of making an existing Kubernetes deployment -confidential and deploying it together with Contrast. - -A running CoCo-enabled cluster is required for these steps, see the [setup guide](./getting-started/cluster-setup.md) on how to set it up. - -## Deploy the Contrast runtime - -Contrast depends on a [custom Kubernetes `RuntimeClass` (`contrast-cc`)](./components/runtime.md), -which needs to be installed in the cluster prior to the Coordinator or any confidential workloads. -This consists of a `RuntimeClass` resource and a `DaemonSet` that performs installation on worker nodes. -This step is only required once for each version of the runtime. -It can be shared between Contrast deployments. - -```sh -kubectl apply -f https://github.com/edgelesssys/contrast/releases/download/v0.7.3/runtime.yml -``` - -## Deploy the Contrast Coordinator - -Install the latest Contrast Coordinator release, comprising a single replica deployment and a -LoadBalancer service, into your cluster. - -```sh -kubectl apply -f https://github.com/edgelesssys/contrast/releases/download/v0.7.3/coordinator.yml -``` - -## Prepare your Kubernetes resources - -Your Kubernetes resources need some modifications to run as Confidential Containers. -This section guides you through the process and outlines the necessary changes. - -### RuntimeClass - -Contrast will add annotations to your Kubernetes YAML files. If you want to keep the original files -unchanged, you can copy the files into a separate local directory. -You can also generate files from a Helm chart or from a Kustomization. - - - - -```sh -mkdir resources -kustomize build $MY_RESOURCE_DIR > resources/all.yml -``` - - - - -```sh -mkdir resources -helm template $RELEASE_NAME $CHART_NAME > resources/all.yml -``` - - - - -```sh -cp -R $MY_RESOURCE_DIR resources/ -``` - - - - -To specify that a workload (pod, deployment, etc.) should be deployed as confidential containers, -add `runtimeClassName: contrast-cc` to the pod spec (pod definition or template). -This is a placeholder name that will be replaced by a versioned `runtimeClassName` when generating policies. - -```yaml -spec: # v1.PodSpec - runtimeClassName: contrast-cc -``` - -### Handling TLS - -In the initialization process, the `contrast-tls-certs` shared volume is populated with X.509 certificates for your workload. -These certificates are used by the [Contrast Service Mesh](components/service-mesh.md), but can also be used by your application directly. -The following tab group explains the setup for both scenarios. - - - - -Contrast can be configured to handle TLS in a sidecar container. -This is useful for workloads that are hard to configure with custom certificates, like Java applications. - -Configuration of the sidecar depends heavily on the application. -The following example is for an application with these properties: - -* The container has a main application at TCP port 8001, which should be TLS-wrapped and doesn't require client authentication. -* The container has a metrics endpoint at TCP port 8080, which should be accessible in plain text. -* All other endpoints require client authentication. -* The app connects to a Kubernetes service `backend.default:4001`, which requires client authentication. - -Add the following annotations to your workload: - -```yaml -metadata: # apps/v1.Deployment, apps/v1.DaemonSet, ... - annotations: - contrast.edgeless.systems/servicemesh-ingress: "main#8001#false##metrics#8080#true" - contrast.edgeless.systems/servicemesh-egress: "backend#127.0.0.2:4001#backend.default:4001" -``` - -During the `generate` step, this configuration will be translated into a Service Mesh sidecar container which handles TLS connections automatically. -The only change required to the app itself is to let it connect to `127.0.0.2:4001` to reach the backend service. -You can find more detailed documentation in the [Service Mesh chapter](components/service-mesh.md). - - - - - -The mesh certificate contained in `certChain.pem` authenticates this workload, while the mesh CA certificate `mesh-ca.pem` authenticates its peers. -Your app should turn on client authentication to ensure peers are running as confidential containers, too. -See the [Certificate Authority](architecture/certificates.md) section for detailed information about these certificates. - -The following example shows how to configure a Golang app, with error handling omitted for clarity. - - - - -```go -caCerts := x509.NewCertPool() -caCert, _ := os.ReadFile("/tls-config/mesh-ca.pem") -caCerts.AppendCertsFromPEM(caCert) -cert, _ := tls.LoadX509KeyPair("/tls-config/certChain.pem", "/tls-config/key.pem") -cfg := &tls.Config{ - Certificates: []tls.Certificate{cert}, - RootCAs: caCerts, -} -``` - - - - -```go -caCerts := x509.NewCertPool() -caCert, _ := os.ReadFile("/tls-config/mesh-ca.pem") -caCerts.AppendCertsFromPEM(caCert) -cert, _ := tls.LoadX509KeyPair("/tls-config/certChain.pem", "/tls-config/key.pem") -cfg := &tls.Config{ - Certificates: []tls.Certificate{cert}, - ClientAuth: tls.RequireAndVerifyClientCert, - ClientCAs: caCerts, -} -``` - - - - - - - -## Generate policy annotations and manifest - -Run the `generate` command to add the necessary components to your deployment files. -This will add the Contrast Initializer to every workload with the specified `contrast-cc` runtime class -and the Contrast Service Mesh to all workloads that have a specified configuration. -After that, it will generate the execution policies and add them as annotations to your deployment files. -A `manifest.json` with the reference values of your deployment will be created. - -```sh -contrast generate resources/ -``` - -:::warning -Please be aware that runtime policies currently have some blind spots. For example, they can't guarantee the starting order of containers. See the [current limitations](features-limitations.md#runtime-policies) for more details. -::: - -If you don't want the Contrast Initializer to automatically be added to your -workloads, there are two ways you can skip the Initializer injection step, -depending on how you want to customize your deployment. - - - - -You can disable the Initializer injection completely by specifying the -`--skip-initializer` flag in the `generate` command. - -```sh -contrast generate --skip-initializer resources/ -``` - - - - - -If you want to disable the Initializer injection for a specific workload with -the `contrast-cc` runtime class, you can do so by adding an annotation to the workload. - -```yaml -metadata: # apps/v1.Deployment, apps/v1.DaemonSet, ... - annotations: - contrast.edgeless.systems/skip-initializer: "true" -``` - - - - -When disabling the automatic Initializer injection, you can manually add the -Initializer as a sidecar container to your workload before generating the -policies. Configure the workload to use the certificates written to the -`contrast-tls-certs` `volumeMount`. - -```yaml -# v1.PodSpec -spec: - initContainers: - - env: - - name: COORDINATOR_HOST - value: coordinator - image: "ghcr.io/edgelesssys/contrast/initializer:v0.7.3@sha256:55475365c8177420ff3b27ad48bb0f38f8a92bfe754f50f1ed97f50f17ee23b8" - name: contrast-initializer - volumeMounts: - - mountPath: /tls-config - name: contrast-tls-certs - volumes: - - emptyDir: {} - name: contrast-tls-certs -``` - -## Apply the resources - -Apply the resources to the cluster. Your workloads will block in the initialization phase until a -manifest is set at the Coordinator. - -```sh -kubectl apply -f resources/ -``` - -## Connect to the Contrast Coordinator - -For the next steps, we will need to connect to the Coordinator. The released Coordinator resource -includes a LoadBalancer definition we can use. - -```sh -coordinator=$(kubectl get svc coordinator -o=jsonpath='{.status.loadBalancer.ingress[0].ip}') -``` - -:::info[Port-forwarding of Confidential Containers] - -`kubectl port-forward` uses a Container Runtime Interface (CRI) method that isn't supported by the Kata shim. -If you can't use a public load balancer, you can deploy a [port-forwarder](https://github.com/edgelesssys/contrast/blob/ddc371b/deployments/emojivoto/portforwarder.yml). -The port-forwarder relays traffic from a CoCo pod and can be accessed via `kubectl port-forward`. - - - -Upstream tracking issue: https://github.com/kata-containers/kata-containers/issues/1693. - -::: - -## Set the manifest - -Attest the Coordinator and set the manifest: - -```sh -contrast set -c "${coordinator}:1313" resources/ -``` - -After this step, the Coordinator will start issuing TLS certificates to the workloads. The init container -will fetch a certificate for the workload and the workload is started. - -## Verify the Coordinator - -An end user (data owner) can verify the Contrast deployment using the `verify` command. - -```sh -contrast verify -c "${coordinator}:1313" -``` - -The CLI will attest the Coordinator using embedded reference values. The CLI will write the service mesh -root certificate and the history of manifests into the `verify/` directory. In addition, the policies referenced -in the manifest are also written to the directory. - -## Communicate with workloads - -You can securely connect to the workloads using the Coordinator's `mesh-ca.pem` as a trusted CA certificate. -First, expose the service on a public IP address via a LoadBalancer service: - -```sh -kubectl patch svc ${MY_SERVICE} -p '{"spec": {"type": "LoadBalancer"}}' -kubectl wait --timeout=30s --for=jsonpath='{.status.loadBalancer.ingress}' service/${MY_SERVICE} -lbip=$(kubectl get svc ${MY_SERVICE} -o=jsonpath='{.status.loadBalancer.ingress[0].ip}') -echo $lbip -``` - -:::info[Subject alternative names and LoadBalancer IP] - -By default, mesh certificates are issued with a wildcard DNS entry. The web frontend is accessed -via load balancer IP in this demo. Tools like curl check the certificate for IP entries in the SAN field. -Validation fails since the certificate contains no IP entries as a subject alternative name (SAN). -For example, a connection attempt using the curl and the mesh CA certificate with throw the following error: - -```sh -$ curl --cacert ./verify/mesh-ca.pem "https://${frontendIP}:443" -curl: (60) SSL: no alternative certificate subject name matches target host name '203.0.113.34' -``` - -::: - -Using `openssl`, the certificate of the service can be validated with the `mesh-ca.pem`: - -```sh -openssl s_client -CAfile verify/mesh-ca.pem -verify_return_error -connect ${frontendIP}:443 < /dev/null -``` diff --git a/docs/versioned_docs/version-0.7/examples/emojivoto.md b/docs/versioned_docs/version-0.7/examples/emojivoto.md deleted file mode 100644 index 6d7c1c8749..0000000000 --- a/docs/versioned_docs/version-0.7/examples/emojivoto.md +++ /dev/null @@ -1,242 +0,0 @@ -# Confidential emoji voting - - -![screenshot of the emojivoto UI](../_media/emoijvoto.png) - -**This tutorial guides you through deploying [emojivoto](https://github.com/BuoyantIO/emojivoto) as a -confidential Contrast deployment and validating the deployment from a voters perspective.** - -Emojivoto is an example app allowing users to vote for different emojis and view votes -on a leader board. It has a microservice architecture consisting of a -web frontend (`web`), a gRPC backend for listing available emojis (`emoji`), and a backend for -the voting and leader board logic (`voting`). The `vote-bot` simulates user traffic by submitting -votes to the frontend. - - -![emojivoto components topology](https://raw.githubusercontent.com/BuoyantIO/emojivoto/e490d5789086e75933a474b22f9723fbfa0b29ba/assets/emojivoto-topology.png) - -### Motivation - -Using a voting service, users' votes are considered highly sensitive data, as we require -a secret ballot. Also, users are likely interested in the fairness of the ballot. For -both requirements, we can use Confidential Computing and, specifically, workload attestation -to prove to those interested in voting that the app is running in a protected environment -where their votes are processed without leaking to the platform provider or workload owner. - -## Prerequisites - -- **Installed Contrast CLI.** - See the [installation instructions](./../getting-started/install.md) on how to get it. -- **Running cluster with Confidential Containers support.** - Please follow the [cluster setup instructions](./../getting-started/cluster-setup.md) - to create a cluster. - -## Steps to deploy emojivoto with Contrast - -### Downloading the deployment - -The emojivoto deployment files are part of a zip file in the Contrast release. You can download the -latest deployment by running: - -```sh -curl -fLO https://github.com/edgelesssys/contrast/releases/download/v0.7.3/emojivoto-demo.zip -``` - -After that, unzip the `emojivoto-demo.zip` file to extract the `deployment/` directory. - -```sh -unzip emojivoto-demo.zip -``` - -### Deploy the Contrast runtime - -Contrast depends on a [custom Kubernetes `RuntimeClass` (`contrast-cc`)](../components/runtime.md), -which needs to be installed in the cluster prior to the Coordinator or any confidential workloads. -This consists of a `RuntimeClass` resource and a `DaemonSet` that performs installation on worker nodes. -This step is only required once for each version of the runtime. -It can be shared between Contrast deployments. - -```sh -kubectl apply -f https://github.com/edgelesssys/contrast/releases/download/v0.7.3/runtime.yml -``` - -### Deploy the Contrast Coordinator - -Deploy the Contrast Coordinator, comprising a single replica deployment and a -LoadBalancer service, into your cluster: - -```sh -kubectl apply -f https://github.com/edgelesssys/contrast/releases/download/v0.7.3/coordinator.yml -``` - -### Generate policy annotations and manifest - -Run the `generate` command to generate the execution policies and add them as -annotations to your deployment files. A `manifest.json` file with the reference values -of your deployment will be created: - -```sh -contrast generate deployment/ -``` - -:::note[Runtime class and Initializer] - -The deployment YAML shipped for this demo is already configured to be used with Contrast. -A [runtime class](https://docs.edgeless.systems/contrast/components/runtime) `contrast-cc-` -was added to the pods to signal they should be run as Confidential Containers. During the generation process, -the Contrast [Initializer](../components/index.md#the-initializer) will be added as an init container to these -workloads to facilitate the attestation and certificate pulling before the actual workload is started. - -Further, the deployment YAML is also configured with the Contrast [service mesh](../components/service-mesh.md). -The configured service mesh proxy provides transparent protection for the communication between -the different components of emojivoto. -::: - -### Set the manifest - -Configure the coordinator with a manifest. It might take up to a few minutes -for the load balancer to be created and the Coordinator being available. - -```sh -coordinator=$(kubectl get svc coordinator -o=jsonpath='{.status.loadBalancer.ingress[0].ip}') -echo "The user API of your Contrast Coordinator is available at $coordinator:1313" -contrast set -c "${coordinator}:1313" deployment/ -``` - -The CLI will use the embedded reference values to attest the Coordinator deployment -during the TLS handshake. If the connection succeeds, it's ensured that the Coordinator -deployment hasn't been tampered with. - -### Deploy emojivoto - -Now that the coordinator has a manifest set, which defines the emojivoto deployment as an allowed workload, -we can deploy the application: - -```sh -kubectl apply -f deployment/ -``` - -:::note[Inter-deployment communication] - -The Contrast Coordinator issues mesh certificates after successfully validating workloads. -These certificates can be used for secure inter-deployment communication. The Initializer -sends an attestation report to the Coordinator, retrieves certificates and a private key in return -and writes them to a `volumeMount`. The service mesh sidecar is configured to use the credentials -from the `volumeMount` when communicating with other parts of the deployment over mTLS. -The public facing frontend for voting uses the mesh certificate without client authentication. - -::: - -## Voter's perspective: Verifying the ballot - -As voters, we want to verify the fairness and confidentiality of the deployment before -deciding to vote. Regardless of the scale of our distributed deployment, Contrast only -needs a single remote attestation step to verify the deployment. By doing remote attestation -of the Coordinator, we transitively verify those systems the Coordinator has already attested -or will attest in the future. Successful verification of the Coordinator means that -we can be sure it will enforce the configured manifest. - -### Attest the Coordinator - -A potential voter can verify the Contrast deployment using the verify -command: - -```sh -contrast verify -c "${coordinator}:1313" -``` - -The CLI will attest the Coordinator using embedded reference values. If the command succeeds, -the Coordinator deployment was successfully verified to be running in the expected Confidential -Computing environment with the expected code version. The Coordinator will then return its -configuration over the established TLS channel. The CLI will store this information, namely the root -certificate of the mesh (`mesh-ca.pem`) and the history of manifests, into the `verify/` directory. -In addition, the policies referenced in the manifest history are also written into the same directory. - -### Manifest history and artifact audit - -In the next step, the Coordinator configuration that was written by the `verify` command needs to be audited. -A potential voter should inspect the manifest and the referenced policies. They could delegate -this task to an entity they trust. - -### Confidential connection to the attested workload - -After ensuring the configuration of the Coordinator fits the expectation, you can securely connect -to the workloads using the Coordinator's `mesh-ca.pem` as a trusted CA certificate. - -To access the web frontend, expose the service on a public IP address via a LoadBalancer service: - -```sh -frontendIP=$(kubectl get svc web-svc -o=jsonpath='{.status.loadBalancer.ingress[0].ip}') -echo "Frontend is available at https://$frontendIP, you can visit it in your browser." -``` - -Using `openssl`, the certificate of the service can be validated with the `mesh-ca.pem`: - -```sh -openssl s_client -CAfile verify/mesh-ca.pem -verify_return_error -connect ${frontendIP}:443 < /dev/null -``` - -## Certificate SAN and manifest update (optional) - -By default, mesh certificates are issued with a wildcard DNS entry. The web frontend is accessed -via load balancer IP in this demo. Tools like curl check the certificate for IP entries in the subject alternative name (SAN) field. -Validation fails since the certificate contains no IP entries as a SAN. -For example, a connection attempt using the curl and the mesh CA certificate with throw the following error: - -```sh -$ curl --cacert ./verify/mesh-ca.pem "https://${frontendIP}:443" -curl: (60) SSL: no alternative certificate subject name matches target host name '203.0.113.34' -``` - -### Configure the service SAN in the manifest - -The `Policies` section of the manifest maps policy hashes to a list of SANs. To enable certificate verification -of the web frontend with tools like curl, edit the policy with your favorite editor and add the `frontendIP` to -the list that already contains the `"web"` DNS entry: - -```diff - "Policies": { - ... - "99dd77cbd7fe2c4e1f29511014c14054a21a376f7d58a48d50e9e036f4522f6b": [ - "web", -- "*" -+ "*", -+ "203.0.113.34" - ], -``` - -### Update the manifest - -Next, set the changed manifest at the coordinator with: - -```sh -contrast set -c "${coordinator}:1313" deployment/ -``` - -The Contrast Coordinator will rotate the mesh ca certificate on the manifest update. Workload certificates issued -after the manifest update are thus issued by another certificate authority and services receiving the new CA certificate chain -won't trust parts of the deployment that got their certificate issued before the update. This way, Contrast ensures -that parts of the deployment that received a security update won't be infected by parts of the deployment at an older -patch level that may have been compromised. The `mesh-ca.pem` is updated with the new CA certificate chain. - -### Rolling out the update - -The Coordinator has the new manifest set, but the different containers of the app are still -using the older certificate authority. The Contrast Initializer terminates after the initial attestation -flow and won't pull new certificates on manifest updates. - -To roll out the update, use: - -```sh -kubectl rollout restart deployment/emoji -kubectl rollout restart deployment/vote-bot -kubectl rollout restart deployment/voting -kubectl rollout restart deployment/web -``` - -After the update has been rolled out, connecting to the frontend using curl will successfully validate -the service certificate and return the HTML document of the voting site: - -```sh -curl --cacert ./mesh-ca.pem "https://${frontendIP}:443" -``` diff --git a/docs/versioned_docs/version-0.7/examples/index.md b/docs/versioned_docs/version-0.7/examples/index.md deleted file mode 100644 index 252c82c820..0000000000 --- a/docs/versioned_docs/version-0.7/examples/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# Examples - -import DocCardList from '@theme/DocCardList'; - - diff --git a/docs/versioned_docs/version-0.7/features-limitations.md b/docs/versioned_docs/version-0.7/features-limitations.md deleted file mode 100644 index 919d804901..0000000000 --- a/docs/versioned_docs/version-0.7/features-limitations.md +++ /dev/null @@ -1,29 +0,0 @@ -# Planned features and limitations - -This section lists planned features and current limitations of Contrast. - -## Availability - -- **Platform support**: At present, Contrast is exclusively available on Azure AKS, supported by the [Confidential Container preview for AKS](https://learn.microsoft.com/en-us/azure/confidential-computing/confidential-containers-on-aks-preview). Expansion to other cloud platforms is planned, pending the availability of necessary infrastructure enhancements. -- **Bare-metal support**: Support for running Contrast on bare-metal Kubernetes will be available soon for AMD SEV and Intel TDX. - -## Kubernetes features - -- **Persistent volumes**: Not currently supported within Confidential Containers. -- **Port forwarding**: This feature [isn't yet supported by Kata Containers](https://github.com/kata-containers/kata-containers/issues/1693). You can [deploy a port-forwarder](https://docs.edgeless.systems/contrast/deployment#connect-to-the-contrast-coordinator) as a workaround. -- **Resource limits**: There is an existing bug on AKS where container memory limits are incorrectly applied. The current workaround involves using only memory requests instead of limits. - -## Runtime policies - -- **Coverage**: While the enforcement of workload policies generally functions well, [there are scenarios not yet fully covered](https://github.com/microsoft/kata-containers/releases/tag/3.2.0.azl0.genpolicy). It's crucial to review deployments specifically for these edge cases. -- **Order of events**: The current policy evaluation mechanism on API requests isn't stateful, so it can't ensure a prescribed order of events. Consequently, there's no guaranteed enforcement that the [service mesh sidecar](components/service-mesh.md) container runs *before* the workload container. This order ensures that all traffic between pods is securely encapsulated within TLS connections. -- **Absence of events**: Policies can't ensure certain events have happened. A container, such as the [service mesh sidecar](components/service-mesh.md), can be omitted entirely. Environment variables may be missing. -- **Volume integrity checks**: While persistent volumes aren't supported yet, integrity checks don't currently cover other objects such as `ConfigMaps` and `Secrets`. - -:::warning -The policy limitations, in particular the missing guarantee that our service mesh sidecar has been started before the workload container affects the service mesh implementation of Contrast. Currently, this requires inspecting the iptables rules on startup or terminating TLS connections in the workload directly. -::: - -## Tooling integration - -- **CLI availability**: The CLI tool is currently only available for Linux. This limitation arises because certain upstream dependencies haven't yet been ported to other platforms. diff --git a/docs/versioned_docs/version-0.7/getting-started/cluster-setup.md b/docs/versioned_docs/version-0.7/getting-started/cluster-setup.md deleted file mode 100644 index 3f0b19ead3..0000000000 --- a/docs/versioned_docs/version-0.7/getting-started/cluster-setup.md +++ /dev/null @@ -1,169 +0,0 @@ -# Create a cluster - -## Prerequisites - -Install the latest version of the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/). - -[Login to your account](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli), which needs -to have the permissions to create an AKS cluster, by executing: - -```bash -az login -``` - -## Prepare using the AKS preview - -CoCo on AKS is currently in preview. An extension for the `az` CLI is needed to create such a cluster. -Add the extension with the following commands: - -```bash -az extension add \ - --name aks-preview \ - --allow-preview true -az extension update \ - --name aks-preview \ - --allow-preview true -``` - -Then register the required feature flags in your subscription to allow access to the public preview: - -```bash -az feature register \ - --namespace "Microsoft.ContainerService" \ - --name "KataCcIsolationPreview" -``` - -The registration can take a few minutes. The status of the operation can be checked with the following -command, which should show the registration state as `Registered`: - -```sh -az feature show \ - --namespace "Microsoft.ContainerService" \ - --name "KataCcIsolationPreview" \ - --output table -``` - -Afterward, refresh the registration of the ContainerService provider: - -```sh -az provider register \ - --namespace "Microsoft.ContainerService" -``` - -## Create resource group - -The AKS with CoCo preview is currently available in the following locations: - -``` -CentralIndia -eastus -EastUS2EUAP -GermanyWestCentral -japaneast -northeurope -SwitzerlandNorth -UAENorth -westeurope -westus -``` - -Set the name of the resource group you want to use: - -```bash -azResourceGroup="ContrastDemo" -``` - -You can either use an existing one or create a new resource group with the following command: - -```bash -azLocation="westus" # Select a location from the list above - -az group create \ - --name "${azResourceGroup:?}" \ - --location "${azLocation:?}" -``` - -## Create AKS cluster - -First, we need to create an AKS cluster. We can't directly create a CoCo-enabled cluster, so we'll need to create a -non-CoCo cluster first, and then add a CoCo node pool, optionally replacing the non-CoCo node pool. - -We'll first start by creating the non-CoCo cluster: - -```sh -# Select the name for your AKS cluster -azClusterName="ContrastDemo" - -az aks create \ - --resource-group "${azResourceGroup:?}" \ - --name "${azClusterName:?}" \ - --kubernetes-version 1.29 \ - --os-sku AzureLinux \ - --node-vm-size Standard_DC4as_cc_v5 \ - --node-count 1 \ - --generate-ssh-keys -``` - -We then add a second node pool with CoCo support: - -```bash -az aks nodepool add \ - --resource-group "${azResourceGroup:?}" \ - --name nodepool2 \ - --cluster-name "${azClusterName:?}" \ - --node-count 1 \ - --os-sku AzureLinux \ - --node-vm-size Standard_DC4as_cc_v5 \ - --workload-runtime KataCcIsolation -``` - -Optionally, we can now remove the non-CoCo node pool: - -```bash -az aks nodepool delete \ - --resource-group "${azResourceGroup:?}" \ - --cluster-name "${azClusterName:?}" \ - --name nodepool1 -``` - -Finally, update your kubeconfig with the credentials to access the cluster: - -```bash -az aks get-credentials \ - --resource-group "${azResourceGroup:?}" \ - --name "${azClusterName:?}" -``` - -For validation, list the available nodes using kubectl: - -```bash -kubectl get nodes -``` - -It should show two nodes: - -```bash -NAME STATUS ROLES AGE VERSION -aks-nodepool1-32049705-vmss000000 Ready 9m47s v1.29.0 -aks-nodepool2-32238657-vmss000000 Ready 45s v1.29.0 -``` - -## Cleanup - -After trying out Contrast, you might want to clean up the cloud resources created in this step. -In case you've created a new resource group, you can just delete that group with - -```sh -az group delete \ - --name "${azResourceGroup:?}" -``` - -Deleting the resource group will also delete the cluster and all other related resources. - -To only cleanup the AKS cluster and node pools, run - -```sh -az aks delete \ - --resource-group "${azResourceGroup:?}" \ - --name "${azClusterName:?}" -``` diff --git a/docs/versioned_docs/version-0.7/getting-started/index.md b/docs/versioned_docs/version-0.7/getting-started/index.md deleted file mode 100644 index 71e5bd4233..0000000000 --- a/docs/versioned_docs/version-0.7/getting-started/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# Getting started - -import DocCardList from '@theme/DocCardList'; - - diff --git a/docs/versioned_docs/version-0.7/getting-started/install.md b/docs/versioned_docs/version-0.7/getting-started/install.md deleted file mode 100644 index 33152e025f..0000000000 --- a/docs/versioned_docs/version-0.7/getting-started/install.md +++ /dev/null @@ -1,13 +0,0 @@ -# Installation - -Download the Contrast CLI from the latest release: - -```bash -curl --proto '=https' --tlsv1.2 -fLo contrast https://github.com/edgelesssys/contrast/releases/download/v0.7.3/contrast -``` - -After that, install the Contrast CLI in your PATH, e.g.: - -```bash -sudo install contrast /usr/local/bin/contrast -``` diff --git a/docs/versioned_docs/version-0.7/intro.md b/docs/versioned_docs/version-0.7/intro.md deleted file mode 100644 index b8962edea0..0000000000 --- a/docs/versioned_docs/version-0.7/intro.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -slug: / -id: intro ---- - -# Contrast - -Welcome to the documentation of Contrast! Contrast runs confidential container deployments on Kubernetes at scale. - -![Contrast concept](/img/concept.svg) - -Contrast is based on the [Kata Containers](https://github.com/kata-containers/kata-containers) and -[Confidential Containers](https://github.com/confidential-containers) projects. -Confidential Containers are Kubernetes pods that are executed inside a confidential micro-VM and provide strong hardware-based isolation from the surrounding environment. -This works with unmodified containers in a lift-and-shift approach. -Contrast currently targets the [CoCo preview on AKS](https://learn.microsoft.com/en-us/azure/confidential-computing/confidential-containers-on-aks-preview). - -:::tip -See the 📄[whitepaper](https://content.edgeless.systems/hubfs/Confidential%20Computing%20Whitepaper.pdf) for more information on confidential computing. -::: - -## Goal - -Contrast is designed to keep all data always encrypted and to prevent access from the infrastructure layer. It removes the infrastructure provider from the trusted computing base (TCB). This includes access from datacenter employees, privileged cloud admins, own cluster administrators, and attackers coming through the infrastructure, for example, malicious co-tenants escalating their privileges. - -Contrast integrates fluently with the existing Kubernetes workflows. It's compatible with managed Kubernetes, can be installed as a day-2 operation and imposes only minimal changes to your deployment flow. - -## Use Cases - -Contrast provides unique security [features](basics/features.md) and [benefits](basics/security-benefits.md). The core use cases are: - -* Increasing the security of your containers -* Moving sensitive workloads from on-prem to the cloud with Confidential Computing -* Shielding the code and data even from the own cluster administrators -* Increasing the trustworthiness of your SaaS offerings -* Simplifying regulatory compliance -* Multi-party computation for data collaboration - -## Next steps - -You can learn more about the concept of [Confidential Containers](basics/confidential-containers.md), [features](basics/features.md), and [security benefits](basics/security-benefits.md) of Contrast in this section. To jump right into the action head to [*Getting started*](getting-started/index.md). diff --git a/docs/versioned_sidebars/version-0.5-sidebars.json b/docs/versioned_sidebars/version-0.5-sidebars.json deleted file mode 100644 index 9bb8b122a3..0000000000 --- a/docs/versioned_sidebars/version-0.5-sidebars.json +++ /dev/null @@ -1,182 +0,0 @@ -{ - "docs": [ - { - "type": "category", - "label": "What is Contrast?", - "collapsed": false, - "link": { - "type": "doc", - "id": "intro" - }, - "items": [ - { - "type": "doc", - "label": "Confidential Containers", - "id": "basics/confidential-containers" - }, - { - "type": "doc", - "label": "Security benefits", - "id": "basics/security-benefits" - }, - { - "type": "doc", - "label": "Features", - "id": "basics/features" - } - ] - }, - { - "type": "category", - "label": "Getting started", - "collapsed": false, - "link": { - "type": "doc", - "id": "getting-started/index" - }, - "items": [ - { - "type": "doc", - "label": "Install", - "id": "getting-started/install" - }, - { - "type": "doc", - "label": "Cluster setup", - "id": "getting-started/cluster-setup" - }, - { - "type": "doc", - "label": "First steps", - "id": "getting-started/first-steps" - } - ] - }, - { - "type": "category", - "label": "Examples", - "link": { - "type": "doc", - "id": "examples/index" - }, - "items": [ - { - "type": "doc", - "label": "Confidential emoji voting", - "id": "examples/emojivoto" - } - ] - }, - { - "type": "doc", - "label": "Workload deployment", - "id": "deployment" - }, - { - "type": "category", - "label": "Architecture", - "link": { - "type": "doc", - "id": "architecture/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": "Confidential Containers", - "id": "architecture/confidential-containers" - }, - { - "type": "category", - "label": "Attestation", - "link": { - "type": "generated-index" - }, - "items": [ - { - "type": "doc", - "label": "Hardware", - "id": "architecture/attestation/hardware" - }, - { - "type": "doc", - "label": "Pod VM", - "id": "architecture/attestation/pod-vm" - }, - { - "type": "doc", - "label": "Runtime policies", - "id": "architecture/attestation/runtime-policies" - }, - { - "type": "doc", - "label": "Manifest", - "id": "architecture/attestation/manifest" - }, - { - "type": "doc", - "label": "Coordinator", - "id": "architecture/attestation/coordinator" - } - ] - }, - { - "type": "category", - "label": "Certificates and Identities", - "link": { - "type": "generated-index" - }, - "items": [ - { - "type": "doc", - "label": "PKI", - "id": "architecture/certificates-and-identities/pki" - } - ] - }, - { - "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" - } - ] - } - ] - } - ] -} diff --git a/docs/versioned_sidebars/version-0.6-sidebars.json b/docs/versioned_sidebars/version-0.6-sidebars.json deleted file mode 100644 index ed262eaa18..0000000000 --- a/docs/versioned_sidebars/version-0.6-sidebars.json +++ /dev/null @@ -1,136 +0,0 @@ -{ - "docs": [ - { - "type": "category", - "label": "What is Contrast?", - "collapsed": false, - "link": { - "type": "doc", - "id": "intro" - }, - "items": [ - { - "type": "doc", - "label": "Confidential Containers", - "id": "basics/confidential-containers" - }, - { - "type": "doc", - "label": "Security benefits", - "id": "basics/security-benefits" - }, - { - "type": "doc", - "label": "Features", - "id": "basics/features" - } - ] - }, - { - "type": "category", - "label": "Getting started", - "collapsed": false, - "link": { - "type": "doc", - "id": "getting-started/index" - }, - "items": [ - { - "type": "doc", - "label": "Install", - "id": "getting-started/install" - }, - { - "type": "doc", - "label": "Cluster setup", - "id": "getting-started/cluster-setup" - } - ] - }, - { - "type": "category", - "label": "Examples", - "link": { - "type": "doc", - "id": "examples/index" - }, - "items": [ - { - "type": "doc", - "label": "Confidential emoji voting", - "id": "examples/emojivoto" - } - ] - }, - { - "type": "doc", - "label": "Workload deployment", - "id": "deployment" - }, - { - "type": "category", - "label": "Components", - "link": { - "type": "doc", - "id": "components/index" - }, - "items": [ - { - "type": "doc", - "label": "Runtime", - "id": "components/runtime" - }, - { - "type": "doc", - "label": "Policies", - "id": "components/policies" - }, - { - "type": "doc", - "label": "Service mesh", - "id": "components/service-mesh" - } - ] - }, - { - "type": "category", - "label": "Architecture", - "link": { - "type": "doc", - "id": "architecture/index" - }, - "items": [ - { - "type": "doc", - "label": "Attestation", - "id": "architecture/attestation" - }, - { - "type": "doc", - "label": "Certificate authority", - "id": "architecture/certificates" - } - ] - }, - { - "type": "doc", - "label": "Known limitations", - "id": "known-limitations" - }, - { - "type": "category", - "label": "About", - "link": { - "type": "doc", - "id": "about/index" - }, - "items": [ - { - "type": "doc", - "label": "Telemetry", - "id": "about/telemetry" - } - ] - } - ] -} diff --git a/docs/versioned_sidebars/version-0.7-sidebars.json b/docs/versioned_sidebars/version-0.7-sidebars.json deleted file mode 100644 index 6833af6cf6..0000000000 --- a/docs/versioned_sidebars/version-0.7-sidebars.json +++ /dev/null @@ -1,141 +0,0 @@ -{ - "docs": [ - { - "type": "category", - "label": "What is Contrast?", - "collapsed": false, - "link": { - "type": "doc", - "id": "intro" - }, - "items": [ - { - "type": "doc", - "label": "Confidential Containers", - "id": "basics/confidential-containers" - }, - { - "type": "doc", - "label": "Security benefits", - "id": "basics/security-benefits" - }, - { - "type": "doc", - "label": "Features", - "id": "basics/features" - } - ] - }, - { - "type": "category", - "label": "Getting started", - "collapsed": false, - "link": { - "type": "doc", - "id": "getting-started/index" - }, - "items": [ - { - "type": "doc", - "label": "Install", - "id": "getting-started/install" - }, - { - "type": "doc", - "label": "Cluster setup", - "id": "getting-started/cluster-setup" - } - ] - }, - { - "type": "category", - "label": "Examples", - "link": { - "type": "doc", - "id": "examples/index" - }, - "items": [ - { - "type": "doc", - "label": "Confidential emoji voting", - "id": "examples/emojivoto" - } - ] - }, - { - "type": "doc", - "label": "Workload deployment", - "id": "deployment" - }, - { - "type": "category", - "label": "Components", - "link": { - "type": "doc", - "id": "components/index" - }, - "items": [ - { - "type": "doc", - "label": "Runtime", - "id": "components/runtime" - }, - { - "type": "doc", - "label": "Policies", - "id": "components/policies" - }, - { - "type": "doc", - "label": "Service mesh", - "id": "components/service-mesh" - } - ] - }, - { - "type": "category", - "label": "Architecture", - "link": { - "type": "doc", - "id": "architecture/index" - }, - "items": [ - { - "type": "doc", - "label": "Attestation", - "id": "architecture/attestation" - }, - { - "type": "doc", - "label": "Certificate authority", - "id": "architecture/certificates" - }, - { - "type": "doc", - "label": "Observability", - "id": "architecture/observability" - } - ] - }, - { - "type": "doc", - "label": "Planned features and limitations", - "id": "features-limitations" - }, - { - "type": "category", - "label": "About", - "link": { - "type": "doc", - "id": "about/index" - }, - "items": [ - { - "type": "doc", - "label": "Telemetry", - "id": "about/telemetry" - } - ] - } - ] -} diff --git a/docs/versions.json b/docs/versions.json index c8fcca2afa..4644282b36 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -4,8 +4,5 @@ "1.1", "1.0", "0.9", - "0.8", - "0.7", - "0.6", - "0.5" + "0.8" ]