Git-Mirrors/constellation
1
0
Fork 0
mirror of https://github.com/edgelesssys/constellation.git synced 2025-02-23 16:30:11 -05:00
Code Issues Packages Projects Releases Wiki Activity

further changes

Browse Source
This commit is contained in:
david-crypto 2024-10-25 09:30:58 +02:00
parent 7ad885cea0
commit b47bbec534
6 changed files with 34 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
docs/docs/architecture/components/cli.md
View File

@ -2,10 +2,9 @@
The command-line interface (CLI) is one of the key components of Constellation and is used for **orchestrating constellation clusters**. It is run by the cloud administrator on a local machine and is used to **create, manage, and update confidential clusters** directly from the command line. The command-line interface (CLI) is one of the key components of Constellation and is used for **orchestrating constellation clusters**. It is run by the cloud administrator on a local machine and is used to **create, manage, and update confidential clusters** directly from the command line.
You can use the CLI to create a cluster on the supported cloud platforms. You can use the CLI to create a cluster on the [supported cloud platforms](../../overview/product.md). It provisions the necessary resources in your cloud environment and initiates the cluster setup.
The CLI provisions the resources in your cloud environment and initiates the initialization of your cluster.
It uses a set of parameters and an optional configuration file to manage your cluster installation. The CLI uses a set of parameters and an optional configuration file to manage your cluster installation. You can also use the CLI to update your cluster.
The CLI is also used for updating your cluster.
## Workspaces ## Workspaces
@ -35,16 +34,16 @@ Altogether, the following files are generated during the creation of a Constella
After the initialization of your cluster, the CLI will provide you with a Kubernetes `kubeconfig` file. After the initialization of your cluster, the CLI will provide you with a Kubernetes `kubeconfig` file.
This file grants you access to your Kubernetes cluster and configures the [kubectl](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) tool. This file grants you access to your Kubernetes cluster and configures the [kubectl](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) tool.
In addition, the cluster's [identifier](../old/orchestration.md#post-installation-configuration) is returned and stored in the state file. In addition, the cluster's [identifier](../components/cli.md#post-installation-configuration) is returned and stored in the state file.
### Creation flow ### Creation flow
1. The CLI `apply` command first creates the confidential VM (CVM) resources in your cloud environment and configures the network 1. The CLI `apply` command first creates the confidential VM (CVM) resources in your cloud environment and configures the network
2. Each CVM boots the Constellation node image and measures every component in the boot chain 2. Each CVM boots the Constellation node image and measures every component in the boot chain
3. The first microservice launched in each node is the [_Bootstrapper_](../old/microservices.md#bootstrapper) 3. The first microservice launched in each node is the [_Bootstrapper_](../components/microservices.md#bootstrapper)
4. The _Bootstrapper_ waits until it either receives an initialization request or discovers an initialized cluster 4. The _Bootstrapper_ waits until it either receives an initialization request or discovers an initialized cluster
5. The CLI then connects to the _Bootstrapper_ of a selected node, sends the configuration, and initiates the initialization of the cluster 5. The CLI then connects to the _Bootstrapper_ of a selected node — which we also refer to as _first node_, sends the configuration, and initiates the initialization of the cluster
6. The _Bootstrapper_ of **that** node [initializes the Kubernetes cluster](../old/microservices.md#bootstrapper) and deploys the other Constellation [microservices](microservices.md) including the [_JoinService_](microservices.md#joinservice) 6. The _Bootstrapper_ of the first node [initializes the Kubernetes cluster](../components/microservices.md#bootstrapper) and deploys the other Constellation [microservices](microservices.md) including the [_JoinService_](microservices.md#joinservice)
7. Subsequently, the _Bootstrappers_ of the other nodes discover the initialized cluster and send join requests to the _JoinService_ 7. Subsequently, the _Bootstrappers_ of the other nodes discover the initialized cluster and send join requests to the _JoinService_
8. As part of the join request each node includes an attestation statement of its boot measurements as authentication 8. As part of the join request each node includes an attestation statement of its boot measurements as authentication
9. The _JoinService_ verifies the attestation statements and joins the nodes to the Kubernetes cluster 9. The _JoinService_ verifies the attestation statements and joins the nodes to the Kubernetes cluster
@ -52,23 +51,23 @@ In addition, the cluster's [identifier](../old/orchestration.md#post-installatio
## Post-installation configuration ## Post-installation configuration
Post-installation the CLI provides a configuration for [accessing the cluster using the Kubernetes API](https://kubernetes.io/docs/tasks/administer-cluster/access-cluster-api/). After installation, the CLI provides a configuration for [accessing the cluster using the Kubernetes API](https://kubernetes.io/docs/tasks/administer-cluster/access-cluster-api/).
The `kubeconfig` file provides the credentials and configuration for connecting and authenticating to the API server.
Once configured, orchestrate the Kubernetes cluster via `kubectl`. The `kubeconfig` file contains the credentials and configuration needed for connecting and authenticating to the API server. Once configured, you can orchestrate the Kubernetes cluster via `kubectl`.
After the initialization, the CLI will present you with a couple of tokens: After the initialization, the CLI will present you with a couple of tokens:
- The [_master secret_](../old/keys.md#master-secret) (stored in the `constellation-mastersecret.json` file by default) - The [_master secret_](../security/keys.md#master-secret) (stored in the `constellation-mastersecret.json` file by default)
- The [_clusterID_](../old/keys.md#cluster-identity) of your cluster in Base64 encoding - The [_clusterID_](../security/keys.md#cluster-identity) of your cluster in Base64 encoding
You can read more about these values and their meaning in the guide on [cluster identity](../old/keys.md#cluster-identity). You can read more about these values and their meaning in the guide on [cluster identity](../security/keys.md#cluster-identity).
The _master secret_ must be kept secret and can be used to [recover your cluster](../../workflows/recovery.md). The _master secret_ must be kept secret and can be used to [recover your cluster](../../workflows/recovery.md).
Instead of managing this secret manually, you can [use your key management solution of choice](../old/keys.md#user-managed-key-management) with Constellation. Instead of managing this secret manually, you can [use your key management solution of choice](../security/keys.md#user-managed-key-management) with Constellation.
The _clusterID_ uniquely identifies a cluster and can be used to [verify your cluster](../../workflows/verify-cluster.md). The _clusterID_ uniquely identifies a cluster and can be used to [verify your cluster](../../workflows/verify-cluster.md).
## Upgrades ## Constellation Upgrades
Constellation images and microservices may need to be upgraded to new versions during the lifetime of a cluster. Constellation images and microservices may need to be upgraded to new versions during the lifetime of a cluster.
Constellation implements a rolling update mechanism ensuring no downtime of the control or data plane. Constellation implements a rolling update mechanism ensuring no downtime of the control or data plane.
@ -78,8 +77,8 @@ For step-by-step instructions on how to do this, refer to [Upgrade your cluster]
### Attestation of upgrades ### Attestation of upgrades
With every new image, corresponding measurements are released. With every new image, corresponding measurements are released.
During an update procedure, the CLI provides new measurements to the [JoinService](../old/microservices.md#joinservice) securely. During an update procedure, the CLI provides new measurements to the [JoinService](../components/microservices.md#joinservice) securely.
New measurements for an updated image are automatically pulled and verified by the CLI following the [supply chain security concept](../old/attestation.md#chain-of-trust) of Constellation. New measurements for an updated image are automatically pulled and verified by the CLI following the [supply chain security concept](../security/attestation.md#chain-of-trust) of Constellation.
The [attestation section](../old/attestation.md#cluster-facing-attestation) describes in detail how these measurements are then used by the JoinService for the attestation of nodes. The [attestation section](../security/attestation.md#cluster-facing-attestation) describes in detail how these measurements are then used by the JoinService for the attestation of nodes.
<!-- soon: As the [builds of the Constellation images are reproducible](attestation.md#chain-of-trust), the updated measurements are auditable by the customer. --> <!-- soon: As the [builds of the Constellation images are reproducible](attestation.md#chain-of-trust), the updated measurements are auditable by the customer. -->

14
docs/docs/architecture/components/microservices.md
View File

@ -45,7 +45,7 @@ Otherwise, it waits for an initialization request to create a new Kubernetes clu
The _JoinService_ runs as [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) on each control-plane node. The _JoinService_ runs as [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) on each control-plane node.
New nodes (at cluster start, or later through autoscaling) send a request to the service over [attested TLS (aTLS)](../old/attestation.md#attested-tls-atls). New nodes (at cluster start, or later through autoscaling) send a request to the service over [attested TLS (aTLS)](../old/attestation.md#attested-tls-atls).
The _JoinService_ verifies the new node's certificate and attestation statement. The _JoinService_ verifies the new node's certificate and attestation statement.
If attestation is successful, the new node is supplied with an encryption key from the [_KeyService_](microservices.md#keyservice) for its state disk, and a Kubernetes bootstrap token. If attestation is successful, the new node is supplied with an encryption key from the [_KeyService_](microservices.md#keyservice) for its state disk, and a [Kubernetes bootstrap token](https://kubernetes.io/docs/reference/access-authn-authz/bootstrap-tokens/).
```mermaid ```mermaid
sequenceDiagram sequenceDiagram
@ -61,12 +61,12 @@ sequenceDiagram
## VerificationService ## VerificationService
The _VerificationService_ runs as DaemonSet on each node. The _VerificationService_ runs as [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) on each node.
It provides user-facing functionality for remote attestation during the cluster's lifetime via an endpoint for [verifying the cluster](../old/attestation.md#cluster-attestation). It provides user-facing functionality for remote attestation during the cluster's lifetime via an endpoint for [verifying the cluster](../security/attestation.md#cluster-attestation).
Read more about the hardware-based [attestation feature](../old/attestation.md) of Constellation and how to [verify](../../workflows/verify-cluster.md) a cluster on the client side. Read more about the hardware-based [attestation feature](../security/attestation.md) of Constellation and how to [verify](../../workflows/verify-cluster.md) a cluster on the client side.
## KeyService ## KeyService
The _KeyService_ runs as DaemonSet on each control-plane node. The _KeyService_ runs as [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) on each control-plane node.
It implements the key management for the [storage encryption keys](../old/keys.md#storage-encryption) in Constellation. These keys are used for the [state disk](../old/images.md#state-disk) of each node and the [transparently encrypted storage](../old/encrypted-storage.md) for Kubernetes. It implements the key management for the [storage encryption keys](../security/keys.md#storage-encryption) in Constellation. These keys are used for the [state disk](../components/node-images.md#state-disk) of each node and the [transparently encrypted storage](../security/encrypted-storage.md) for Kubernetes.
Depending on wether the [constellation-managed](../old/keys.md#constellation-managed-key-management) or [user-managed](../old/keys.md#user-managed-key-management) mode is used, the _KeyService_ holds the key encryption key (KEK) directly or calls an external key management service (KMS) for key derivation respectively. Depending on wether the [constellation-managed](../security/keys.md#constellation-managed-key-management) or [user-managed](../security/keys.md#user-managed-key-management) mode is used, the _KeyService_ holds the key encryption key (KEK) directly or calls an external key management service (KMS) for key derivation respectively.

4
docs/docs/architecture/components/node-images.md
View File

@ -43,9 +43,9 @@ In addition to the read-only root filesystem, each Constellation node has a disk
This disk is mounted readable and writable by the initramfs and contains data that should persist across reboots. This disk is mounted readable and writable by the initramfs and contains data that should persist across reboots.
Such data can contain sensitive information and, therefore, must be stored securely. Such data can contain sensitive information and, therefore, must be stored securely.
To that end, the state disk is protected by authenticated encryption. To that end, the state disk is protected by authenticated encryption.
See the section on [keys and encryption](../old/keys.md#storage-encryption) for more information on the cryptographic primitives in use. See the section on [keys and encryption](../security/keys.md#storage-encryption) for more information on the cryptographic primitives in use.
## Kubernetes components ## Kubernetes components
During initialization, the [_Bootstrapper_](../old/microservices.md#bootstrapper) downloads and verifies the [Kubernetes components](https://kubernetes.io/docs/concepts/overview/components/) as configured by the user. During initialization, the [_Bootstrapper_](../components/microservices.md#bootstrapper) downloads and verifies the [Kubernetes components](https://kubernetes.io/docs/concepts/overview/components/) as configured by the user.
They're stored on the state partition and can be updated once new releases need to be installed. They're stored on the state partition and can be updated once new releases need to be installed.

4
docs/docs/architecture/intro.md
View File

@ -2,8 +2,8 @@
This section of the documentation provides a comprehensive overview of Constellation's inner workings. It explains the chain of trust between the different components and how they ensure robust protection of your workloads. The main chapters include: This section of the documentation provides a comprehensive overview of Constellation's inner workings. It explains the chain of trust between the different components and how they ensure robust protection of your workloads. The main chapters include:
- [**Protocol overview**](./overview.md): The best **starting point** for exploring the architecture documentation. This chapter provides an overview of Constellation's architecture and explains the underlying security protocol used to achieve confidentiality. - [**Protocol overview**](./overview.md): The recommended **starting point** for exploring the architecture documentation. This chapter provides an overview of Constellation's architecture and explains the underlying security protocol used to achieve confidentiality and thorough protection.
- [**Key components**](./components/cli.md): This chapter outlines Constellation's key components, their main purposes, and how users interact with them. - [**Key components**](./components/cli.md): This chapter outlines Constellation's key components, their main purposes, and how users interact with them.
- [**Protection mechanisms**](./security/attestation.md): A deeper dive into how various implemented concepts deliver such strong protection guarantees. - [**Protection mechanisms**](./security/attestation.md): A deeper dive into how various implemented concepts deliver such strong protection guarantees for your Kubernetes clusters.
- [**Observability**](./observability.md): In a Kubernetes context, observability is essential for identifying and resolving issues effectively. This chapter explains Constellation's observability capabilities. - [**Observability**](./observability.md): In a Kubernetes context, observability is essential for identifying and resolving issues effectively. This chapter explains Constellation's observability capabilities.
- [**Versions**](./versions.md): Provides an overview of Constellation's versions and support policy. - [**Versions**](./versions.md): Provides an overview of Constellation's versions and support policy.

52
docs/docs/architecture/security/attestation.md
View File

@ -113,7 +113,7 @@ The runtime measurements consist of two types of values:
The [signed image measurements](#chain-of-trust) include measurements that are known, previously observed values. The [signed image measurements](#chain-of-trust) include measurements that are known, previously observed values.
- **Measurements produced by the Constellation bootloader and boot chain**: - **Measurements produced by the Constellation bootloader and boot chain**:
The Constellation Bootloader takes over from the CVM firmware and [measures the rest of the boot chain](../components/node-images.md). The Constellation bootloader takes over from the CVM firmware and [measures the rest of the boot chain](../components/node-images.md).
The Constellation [Bootstrapper](../components/microservices.md#bootstrapper) is the first user mode component that runs in a Constellation image. The Constellation [Bootstrapper](../components/microservices.md#bootstrapper) is the first user mode component that runs in a Constellation image.
It extends PCR registers with the [IDs](keys.md#cluster-identity) of the cluster marking a node as initialized. It extends PCR registers with the [IDs](keys.md#cluster-identity) of the cluster marking a node as initialized.
@ -336,9 +336,9 @@ There is no additional configuration available for STACKIT.
## Cluster attestation ## Cluster attestation
Cluster-facing, Constellation's [_JoinService_](../components/microservices.md#joinservice) verifies each node joining the cluster given the configured ground truth runtime measurements. Cluster-facing, Constellation's [_JoinService_](../components/microservices.md#joinservice) verifies each node joining the cluster given the configured ground-truth runtime measurements that serve as a reference for a trusted cluster state.
User-facing, the [_VerificationService_](../components/microservices.md#verificationservice) provides an interface to verify a node using remote attestation. User-facing, the [_VerificationService_](../components/microservices.md#verificationservice) provides an interface to verify a node using remote attestation.
By verifying the first node during the [initialization](../components/microservices.md#bootstrapper) and configuring the ground truth measurements that are subsequently enforced by the _JoinService_, the whole cluster is verified in a transitive way. By verifying the first node during the [initialization](../components/microservices.md#bootstrapper) and configuring the reference measurements that are subsequently enforced by the _JoinService_, the whole cluster is verified in a transitive way.
### Cluster-facing attestation ### Cluster-facing attestation
@ -358,51 +358,7 @@ A user can [verify](../../workflows/verify-cluster.md) this statement and compar
## Putting it all together ## Putting it all together
This section puts the aforementioned concepts together and illustrate how trust into a Constellation cluster is established and maintained. An overview of how these concepts are applied and how the different components are interacting with each other is given in our [protocol overview](../overview.md).
### CLI and node images
It all starts with the CLI executable. The CLI is signed by Edgeless Systems. To ensure non-repudiability for CLI releases, Edgeless Systems publishes corresponding signatures to the public ledger of the [sigstore project](https://www.sigstore.dev/). There's a [step-by-step guide](../../workflows/verify-cli.md) on how to verify CLI signatures based on sigstore.
The CLI contains the latest runtime measurements of the Constellation node image for all supported cloud platforms. In case a different version of the node image is to be used, the corresponding runtime measurements can be fetched using the CLI's [fetch-measurements command](../../reference/cli.md#constellation-config-fetch-measurements). This command downloads the runtime measurements and the corresponding signature from cdn.confidential.cloud. See for example the following files corresponding to node image v2.16.3:
- [Measurements](https://cdn.confidential.cloud/constellation/v2/ref/-/stream/stable/v2.16.3/image/measurements.json)
- [Signature](https://cdn.confidential.cloud/constellation/v2/ref/-/stream/stable/v2.16.3/image/measurements.json.sig)
The CLI contains the long-term public key of Edgeless Systems to verify the signature of downloaded runtime measurements.
### Cluster creation
When a cluster is [created](../../workflows/create.md), the CLI automatically verifies the runtime measurements of the _first node_ using remote attestation. Based on this, the CLI and the first node set up a temporary TLS connection. This [aTLS](#attested-tls-atls) connection is used for two things:
1. The CLI sends the [master secret](keys.md#master-secret) of the to-be-created cluster to the CLI. The master secret is generated by the first node.
2. The first node sends a [kubeconfig file](https://www.redhat.com/sysadmin/kubeconfig) with Kubernetes credentials to the CLI.
After this, the aTLS connection is closed and the first node bootstraps the Kubernetes cluster. All subsequent interactions between the CLI and the cluster go via the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/) server running inside the cluster. The CLI (and other tools like kubectl) use the credentials referenced by the kubeconfig file to authenticate themselves towards the Kubernetes API server and to establish a mTLS connection.
The CLI connects to the Kubernetes API to write the runtime measurements for the applicable node image to etcd. The JoinService uses these runtime measurements to verify all nodes that join the cluster subsequently.
### Chain of trust
In summary, there's a chain of trust based on cryptographic signatures that goes from the user to the cluster via the CLI. This is illustrated in the following diagram.
```mermaid
flowchart LR
A[User]-- "verifies" -->B[CLI]
B[CLI]-- "verifies" -->C([Runtime measurements])
D[Edgeless Systems]-- "signs" -->B[CLI]
D[Edgeless Systems]-- "signs" -->C([Runtime measurements])
B[CLI]-- "verifies (remote attestation)" -->E[First node]
E[First node]-- "verifies (remote attestation)" -->F[Other nodes]
C([Runtime measurements]) -.-> E[First node]
C([Runtime measurements]) -.-> F[Other nodes]
```
### Upgrades
Whenever a cluster is [upgraded](../../workflows/upgrade.md) to a new version of the node image, the CLI sends the corresponding runtime measurements via the Kubernetes API server. The new runtime measurements are stored in etcd within the cluster and replace any previous runtime measurements. The new runtime measurements are then used automatically by the JoinService for the verification of new nodes.
## References
[^1]: [^1]:
Linux IMA produces runtime measurements of user-space binaries. Linux IMA produces runtime measurements of user-space binaries.

2
docs/sidebars.js
View File

@ -257,7 +257,7 @@ const sidebars = {
}, },
{ {
type: "doc", type: "doc",
label: "Core Services", label: "Core services",
id: "architecture/components/microservices", id: "architecture/components/microservices",
}, },
], ],