constellation/docs/docs/getting-started/first-steps.md

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, check out MiniConstellation, which lets you set up a local Constellation cluster using virtualization. :::

Create a cluster

1. Create the configuration file and IAM resources for your selected cloud provider

   First, you need to create a configuration file and an IAM configuration. The easiest way to do this is the following CLI command:

   constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest --generate-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 creates the configuration file constellation-conf.yaml in your current directory with the IAM values filled in.

   Note that CVMs are currently only supported in a few regions, check Azure's products available by region. These are:

   • westus
   • eastus
   • northeurope
   • westeurope

   constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test --generate-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 creates the configuration file constellation-conf.yaml in your current directory with the IAM values filled in.

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

   constellation iam create aws --zone=eu-central-1a --prefix=constellTest --generate-config
   

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

   Constellation OS images are currently replicated to the following regions:

   • eu-central-1
   • 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.

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

2. Create the cluster with one control-plane node and two worker nodes. constellation create uses options set in constellation-conf.yaml.

   :::tip

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

   :::

   constellation create --control-plane-nodes 1 --worker-nodes 2 -y
   

   This should give the following output:

   $ constellation create ...
   Your Constellation cluster was created successfully.
   

3. Initialize the cluster

   constellation init
   

   This should give the following output:

   $ constellation init
   Your Constellation master secret was successfully written to ./constellation-mastersecret.json
   Initializing cluster ...
   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 init may take 10+ minutes to complete.

   :::

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

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.