Configure your cluster

info

This recording presents the essence of this page. It's recommended to read it in full for the motivation and all details.

Loading asciinema cast...

---

Before you can create your cluster, you need to configure the identity and access management (IAM) for your cloud service provider (CSP) and choose machine types for the nodes.

Creating the configuration file

You can generate a configuration file for your CSP by using the following CLI command:

Azure

constellation config generate azure

GCP

constellation config generate gcp

AWS

constellation config generate aws

This creates the file constellation-conf.yaml in the current directory.

tip

You can also automatically generate a configuration file by adding the --generate-config flag to the constellation iam create command when creating an IAM configuration.

Choosing a VM type

Constellation supports the following VM types:

Azure

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 or ECasv5 & ECadsv5 families is supported.

You can also run constellation config instance-types to get the list of all supported options.

GCP

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 with a minimum of 4 vCPUs from the C2D or N2D family. You can run constellation config instance-types to get the list of all supported options.

AWS

By default, Constellation uses m6a.xlarge 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 nitroTPM-enabled machines with a minimum of 4 vCPUs (xlarge or larger). Refer to the list of nitroTPM-enabled instance types or run constellation config instance-types to get the list of all supported options.

Fill the desired VM type into the instanceType field in the constellation-conf.yml file.

Choosing a Kubernetes version

To learn which Kubernetes versions can be installed with your current CLI, you can run constellation config kubernetes-versions. See also Constellation's Kubernetes support policy.

Creating an IAM configuration

You can create an IAM configuration for your cluster automatically using the constellation iam create command. If you haven't generated a configuration file yet, you can do so by adding the --generate-config flag to the command. This creates a configuration file and populates it with the created IAM values.

Azure

You must be authenticated with the Azure CLI in the shell session with a user that has the required permissions for IAM creation.

constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest

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. These are:

• westus
• eastus
• northeurope
• westeurope
• southeastasia

Paste the output into the corresponding fields of the constellation-conf.yaml file.

tip

Since clientSecretValue is a sensitive value, you can leave it empty in the configuration file and pass it via an environment variable instead. To this end, create the environment variable CONSTELL_AZURE_CLIENT_SECRET_VALUE and set it to the secret value.

GCP

You must be authenticated with the GCP CLI in the shell session with a user that has the required permissions for IAM creation.

constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test

This command creates IAM configuration in the GCP project yourproject-12345 on the GCP zone europe-west2-a creating a new service account constell-test.

Note that only regions offering CVMs of the C2D or N2D series are supported. You can find a list of all regions in Google's documentation, which you can filter by machine type N2D.

Paste the output into the corresponding fields of the constellation-conf.yaml file.

AWS

You must be authenticated with the AWS CLI in the shell session with a user that has the required permissions for IAM creation.

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
• us-east-2
• ap-south-1

If you require the OS image to be available in another region, let us know.

You can find a list of all regions in AWS's documentation.

Paste the output into the corresponding fields of the constellation-conf.yaml file.

Alternatively, you can manually create the IAM configuration on your CSP.

The following describes the configuration fields and how you obtain the required information or create the required resources.

Azure

• 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.

• 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.

• 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. These are:

  • westus
  • eastus
  • northeurope
  • westeurope
  • southeastasia

• resourceGroup: Create a new resource group in Azure for your Constellation cluster. Set this configuration field to the name of the created resource group.

• userAssignedIdentity: Create a new managed identity in Azure. 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 three role assignments to the identity: Owner, Virtual Machine Contributor and Application Insights Component Contributor. The scope of all three 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.

• appClientID: Create a new app registration in Azure.

  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

  Since this is a sensitive value, alternatively you can leave clientSecretValue empty in the configuration file and pass it via an environment variable instead. To this end, create the environment variable CONSTELL_AZURE_CLIENT_SECRET_VALUE and set it to the secret value.

GCP

• project: The ID of your GCP project, e.g., constellation-129857.

  You can find it on the welcome screen of your GCP project. For more information refer to Google's documentation.

• region: The GCP region you want to deploy your cluster in, e.g., us-west1.

  You can find a list of all regions in Google's documentation.

• 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.

• serviceAccountKeyPath: To configure this, you need to create a GCP 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)

  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.

AWS

• region: The name of your chosen AWS data center region, e.g., us-east-2.

  Constellation OS images are currently replicated to the following regions:

  • eu-central-1
  • eu-west-1
  • eu-west-3
  • us-east-2
  • ap-south-1

  If you require the OS image to be available in another region, let us know.

  You can find a list of all regions in AWS's documentation.

• 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.

• iamProfileControlPlane: The name of an IAM instance profile attached to all control-plane nodes.

  You can create the resource with Terraform. For that, use the provided Terraform script 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 in the resource aws_iam_policy.control_plane_policy.

• iamProfileWorkerNodes: The name of an IAM instance profile attached to all worker nodes.

  You can create the resource with Terraform. For that, use the provided Terraform script 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 in the resource aws_iam_policy.worker_node_policy.

Now that you've configured your CSP, you can create your cluster.

Deleting an IAM configuration

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 as a subdirectory):

constellation iam destroy

caution

For Azure, deleting the IAM configuration by executing constellation iam destroy will delete the whole resource group created by constellation iam create. This also includes any additional resources in the resource group that weren't created by Constellation.