mirror of
https://github.com/edgelesssys/constellation.git
synced 2024-09-19 15:56:03 +00:00
docs: improve wording
This commit is contained in:
Thomas Tendyck
Thomas Tendyck
parent
8004edcc14
commit
92d97e117a
@ -33,7 +33,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
<!-- For changes in existing functionality. -->
|
||||
<!-- TODO: Remove `/next/` from URL before release -->
|
||||
- Constellation operators are now deployed using Helm.
|
||||
- Updated the config version to v2. Check [how to migrate your config](https://constellation-docs.edgeless.systems/constellation/next/reference/config-migration).
|
||||
- Updated the config version to v2. Check [how to migrate your config](https://docs.edgeless.systems/constellation/next/reference/config-migration).
|
||||
- OS images are now configured globally in the `images` field of the configuration file.
|
||||
- The `measurements` entry in the CLI now uses an updated format, merging `enforcedMeasurements` and old `measurements` into one
|
||||
- Expected measurements in the config and Constellation's Cluster-ID are now hex encoded by default. Base64 is still supported.
|
||||
|
||||
@ -21,16 +21,15 @@ flowchart LR
|
||||
C[Bootstrapper]
|
||||
end
|
||||
subgraph Kubernetes
|
||||
E[JoinService]
|
||||
F[KMS]
|
||||
G[VerificationService]
|
||||
D[JoinService]
|
||||
E[KMS]
|
||||
F[VerificationService]
|
||||
end
|
||||
A -- deploys -->
|
||||
B -- starts --> C
|
||||
C -- deploys --> D
|
||||
C -- deploys --> E
|
||||
C -- deploys --> F
|
||||
C -- deploys --> G
|
||||
```
|
||||
|
||||
## Bootstrapper
|
||||
|
||||
@ -1,11 +1,11 @@
|
||||
# Configuration Migrations
|
||||
# Configuration migrations
|
||||
|
||||
This document describes breaking changes in the configuration file format between Constellation releases.
|
||||
|
||||
## Migrating from CLI versions < 2.3
|
||||
## Migrating from CLI versions before 2.3
|
||||
|
||||
- The `sshUsers` was deprecated in v2.2 and has now been removed from the configuration in v2.3.
|
||||
As an alternative for SSH, check the workflow section [Connect to nodes](https://constellation-docs.edgeless.systems/constellation/workflows/troubleshooting#connect-to-nodes).
|
||||
- The `sshUsers` field was deprecated in v2.2 and has been removed from the configuration in v2.3.
|
||||
As an alternative for SSH, check the workflow section [Connect to nodes](../workflows/troubleshooting.md#connect-to-nodes).
|
||||
- The `image` field for each cloud service provider has been replaced with a global `image` field. Use the following mapping to migrate your configuration:
|
||||
<details>
|
||||
<summary>Show all</summary>
|
||||
|
||||
@ -56,7 +56,7 @@ constellation create --control-plane-nodes 1 --worker-nodes 2
|
||||
|
||||
For details on the flags, consult the command help via `constellation create -h`.
|
||||
|
||||
*create* stores your cluster's state into a [`terraform.tfstate`](../architecture/orchestration.md#cluster-creation-process) file in your current directory.
|
||||
*create* stores your cluster's state into a [`terraform.tfstate`](../architecture/orchestration.md#cluster-creation-process) file in your workspace.
|
||||
|
||||
## The *init* step
|
||||
|
||||
|
||||
@ -54,7 +54,7 @@ Note that in case the options above aren't a suitable solution for you, Constell
|
||||
|
||||
## Installation
|
||||
|
||||
The Constellation CLI will automatically install Constellation's CSI driver for the selected CSP in your cluster.
|
||||
The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster.
|
||||
If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file.
|
||||
|
||||
<tabs groupId="csp">
|
||||
@ -72,15 +72,16 @@ Azure comes with two storage classes by default.
|
||||
* Encryption of all data written to disk
|
||||
* Integrity protection of data written to disk
|
||||
|
||||
For more info on encryption algorithms and key sizes, please refer to [cryptographic-algorithms](../architecture/encrypted-storage.md#cryptographic-algorithms).
|
||||
For more information on encryption algorithms and key sizes, refer to [cryptographic algorithms](../architecture/encrypted-storage.md#cryptographic-algorithms).
|
||||
|
||||
:::info
|
||||
|
||||
The default storage class is set to `encrypted-rwo` for performance reasons.
|
||||
If you want integrity-protected storage, set the `storageClassName` parameter of your persistent volume claim to `integrity-encrypted-rwo`
|
||||
If you want integrity-protected storage, set the `storageClassName` parameter of your persistent volume claim to `integrity-encrypted-rwo`.
|
||||
|
||||
Alternatively, you can create your own storage class with integrity protection enabled by adding `csi.storage.k8s.io/fstype: ext4-integrity` to the class `parameters`.
|
||||
Or use another filesystem by specifying another file system type with the suffix `-integrity`.
|
||||
For example `csi.storage.k8s.io/fstype: xfs-integrity`.
|
||||
Or use another filesystem by specifying another file system type with the suffix `-integrity`, e.g., `csi.storage.k8s.io/fstype: xfs-integrity`.
|
||||
|
||||
Note that volume expansion isn't supported for integrity-protected disks.
|
||||
|
||||
:::
|
||||
@ -91,7 +92,7 @@ Note that volume expansion isn't supported for integrity-protected disks.
|
||||
GCP comes with two storage classes by default.
|
||||
|
||||
* `encrypted-rwo`
|
||||
* Uses [standard persistent-disks](https://cloud.google.com/compute/docs/disks#pdspecs)
|
||||
* Uses [standard persistent disks](https://cloud.google.com/compute/docs/disks#pdspecs)
|
||||
* ext-4 filesystem
|
||||
* Encryption of all data written to disk
|
||||
* `integrity-encrypted-rwo`
|
||||
@ -100,15 +101,16 @@ GCP comes with two storage classes by default.
|
||||
* Encryption of all data written to disk
|
||||
* Integrity protection of data written to disk
|
||||
|
||||
For more info on encryption algorithms and key sizes, please refer to [cryptographic-algorithms](../architecture/encrypted-storage.md#cryptographic-algorithms).
|
||||
For more information on encryption algorithms and key sizes, refer to [cryptographic algorithms](../architecture/encrypted-storage.md#cryptographic-algorithms).
|
||||
|
||||
:::info
|
||||
|
||||
The default storage class is set to `encrypted-rwo` for performance reasons.
|
||||
If you want integrity-protected storage, set the `storageClassName` parameter of your persistent volume claim to `integrity-encrypted-rwo`
|
||||
If you want integrity-protected storage, set the `storageClassName` parameter of your persistent volume claim to `integrity-encrypted-rwo`.
|
||||
|
||||
Alternatively, you can create your own storage class with integrity protection enabled by adding `csi.storage.k8s.io/fstype: ext4-integrity` to the class `parameters`.
|
||||
Or use another filesystem by specifying another file system type with the suffix `-integrity`.
|
||||
For example `csi.storage.k8s.io/fstype: xfs-integrity`.
|
||||
Or use another filesystem by specifying another file system type with the suffix `-integrity`, e.g., `csi.storage.k8s.io/fstype: xfs-integrity`.
|
||||
|
||||
Note that volume expansion isn't supported for integrity-protected disks.
|
||||
|
||||
:::
|
||||
|
||||
@ -1,16 +1,16 @@
|
||||
# Upgrade your cluster
|
||||
|
||||
Constellation provides an easy way to upgrade to the next release.
|
||||
This involves updating the CLI, choosing a new VM image to use for all nodes in the cluster and updating the cluster's expected measurements.
|
||||
This involves updating the CLI, choosing a new VM image to use for all nodes in the cluster, and updating the cluster's expected measurements.
|
||||
|
||||
## Update the CLI
|
||||
|
||||
New features and bug fixes are added to the CLI with every release. To use them, you need to update the CLI to the latest version by following the instructions in the [installation guide](../getting-started/install.md).
|
||||
New features and bug fixes are added to the CLI with every release. To use them, update the CLI to the latest version by following the instructions in the [installation guide](../getting-started/install.md).
|
||||
|
||||
## Migrate the configuration
|
||||
|
||||
The Constellation configuration file is located in the file `constellation-conf.yaml` in the current working directory.
|
||||
Refer to the [migration reference](../reference/config-migration.md) to check if fields in your configuration file need to be updated.
|
||||
The Constellation configuration file is located in the file `constellation-conf.yaml` in your workspace.
|
||||
Refer to the [migration reference](../reference/config-migration.md) to check if you need to update fields in your configuration file.
|
||||
|
||||
## Plan the upgrade
|
||||
|
||||
|
||||
@ -40,33 +40,9 @@ tlog entry verified with uuid: afaba7f6635b3e058888692841848e5514357315be9528474
|
||||
Verified OK
|
||||
```
|
||||
|
||||
## Verify the provenance
|
||||
|
||||
Provenance attests that a software artifact was produced by a specific repository and build system invocation. For more information on provenance visit [slsa.dev](https://slsa.dev/provenance/v0.2). We've also detailed our [adoption of SLSA](../reference/slsa.md).
|
||||
|
||||
Just as checking the signature on the CLI proves that the CLI wasn't manipulated, checking the provenance proves that the artifact was produced by our build process and hasn't been tampered with.
|
||||
|
||||
First, download the [slsa-verifier](https://github.com/slsa-framework/slsa-verifier). Then make sure you have the provenance file (`constellation.intoto.jsonl`) and Constellation CLI downloaded. Both are available on our [GitHub release page](https://github.com/edgelesssys/constellation/releases).
|
||||
|
||||
:::info
|
||||
The same provenance file is valid for all Constellation CLI binaries of a given version. Independent of the architecture and the OS the CLI was build for.
|
||||
:::
|
||||
|
||||
Then use the verifier to perform the check:
|
||||
|
||||
```sh
|
||||
$ slsa-verifier verify-artifact constellation-linux-amd64 \
|
||||
--provenance-path constellation.intoto.jsonl \
|
||||
--source-uri github.com/edgelesssys/constellation
|
||||
|
||||
Verified signature against tlog entry index 7771317 at URL: https://rekor.sigstore.dev/api/v1/log/entries/24296fb24b8ad77af2c04c8b4ae0d5bc5...
|
||||
Verified build using builder https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v1.2.2 at commit 18e9924b416323c37b9cdfd6cc728de8a947424a
|
||||
PASSED: Verified SLSA provenance
|
||||
```
|
||||
|
||||
🏁 You now know that your CLI executable was officially released and signed by Edgeless Systems.
|
||||
|
||||
## Optional: Manually inspect the transparency log
|
||||
### Optional: Manually inspect the transparency log
|
||||
|
||||
To further inspect the public Rekor transparency log, [install the Rekor CLI](https://docs.sigstore.dev/rekor/installation). A search for the CLI executable should give a single UUID. (Note that this UUID contains the UUID from the previous `cosign` command.)
|
||||
|
||||
@ -112,3 +88,27 @@ rekor-cli search --public-key https://edgeless.systems/es.pub --pki-format x509
|
||||
```
|
||||
|
||||
Edgeless Systems monitors this list to detect potential unauthorized use of its private key.
|
||||
|
||||
## Verify the provenance
|
||||
|
||||
Provenance attests that a software artifact was produced by a specific repository and build system invocation. For more information on provenance visit [slsa.dev](https://slsa.dev/provenance/v0.2) and learn about the [adoption of SLSA for Constellation](../reference/slsa.md).
|
||||
|
||||
Just as checking its signature proves that the CLI hasn't been manipulated, checking the provenance proves that the artifact was produced by the expected build process and hasn't been tampered with.
|
||||
|
||||
To verify the provenance, first install the [slsa-verifier](https://github.com/slsa-framework/slsa-verifier). Then make sure you have the provenance file (`constellation.intoto.jsonl`) and Constellation CLI downloaded. Both are available on the [GitHub release page](https://github.com/edgelesssys/constellation/releases).
|
||||
|
||||
:::info
|
||||
The same provenance file is valid for all Constellation CLI executables of a given version independent of the target platform.
|
||||
:::
|
||||
|
||||
Use the verifier to perform the check:
|
||||
|
||||
```shell-session
|
||||
$ slsa-verifier verify-artifact constellation-linux-amd64 \
|
||||
--provenance-path constellation.intoto.jsonl \
|
||||
--source-uri github.com/edgelesssys/constellation
|
||||
|
||||
Verified signature against tlog entry index 7771317 at URL: https://rekor.sigstore.dev/api/v1/log/entries/24296fb24b8ad77af2c04c8b4ae0d5bc5...
|
||||
Verified build using builder https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v1.2.2 at commit 18e9924b416323c37b9cdfd6cc728de8a947424a
|
||||
PASSED: Verified SLSA provenance
|
||||
```
|
||||
|
||||
@ -16,7 +16,7 @@ This command performs the following steps:
|
||||
2. Verify the signature of the measurements. This will use Edgeless Systems' [public key](https://edgeless.systems/es.pub).
|
||||
3. Write measurements into configuration file.
|
||||
|
||||
The configuration file then contains a list of `measurements` looking similar to the following:
|
||||
The configuration file then contains a list of `measurements` similar to the following:
|
||||
|
||||
```yaml
|
||||
# ...
|
||||
@ -54,12 +54,11 @@ measurements:
|
||||
# ...
|
||||
```
|
||||
|
||||
Each entry specifies the expected value of the Constellation, and whether the measurement should be enforced (`warnOnly: false`), or only a warning should be logged (`warnOnly: true`).
|
||||
|
||||
This is because only a subset of the [available measurements](../architecture/attestation.md#runtime-measurements) can be locally reproduced and verified.
|
||||
Each entry specifies the expected value of the Constellation node, and whether the measurement should be enforced (`warnOnly: false`), or only a warning should be logged (`warnOnly: true`).
|
||||
By default, the subset of the [available measurements](../architecture/attestation.md#runtime-measurements) that can be locally reproduced and verified is enforced.
|
||||
|
||||
During attestation, the validating side (CLI or [join service](../architecture/components.md#joinservice)) compares each measurement reported by the issuing side (first node or joining node) individually.
|
||||
For mismatching measurements that have set `warnOnly` to `true` only warning is emitted.
|
||||
For mismatching measurements that have set `warnOnly` to `true` only a warning is emitted.
|
||||
For mismatching measurements that have set `warnOnly` to `false` an error is emitted and attestation fails.
|
||||
If attestation fails for a new node, it isn't permitted to join the cluster.
|
||||
|
||||
|
||||
@ -168,9 +168,9 @@ The latter means that the value can be generated offline and compared to the one
|
||||
| PCR | Components | Measured by | Reproducible and verifiable |
|
||||
| ----------- | ---------------------------------------------------------------- | ----------------------------- | --------------------------- |
|
||||
| 0 | CVM constant string | GCP | No |
|
||||
| 1 | Reserved | GCP | No |
|
||||
| 2 | Reserved | GCP | No |
|
||||
| 3 | Reserved | GCP | No |
|
||||
| 1 | Firmware | GCP | No |
|
||||
| 2 | Firmware | GCP | No |
|
||||
| 3 | Firmware | GCP | No |
|
||||
| 4 | Constellation Bootloader, Kernel, initramfs, Kernel command line | GCP, Constellation Bootloader | Yes |
|
||||
| 5 | Disk GUID partition table | GCP | No |
|
||||
| 6 | Disk GUID partition table | GCP | No |
|
||||
@ -185,6 +185,38 @@ The latter means that the value can be generated offline and compared to the one
|
||||
| 15 | ClusterID | Constellation Bootstrapper | Yes |
|
||||
| 16–23 | Unused | - | - |
|
||||
|
||||
</tabItem>
|
||||
<tabItem value="aws" label="AWS">
|
||||
|
||||
Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements.
|
||||
|
||||
The vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification.
|
||||
The VMs are attested by obtaining signed PCR values over the VM's boot configuration from the TPM and comparing them to a known, good state (measured boot).
|
||||
|
||||
The following table lists all PCR values of the vTPM and the measured components.
|
||||
It also lists what components of the boot chain did the measurements and if the value is reproducible and verifiable.
|
||||
The latter means that the value can be generated offline and compared to the one in the vTPM.
|
||||
|
||||
| PCR | Components | Measured by | Reproducible and verifiable |
|
||||
| ----------- | ---------------------------------------------------------------- | ----------------------------- | --------------------------- |
|
||||
| 0 | Firmware | AWS | No |
|
||||
| 1 | Firmware | AWS | No |
|
||||
| 2 | Firmware | AWS | No |
|
||||
| 3 | Firmware | AWS | No |
|
||||
| 4 | Constellation Bootloader, Kernel, initramfs, Kernel command line | AWS, Constellation Bootloader | Yes |
|
||||
| 5 | Firmware | AWS | No |
|
||||
| 6 | Firmware | AWS | No |
|
||||
| 7 | Secure Boot Policy | AWS, Constellation Bootloader | No |
|
||||
| 8 | Kernel command line | Constellation Bootloader | Yes |
|
||||
| 9 | initramfs | Linux Kernel | Yes |
|
||||
| 10 | Reserved | - | No |
|
||||
| 11 | Reserved for Unified Kernel Image components | (Constellation Bootloader) | Yes |
|
||||
| 12 | Reserved | (Constellation Bootloader) | Yes |
|
||||
| 13 | Reserved | (Constellation Bootloader) | Yes |
|
||||
| 14 | Secure Boot State | Constellation Bootloader | No |
|
||||
| 15 | ClusterID | Constellation Bootstrapper | Yes |
|
||||
| 16–23 | Unused | - | - |
|
||||
|
||||
</tabItem>
|
||||
</tabs>
|
||||
|
||||
|
||||
@ -64,7 +64,7 @@ constellation create --control-plane-nodes 1 --worker-nodes 2
|
||||
|
||||
For details on the flags, consult the command help via `constellation create -h`.
|
||||
|
||||
*create* stores your cluster's state into a [`terraform.tfstate`](../architecture/orchestration.md#cluster-creation-process) file in your current directory.
|
||||
*create* stores your cluster's state into a [`terraform.tfstate`](../architecture/orchestration.md#cluster-creation-process) file in your workspace.
|
||||
|
||||
## The *init* step
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@ allowing users to mount storage solutions directly into containers.
|
||||
The [Container Storage Interface (CSI)](https://kubernetes-csi.github.io/docs/) is the standard interface for exposing arbitrary block and file storage systems into containers in Kubernetes.
|
||||
Cloud service providers (CSPs) offer their own CSI-based solutions for cloud storage.
|
||||
|
||||
### Confidential storage
|
||||
## Confidential storage
|
||||
|
||||
Most cloud storage solutions support encryption, such as [GCE Persistent Disks (PD)](https://cloud.google.com/kubernetes-engine/docs/how-to/using-cmek).
|
||||
Constellation supports the available CSI-based storage options for Kubernetes engines in Azure and GCP.
|
||||
|
||||
@ -11,6 +11,7 @@ constellation config fetch-measurements
|
||||
```
|
||||
|
||||
This command performs the following steps:
|
||||
|
||||
1. Download the signed measurements for the configured image. By default, this will use Edgeless Systems' public measurement registry.
|
||||
2. Verify the signature of the measurements. This will use Edgeless Systems' [public key](https://edgeless.systems/es.pub).
|
||||
3. Write measurements into configuration file.
|
||||
@ -37,6 +38,7 @@ constellation verify [--cluster-id ...]
|
||||
```
|
||||
|
||||
From the attestation statement, the command verifies the following properties:
|
||||
|
||||
* The cluster is using the correct Confidential VM (CVM) type.
|
||||
* Inside the CVMs, the correct node images are running. The node images are identified through the measurements obtained in the previous step.
|
||||
* The unique ID of the cluster matches the one from your `constellation-id.json` file or passed in via `--cluster-id`.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user