mirror of
https://github.com/edgelesssys/constellation.git
synced 2024-10-01 01:36:09 -04:00
Update docs to new measurement format (#660)
* Remove fetch-measurements from create workflow * Explain new measurements format in docs Signed-off-by: Daniel Weiße <dw@edgeless.systems>
This commit is contained in:
Daniel Weiße
GitHub
parent
688003cdd9
commit
6bd62f0f7a
7
.github/docs/release.md
vendored
7
.github/docs/release.md
vendored
@ -93,20 +93,23 @@ This checklist will prepare `v1.3.0` from `v1.2.0`. Adjust your version numbers
|
||||
gh workflow run generate-measurements.yml --ref release/v$minor -F osImage=v$ver -F isDebugImage=false -F signMeasurements=true
|
||||
```
|
||||
|
||||
13. Create a new tag on this release branch
|
||||
13. Update expected measurements in [`measurements.go`](/internal/attestation/measurements/measurements.go) using the generated measurements from step 12 and **push your changes**.
|
||||
|
||||
14. Create a new tag on this release branch.
|
||||
|
||||
```sh
|
||||
git tag v$ver
|
||||
git tags --push
|
||||
```
|
||||
|
||||
* Run [Release CLI](https://github.com/edgelesssys/constellation/actions/workflows/release-cli.yml) action on the tag
|
||||
15. Run [Release CLI](https://github.com/edgelesssys/constellation/actions/workflows/release-cli.yml) action on the tag.
|
||||
|
||||
```sh
|
||||
gh workflow run release-cli.yml --ref v$ver
|
||||
```
|
||||
|
||||
* The previous step will create a draft release. Check build output for link to draft release. Review & approve.
|
||||
|
||||
6. Export, download and make image available in S3 for trusted launch users. To achieve this:
|
||||
|
||||
```sh
|
||||
|
||||
@ -35,6 +35,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
- 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).
|
||||
- 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.
|
||||
|
||||
### Deprecated
|
||||
<!-- For soon-to-be removed features. -->
|
||||
|
||||
@ -232,15 +232,7 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step
|
||||
|
||||
:::
|
||||
|
||||
3. Download the trusted measurements for your configured image.
|
||||
|
||||
```bash
|
||||
constellation config fetch-measurements
|
||||
```
|
||||
|
||||
For details, see the [verification section](../workflows/verify-cluster.md).
|
||||
|
||||
4. Create the cluster with one control-plane node and two worker nodes. `constellation create` uses options set in `constellation-conf.yaml`.
|
||||
3. Create the cluster with one control-plane node and two worker nodes. `constellation create` uses options set in `constellation-conf.yaml`.
|
||||
|
||||
:::tip
|
||||
|
||||
@ -259,7 +251,7 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step
|
||||
Your Constellation cluster was created successfully.
|
||||
```
|
||||
|
||||
5. Initialize the cluster
|
||||
4. Initialize the cluster
|
||||
|
||||
```bash
|
||||
constellation init
|
||||
@ -290,7 +282,7 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step
|
||||
|
||||
:::
|
||||
|
||||
6. Configure kubectl
|
||||
5. Configure kubectl
|
||||
|
||||
```bash
|
||||
export KUBECONFIG="$PWD/constellation-admin.conf"
|
||||
|
||||
@ -4,7 +4,7 @@ This document describes breaking changes in the configuration file format betwee
|
||||
|
||||
## Migrating from CLI versions < 2.3
|
||||
|
||||
- The `sshUsers` was deprecated in v2.2 and now has been eventually removed from the configuration in v2.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 `image` field for each cloud service provider has been replaced with a global `image` field. Use the following mapping to migrate your configuration:
|
||||
<details>
|
||||
@ -37,3 +37,20 @@ This document describes breaking changes in the configuration file format betwee
|
||||
| GCP | `projects/constellation-images/global/images/constellation-v2-1-0` | `v2.1.0` |
|
||||
| GCP | `projects/constellation-images/global/images/constellation-v2-0-0` | `v2.0.0` |
|
||||
</details>
|
||||
- The `enforcedMeasurements` field has been removed and merged with the `measurements` field.
|
||||
- To migrate your config containing a new image (`v2.3` or greater), remove the old `measurements` and `enforcedMeasurements` entries from your config and run `constellation fetch-measurements`
|
||||
- To migrate your config containing an image older than `v2.3`, remove the `enforcedMeasurements` entry and replace the entries in `measurements` as shown in the example below:
|
||||
|
||||
```diff
|
||||
measurements:
|
||||
- 0: DzXCFGCNk8em5ornNZtKi+Wg6Z7qkQfs5CfE3qTkOc8=
|
||||
+ 0:
|
||||
+ expected: DzXCFGCNk8em5ornNZtKi+Wg6Z7qkQfs5CfE3qTkOc8=
|
||||
+ warnOnly: true
|
||||
- 8: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
|
||||
+ 8:
|
||||
+ expected: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
|
||||
+ warnOnly: false
|
||||
-enforcedMeasurements:
|
||||
- - 8
|
||||
```
|
||||
|
||||
@ -45,14 +45,6 @@ constellation config generate aws
|
||||
|
||||
This creates the file `constellation-conf.yaml` in the current directory. [Fill in your CSP-specific information](../getting-started/first-steps.md#create-a-cluster) before you continue.
|
||||
|
||||
Next, download the trusted measurements for your configured image.
|
||||
|
||||
```bash
|
||||
constellation config fetch-measurements
|
||||
```
|
||||
|
||||
For details, see the [verification section](../workflows/verify-cluster.md).
|
||||
|
||||
### Create
|
||||
|
||||
Choose the initial size of your cluster.
|
||||
|
||||
@ -11,18 +11,57 @@ 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.
|
||||
|
||||
The configuration file then contains a list of key-value pairs (index, hash) under the `measurements` key and a list of indices under `enforcedMeasurements`.
|
||||
Not all keys under `measurements` will have a matching index under `enforcedMeasurements`.
|
||||
The configuration file then contains a list of `measurements` looking similar to the following:
|
||||
|
||||
```yaml
|
||||
# ...
|
||||
measurements:
|
||||
0:
|
||||
expected: "0f35c214608d93c7a6e68ae7359b4a8be5a0e99eea9107ece427c4dea4e439cf"
|
||||
warnOnly: false
|
||||
4:
|
||||
expected: "02c7a67c01ec70ffaf23d73a12f749ab150a8ac6dc529bda2fe1096a98bf42ea"
|
||||
warnOnly: false
|
||||
5:
|
||||
expected: "e6949026b72e5045706cd1318889b3874480f7a3f7c5c590912391a2d15e6975"
|
||||
warnOnly: true
|
||||
8:
|
||||
expected: "0000000000000000000000000000000000000000000000000000000000000000"
|
||||
warnOnly: false
|
||||
9:
|
||||
expected: "f0a6e8601b00e2fdc57195686cd4ef45eb43a556ac1209b8e25d993213d68384"
|
||||
warnOnly: false
|
||||
11:
|
||||
expected: "0000000000000000000000000000000000000000000000000000000000000000"
|
||||
warnOnly: false
|
||||
12:
|
||||
expected: "da99eb6cf7c7fbb692067c87fd5ca0b7117dc293578e4fea41f95d3d3d6af5e2"
|
||||
warnOnly: false
|
||||
13:
|
||||
expected: "0000000000000000000000000000000000000000000000000000000000000000"
|
||||
warnOnly: false
|
||||
14:
|
||||
expected: "d7c4cc7ff7933022f013e03bdee875b91720b5b86cf1753cad830f95e791926f"
|
||||
warnOnly: true
|
||||
15:
|
||||
expected: "0000000000000000000000000000000000000000000000000000000000000000"
|
||||
warnOnly: false
|
||||
# ...
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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 are only set under the `measurements` key a warning is emitted.
|
||||
For mismatching measurements that are additionally set under `enforcedMeasurements` an error is emitted and attestation fails.
|
||||
If attestation fails, the new node can't join the cluster.
|
||||
For mismatching measurements that have set `warnOnly` to `true` only 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.
|
||||
|
||||
## The *verify* command
|
||||
|
||||
@ -37,6 +76,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