mirror of
https://github.com/edgelesssys/constellation.git
synced 2024-10-01 01:36:09 -04:00
Restructure config docs (#44)
* more guided UX when generating and filling in config Signed-off-by: Fabian Kammel <fk@edgeless.systems>
This commit is contained in:
Fabian Kammel
GitHub
parent
2f871578b2
commit
106635a9ee
@ -65,6 +65,9 @@ func configGenerate(cmd *cobra.Command, fileHandler file.Handler, provider cloud
|
||||
cmd.Println("Please fill in your CSP specific configuration before proceeding.")
|
||||
cmd.Println("You can find the list of supported virtual machine types by executing:")
|
||||
cmd.Println("\tconstellation config instance-types")
|
||||
cmd.Println("Fore more information refer to our documentation:")
|
||||
cmd.Println("\thttps://constellation-docs.edgeless.systems/constellation/getting-started/first-steps#create-a-cluster")
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
|
||||
@ -9,10 +9,6 @@ The following steps will guide you through the process of creating a cluster and
|
||||
<tabs>
|
||||
<tabItem value="azure" label="Azure" default>
|
||||
|
||||
On Azure you also need a *user-assigned managed identity* with the [correct permissions](install.md?id=authorization).
|
||||
|
||||
Then execute:
|
||||
|
||||
```bash
|
||||
constellation config generate azure
|
||||
```
|
||||
@ -27,11 +23,109 @@ The following steps will guide you through the process of creating a cluster and
|
||||
</tabItem>
|
||||
</tabs>
|
||||
|
||||
This creates the file `constellation-conf.yaml` in your current working directory. Edit this file to set your cloud subscription IDs and optionally customize further options of your Constellation cluster. All configuration options are documented in this file.
|
||||
This creates the file `constellation-conf.yaml` in your current working directory.
|
||||
|
||||
For more details, see the [reference section](../reference/config.md#required-customizations).
|
||||
2. Fill in your cloud provider specific information:
|
||||
|
||||
2. Download the measurements for your configured image.
|
||||
<tabs>
|
||||
<tabItem value="azure-cli" label="Azure (CLI)" default>
|
||||
|
||||
For a quick start it's recommended to use our `az` script to automatically create all required resources:
|
||||
|
||||
```bash
|
||||
RESOURCE_GROUP=constellation # enter name of resource group here
|
||||
LOCATION=westus # enter location of resources here
|
||||
SUBSCRIPTION_ID=$(az account show --query id --out tsv)
|
||||
SERVICE_PRINCIPLE_NAME=constell
|
||||
az group create --name "${RESOURCE_GROUP}" --location "${LOCATION}"
|
||||
az group create --name "${RESOURCE_GROUP}-identity" --location "${LOCATION}"
|
||||
az ad sp create-for-rbac -n "${SERVICE_PRINCIPLE_NAME}" --role Owner --scopes "/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}" | tee azureServiceAccountKey.json
|
||||
az identity create -g "${RESOURCE_GROUP}-identity" -n "${SERVICE_PRINCIPLE_NAME}"
|
||||
identityID=$(az identity show -n "${SERVICE_PRINCIPLE_NAME}" -g "${RESOURCE_GROUP}-identity" --query principalId --out tsv)
|
||||
az role assignment create --assignee-principal-type ServicePrincipal --assignee-object-id "${identityID}" --role 'Virtual Machine Contributor' --scope "/subscriptions/${SUBSCRIPTION_ID}"
|
||||
az role assignment create --assignee-principal-type ServicePrincipal --assignee-object-id "${identityID}" --role 'Application Insights Component Contributor' --scope "/subscriptions/${SUBSCRIPTION_ID}"
|
||||
echo "subscription: ${SUBSCRIPTION_ID}"
|
||||
echo "tenant: $(az account show --query tenantId -o tsv)"
|
||||
echo "location: ${LOCATION}"
|
||||
echo "resourceGroup: ${RESOURCE_GROUP}"
|
||||
echo "userAssignedIdentity: $(az identity show -n "${SERVICE_PRINCIPLE_NAME}" -g "${RESOURCE_GROUP}-identity" --query id --out tsv)"
|
||||
echo "appClientID: $(jq -r '.appId' azureServiceAccountKey.json)"
|
||||
echo "clientSecretValue: $(jq -r '.password' azureServiceAccountKey.json)"
|
||||
```
|
||||
|
||||
Fill in the printed out values to your configuration file.
|
||||
|
||||
</tabItem>
|
||||
<tabItem value="azure-portal" label="Azure (Portal)" default>
|
||||
|
||||
* **subscription**: Is the UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`.
|
||||
|
||||
You can view your subscription UUID via `az account show` and read the `id` field. For more information refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id#find-your-azure-subscription).
|
||||
|
||||
* **tenant**: Is the UUID of your Azure tenant, e.g., `3400e5a2-8fe2-492a-886c-38cb66170f25`.
|
||||
|
||||
You can view your tenant UUID via `az account show` and read the `tenant` field. For more information refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id#find-your-azure-ad-tenant).
|
||||
|
||||
* **location**: Is the Azure datacenter location you want to deploy your cluster in, e.g., `westus`. Notice 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®ions=all). Currently these are supported:
|
||||
|
||||
* `westus`
|
||||
* `eastus`
|
||||
* `northeurope`
|
||||
* `westeurope`
|
||||
|
||||
* **resourceGroup**: [Create a new resource group in Azure](https://portal.azure.com/#create/Microsoft.ResourceGroup), to deploy your Constellation cluster into. Afterwards set the configuration field to the name of the created resource group, e.g., `constellation`.
|
||||
|
||||
* **userAssignedIdentity**: [Create a new managed identity in Azure](https://portal.azure.com/#create/Microsoft.ManagedIdentity). Notice that the identity should be created in a different resource group as all resources within the cluster resource group will be deleted on cluster termination.
|
||||
|
||||
After creation, add two role assignments to the identity, for the roles `Virtual Machine Contributor` and `Application Insights Component Contributor`. The `scope` of both should refer to the previously created resource group.
|
||||
|
||||
Set the configuration value to the full ID of the created identity, e.g., `/subscriptions/8b8bd01f-efd9-4113-9bd1-c82137c32da7/resourcegroups/constellation-identity/providers/Microsoft.ManagedIdentity/userAssignedIdentities/constellation-identity`.
|
||||
|
||||
The user-assigned identity is used by instances of the cluster to access other cloud resources.
|
||||
|
||||
For more information about managed identities refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities).
|
||||
|
||||
* **appClientID**: [Create a new app registration in Azure](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/CreateApplicationBlade/quickStartType~/null/isMSAApp~/false).
|
||||
|
||||
As `Supported account types` choose `Accounts in this organizational directory only`, and leave the `Redirect URI` empty.
|
||||
|
||||
In the cluster resource group, go to `Access Control (IAM)`, and set the created app registration as `Owner`.
|
||||
|
||||
Set the configuration value to the `Application (client) ID`, e.g., `86ec31dd-532b-4a8c-a055-dd23f25fb12f`.
|
||||
|
||||
* **clientSecretValue**: In our previously created app registration, go to `Certificates & secrets` and create a new `Client secret`.
|
||||
|
||||
Set the configuration value to the secret value.
|
||||
|
||||
</tabItem>
|
||||
<tabItem value="gcp" label="GCP" default>
|
||||
|
||||
* **project**: Is the ID of your GCP project, e.g., `constellation-129857`.
|
||||
|
||||
You will find it on the [welcome screen of your GCP project](https://console.cloud.google.com/welcome). For more information refer to [Google's documentation](https://support.google.com/googleapi/answer/7014113).
|
||||
|
||||
* **region**: Is the GCP region you want to deploy your cluster in, e.g., `us-west-1`.
|
||||
|
||||
You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available).
|
||||
|
||||
* **zone**: Is the GCP zone you want to deploy your cluster in, e.g., `us-west-1a`.
|
||||
|
||||
You can find a [list of all zones in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available).
|
||||
|
||||
* **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)`
|
||||
|
||||
Afterwards, 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`.
|
||||
|
||||
</tabItem>
|
||||
</tabs>
|
||||
|
||||
3. Download the measurements for your configured image.
|
||||
|
||||
```bash
|
||||
constellation config fetch-measurements
|
||||
@ -41,7 +135,7 @@ The following steps will guide you through the process of creating a cluster and
|
||||
|
||||
For more details, see the [verification section](../workflows/verify.md).
|
||||
|
||||
3. Create the cluster with one control-plane node and two worker nodes. `constellation create` uses options set in `constellation-conf.yaml` automatically.
|
||||
4. Create the cluster with one control-plane node and two worker nodes. `constellation create` uses options set in `constellation-conf.yaml` automatically.
|
||||
|
||||
<tabs>
|
||||
<tabItem value="azure" label="Azure" default>
|
||||
@ -67,7 +161,7 @@ The following steps will guide you through the process of creating a cluster and
|
||||
Your Constellation cluster was created successfully.
|
||||
```
|
||||
|
||||
4. Initialize the cluster
|
||||
5. Initialize the cluster
|
||||
|
||||
```bash
|
||||
constellation init
|
||||
@ -89,7 +183,7 @@ The following steps will guide you through the process of creating a cluster and
|
||||
Keep `constellation-mastersecret.json` somewhere safe.
|
||||
This will allow you to [recover your cluster](../workflows/recovery.md) in case of a disaster.
|
||||
|
||||
5. Configure kubectl
|
||||
6. Configure kubectl
|
||||
|
||||
```bash
|
||||
export KUBECONFIG="$PWD/constellation-admin.conf"
|
||||
@ -125,3 +219,12 @@ $ constellation terminate
|
||||
Terminating ...
|
||||
Your Constellation cluster was terminated successfully.
|
||||
```
|
||||
|
||||
In case you have used `az` CLI to create your environment, make sure to clean up afterwards:
|
||||
|
||||
```bash
|
||||
APPID=$(jq -r '.appId' azureServiceAccountKey.json)
|
||||
az ad sp delete --id "${APPID}"
|
||||
az group delete -g "${RESOURCE_GROUP}-identity" --yes --no-wait
|
||||
az group delete -g "${RESOURCE_GROUP}" --yes --no-wait
|
||||
```
|
||||
|
||||
@ -15,7 +15,7 @@ Before we start, make sure the following requirements are fulfilled:
|
||||
|
||||
## Install the Constellation CLI
|
||||
|
||||
The Constellation CLI can be downloaded from our [release page](https://github.com/edgelesssys/constellation/releases). Therefore, navigate to a release and download the file `constellation`. Move the downloaded file to a directory in your `PATH` (default: `/usr/local/bin`) and make it executable by entering `chmod s+x constellation` in your terminal.
|
||||
The Constellation CLI can be downloaded from our [release page](https://github.com/edgelesssys/constellation/releases). Therefore, navigate to a release and download the `constellation` binary for your operating system and architecture. Move the downloaded file to a directory in your `PATH` (default: `/usr/local/bin`) and make it executable by entering `chmod u+x constellation` in your terminal.
|
||||
|
||||
Running `constellation` should then give you:
|
||||
|
||||
@ -38,7 +38,7 @@ The Constellation CLI supports autocompletion for various shells. To set it up,
|
||||
For extra security, make sure to verify your CLI. Therefore, install [cosign](https://github.com/sigstore/cosign). Then, head to our [release page](https://github.com/edgelesssys/constellation/releases) again and, from the same release as before, download the following files:
|
||||
|
||||
- `cosign.pub` (Edgeless System's cosign public key)
|
||||
- `constellation.sig` (the CLI's signature)
|
||||
- `constellation-*.sig` (the CLI's signature)
|
||||
|
||||
You can then verify your CLI before launching a cluster using the paths to the public key, signature, and CLI executable:
|
||||
|
||||
@ -124,23 +124,6 @@ Your user account needs the following permissions to set up a Constellation clus
|
||||
- `Contributor`
|
||||
- `User Access Administrator`
|
||||
|
||||
Additionally, you need to [create a user-assigned managed identity](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities) with the following roles:
|
||||
|
||||
- `Virtual Machine Contributor`
|
||||
- `Application Insights Component Contributor`
|
||||
|
||||
The user-assigned identity is used by the instances of the cluster to access other cloud resources.
|
||||
|
||||
You also need an empty resource group per cluster. Notice that the user-assigned identity has to be created in a
|
||||
different resource group as all resources within the cluster resource group will be deleted on cluster termination.
|
||||
|
||||
Last, you need to [create an Active Directory app registration](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-an-application) (you don't need to add a redirect URI).
|
||||
As supported account types choose 'Accounts in this organizational directory only'. Then [create a client secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#option-2-create-a-new-application-secret), which will be used by Kubernetes.
|
||||
On the cluster resource group, [add the app registration](https://docs.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal?tabs=current#step-2-open-the-add-role-assignment-page)
|
||||
with role `Owner`.
|
||||
|
||||
User-assigned identity, cluster resource group, app registration client ID and client secret value need to be set in the `constellation-conf.yaml` configuration file.
|
||||
|
||||
</tabItem>
|
||||
<tabItem value="gcp" label="GCP" default>
|
||||
|
||||
@ -150,20 +133,6 @@ Your user account needs the following permissions to set up a Constellation:
|
||||
|
||||
Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access).
|
||||
|
||||
Additionally, you need a service account 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)`
|
||||
|
||||
The key for this service account is passed to the CLI and used by Kubernetes to authenticate with the cloud.
|
||||
You can configure the path to the key in the `constellation-conf.yaml` configuration file.
|
||||
|
||||
GCP instances come with a [default service account](https://cloud.google.com/iam/docs/service-accounts#default) attached
|
||||
that's used by the instances to access the cloud resources of the cluster. You don't need to configure it.
|
||||
|
||||
</tabItem>
|
||||
</tabs>
|
||||
|
||||
|
||||
@ -50,7 +50,7 @@ provider:
|
||||
measurements:
|
||||
11: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
|
||||
12: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
|
||||
userAssignedIdentity: "" # Authorize spawned VMs to access Azure API. See: https://docs.edgeless.systems/constellation/getting-started/install#authorization
|
||||
userAssignedIdentity: "" # Authorize spawned VMs to access Azure API.
|
||||
kubernetesVersion: "1.24" # Kubernetes version installed in the cluster.
|
||||
|
||||
# # Egress firewall rules for node network.
|
||||
@ -67,17 +67,3 @@ kubernetesVersion: "1.24" # Kubernetes version installed in the cluster.
|
||||
# - username: Alice # Username of new SSH user.
|
||||
# publicKey: ssh-rsa AAAAB3NzaC...5QXHKW1rufgtJeSeJ8= alice@domain.com # Public key of new SSH user.
|
||||
```
|
||||
|
||||
## Required customizations
|
||||
|
||||
Most options of a generated configuration can be kept at their default values. However, you must edit some cloud provider options.
|
||||
|
||||
### Azure
|
||||
|
||||
Set the `subscription` and `tenant` IDs of your subscription.
|
||||
|
||||
Set the `userAssignedIdentity` that you [created for Constellation](../getting-started/install.md#azure).
|
||||
|
||||
### GCP
|
||||
|
||||
Set the `project` that you want to use for your Constellation cluster.
|
||||
|
||||
@ -50,7 +50,7 @@ provider:
|
||||
measurements:
|
||||
11: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
|
||||
12: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
|
||||
userAssignedIdentity: "" # Authorize spawned VMs to access Azure API. See: https://docs.edgeless.systems/constellation/getting-started/install#authorization
|
||||
userAssignedIdentity: "" # Authorize spawned VMs to access Azure API.
|
||||
kubernetesVersion: "1.24" # Kubernetes version installed in the cluster.
|
||||
|
||||
# # Egress firewall rules for node network.
|
||||
|
||||
@ -153,12 +153,12 @@ type AzureConfig struct {
|
||||
// Type of a node's state disk. The type influences boot time and I/O performance. See: https://docs.microsoft.com/en-us/azure/virtual-machines/disks-types#disk-type-comparison
|
||||
StateDiskType string `yaml:"stateDiskType" validate:"oneof=Premium_LRS Premium_ZRS Standard_LRS StandardSSD_LRS StandardSSD_ZRS"`
|
||||
// description: |
|
||||
// Authorize spawned VMs to access Azure API. See: https://docs.edgeless.systems/constellation/getting-started/install#authorization
|
||||
UserAssignedIdentity string `yaml:"userAssignedIdentity" validate:"required"`
|
||||
// description: |
|
||||
// Resource group to use.
|
||||
ResourceGroup string `yaml:"resourceGroup" validate:"required"`
|
||||
// description: |
|
||||
// Authorize spawned VMs to access Azure API.
|
||||
UserAssignedIdentity string `yaml:"userAssignedIdentity" validate:"required"`
|
||||
// description: |
|
||||
// Application client ID of the Active Directory app registration.
|
||||
AppClientID string `yaml:"appClientID" validate:"required"`
|
||||
// description: |
|
||||
@ -282,7 +282,7 @@ func Default() *Config {
|
||||
Image: DefaultImageGCP,
|
||||
InstanceType: "n2d-standard-4",
|
||||
StateDiskType: "pd-ssd",
|
||||
ServiceAccountKeyPath: "serviceAccountKey.json",
|
||||
ServiceAccountKeyPath: "",
|
||||
Measurements: copyPCRMap(gcpPCRs),
|
||||
EnforcedMeasurements: []uint32{0, 8, 9, 11, 12},
|
||||
},
|
||||
|
||||
@ -230,16 +230,16 @@ func init() {
|
||||
AzureConfigDoc.Fields[5].Note = ""
|
||||
AzureConfigDoc.Fields[5].Description = "Type of a node's state disk. The type influences boot time and I/O performance. See: https://docs.microsoft.com/en-us/azure/virtual-machines/disks-types#disk-type-comparison"
|
||||
AzureConfigDoc.Fields[5].Comments[encoder.LineComment] = "Type of a node's state disk. The type influences boot time and I/O performance. See: https://docs.microsoft.com/en-us/azure/virtual-machines/disks-types#disk-type-comparison"
|
||||
AzureConfigDoc.Fields[6].Name = "userAssignedIdentity"
|
||||
AzureConfigDoc.Fields[6].Name = "resourceGroup"
|
||||
AzureConfigDoc.Fields[6].Type = "string"
|
||||
AzureConfigDoc.Fields[6].Note = ""
|
||||
AzureConfigDoc.Fields[6].Description = "Authorize spawned VMs to access Azure API. See: https://docs.edgeless.systems/constellation/getting-started/install#authorization"
|
||||
AzureConfigDoc.Fields[6].Comments[encoder.LineComment] = "Authorize spawned VMs to access Azure API. See: https://docs.edgeless.systems/constellation/getting-started/install#authorization"
|
||||
AzureConfigDoc.Fields[7].Name = "resourceGroup"
|
||||
AzureConfigDoc.Fields[6].Description = "Resource group to use."
|
||||
AzureConfigDoc.Fields[6].Comments[encoder.LineComment] = "Resource group to use."
|
||||
AzureConfigDoc.Fields[7].Name = "userAssignedIdentity"
|
||||
AzureConfigDoc.Fields[7].Type = "string"
|
||||
AzureConfigDoc.Fields[7].Note = ""
|
||||
AzureConfigDoc.Fields[7].Description = "Resource group to use."
|
||||
AzureConfigDoc.Fields[7].Comments[encoder.LineComment] = "Resource group to use."
|
||||
AzureConfigDoc.Fields[7].Description = "Authorize spawned VMs to access Azure API."
|
||||
AzureConfigDoc.Fields[7].Comments[encoder.LineComment] = "Authorize spawned VMs to access Azure API."
|
||||
AzureConfigDoc.Fields[8].Name = "appClientID"
|
||||
AzureConfigDoc.Fields[8].Type = "string"
|
||||
AzureConfigDoc.Fields[8].Note = ""
|
||||
|
||||
Loading…
Reference in New Issue
Block a user