Git-Mirrors/constellation
1
0
Fork 0
mirror of https://github.com/edgelesssys/constellation.git synced 2024-10-01 01:36:09 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: improve wording

Browse Source
This commit is contained in:
Thomas Tendyck 2022-11-30 12:12:41 +01:00 committed by Thomas Tendyck
parent 8004edcc14
commit 92d97e117a
12 changed files with 93 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@ -33,7 +33,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
<!-- For changes in existing functionality. --> <!-- For changes in existing functionality. -->
<!-- TODO: Remove `/next/` from URL before release --> <!-- TODO: Remove `/next/` from URL before release -->
- Constellation operators are now deployed using Helm. - 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. - 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 - 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. - Expected measurements in the config and Constellation's Cluster-ID are now hex encoded by default. Base64 is still supported.

7
docs/docs/architecture/components.md
View File

@ -21,16 +21,15 @@ flowchart LR
C[Bootstrapper] C[Bootstrapper]
end end
subgraph Kubernetes subgraph Kubernetes
E[JoinService] D[JoinService]
F[KMS] E[KMS]
G[VerificationService] F[VerificationService]
end end
A -- deploys --> A -- deploys -->
B -- starts --> C B -- starts --> C
C -- deploys --> D C -- deploys --> D
C -- deploys --> E C -- deploys --> E
C -- deploys --> F C -- deploys --> F
C -- deploys --> G
``` ```
## Bootstrapper ## Bootstrapper

8
docs/docs/reference/config-migration.md
View File

@ -1,11 +1,11 @@
# Configuration Migrations # Configuration migrations
This document describes breaking changes in the configuration file format between Constellation releases. 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. - 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](https://constellation-docs.edgeless.systems/constellation/workflows/troubleshooting#connect-to-nodes). 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: - 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> <details>
<summary>Show all</summary> <summary>Show all</summary>

2
docs/docs/workflows/create.md
View File

@ -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`. 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 ## The *init* step

22
docs/docs/workflows/storage.md
View File

@ -54,7 +54,7 @@ Note that in case the options above aren't a suitable solution for you, Constell
## Installation ## 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. 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"> <tabs groupId="csp">
@ -72,15 +72,16 @@ Azure comes with two storage classes by default.
* Encryption of all data written to disk * Encryption of all data written to disk
* Integrity protection of 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 :::info
The default storage class is set to `encrypted-rwo` for performance reasons. 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`. 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`. Or use another filesystem by specifying another file system type with the suffix `-integrity`, e.g., `csi.storage.k8s.io/fstype: xfs-integrity`.
For example `csi.storage.k8s.io/fstype: xfs-integrity`.
Note that volume expansion isn't supported for integrity-protected disks. 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. GCP comes with two storage classes by default.
* `encrypted-rwo` * `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 * ext-4 filesystem
* Encryption of all data written to disk * Encryption of all data written to disk
* `integrity-encrypted-rwo` * `integrity-encrypted-rwo`
@ -100,15 +101,16 @@ GCP comes with two storage classes by default.
* Encryption of all data written to disk * Encryption of all data written to disk
* Integrity protection of 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 :::info
The default storage class is set to `encrypted-rwo` for performance reasons. 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`. 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`. Or use another filesystem by specifying another file system type with the suffix `-integrity`, e.g., `csi.storage.k8s.io/fstype: xfs-integrity`.
For example `csi.storage.k8s.io/fstype: xfs-integrity`.
Note that volume expansion isn't supported for integrity-protected disks. Note that volume expansion isn't supported for integrity-protected disks.
::: :::

8
docs/docs/workflows/upgrade.md
View File

@ -1,16 +1,16 @@
# Upgrade your cluster # Upgrade your cluster
Constellation provides an easy way to upgrade to the next release. 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 ## 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 ## Migrate the configuration
The Constellation configuration file is located in the file `constellation-conf.yaml` in the current working directory. 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 fields in your configuration file need to be updated. Refer to the [migration reference](../reference/config-migration.md) to check if you need to update fields in your configuration file.
## Plan the upgrade ## Plan the upgrade

50
docs/docs/workflows/verify-cli.md
View File

@ -40,33 +40,9 @@ tlog entry verified with uuid: afaba7f6635b3e058888692841848e5514357315be9528474
Verified OK 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. 🏁 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.) 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. 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
```

9
docs/docs/workflows/verify-cluster.md
View File

@ -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). 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. 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 ```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`). 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.
This is because only a subset of the [available measurements](../architecture/attestation.md#runtime-measurements) can be locally reproduced and verified.
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. 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. 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. If attestation fails for a new node, it isn't permitted to join the cluster.

38
docs/versioned_docs/version-2.2/architecture/attestation.md
View File

@ -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 | | PCR | Components | Measured by | Reproducible and verifiable |
| ----------- | ---------------------------------------------------------------- | ----------------------------- | --------------------------- | | ----------- | ---------------------------------------------------------------- | ----------------------------- | --------------------------- |
| 0 | CVM constant string | GCP | No | | 0 | CVM constant string | GCP | No |
| 1 | Reserved | GCP | No | | 1 | Firmware | GCP | No |
| 2 | Reserved | GCP | No | | 2 | Firmware | GCP | No |
| 3 | Reserved | GCP | No | | 3 | Firmware | GCP | No |
| 4 | Constellation Bootloader, Kernel, initramfs, Kernel command line | GCP, Constellation Bootloader | Yes | | 4 | Constellation Bootloader, Kernel, initramfs, Kernel command line | GCP, Constellation Bootloader | Yes |
| 5 | Disk GUID partition table | GCP | No | | 5 | Disk GUID partition table | GCP | No |
| 6 | 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 | | 15 | ClusterID | Constellation Bootstrapper | Yes |
| 16&ndash;23 | Unused | - | - | | 16&ndash;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&ndash;23 | Unused | - | - |
</tabItem> </tabItem>
</tabs> </tabs>

2
docs/versioned_docs/version-2.2/workflows/create.md
View File

@ -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`. 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 ## The *init* step

2
docs/versioned_docs/version-2.2/workflows/storage.md
View File

@ -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. 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. 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). 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. Constellation supports the available CSI-based storage options for Kubernetes engines in Azure and GCP.

2
docs/versioned_docs/version-2.2/workflows/verify-cluster.md
View File

@ -11,6 +11,7 @@ constellation config fetch-measurements
``` ```
This command performs the following steps: 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. 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). 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. 3. Write measurements into configuration file.
@ -37,6 +38,7 @@ constellation verify [--cluster-id ...]
``` ```
From the attestation statement, the command verifies the following properties: From the attestation statement, the command verifies the following properties:
* The cluster is using the correct Confidential VM (CVM) type. * 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. * 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`. * The unique ID of the cluster matches the one from your `constellation-id.json` file or passed in via `--cluster-id`.