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: publish

Browse Source
This commit is contained in:
Thomas Tendyck 2023-07-10 09:06:14 +02:00 committed by Thomas Tendyck
parent 0aaf58b710
commit 2c1da48437
15 changed files with 70 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/versioned_docs/version-2.6/architecture/attestation.md
View File

@ -144,7 +144,7 @@ The latter means that the value can be generated offline and compared to the one
| 7 | Secure Boot State | Azure, Constellation Bootloader | No |
| 8 | - | - | - |
| 9 | initramfs | Linux Kernel | Yes |
| 10 | Reserved | - | No |
| 10 | User space | Linux IMA | No[^1] |
| 11 | Reserved for Unified Kernel Image components | (Constellation Bootloader) | Yes |
| 12 | Kernel command line | Constellation Bootloader | Yes |
| 13 | Reserved | (Constellation Bootloader) | Yes |
@ -177,7 +177,7 @@ The latter means that the value can be generated offline and compared to the one
| 7 | GCP Secure Boot Policy | GCP, Constellation Bootloader | No |
| 8 | - | - | - |
| 9 | initramfs | Linux Kernel | Yes |
| 10 | Reserved | - | No |
| 10 | User space | Linux IMA | No[^1] |
| 11 | Reserved for Unified Kernel Image components | (Constellation Bootloader) | Yes |
| 12 | Kernel command line | Constellation Bootloader | Yes |
| 13 | Reserved | (Constellation Bootloader) | Yes |
@ -209,7 +209,7 @@ The latter means that the value can be generated offline and compared to the one
| 7 | Secure Boot Policy | AWS, Constellation Bootloader | No |
| 8 | - | - | - |
| 9 | initramfs | Linux Kernel | Yes |
| 10 | Reserved | - | No |
| 10 | User space | Linux IMA | No[^1] |
| 11 | Reserved for Unified Kernel Image components | (Constellation Bootloader) | Yes |
| 12 | Kernel command line | Constellation Bootloader | Yes |
| 13 | Reserved | (Constellation Bootloader) | Yes |
@ -267,3 +267,9 @@ flowchart LR
D["Public key"]-- "verifies" -->E["Runtime measurements"]
E["Runtime measurements"]-- "verify" -->F["Constellation cluster"]
```
## References
[^1]: Linux IMA produces runtime measurements of user-space binaries.
However, these measurements aren't deterministic and thus, PCR\[10] can't be compared to a constant value.
Instead, a policy engine must be used to verify the TPM event log against a policy.

2
docs/versioned_docs/version-2.6/architecture/versions.md
View File

@ -7,7 +7,7 @@ Additional `PATCH` releases may be created on demand, to fix security issues or
New releases are published on [GitHub](https://github.com/edgelesssys/constellation/releases).
### Kubernetes support policy
## Kubernetes support policy
Constellation is aligned to the [version support policy of Kubernetes](https://kubernetes.io/releases/version-skew-policy/#supported-versions), and therefore usually supports the most recent three minor versions.
When a new minor version of Kubernetes is released, support is added to the next Constellation release, and that version then supports four Kubernetes versions.

12
docs/versioned_docs/version-2.7/architecture/attestation.md
View File

@ -144,7 +144,7 @@ The latter means that the value can be generated offline and compared to the one
| 7 | Secure Boot State | Azure, Constellation Bootloader | No |
| 8 | - | - | - |
| 9 | initramfs | Linux Kernel | Yes |
| 10 | Reserved | - | No |
| 10 | User space | Linux IMA | No[^1] |
| 11 | Reserved for Unified Kernel Image components | (Constellation Bootloader) | Yes |
| 12 | Kernel command line | Constellation Bootloader | Yes |
| 13 | Reserved | (Constellation Bootloader) | Yes |
@ -177,7 +177,7 @@ The latter means that the value can be generated offline and compared to the one
| 7 | GCP Secure Boot Policy | GCP, Constellation Bootloader | No |
| 8 | - | - | - |
| 9 | initramfs | Linux Kernel | Yes |
| 10 | Reserved | - | No |
| 10 | User space | Linux IMA | No[^1] |
| 11 | Reserved for Unified Kernel Image components | (Constellation Bootloader) | Yes |
| 12 | Kernel command line | Constellation Bootloader | Yes |
| 13 | Reserved | (Constellation Bootloader) | Yes |
@ -209,7 +209,7 @@ The latter means that the value can be generated offline and compared to the one
| 7 | Secure Boot Policy | AWS, Constellation Bootloader | No |
| 8 | - | - | - |
| 9 | initramfs | Linux Kernel | Yes |
| 10 | Reserved | - | No |
| 10 | User space | Linux IMA | No[^1] |
| 11 | Reserved for Unified Kernel Image components | (Constellation Bootloader) | Yes |
| 12 | Kernel command line | Constellation Bootloader | Yes |
| 13 | Reserved | (Constellation Bootloader) | Yes |
@ -267,3 +267,9 @@ flowchart LR
D["Public key"]-- "verifies" -->E["Runtime measurements"]
E["Runtime measurements"]-- "verify" -->F["Constellation cluster"]
```
## References
[^1]: Linux IMA produces runtime measurements of user-space binaries.
However, these measurements aren't deterministic and thus, PCR\[10] can't be compared to a constant value.
Instead, a policy engine must be used to verify the TPM event log against a policy.

2
docs/versioned_docs/version-2.7/architecture/versions.md
View File

@ -7,7 +7,7 @@ Additional `PATCH` releases may be created on demand, to fix security issues or
New releases are published on [GitHub](https://github.com/edgelesssys/constellation/releases).
### Kubernetes support policy
## Kubernetes support policy
Constellation is aligned to the [version support policy of Kubernetes](https://kubernetes.io/releases/version-skew-policy/#supported-versions), and therefore usually supports the most recent three minor versions.
When a new minor version of Kubernetes is released, support is added to the next Constellation release, and that version then supports four Kubernetes versions.

2
docs/versioned_docs/version-2.7/getting-started/first-steps-local.md
View File

@ -2,6 +2,7 @@
A local cluster lets you deploy and test Constellation without a cloud subscription.
You have two options:
* Use MiniConstellation to automatically deploy a two-node cluster.
* For more fine-grained control, create the cluster using the QEMU provider.
@ -110,6 +111,7 @@ attaching persistent storage, or autoscaling aren't available.
```shell-session
$ constellation init
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 ...
Your Constellation cluster was successfully initialized.

1
docs/versioned_docs/version-2.7/getting-started/first-steps.md
View File

@ -112,6 +112,7 @@ If you encounter any problem with the following steps, make sure to use the [lat
```shell-session
$ constellation init
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 ...
Your Constellation cluster was successfully initialized.

14
docs/versioned_docs/version-2.7/workflows/troubleshooting.md
View File

@ -12,6 +12,7 @@ If something doesn't work, check out the [known issues](https://github.com/edgel
### Azure: Resource Providers can't be registered
On Azure, you may receive the following error when running `create` or `terminate` with limited IAM permissions:
```shell-session
Error: Error ensuring Resource Providers are registered.
@ -28,11 +29,13 @@ To continue, please ensure that the [required resource providers](../getting-sta
Afterward, set `ARM_SKIP_PROVIDER_REGISTRATION=true` as an environment variable and either run `create` or `terminate` again.
For example:
```bash
ARM_SKIP_PROVIDER_REGISTRATION=true constellation create --control-plane-nodes 1 --worker-nodes 2 -y
```
Or alternatively, for `terminate`:
```bash
ARM_SKIP_PROVIDER_REGISTRATION=true constellation terminate
```
@ -59,6 +62,7 @@ You can use the `upgrade apply` command to change measurements of a running clus
Keep in mind that running `upgrade 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:
- Kubernetes API server version: `kubectl get nodeversion constellation-version -o json -n kube-system | jq .spec.kubernetesClusterVersion`
- image version: `kubectl get nodeversion constellation-version -o json -n kube-system | jq .spec.imageVersion`
- microservices versions: `helm list --filter 'constellation-services' -n kube-system`
@ -77,7 +81,7 @@ You can view this information in the following places:
1. In your Azure subscription find the Constellation resource group.
2. Inside the resource group find the Application Insights resource called `constellation-insights-*`.
3. On the left-hand side go to `Logs`, which is located in the section `Monitoring`.
+ Close the Queries page if it pops up.
- Close the Queries page if it pops up.
5. In the query text field type in `traces`, and click `Run`.
To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"`
@ -88,7 +92,7 @@ To **find the disk UUIDs** use the following query: `traces | where message cont
1. Select the project that hosts Constellation.
2. Go to the `Compute Engine` service.
3. On the right-hand side of a VM entry select `More Actions` (a stacked ellipsis)
+ Select `View logs`
- Select `View logs`
To **find the disk UUIDs** use the following query: `resource.type="gce_instance" text_payload=~"Disk UUID:.*\n" logName=~".*/constellation-boot-log"`
@ -115,7 +119,7 @@ Debugging via a shell on a node is [directly supported by Kubernetes](https://ku
1. Figure out which node to connect to:
```sh
```bash
kubectl get nodes
# or to see more information, such as IPs:
kubectl get nodes -o wide
@ -123,7 +127,7 @@ Debugging via a shell on a node is [directly supported by Kubernetes](https://ku
2. Connect to the node:
```sh
```bash
kubectl debug node/constell-worker-xksa0-000000 -it --image=busybox
```
@ -133,6 +137,6 @@ Debugging via a shell on a node is [directly supported by Kubernetes](https://ku
3. Once finished, clean up the debug pod:
```sh
```bash
kubectl delete pod node-debugger-constell-worker-xksa0-000000-bjthj
```

12
docs/versioned_docs/version-2.8/architecture/attestation.md
View File

@ -144,7 +144,7 @@ The latter means that the value can be generated offline and compared to the one
| 7 | Secure Boot State | Azure, Constellation Bootloader | No |
| 8 | - | - | - |
| 9 | initramfs | Linux Kernel | Yes |
| 10 | Reserved | - | No |
| 10 | User space | Linux IMA | No[^1] |
| 11 | Reserved for Unified Kernel Image components | (Constellation Bootloader) | Yes |
| 12 | Kernel command line | Constellation Bootloader | Yes |
| 13 | Reserved | (Constellation Bootloader) | Yes |
@ -177,7 +177,7 @@ The latter means that the value can be generated offline and compared to the one
| 7 | GCP Secure Boot Policy | GCP, Constellation Bootloader | No |
| 8 | - | - | - |
| 9 | initramfs | Linux Kernel | Yes |
| 10 | Reserved | - | No |
| 10 | User space | Linux IMA | No[^1] |
| 11 | Reserved for Unified Kernel Image components | (Constellation Bootloader) | Yes |
| 12 | Kernel command line | Constellation Bootloader | Yes |
| 13 | Reserved | (Constellation Bootloader) | Yes |
@ -209,7 +209,7 @@ The latter means that the value can be generated offline and compared to the one
| 7 | Secure Boot Policy | AWS, Constellation Bootloader | No |
| 8 | - | - | - |
| 9 | initramfs | Linux Kernel | Yes |
| 10 | Reserved | - | No |
| 10 | User space | Linux IMA | No[^1] |
| 11 | Reserved for Unified Kernel Image components | (Constellation Bootloader) | Yes |
| 12 | Kernel command line | Constellation Bootloader | Yes |
| 13 | Reserved | (Constellation Bootloader) | Yes |
@ -308,3 +308,9 @@ flowchart LR
D["Public key"]-- "verifies" -->E["Runtime measurements"]
E["Runtime measurements"]-- "verify" -->F["Constellation cluster"]
```
## References
[^1]: Linux IMA produces runtime measurements of user-space binaries.
However, these measurements aren't deterministic and thus, PCR\[10] can't be compared to a constant value.
Instead, a policy engine must be used to verify the TPM event log against a policy.

2
docs/versioned_docs/version-2.8/architecture/versions.md
View File

@ -7,7 +7,7 @@ Additional `PATCH` releases may be created on demand, to fix security issues or
New releases are published on [GitHub](https://github.com/edgelesssys/constellation/releases).
### Kubernetes support policy
## Kubernetes support policy
Constellation is aligned to the [version support policy of Kubernetes](https://kubernetes.io/releases/version-skew-policy/#supported-versions), and therefore usually supports the most recent three minor versions.
When a new minor version of Kubernetes is released, support is added to the next Constellation release, and that version then supports four Kubernetes versions.

2
docs/versioned_docs/version-2.8/getting-started/first-steps-local.md
View File

@ -2,6 +2,7 @@
A local cluster lets you deploy and test Constellation without a cloud subscription.
You have two options:
* Use MiniConstellation to automatically deploy a two-node cluster.
* For more fine-grained control, create the cluster using the QEMU provider.
@ -110,6 +111,7 @@ attaching persistent storage, or autoscaling aren't available.
```shell-session
$ constellation init
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 ...
Your Constellation cluster was successfully initialized.

2
docs/versioned_docs/version-2.8/getting-started/first-steps.md
View File

@ -32,6 +32,7 @@ If you encounter any problem with the following steps, make sure to use the [lat
* `eastus`
* `northeurope`
* `westeurope`
* `southeastasia`
</tabItem>
@ -112,6 +113,7 @@ If you encounter any problem with the following steps, make sure to use the [lat
```shell-session
$ constellation init
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 ...
Your Constellation cluster was successfully initialized.

8
docs/versioned_docs/version-2.8/reference/migration.md
View File

@ -6,21 +6,19 @@ Use [`constellation config migrate`](./cli.md#constellation-config-migrate) to a
## Migrating from Azure's service principal authentication to managed identity authentication
- The `provider.azure.appClientID` and `provider.azure.appClientSecret` fields are no longer required and should be removed.
- To keep using an existing UAMI add the `Owner` permission with the scope of your `resourceGroup`.
- Otherwise, simply [create new Constellation IAM credentials](../workflows/config.md#creating-iam-credentials) and use the created UAMI.
- To migrate the authentication for an existing Constellation on Azure to an UAMI with the necessary permissions:
- To keep using an existing UAMI, add the `Owner` permission with the scope of your `resourceGroup`.
- Otherwise, simply [create new Constellation IAM credentials](../workflows/config.md#creating-an-iam-configuration) and use the created UAMI.
- To migrate the authentication for an existing cluster on Azure to an UAMI with the necessary permissions:
1. Remove the `aadClientId` and `aadClientSecret` from the azureconfig secret.
2. Set `useManagedIdentityExtension` to `true` and use the `userAssignedIdentity` from the Constellation config for the value of `userAssignedIdentityID`.
3. Restart the CSI driver, cloud controller manager, cluster autoscaler, and Constellation operator pods.
## Migrating from CLI versions before 2.8
- The `measurements` field for each cloud service provider was replaced with a global `attestation` field.
- The `confidentialVM`, `idKeyDigest`, and `enforceIdKeyDigest` fields for the Azure cloud service provider were removed in favor of using the global `attestation` field.
- The optional global field `attestationVariant` was replaced by the now required `attestation` field.
## Migrating from CLI versions before 2.3
- The `sshUsers` field was deprecated in v2.2 and has been removed from the configuration in v2.3.

15
docs/versioned_docs/version-2.8/workflows/config.md
View File

@ -91,10 +91,12 @@ constellation iam create azure --region=westus --resourceGroup=constellTest --se
This command creates IAM configuration on the Azure region `westus` creating a new resource group `constellTest` and a new service principal `spTest`.
Note that CVMs are currently only supported in a few regions, check [Azure's products available by region](https://azure.microsoft.com/en-us/global-infrastructure/services/?products=virtual-machines&regions=all). These are:
* `westus`
* `eastus`
* `northeurope`
* `westeurope`
* `southeastasia`
Paste the output into the corresponding fields of the `constellation-conf.yaml` file.
@ -129,6 +131,7 @@ constellation iam create aws --zone=eu-central-1a --prefix=constellTest
This command creates IAM configuration for the AWS zone `eu-central-1a` using the prefix `constellTest` for all named resources being created.
Constellation OS images are currently replicated to the following regions:
* `eu-central-1`
* `eu-west-1`
* `eu-west-3`
@ -166,6 +169,7 @@ The following describes the configuration fields and how you obtain the required
* `eastus`
* `northeurope`
* `westeurope`
* `southeastasia`
* **resourceGroup**: [Create a new resource group in Azure](https://portal.azure.com/#create/Microsoft.ResourceGroup) for your Constellation cluster. Set this configuration field to the name of the created resource group.
@ -212,11 +216,11 @@ The following describes the configuration fields and how you obtain the required
* **serviceAccountKeyPath**: To configure this, you need to create a GCP [service account](https://cloud.google.com/iam/docs/service-accounts) with the following permissions:
- `Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)`
- `Compute Network Admin (roles/compute.networkAdmin)`
- `Compute Security Admin (roles/compute.securityAdmin)`
- `Compute Storage Admin (roles/compute.storageAdmin)`
- `Service Account User (roles/iam.serviceAccountUser)`
* `Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)`
* `Compute Network Admin (roles/compute.networkAdmin)`
* `Compute Security Admin (roles/compute.securityAdmin)`
* `Compute Storage Admin (roles/compute.storageAdmin)`
* `Service Account User (roles/iam.serviceAccountUser)`
Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`.
@ -265,6 +269,7 @@ Now that you've configured your CSP, you can [create your cluster](./create.md).
You can keep a created IAM configuration and reuse it for new clusters. Alternatively, you can also delete it if you don't want to use it anymore.
Delete the IAM configuration by executing the following command in the same directory where you executed `constellation iam create` (the directory that contains [`constellation-iam-terraform`](../reference/terraform.md) as a subdirectory):
```bash
constellation iam destroy
```

14
docs/versioned_docs/version-2.8/workflows/troubleshooting.md
View File

@ -12,6 +12,7 @@ If something doesn't work, check out the [known issues](https://github.com/edgel
### Azure: Resource Providers can't be registered
On Azure, you may receive the following error when running `create` or `terminate` with limited IAM permissions:
```shell-session
Error: Error ensuring Resource Providers are registered.
@ -28,11 +29,13 @@ To continue, please ensure that the [required resource providers](../getting-sta
Afterward, set `ARM_SKIP_PROVIDER_REGISTRATION=true` as an environment variable and either run `create` or `terminate` again.
For example:
```bash
ARM_SKIP_PROVIDER_REGISTRATION=true constellation create --control-plane-nodes 1 --worker-nodes 2 -y
```
Or alternatively, for `terminate`:
```bash
ARM_SKIP_PROVIDER_REGISTRATION=true constellation terminate
```
@ -59,6 +62,7 @@ You can use the `upgrade apply` command to change measurements of a running clus
Keep in mind that running `upgrade 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:
- Kubernetes API server version: `kubectl get nodeversion constellation-version -o json -n kube-system | jq .spec.kubernetesClusterVersion`
- image version: `kubectl get nodeversion constellation-version -o json -n kube-system | jq .spec.imageVersion`
- microservices versions: `helm list --filter 'constellation-services' -n kube-system`
@ -77,7 +81,7 @@ You can view this information in the following places:
1. In your Azure subscription find the Constellation resource group.
2. Inside the resource group find the Application Insights resource called `constellation-insights-*`.
3. On the left-hand side go to `Logs`, which is located in the section `Monitoring`.
+ Close the Queries page if it pops up.
- Close the Queries page if it pops up.
5. In the query text field type in `traces`, and click `Run`.
To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"`
@ -88,7 +92,7 @@ To **find the disk UUIDs** use the following query: `traces | where message cont
1. Select the project that hosts Constellation.
2. Go to the `Compute Engine` service.
3. On the right-hand side of a VM entry select `More Actions` (a stacked ellipsis)
+ Select `View logs`
- Select `View logs`
To **find the disk UUIDs** use the following query: `resource.type="gce_instance" text_payload=~"Disk UUID:.*\n" logName=~".*/constellation-boot-log"`
@ -115,7 +119,7 @@ Debugging via a shell on a node is [directly supported by Kubernetes](https://ku
1. Figure out which node to connect to:
```sh
```bash
kubectl get nodes
# or to see more information, such as IPs:
kubectl get nodes -o wide
@ -123,7 +127,7 @@ Debugging via a shell on a node is [directly supported by Kubernetes](https://ku
2. Connect to the node:
```sh
```bash
kubectl debug node/constell-worker-xksa0-000000 -it --image=busybox
```
@ -133,6 +137,6 @@ Debugging via a shell on a node is [directly supported by Kubernetes](https://ku
3. Once finished, clean up the debug pod:
```sh
```bash
kubectl delete pod node-debugger-constell-worker-xksa0-000000-bjthj
```

3
docs/versioned_docs/version-2.8/workflows/upgrade.md
View File

@ -20,6 +20,7 @@ Most importantly, a given CLI version can only upgrade a cluster of the previous
This means that you have to upgrade your CLI and cluster one minor version at a time.
For example, if you are currently on CLI version v2.6 and the latest version is v2.8, you should
* upgrade the CLI to v2.7,
* upgrade the cluster to v2.7,
* and only then continue upgrading the CLI (and the cluster) to v2.8 after.
@ -47,7 +48,7 @@ constellation upgrade check --write-config
```
You can either enter the reported target versions into your config manually or run the above command with the `--write-config` flag.
When using this flag, the `kubernetesVersion`, `image`, `microserviceVersion` and `attestation` fields are overwritten with the smallest available upgrade.
When using this flag, the `kubernetesVersion`, `image`, `microserviceVersion`, and `attestation` fields are overwritten with the smallest available upgrade.
## Apply the upgrade