From dd4fc0d86961aa9941f6d27da4c15c8d1855b32f Mon Sep 17 00:00:00 2001 From: Moritz Sanft <58110325+stdoutput@users.noreply.github.com> Date: Mon, 12 Dec 2022 13:33:19 +0100 Subject: [PATCH] AB#2685 Add documentation for automatic IAM creation (#711) --- docs/README.md | 3 +- docs/docs/getting-started/first-steps.md | 206 +++--------------- docs/docs/reference/cli.md | 132 ++++++++++++ docs/docs/workflows/config.md | 255 +++++++++++++++++++++++ docs/docs/workflows/create.md | 31 +-- docs/sidebars.js | 5 + 6 files changed, 427 insertions(+), 205 deletions(-) create mode 100644 docs/docs/workflows/config.md diff --git a/docs/README.md b/docs/README.md index ad101209a..dea229064 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,7 +13,7 @@ npm run build npm run serve ``` -Browse to +Browse to and choose the "Next" version in the top right. ## Release process @@ -28,4 +28,3 @@ Browse to Copy the full `docs/` folder contents into a new `versioned_docs/version-[versionName]/` folder. Create a versioned sidebars file based from your current sidebar configuration (if it exists) - saved as `versioned_sidebars/version-[versionName]-sidebars.json`. Append the new version number to `versions.json`. - diff --git a/docs/docs/getting-started/first-steps.md b/docs/docs/getting-started/first-steps.md index 8d5eb19ba..ff6ddc5c0 100644 --- a/docs/docs/getting-started/first-steps.md +++ b/docs/docs/getting-started/first-steps.md @@ -39,192 +39,66 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step 2. Fill in your cloud provider specific information. - - + First you need to create an [IAM configuration](../workflows/config.md#creating-an-iam-configuration). The easiest way to do this is the following CLI command: - You need several resources for the cluster. You can use the following `az` script to create them: + + + ```bash - RESOURCE_GROUP=constellation # enter name of new resource group for your cluster here - LOCATION=westus # enter location of resources here - SUBSCRIPTION_ID=$(az account show --query id --out tsv) - SERVICE_PRINCIPAL_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_PRINCIPAL_NAME}" --role Owner --scopes "/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}" | tee azureServiceAccountKey.json - az identity create -g "${RESOURCE_GROUP}-identity" -n "${SERVICE_PRINCIPAL_NAME}" - identityID=$(az identity show -n "${SERVICE_PRINCIPAL_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} - tenant: $(az account show --query tenantId -o tsv) - location: ${LOCATION} - resourceGroup: ${RESOURCE_GROUP} - userAssignedIdentity: $(az identity show -n "${SERVICE_PRINCIPAL_NAME}" -g "${RESOURCE_GROUP}-identity" --query id --out tsv) - appClientID: $(jq -r '.appId' azureServiceAccountKey.json) - clientSecretValue: $(jq -r '.password' azureServiceAccountKey.json)" + constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest ``` - Fill the values produced by the script into your configuration file. - - :::tip - - Alternatively, you can leave `clientSecretValue` empty and provide the secret via the `CONSTELL_AZURE_CLIENT_SECRET_VALUE` environment variable. - - ::: + 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®ions=all). These are: - - * `westus` - * `eastus` - * `northeurope` - * `westeurope` - - By default, Constellation uses `Standard_DC4as_v5` CVMs (4 vCPUs, 16 GB RAM) to create your cluster. Optionally, you can switch to a different VM type by modifying **instanceType** in the configuration file. For CVMs, any VM type with a minimum of 4 vCPUs from the [DCasv5 & DCadsv5](https://docs.microsoft.com/en-us/azure/virtual-machines/dcasv5-dcadsv5-series) or [ECasv5 & ECadsv5](https://docs.microsoft.com/en-us/azure/virtual-machines/ecasv5-ecadsv5-series) families is supported. - - Run `constellation config instance-types` to get the list of all supported options. + * `westus` + * `eastus` + * `northeurope` + * `westeurope` - - * **subscription**: 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**: 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**: The Azure datacenter location you want to deploy your cluster in, e.g., `westus`. 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). These are: - - * `westus` - * `eastus` - * `northeurope` - * `westeurope` - - * **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. - - * **userAssignedIdentity**: [Create a new managed identity in Azure](https://portal.azure.com/#create/Microsoft.ManagedIdentity). You should create the identity in a different resource group as all resources within the cluster resource group will be deleted on cluster termination. - - Add two role assignments to the identity: `Virtual Machine Contributor` and `Application Insights Component Contributor`. The `scope` of both should refer to the previously created cluster 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`. You can get it by opening the `JSON View` from the `Overview` section of the 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). - - Set `Supported account types` to `Accounts in this organizational directory only` and leave the `Redirect URI` empty. - - Set the configuration value to the `Application (client) ID`, e.g., `86ec31dd-532b-4a8c-a055-dd23f25fb12f`. - - In the cluster resource group, go to `Access Control (IAM)` and set the created app registration as `Owner`. - - * **clientSecretValue**: In the previously created app registration, go to `Certificates & secrets` and create a new `Client secret`. - - Set the configuration value to the secret value. - - :::tip - - Alternatively, you can leave `clientSecretValue` empty and provide the secret via the `CONSTELL_AZURE_CLIENT_SECRET_VALUE` environment variable. - - ::: - - * **instanceType**: The VM type you want to use for your Constellation nodes. - - For CVMs, any type with a minimum of 4 vCPUs from the [DCasv5 & DCadsv5](https://docs.microsoft.com/en-us/azure/virtual-machines/dcasv5-dcadsv5-series) or [ECasv5 & ECadsv5](https://docs.microsoft.com/en-us/azure/virtual-machines/ecasv5-ecadsv5-series) families is supported. It defaults to `Standard_DC4as_v5` (4 vCPUs, 16 GB RAM). - - Run `constellation config instance-types` to get the list of all supported options. - - - - - You need a service account for the cluster. You can use the following `gcloud` script to create it: + ```bash - SERVICE_ACCOUNT_ID=constell # enter name of service account here - PROJECT_ID= # enter project id here - SERVICE_ACCOUNT_EMAIL=${SERVICE_ACCOUNT_ID}@${PROJECT_ID}.iam.gserviceaccount.com - gcloud iam service-accounts create "${SERVICE_ACCOUNT_ID}" --description="Service account used inside Constellation" --display-name="Constellation service account" --project="${PROJECT_ID}" - gcloud projects add-iam-policy-binding "${PROJECT_ID}" --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" --role='roles/compute.instanceAdmin.v1' - gcloud projects add-iam-policy-binding "${PROJECT_ID}" --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" --role='roles/compute.networkAdmin' - gcloud projects add-iam-policy-binding "${PROJECT_ID}" --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" --role='roles/compute.securityAdmin' - gcloud projects add-iam-policy-binding "${PROJECT_ID}" --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" --role='roles/compute.storageAdmin' - gcloud projects add-iam-policy-binding "${PROJECT_ID}" --member="serviceAccount:${SERVICE_ACCOUNT_EMAIL}" --role='roles/iam.serviceAccountUser' - gcloud iam service-accounts keys create gcpServiceAccountKey.json --iam-account="${SERVICE_ACCOUNT_EMAIL}" - echo "project: ${PROJECT_ID} - serviceAccountKeyPath: $(realpath gcpServiceAccountKey.json)" + constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west1-a --serviceAccountID=constell-test ``` - Fill the values produced by the script into your configuration file. + This command creates IAM configuration in the GCP project `yourproject-12345` on the GCP zone `europe-west1-a` creating a new service account `constell-test`. - Note that only regions offering CVMs of the `N2D` series mentioned below are supported. Find a full [list of regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones), which you can filter by machine type `N2D`. - - By default, Constellation uses `n2d-standard-4` VMs (4 vCPUs, 16 GB RAM) to create your cluster. Optionally, you can switch to a different VM type by modifying **instanceType** in the configuration file. Supported are all machines from the N2D family. Refer to [N2D machine series](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) or run `constellation config instance-types` to get the list of all supported options. + Note that only regions offering CVMs of the `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `N2D`. - - * **project**: The ID of your GCP project, e.g., `constellation-129857`. - - You can 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**: The GCP region you want to deploy your cluster in, e.g., `us-west1`. - - Note that only regions offering CVMs of the `N2D` series mentioned below are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `N2D`. - - * **zone**: The GCP zone you want to deploy your cluster in, e.g., `us-west1-a`. - - You can find a [list of all zones in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available). The zone must be in the region specified above. - - * **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)` - - 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`. - - * **instanceType**: The VM type you want to use for your Constellation nodes. - - Supported are all machines from the N2D family. It defaults to `n2d-standard-4` (4 vCPUs, 16 GB RAM), but you can use any other VMs from the same family. Refer to [N2D machine series](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) or run `constellation config instance-types` to get the list of all supported options. - - - * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. + ```bash + constellation iam create aws --zone=eu-central-1a --prefix=constellTest + ``` - Constellation OS images are currently replicated to the following regions: - * `eu-central-1` - * `us-east-2` - * `ap-south-1` + This command creates IAM configuration for the AWS zone `eu-central-1a` using the prefix `constellTest` for all named resources being created. - If you require the OS image to be available in another region, [let us know](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&template=feature_request.md&title=Support+new+AWS+image+region:+xx-xxxx-x). + Constellation OS images are currently replicated to the following regions: + * `eu-central-1` + * `us-east-2` + * `ap-south-1` - You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). + If you require the OS image to be available in another region, [let us know](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&template=feature_request.md&title=Support+new+AWS+image+region:+xx-xxxx-x). - * **zone**: The name of your chosen AWS data center availability zone, e.g., `us-east-2a`. - - Learn more about [availability zones in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-availability-zones). - - * **iamProfileControlPlane**: The name of an IAM instance profile attached to all control-plane nodes. - - Use the [provided Terraform script](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam) to generate the necessary profile. The profile name will be provided as Terraform output value: `control_plane_instance_profile`. - - Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.control_plane_policy`. - - * **iamProfileWorkerNodes**: The name of an IAM instance profile attached to all worker nodes. - - Use the [provided Terraform script](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam) to generate the necessary profile. The profile name will be provided as Terraform output value: `worker_nodes_instance_profile`. - - Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. + You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). + Now, fill the output values of the command into the corresponding fields of the `constellation-conf.yaml` file. + + :::tip + + To learn how to delete your IAM configuration and to get more detailed information on the IAM process and the VM types supported by Constellation, see the [Configuration workflow](../workflows/config.md). + + ::: +