Skip to main content
Version: 2.5

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.


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

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

  1. Create the cluster with one control-plane node and two worker nodes. constellation create uses options set in constellation-conf.yaml. If you want to use Terraform for managing the cloud resources instead, follow the corresponding instructions in the Create workflow.


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


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

  3. Configure kubectl

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

Deploy a sample application

  1. Deploy the emojivoto app

    kubectl apply -k
  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 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.