Git-Mirrors/constellation
1
0
Fork 0
mirror of https://github.com/edgelesssys/constellation.git synced 2024-12-15 02:44:24 -05:00
Code Issues Packages Projects Releases Wiki Activity
c23f17de41
constellation/docs/versioned_docs/version-2.16/getting-started/first-steps.md
malt3 c4f27f62ee docs: add release v2.16.0
2024-02-29 17:22:19 +01:00

8.9 KiB
Raw Blame History

First steps with Constellation

The following steps guide you through the process of creating a cluster and deploying a sample app. This example assumes that you have successfully installed and set up Constellation, and have access to a cloud subscription.

:::tip If you don't have a cloud subscription, you can also set up a local Constellation cluster using virtualization for testing. :::

:::note If you encounter any problem with the following steps, make sure to use the latest release and check out the known issues. :::

Create a cluster

  1. Create the configuration file and state file for your cloud provider.

    constellation config generate azure

    constellation config generate gcp

    constellation config generate aws

    constellation config generate stackit

  2. Create your IAM configuration.

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

    This command creates IAM configuration on the Azure region westus creating a new resource group constellTest and a new service principal spTest. It also updates the configuration file constellation-conf.yaml in your current directory with the IAM values filled in.

    CVMs are available in several Azure regions. Constellation OS images are currently replicated to the following:

    • germanywestcentral
    • westus
    • eastus
    • northeurope
    • westeurope
    • southeastasia

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

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

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

    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. It also updates the configuration file constellation-conf.yaml in your current directory with the IAM values filled in.

    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 C2D or N2D.

    constellation iam create aws --zone=us-east-2a --prefix=constellTest --update-config

    This command creates IAM configuration for the AWS zone us-east-2a using the prefix constellTest for all named resources being created. It also updates the configuration file constellation-conf.yaml in your current directory with the IAM values filled in.

    Depending on the attestation variant selected on config generation, different regions are available. AMD SEV-SNP machines (requires the default attestation variant awsSEVSNP) are currently available in the following regions:

    • eu-west-1
    • us-east-2

    You can find a list of regions that support AMD SEV-SNP in AWS's documentation.

    NitroTPM machines (requires the attestation variant awsNitroTPM) are available in all regions. 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.

    To use Constellation on STACKIT, the cluster will use the User Access Token (UAT) that's generated during the install step. After creating the accounts, fill in the STACKIT details in constellation-conf.yaml under provider.openstack:

    • projectID: OpenStack project id (can be found in clouds.yaml or openrc file of UAT)
    • projectName: OpenStack project name (can be found in clouds.yaml or openrc file of UAT)
    • stackitProjectID: STACKIT project id (can be found after login on https://portal.stackit.cloud)
    • username: username of the UAT
    • password: password of the UAT

    :::tip To learn about all options you have for managing IAM resources and Constellation configuration, see the Configuration workflow. :::

  1. Create the cluster. constellation apply uses options set in constellation-conf.yaml. If you want to manually manage your cloud resources, for example by using Terraform, follow the corresponding instructions in the Create workflow.

    :::tip

    On Azure, you may need to wait 15+ minutes at this point for role assignments to propagate.

    :::

    constellation apply -y

    This should look similar to the following:

    $ constellation apply -y
Checking for infrastructure changes
The following Constellation cluster will be created:
  3 control-plane nodes of type n2d-standard-4 will be created.
  1 worker node of type n2d-standard-4 will be created.
Creating
Cloud infrastructure created successfully
Your Constellation master secret was successfully written to ./constellation-mastersecret.json
Connecting
Initializing cluster
Installing Kubernetes components
Your Constellation cluster was successfully initialized.

Constellation cluster identifier  g6iMP5wRU1b7mpOz2WEISlIYSfdAhB0oNaOg6XEwKFY=
Kubernetes configuration          constellation-admin.conf

You can now connect to your cluster by executing:
        export KUBECONFIG="$PWD/constellation-admin.conf"

    The cluster's identifier will be different in your output. Keep constellation-mastersecret.json somewhere safe. This will allow you to recover your cluster in case of a disaster.

    :::info

    Depending on your CSP and region, constellation apply may take 10+ minutes to complete.

    :::

  2. Configure kubectl.

    export KUBECONFIG="$PWD/constellation-admin.conf"

Deploy a sample application

  1. Deploy the emojivoto app

    kubectl apply -k github.com/BuoyantIO/emojivoto/kustomize/deployment

  2. Expose the frontend service locally

    kubectl wait --for=condition=available --timeout=60s -n emojivoto --all deployments
kubectl -n emojivoto port-forward svc/web-svc 8080:80 &
curl http://localhost:8080
kill %1

Terminate your cluster

Use the CLI to terminate your cluster. If you manually used Terraform to manage your cloud resources, follow the corresponding instructions in the Terminate workflow.

constellation terminate

This should give the following output:

$ constellation terminate
You are about to terminate a Constellation cluster.
All of its associated resources will be DESTROYED.
This action is irreversible and ALL DATA WILL BE LOST.
Do you want to continue? [y/n]:

Confirm with y to terminate the cluster:

Terminating ...
Your Constellation cluster was terminated successfully.

Optionally, you can also delete your IAM resources.