diff --git a/debugd/README.md b/debugd/README.md index c474659c59..83a8e5fc38 100644 --- a/debugd/README.md +++ b/debugd/README.md @@ -5,7 +5,7 @@ The debugd gets embedded into OS images at the place where the bootstrapper norm Therefore, when a debug image is started, the debugd starts executing instead of the bootstrapper. The debugd will then wait for a request from the `cdbg` tool to upload a bootstrapper binary. Once the upload is finished debugd will start the bootstrapper. -Subsequently you can initialize your cluster with `constellation init` as usual. +Subsequently you can initialize your cluster with `constellation apply` as usual. ## Build cdbg @@ -45,7 +45,7 @@ With `cdbg` and `yq` installed in your path: By default, `cdbg` searches for the bootstrapper in the current path (`./bootstrapper`). You can define a custom path by appending the argument `--bootstrapper ` to `cdbg deploy`. -6. Run `constellation init […]` as usual +6. Run `constellation apply […]` as usual ### Logcollection to Opensearch diff --git a/dev-docs/workflows/debug-cluster.md b/dev-docs/workflows/debug-cluster.md index 3d430ca4b9..6329fc9eb6 100644 --- a/dev-docs/workflows/debug-cluster.md +++ b/dev-docs/workflows/debug-cluster.md @@ -45,7 +45,7 @@ Create the cluster and deploy the debug images: Finally run: ```sh -./constellation init +./constellation apply ``` ## Access bootstrapper logs diff --git a/dev-docs/workflows/release.md b/dev-docs/workflows/release.md index 7e943404b2..0d0ae00d7c 100644 --- a/dev-docs/workflows/release.md +++ b/dev-docs/workflows/release.md @@ -62,7 +62,7 @@ Releases should be performed using [the automated release pipeline](https://gith ./constellation upgrade check --update-config yq eval -i '.image="vX.YY.Z"' constellation-conf.yaml ./constellation config fetch-measurements - ./constellation upgrade apply --yes --debug + ./constellation apply --yes --debug ``` Then wait until the node / Kubernetes upgrades are finished by periodically checking: diff --git a/dev-docs/workflows/versions-support.md b/dev-docs/workflows/versions-support.md index 8f3496862d..a3388167a0 100644 --- a/dev-docs/workflows/versions-support.md +++ b/dev-docs/workflows/versions-support.md @@ -4,20 +4,20 @@ This explains the support and compatibility of the different versions that are p ## Microservice version -(the version that is referenced in the config during constellation init or referenced as target version during upgrade apply) must match the CLI version exactly (down to the version suffix). When planning an upgrade, the source version (current version before the upgrade is applied) may be up to one minor version older (allow upgrades from v2.8.x to v2.9.x). +(the version that is referenced in the config during `constellation apply`) must match the CLI version exactly (down to the version suffix). When planning an upgrade, the source version (current version before the upgrade is applied) may be up to one minor version older (allow upgrades from v2.8.x to v2.9.x). The reason is this: The CLI embeds exactly one version of the helm charts (the version of the CLI). So whenever we deploy the helm charts, we can only use the embedded chart version. The source version can only be older by one minor version to ensure we can perform safe upgrades where we can reasonably test what microservice versions will interact with other versions of CLI, OS images, other microservices. ## Kubernetes version -(the version that is referenced in the config during constellation init or referenced as target version during upgrade apply) must match one of the embedded k8s versions. We have a hardcoded list that is embedded in the CLI. +(the version that is referenced in the config during `constellation apply`) must match one of the embedded k8s versions. We have a hardcoded list that is embedded in the CLI. When planning an upgrade, the source k8s version may be up to one minor version older (allow upgrades from k8s 1.25.x to 1.26.x). -The reason is this: The CLI embeds components for kubernetes version for the hardcoded list of supported k8s versions. So whenever we deploy a k8s version (during constellation init or constellation upgrade apply), the k8s components for the target version need to be available. +The reason is this: The CLI embeds components for kubernetes version for the hardcoded list of supported k8s versions. So whenever we deploy a k8s version (during `constellation apply`), the k8s components for the target version need to be available. The source version drift is a general k8s recommendation: k8s was designed to withstand a version drift of one minor version in each component during a rolling upgrade. ## Image version -(the version that is referenced in the config during constellation init or referenced as target version during upgrade apply) must have the same major and minor version (but can have a different patch or suffix) when upgrading compared to the cli. Examples: CLI v2.8.2 could correctly upgrade to OS image v2.8.1 or v2.8.2-nightly-foo-bar. +(the version that is referenced in the config during `constellation apply`) must have the same major and minor version (but can have a different patch or suffix) when upgrading compared to the cli. Examples: CLI v2.8.2 could correctly upgrade to OS image v2.8.1 or v2.8.2-nightly-foo-bar. When planning an upgrade, the source image version may be up to one minor version older (allow upgrades from v2.8.x to 2.9.x). The reason is this: The CLI uses an API endpoint to query configuration and measurements for a configured target image. This generally allows for arbitrary image versions to be referenced/deployed by the CLI. However, to ensure safe upgrades, we always upgrade by at most one minor version and ensure that the CLI is at the same minor version that we target. This allows us to test upgrades with only a reasonable amount of moving parts. diff --git a/docs/docs/architecture/attestation.md b/docs/docs/architecture/attestation.md index e375339950..576bc88657 100644 --- a/docs/docs/architecture/attestation.md +++ b/docs/docs/architecture/attestation.md @@ -90,7 +90,7 @@ Any changes to the image will inevitably also change the measured boot's PCR val To create a node attestation statement, the Constellation image obtains a CVM attestation statement from the hardware. This includes the runtime measurements and thereby binds the measured boot results to the CVM hardware measurement. -In addition to the image measurements, Constellation extends a PCR during the [initialization phase](../workflows/create.md#the-init-step) that irrevocably marks the node as initialized. +In addition to the image measurements, Constellation extends a PCR during the [initialization phase](../workflows/create.md#the-apply-step) that irrevocably marks the node as initialized. The measurement is created using the [*clusterID*](../architecture/keys.md#cluster-identity), tying all future attestation statements to this ID. Thereby, an attestation statement is unique for every cluster and a node can be identified unambiguously as being initialized. diff --git a/docs/docs/architecture/orchestration.md b/docs/docs/architecture/orchestration.md index f612e03cf7..28821dfa9b 100644 --- a/docs/docs/architecture/orchestration.md +++ b/docs/docs/architecture/orchestration.md @@ -36,7 +36,7 @@ In addition, the cluster's [identifier](orchestration.md#post-installation-confi 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*](microservices.md#bootstrapper) 4. The *Bootstrapper* waits until it either receives an initialization request or discovers an initialized cluster -5. The CLI `init` command connects to the *Bootstrapper* of a selected node, sends the configuration, and initiates the initialization of the cluster +5. The CLI `apply` command connects to the *Bootstrapper* of a selected node, sends the configuration, and initiates the initialization of the cluster 6. The *Bootstrapper* of **that** node [initializes the Kubernetes cluster](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* 8. As part of the join request each node includes an attestation statement of its boot measurements as authentication diff --git a/docs/docs/getting-started/first-steps-local.md b/docs/docs/getting-started/first-steps-local.md index de9c66e9b1..90a7317afa 100644 --- a/docs/docs/getting-started/first-steps-local.md +++ b/docs/docs/getting-started/first-steps-local.md @@ -116,16 +116,17 @@ attaching persistent storage, or autoscaling aren't available. 3. Initialize the cluster ```bash - constellation init + constellation apply ``` This should give the following output: ```shell-session - $ constellation init + $ constellation apply Your Constellation master secret was successfully written to ./constellation-mastersecret.json - Note: If you just created the cluster, it can take a few minutes to connect. - Initializing cluster ... + Connecting + Initializing cluster + Installing Kubernetes components Your Constellation cluster was successfully initialized. Constellation cluster identifier g6iMP5wRU1b7mpOz2WEISlIYSfdAhB0oNaOg6XEwKFY= @@ -141,7 +142,7 @@ attaching persistent storage, or autoscaling aren't available. :::info - Depending on your setup, `constellation init` may take 10+ minutes to complete. + Depending on your setup, `constellation apply` may take 10+ minutes to complete. ::: diff --git a/docs/docs/getting-started/first-steps.md b/docs/docs/getting-started/first-steps.md index ba2e87cbae..1b155f66c9 100644 --- a/docs/docs/getting-started/first-steps.md +++ b/docs/docs/getting-started/first-steps.md @@ -141,16 +141,17 @@ If you encounter any problem with the following steps, make sure to use the [lat 4. Initialize the cluster. ```bash - constellation init + constellation apply ``` This should give the following output: ```shell-session - $ constellation init + $ constellation apply Your Constellation master secret was successfully written to ./constellation-mastersecret.json - Note: If you just created the cluster, it can take a few minutes to connect. - Initializing cluster ... + Connecting + Initializing cluster + Installing Kubernetes components Your Constellation cluster was successfully initialized. Constellation cluster identifier g6iMP5wRU1b7mpOz2WEISlIYSfdAhB0oNaOg6XEwKFY= @@ -166,7 +167,7 @@ If you encounter any problem with the following steps, make sure to use the [lat :::info - Depending on your CSP and region, `constellation init` may take 10+ minutes to complete. + Depending on your CSP and region, `constellation apply` may take 10+ minutes to complete. ::: diff --git a/docs/docs/workflows/create.md b/docs/docs/workflows/create.md index 73e30fe36f..7571ab0c8c 100644 --- a/docs/docs/workflows/create.md +++ b/docs/docs/workflows/create.md @@ -171,7 +171,7 @@ terraform init terraform apply ``` -The Constellation [init step](#the-init-step) requires the already created `constellation-config.yaml` and the `constellation-state.yaml`. +The Constellation [apply step](#the-apply-step) requires the already created `constellation-config.yaml` and the `constellation-state.yaml`. Create the `constellation-state.yaml` using the output from the Terraform state and the `constellation-conf.yaml`: ```bash @@ -199,12 +199,12 @@ Continue with [initializing your cluster](#the-init-step). -## The *init* step +## The *apply* step The following command initializes and bootstraps your cluster: ```bash -constellation init +constellation apply ``` Next, configure `kubectl` for your cluster: @@ -215,6 +215,6 @@ export KUBECONFIG="$PWD/constellation-admin.conf" 🏁 That's it. You've successfully created a Constellation cluster. - ### Troubleshooting -In case `init` fails, the CLI collects logs from the bootstrapping instance and stores them inside `constellation-cluster.log`. + +In case `apply` fails, the CLI collects logs from the bootstrapping instance and stores them inside `constellation-cluster.log`. diff --git a/docs/docs/workflows/terminate.md b/docs/docs/workflows/terminate.md index 14a130d55c..062214c1cf 100644 --- a/docs/docs/workflows/terminate.md +++ b/docs/docs/workflows/terminate.md @@ -31,7 +31,7 @@ constellation terminate --yes ``` This deletes all resources created by Constellation in your cloud environment. -All local files created by the `create` and `init` commands are deleted as well, except for `constellation-mastersecret.json` and the configuration file. +All local files created by the `create` and `apply` commands are deleted as well, except for `constellation-mastersecret.json` and the configuration file. :::caution diff --git a/docs/docs/workflows/troubleshooting.md b/docs/docs/workflows/troubleshooting.md index a3e25a0fea..05f515ed7e 100644 --- a/docs/docs/workflows/troubleshooting.md +++ b/docs/docs/workflows/troubleshooting.md @@ -65,12 +65,12 @@ kubectl patch configmaps -n kube-system join-config -p "{\"data\":{\"attestation ::: -You can use the `upgrade apply` command to change measurements of a running cluster: +You can use the `apply` command to change measurements of a running cluster: 1. Modify the `measurements` key in your local `constellation-conf.yaml` to the expected values. -2. Run `constellation upgrade apply`. +2. Run `constellation apply`. -Keep in mind that running `upgrade apply` also applies any version changes from your config to the cluster. +Keep in mind that running `apply` also applies any version changes from your config to the cluster. You can run these commands to learn about the versions currently configured in the cluster: diff --git a/docs/docs/workflows/upgrade.md b/docs/docs/workflows/upgrade.md index e0a33734a1..7348c0dbc2 100644 --- a/docs/docs/workflows/upgrade.md +++ b/docs/docs/workflows/upgrade.md @@ -2,7 +2,7 @@ Constellation provides an easy way to upgrade all components of your cluster, without disrupting it's availability. Specifically, you can upgrade the Kubernetes version, the nodes' image, and the Constellation microservices. -You configure the desired versions in your local Constellation configuration and trigger upgrades with the `upgrade apply` command. +You configure the desired versions in your local Constellation configuration and trigger upgrades with the `apply` command. To learn about available versions you use the `upgrade check` command. Which versions are available depends on the CLI version you are using. @@ -48,7 +48,7 @@ When using this flag, the `kubernetesVersion`, `image`, `microserviceVersion`, a Once you updated your config with the desired versions, you can trigger the upgrade with this command: ```bash -constellation upgrade apply +constellation apply ``` Microservice upgrades will be finished within a few minutes, depending on the cluster size. @@ -73,7 +73,7 @@ The phases are `infrastracture` for the cloud resource management through Terraf ## Check the status Upgrades are asynchronous operations. -After you run `upgrade apply`, it will take a while until the upgrade has completed. +After you run `apply`, it will take a while until the upgrade has completed. To understand if an upgrade is finished, you can run: ```bash diff --git a/docs/docs/workflows/verify-cluster.md b/docs/docs/workflows/verify-cluster.md index a0452802e8..20d4167901 100644 --- a/docs/docs/workflows/verify-cluster.md +++ b/docs/docs/workflows/verify-cluster.md @@ -65,7 +65,7 @@ If attestation fails for a new node, it isn't permitted to join the cluster. ## The *verify* command :::note -The steps below are purely optional. They're automatically executed by `constellation init` when you initialize your cluster. The `constellation verify` command mostly has an illustrative purpose. +The steps below are purely optional. They're automatically executed by `constellation apply` when you initialize your cluster. The `constellation verify` command mostly has an illustrative purpose. ::: The `verify` command obtains and verifies an attestation statement from a running Constellation cluster. diff --git a/docs/screencasts/docker/create-cluster.expect b/docs/screencasts/docker/create-cluster.expect index 7d640b2b1d..a9b290892a 100755 --- a/docs/screencasts/docker/create-cluster.expect +++ b/docs/screencasts/docker/create-cluster.expect @@ -33,7 +33,7 @@ expect_prompt run_command "# Step 2: Initialize Constellation" expect_prompt -run_command "constellation init" +run_command "constellation apply" expect_prompt run_command "# Wait for cluster to finish bootstrapping..." diff --git a/docs/screencasts/docker/github-readme.expect b/docs/screencasts/docker/github-readme.expect index 733b41a531..d5399c54b3 100644 --- a/docs/screencasts/docker/github-readme.expect +++ b/docs/screencasts/docker/github-readme.expect @@ -29,7 +29,7 @@ send "y" send "\r" expect_prompt -run_command "constellation init" +run_command "constellation apply" expect_prompt run_command "export KUBECONFIG=/constellation/constellation-admin.conf" diff --git a/e2e/internal/upgrade/upgrade.go b/e2e/internal/upgrade/upgrade.go index 3f50a4cd96..6fa5036550 100644 --- a/e2e/internal/upgrade/upgrade.go +++ b/e2e/internal/upgrade/upgrade.go @@ -4,7 +4,7 @@ Copyright (c) Edgeless Systems GmbH SPDX-License-Identifier: AGPL-3.0-only */ -// Package upgrade tests that the CLI's upgrade apply command works as expected and +// Package upgrade tests that the CLI's apply command works as expected and // the operators eventually upgrade all nodes inside the cluster. // The test is written as a go test because: // 1. the helm cli does not directly provide the chart version of a release diff --git a/internal/kms/README.md b/internal/kms/README.md index f14be0751b..3afa508c7a 100644 --- a/internal/kms/README.md +++ b/internal/kms/README.md @@ -12,7 +12,7 @@ We differentiate between two cases: * cluster KMS (cKMS): The Constellation cluster itself holds the master secret (KEK) and manages key derivation. - The KEK is generated by an admin on `constellation init`. + The KEK is generated by an admin on `constellation apply`. Once send to the cluster, the KEK never leaves the confidential computing context. As keys are only derived on demand, no DEK is ever persisted to memory by the cKMS. diff --git a/operators/constellation-node-operator/README.md b/operators/constellation-node-operator/README.md index 0acc739aa6..598e054313 100644 --- a/operators/constellation-node-operator/README.md +++ b/operators/constellation-node-operator/README.md @@ -5,7 +5,7 @@ In particular, it is responsible for updating the OS images of nodes by replacin ## High level goals -- Admin or `constellation init` can create custom resources for node related components +- Admin or `constellation apply` can create custom resources for node related components - The operator will manage nodes in the cluster by trying to ensure every node has the specified image - If a node uses an outdated image, it will be replaced by a new node - Admin can update the specified image at any point in time which will trigger a rolling upgrade through the cluster @@ -20,6 +20,7 @@ The operator has multiple controllers with corresponding custom resource definit `NodeVersion` is the only user controlled CRD. The spec allows an administrator to update the desired image and trigger a rolling update. Example for GCP: + ```yaml apiVersion: update.edgeless.systems/v1alpha1 kind: NodeVersion @@ -30,6 +31,7 @@ spec: ``` Example for Azure: + ```yaml apiVersion: update.edgeless.systems/v1alpha1 kind: NodeVersion @@ -39,7 +41,6 @@ spec: image: "/subscriptions//resourceGroups/CONSTELLATION-IMAGES/providers/Microsoft.Compute/galleries/Constellation/images//versions/" ``` - ### AutoscalingStrategy `AutoscalingStrategy` is used and modified by the `NodeVersion` controller to pause the `cluster-autoscaler` while an image update is in progress. @@ -124,12 +125,13 @@ spec: deadline: "2022-07-04T08:33:18+00:00" ``` - ## Getting Started + You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster. **Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows). ### Running on the cluster + 1. Install Instances of Custom Resources: ```sh @@ -149,6 +151,7 @@ make deploy IMG=/constellation/node-operator:tag ``` ### Uninstall CRDs + To delete the CRDs from the cluster: ```sh @@ -156,6 +159,7 @@ make uninstall ``` ### Undeploy controller + UnDeploy the controller to the cluster: ```sh @@ -163,12 +167,14 @@ make undeploy ``` ### How it works + This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/) which provides a reconcile function responsible for synchronizing resources until the desired state is reached on the cluster ### Test It Out + 1. Install the CRDs into the cluster: ```sh @@ -184,6 +190,7 @@ make run **NOTE:** You can also run this in one step by running: `make install run` ### Modifying the API definitions + If you are editing the API definitions, generate the manifests such as CRs or CRDs using: ```sh