constellation/docs/versioned_docs/version-2.16/getting-started/install.md

Installation and setup

Constellation runs entirely in your cloud environment and can be controlled via a dedicated command-line interface (CLI) or a Terraform provider.

Prerequisites

Make sure the following requirements are met:

• Your machine is running Linux, macOS, or Windows
• You have admin rights on your machine
• kubectl 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 to manage the cluster's lifecycle.

:::

The CLI executable is available at GitHub. Install it with the following commands:

1. Download the CLI:

curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/constellation-linux-amd64

2. Verify the signature (optional)

3. Install the CLI to your PATH:

sudo install constellation-linux-amd64 /usr/local/bin/constellation

1. Download the CLI:

curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/constellation-linux-arm64

2. Verify the signature (optional)

3. Install the CLI to your PATH:

sudo install constellation-linux-arm64 /usr/local/bin/constellation

1. Download the CLI:

curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/constellation-darwin-arm64

2. Verify the signature (optional)

3. Install the CLI to your PATH:

sudo install constellation-darwin-arm64 /usr/local/bin/constellation

1. Download the CLI:

curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/constellation-darwin-amd64

2. Verify the signature (optional)

3. Install the CLI to your PATH:

sudo install constellation-darwin-amd64 /usr/local/bin/constellation

1. Download the CLI:

Invoke-WebRequest -OutFile ./constellation.exe -Uri 'https://github.com/edgelesssys/constellation/releases/latest/download/constellation-windows-amd64.exe'

2. Verify the signature (optional)

3. Install the CLI under C:\Program Files\Constellation\bin\constellation.exe

4. 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 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 for Constellation, you need the following permissions:

{
    "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, see the permissions of main.tf.

The built-in PowerUserAccess policy is a superset of these permissions.

Follow Amazon's guide on understanding and managing policies.

The following resource providers need to be registered in your subscription:

• Microsoft.Attestation
• 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 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, you need the following permissions:

• Microsoft.Attestation/attestationProviders/*
• 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 and assigning roles.

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.

Create a new project for Constellation or use an existing one. Enable the Compute Engine API on it.

To create the 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, 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 and assigning roles.

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 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. Make sure you are authorized to use it.

Production

Use the latest version of the AWS CLI on a trusted machine:

aws configure

Options and first steps are described in the AWS CLI documentation.

Testing

Simply open the Azure Cloud Shell.

Production

Use the latest version of the Azure CLI on a trusted machine:

az login

Other options are described in Azure's authentication guide.

Testing

You can use the Google Cloud Shell. Make sure your session is authorized. For example, execute gsutil and accept the authorization prompt.

Production

Use one of the following options on a trusted machine:

• Use the gcloud CLI

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

   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 for creating a service account and an access token

4. Assign the editor role to the service account by following the documentation

5. Create a configuration file under ~/.stackit/credentials.json (%USERPROFILE%\.stackit\credentials.json on Windows)

   {"STACKIT_SERVICE_ACCOUNT_TOKEN":"REPLACE_WITH_TOKEN"}
   

Next steps

You are now ready to deploy your first confidential Kubernetes cluster and application.