mirror of
https://github.com/edgelesssys/constellation.git
synced 2024-12-26 16:09:45 -05:00
352 lines
12 KiB
Markdown
352 lines
12 KiB
Markdown
# Installation and setup
|
|
|
|
Constellation runs entirely in your cloud environment and can be controlled via a dedicated command-line interface (CLI).
|
|
|
|
The following guides you through the steps of installing the CLI on your machine, verifying it, and connecting it to your cloud service provider (CSP).
|
|
|
|
## Prerequisites
|
|
|
|
Make sure the following requirements are met:
|
|
|
|
- Your machine is running Linux or macOS
|
|
- You have admin rights on your machine
|
|
- [kubectl](https://kubernetes.io/docs/tasks/tools/) is installed
|
|
- Your CSP is Microsoft Azure, Google Cloud Platform (GCP), or Amazon Web Services (AWS)
|
|
|
|
## Install the Constellation CLI
|
|
|
|
The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases).
|
|
Install it with the following commands:
|
|
|
|
<tabs>
|
|
<tabItem value="linux-amd64" label="Linux (amd64)">
|
|
|
|
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
|
|
```
|
|
|
|
</tabItem>
|
|
<tabItem value="linux-arm64" label="Linux (arm64)">
|
|
|
|
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
|
|
```
|
|
|
|
|
|
</tabItem>
|
|
|
|
<tabItem value="darwin-arm64" label="macOS (Apple Silicon)">
|
|
|
|
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
|
|
```
|
|
|
|
|
|
|
|
</tabItem>
|
|
|
|
<tabItem value="darwin-amd64" label="macOS (Intel)">
|
|
|
|
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
|
|
```
|
|
|
|
</tabItem>
|
|
</tabs>
|
|
|
|
:::tip
|
|
The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps.
|
|
:::
|
|
|
|
## Set up cloud credentials
|
|
|
|
The CLI 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 try [MiniConstellation](first-steps-local.md), which lets you set up a local Constellation cluster using virtualization.
|
|
:::
|
|
|
|
### Required permissions
|
|
|
|
<tabs groupId="csp">
|
|
<tabItem value="azure" label="Azure">
|
|
|
|
The following [resource providers need to be 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.Compute`
|
|
* `Microsoft.ManagedIdentity`
|
|
* `Microsoft.Network`
|
|
* `microsoft.insights`
|
|
|
|
By default, Constellation tries to register these automatically if they haven't been registered before.
|
|
|
|
You need the following permissions for your user account:
|
|
|
|
- `Contributor` (to create cloud resources)
|
|
- `User Access Administrator` (to create a service account)
|
|
|
|
If you don't have these permissions with scope *subscription*, ask your administrator to [create the service account and a resource group for your Constellation cluster](first-steps.md).
|
|
Your user account needs the `Contributor` permission scoped to this resource group.
|
|
|
|
</tabItem>
|
|
<tabItem value="gcp" label="GCP">
|
|
|
|
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.
|
|
|
|
You need the following permissions on this project:
|
|
|
|
- `compute.*` (or the subset defined by `roles/compute.instanceAdmin.v1`)
|
|
- `iam.serviceAccountUser`
|
|
|
|
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).
|
|
|
|
</tabItem>
|
|
<tabItem value="aws" label="AWS">
|
|
|
|
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 AWS IAM policies, your user requires the following minimal set of permissions:
|
|
|
|
```json
|
|
{
|
|
"Version": "2012-10-17",
|
|
"Statement": [
|
|
{
|
|
"Effect": "Allow",
|
|
"Action": [
|
|
"sts:GetCallerIdentity",
|
|
"ec2:DescribeAccountAttributes",
|
|
"iam:CreateRole",
|
|
"iam:CreatePolicy",
|
|
"iam:GetPolicy",
|
|
"iam:GetRole",
|
|
"iam:GetPolicyVersion",
|
|
"iam:ListRolePolicies",
|
|
"iam:ListAttachedRolePolicies",
|
|
"iam:CreateInstanceProfile",
|
|
"iam:AttachRolePolicy",
|
|
"iam:GetInstanceProfile",
|
|
"iam:AddRoleToInstanceProfile",
|
|
"iam:PassRole",
|
|
"iam:RemoveRoleFromInstanceProfile",
|
|
"iam:DetachRolePolicy",
|
|
"iam:DeleteInstanceProfile",
|
|
"iam:ListPolicyVersions",
|
|
"iam:ListInstanceProfilesForRole",
|
|
"iam:DeletePolicy",
|
|
"iam:DeletePolicyVersion",
|
|
"iam:DeleteRole"
|
|
],
|
|
"Resource": "*"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
To create the infrastructure, you can either use a predefined role from Amazon,
|
|
such as `PowerUserAccess`, or use the following minimal set of permissions:
|
|
|
|
```json
|
|
{
|
|
"Version": "2012-10-17",
|
|
"Statement": [
|
|
{
|
|
"Effect": "Allow",
|
|
"Action": [
|
|
"sts:GetCallerIdentity",
|
|
"ec2:DescribeAccountAttributes",
|
|
"ec2:AllocateAddress",
|
|
"ec2:CreateVpc",
|
|
"ec2:CreateTags",
|
|
"logs:CreateLogGroup",
|
|
"ec2:CreateLaunchTemplate",
|
|
"ec2:DescribeAddresses",
|
|
"ec2:DescribeLaunchTemplates",
|
|
"logs:PutRetentionPolicy",
|
|
"logs:DescribeLogGroups",
|
|
"ec2:DescribeVpcs",
|
|
"ec2:DescribeLaunchTemplateVersions",
|
|
"logs:ListTagsLogGroup",
|
|
"ec2:DescribeVpcClassicLink",
|
|
"ec2:DescribeVpcClassicLinkDnsSupport",
|
|
"ec2:DescribeVpcAttribute",
|
|
"ec2:DescribeNetworkAcls",
|
|
"ec2:DescribeRouteTables",
|
|
"ec2:DescribeSecurityGroups",
|
|
"ec2:CreateSubnet",
|
|
"ec2:CreateSecurityGroup",
|
|
"elasticloadbalancing:CreateTargetGroup",
|
|
"ec2:CreateInternetGateway",
|
|
"ec2:DescribeSubnets",
|
|
"elasticloadbalancing:DescribeTargetGroups",
|
|
"ec2:AttachInternetGateway",
|
|
"elasticloadbalancing:ModifyTargetGroupAttributes",
|
|
"ec2:DescribeInternetGateways",
|
|
"autoscaling:CreateAutoScalingGroup",
|
|
"iam:PassRole",
|
|
"ec2:CreateNatGateway",
|
|
"ec2:RevokeSecurityGroupEgress",
|
|
"elasticloadbalancing:DescribeTargetGroupAttributes",
|
|
"elasticloadbalancing:CreateLoadBalancer",
|
|
"ec2:DescribeNatGateways",
|
|
"elasticloadbalancing:DescribeTags",
|
|
"autoscaling:DescribeScalingActivities",
|
|
"ec2:CreateRouteTable",
|
|
"autoscaling:DescribeAutoScalingGroups",
|
|
"ec2:AuthorizeSecurityGroupIngress",
|
|
"ec2:AuthorizeSecurityGroupEgress",
|
|
"ec2:CreateRoute",
|
|
"ec2:AssociateRouteTable",
|
|
"elasticloadbalancing:DescribeTargetHealth",
|
|
"elasticloadbalancing:DescribeLoadBalancers",
|
|
"elasticloadbalancing:ModifyLoadBalancerAttributes",
|
|
"elasticloadbalancing:AddTags",
|
|
"elasticloadbalancing:DescribeLoadBalancerAttributes",
|
|
"elasticloadbalancing:CreateListener",
|
|
"elasticloadbalancing:DescribeListeners",
|
|
"logs:DeleteLogGroup",
|
|
"elasticloadbalancing:DeleteListener",
|
|
"ec2:DisassociateRouteTable",
|
|
"autoscaling:UpdateAutoScalingGroup",
|
|
"elasticloadbalancing:DeleteLoadBalancer",
|
|
"autoscaling:SetInstanceProtection",
|
|
"ec2:DescribeNetworkInterfaces",
|
|
"ec2:DeleteRouteTable",
|
|
"ec2:DeleteNatGateway",
|
|
"ec2:DetachInternetGateway",
|
|
"ec2:DisassociateAddress",
|
|
"ec2:ReleaseAddress",
|
|
"ec2:DeleteInternetGateway",
|
|
"ec2:DeleteSubnet",
|
|
"autoscaling:DeleteAutoScalingGroup",
|
|
"ec2:DeleteLaunchTemplate",
|
|
"elasticloadbalancing:DeleteTargetGroup",
|
|
"ec2:DeleteSecurityGroup",
|
|
"ec2:DeleteVpc"
|
|
],
|
|
"Resource": "*"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
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).
|
|
|
|
</tabItem>
|
|
</tabs>
|
|
|
|
### 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.
|
|
:::
|
|
|
|
<tabs groupId="csp">
|
|
<tabItem value="azure" label="Azure">
|
|
|
|
**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).
|
|
|
|
</tabItem>
|
|
<tabItem value="gcp" label="GCP">
|
|
|
|
**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.
|
|
|
|
</tabItem>
|
|
<tabItem value="aws" label="AWS">
|
|
|
|
**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).
|
|
|
|
</tabItem>
|
|
|
|
|
|
</tabs>
|
|
|
|
## Next steps
|
|
|
|
You are now ready to [deploy your first confidential Kubernetes cluster and application](first-steps.md).
|