# Installation and setup Constellation runs entirely in your cloud environment and can be controlled via a dedicated [command-line interface (CLI)](../reference/cli.md) or a [Terraform provider](../workflows/terraform-provider.md). ## Prerequisites Make sure the following requirements are met: * Your machine is running Linux, macOS, or Windows * You have admin rights on your machine * [kubectl](https://kubernetes.io/docs/tasks/tools/) is installed * Your CSP is Amazon Web Services (AWS), Microsoft Azure, Google Cloud Platform (GCP), or STACKIT ## Install the Constellation CLI :::tip If you prefer to use Terraform, you can alternatively use the [Terraform provider](../workflows/terraform-provider.md) to manage the cluster's lifecycle. ::: The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: 1. Download the CLI: ```bash curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/constellation-linux-amd64 ``` 2. [Verify the signature](../workflows/verify-cli.md) (optional) 3. Install the CLI to your PATH: ```bash sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` 1. Download the CLI: ```bash curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/constellation-linux-arm64 ``` 2. [Verify the signature](../workflows/verify-cli.md) (optional) 3. Install the CLI to your PATH: ```bash sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` 1. Download the CLI: ```bash curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/constellation-darwin-arm64 ``` 2. [Verify the signature](../workflows/verify-cli.md) (optional) 3. Install the CLI to your PATH: ```bash sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` 1. Download the CLI: ```bash curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/constellation-darwin-amd64 ``` 2. [Verify the signature](../workflows/verify-cli.md) (optional) 3. Install the CLI to your PATH: ```bash sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` 1. Download the CLI: ```bash Invoke-WebRequest -OutFile ./constellation.exe -Uri 'https://github.com/edgelesssys/constellation/releases/latest/download/constellation-windows-amd64.exe' ``` 2. [Verify the signature](../workflows/verify-cli.md) (optional) 3. Install the CLI under `C:\Program Files\Constellation\bin\constellation.exe` 3. Add the CLI to your PATH: 1. Open `Advanced system settings` by searching for the App in the Windows search 2. Go to the `Advanced` tab 3. Click `Environment Variables…` 4. Click variable called `Path` and click `Edit…` 5. Click `New` 6. Enter the path to the folder containing the binary you want on your PATH: `C:\Program Files\Constellation\bin` :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. ::: ## Set up cloud credentials Constellation makes authenticated calls to the CSP API. Therefore, you need to set up Constellation with the credentials for your CSP. :::tip If you don't have a cloud subscription, you can also set up a [local Constellation cluster using virtualization](../getting-started/first-steps-local.md) for testing. ::: ### Required permissions To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ec2:DescribeAccountAttributes", "iam:AddRoleToInstanceProfile", "iam:AttachRolePolicy", "iam:CreateInstanceProfile", "iam:CreatePolicy", "iam:CreateRole", "iam:DeleteInstanceProfile", "iam:DeletePolicy", "iam:DeletePolicyVersion", "iam:DeleteRole", "iam:DetachRolePolicy", "iam:GetInstanceProfile", "iam:GetPolicy", "iam:GetPolicyVersion", "iam:GetRole", "iam:ListAttachedRolePolicies", "iam:ListInstanceProfilesForRole", "iam:ListPolicyVersions", "iam:ListRolePolicies", "iam:PassRole", "iam:RemoveRoleFromInstanceProfile", "sts:GetCallerIdentity" ], "Resource": "*" } ] } ``` The built-in `AdministratorAccess` policy is a superset of these permissions. To [create a Constellation cluster](../workflows/create.md), see the permissions of [main.tf](https://github.com/edgelesssys/constellation/blob/main/terraform/infrastructure/iam/aws/main.tf). The built-in `PowerUserAccess` policy is a superset of these permissions. Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: * `Microsoft.Attestation` \[2] * `Microsoft.Compute` * `Microsoft.Insights` * `Microsoft.ManagedIdentity` * `Microsoft.Network` By default, Constellation tries to register these automatically if they haven't been registered before. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: * `*/register/action` \[1] * `Microsoft.Authorization/roleAssignments/*` * `Microsoft.Authorization/roleDefinitions/*` * `Microsoft.ManagedIdentity/userAssignedIdentities/*` * `Microsoft.Resources/subscriptions/resourcegroups/*` The built-in `Owner` role is a superset of these permissions. To [create a Constellation cluster](../workflows/create.md), you need the following permissions: * `Microsoft.Attestation/attestationProviders/*` \[2] * `Microsoft.Compute/virtualMachineScaleSets/*` * `Microsoft.Insights/components/*` * `Microsoft.ManagedIdentity/userAssignedIdentities/*` * `Microsoft.Network/loadBalancers/*` * `Microsoft.Network/loadBalancers/backendAddressPools/*` * `Microsoft.Network/networkSecurityGroups/*` * `Microsoft.Network/publicIPAddresses/*` * `Microsoft.Network/virtualNetworks/*` * `Microsoft.Network/virtualNetworks/subnets/*` * `Microsoft.Network/natGateways/*` The built-in `Contributor` role is a superset of these permissions. Follow Microsoft's guide on [understanding](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-definitions) and [assigning roles](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments). 1: You can omit `*/register/Action` if the resource providers mentioned above are already registered and the `ARM_SKIP_PROVIDER_REGISTRATION` environment variable is set to `true` when creating the IAM configuration. 2: You can omit `Microsoft.Attestation/attestationProviders/*` and the registration of `Microsoft.Attestation` if `EnforceIDKeyDigest` isn't set to `MAAFallback` in the [config file](../workflows/config.md#configure-your-cluster). Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: * `iam.serviceAccountKeys.create` * `iam.serviceAccountKeys.delete` * `iam.serviceAccountKeys.get` * `iam.serviceAccounts.create` * `iam.serviceAccounts.delete` * `iam.serviceAccounts.get` * `resourcemanager.projects.getIamPolicy` * `resourcemanager.projects.setIamPolicy` Together, the built-in roles `roles/editor` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. To [create a Constellation cluster](../workflows/create.md), you need the following permissions: * `compute.addresses.createInternal` * `compute.addresses.deleteInternal` * `compute.addresses.get` * `compute.addresses.useInternal` * `compute.backendServices.create` * `compute.backendServices.delete` * `compute.backendServices.get` * `compute.backendServices.use` * `compute.disks.create` * `compute.firewalls.create` * `compute.firewalls.delete` * `compute.firewalls.get` * `compute.firewalls.update` * `compute.globalAddresses.create` * `compute.globalAddresses.delete` * `compute.globalAddresses.get` * `compute.globalAddresses.use` * `compute.globalForwardingRules.create` * `compute.globalForwardingRules.delete` * `compute.globalForwardingRules.get` * `compute.globalForwardingRules.setLabels` * `compute.globalOperations.get` * `compute.healthChecks.create` * `compute.healthChecks.delete` * `compute.healthChecks.get` * `compute.healthChecks.useReadOnly` * `compute.instanceGroupManagers.create` * `compute.instanceGroupManagers.delete` * `compute.instanceGroupManagers.get` * `compute.instanceGroupManagers.update` * `compute.instanceGroups.create` * `compute.instanceGroups.delete` * `compute.instanceGroups.get` * `compute.instanceGroups.update` * `compute.instanceGroups.use` * `compute.instances.create` * `compute.instances.setLabels` * `compute.instances.setMetadata` * `compute.instances.setTags` * `compute.instanceTemplates.create` * `compute.instanceTemplates.delete` * `compute.instanceTemplates.get` * `compute.instanceTemplates.useReadOnly` * `compute.networks.create` * `compute.networks.delete` * `compute.networks.get` * `compute.networks.updatePolicy` * `compute.routers.create` * `compute.routers.delete` * `compute.routers.get` * `compute.routers.update` * `compute.subnetworks.create` * `compute.subnetworks.delete` * `compute.subnetworks.get` * `compute.subnetworks.use` * `compute.targetTcpProxies.create` * `compute.targetTcpProxies.delete` * `compute.targetTcpProxies.get` * `compute.targetTcpProxies.use` * `iam.serviceAccounts.actAs` Together, the built-in roles `roles/editor`, `roles/compute.instanceAdmin` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. 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). Constellation on STACKIT requires a User Access Token (UAT) for the OpenStack API and a STACKIT service account. The UAT already has all required permissions by default. The STACKIT service account needs the `editor` role to create STACKIT LoadBalancers. Look at the [STACKIT documentation](https://docs.stackit.cloud/stackit/en/getting-started-in-service-accounts-134415831.html) on how to create the service account and assign the role. ### Authentication You need to authenticate with your CSP. The following lists the required steps for *testing* and *production* environments. :::note The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: **Testing** You can use the [AWS CloudShell](https://console.aws.amazon.com/cloudshell/home). Make sure you are [authorized to use it](https://docs.aws.amazon.com/cloudshell/latest/userguide/sec-auth-with-identities.html). **Production** Use the latest version of the [AWS CLI](https://aws.amazon.com/cli/) on a trusted machine: ```bash aws configure ``` Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). **Testing** Simply open the [Azure Cloud Shell](https://docs.microsoft.com/en-us/azure/cloud-shell/overview). **Production** Use the latest version of the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/) on a trusted machine: ```bash az login ``` Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). **Testing** You can use the [Google Cloud Shell](https://cloud.google.com/shell). Make sure your [session is authorized](https://cloud.google.com/shell/docs/auth). For example, execute `gsutil` and accept the authorization prompt. **Production** Use one of the following options on a trusted machine: * Use the [`gcloud` CLI](https://cloud.google.com/sdk/gcloud) ```bash gcloud auth application-default login ``` This will ask you to log-in to your Google account and create your credentials. The Constellation CLI will automatically load these credentials when needed. * Set up a service account and pass the credentials manually Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. You need to authenticate with the infrastructure API (OpenStack) and create a service account (STACKIT API). 1. [Follow the STACKIT documentation](https://docs.stackit.cloud/stackit/en/step-1-generating-of-user-access-token-11763726.html) for obtaining a User Access Token (UAT) to use the infrastructure API 2. Create a configuration file under `~/.config/openstack/clouds.yaml` (`%AppData%\openstack\clouds.yaml` on Windows) with the credentials from the User Access Token ```yaml clouds: stackit: auth: auth_url: https://keystone.api.iaas.eu01.stackit.cloud/v3 username: REPLACE_WITH_UAT_USERNAME password: REPLACE_WITH_UAT_PASSWORD project_id: REPLACE_WITH_STACKIT_PROJECT_ID project_name: REPLACE_WITH_STACKIT_PROJECT_NAME user_domain_name: portal_mvp project_domain_name: portal_mvp region_name: RegionOne identity_api_version: 3 ``` 3. [Follow the STACKIT documentation](https://docs.stackit.cloud/stackit/en/getting-started-in-service-accounts-134415831.html) for creating a service account and an access token 4. Assign the `editor` role to the service account by [following the documentation](https://docs.stackit.cloud/stackit/en/getting-started-in-service-accounts-134415831.html) 5. Create a configuration file under `~/.stackit/credentials.json` (`%USERPROFILE%\.stackit\credentials.json` on Windows) ```json {"STACKIT_SERVICE_ACCOUNT_TOKEN":"REPLACE_WITH_TOKEN"} ``` ## Next steps You are now ready to [deploy your first confidential Kubernetes cluster and application](first-steps.md).