Skip to main content
Version: 2.2

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 for your selected cloud provider.

    constellation config generate azure

    This creates the file constellation-conf.yaml in your current working directory.

  2. Fill in your cloud provider specific information.

    You need several resources for the cluster. You can use the following az script to create them:

    RESOURCE_GROUP=constellation # enter name of new resource group for your cluster here
    LOCATION=westus # enter location of resources here
    SUBSCRIPTION_ID=$(az account show --query id --out tsv)
    SERVICE_PRINCIPAL_NAME=constell
    az group create --name "${RESOURCE_GROUP}" --location "${LOCATION}"
    az group create --name "${RESOURCE_GROUP}-identity" --location "${LOCATION}"
    az ad sp create-for-rbac -n "${SERVICE_PRINCIPAL_NAME}" --role Owner --scopes "/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}" | tee azureServiceAccountKey.json
    az identity create -g "${RESOURCE_GROUP}-identity" -n "${SERVICE_PRINCIPAL_NAME}"
    identityID=$(az identity show -n "${SERVICE_PRINCIPAL_NAME}" -g "${RESOURCE_GROUP}-identity" --query principalId --out tsv)
    az role assignment create --assignee-principal-type ServicePrincipal --assignee-object-id "${identityID}" --role 'Virtual Machine Contributor' --scope "/subscriptions/${SUBSCRIPTION_ID}"
    az role assignment create --assignee-principal-type ServicePrincipal --assignee-object-id "${identityID}" --role 'Application Insights Component Contributor' --scope "/subscriptions/${SUBSCRIPTION_ID}"
    echo "subscription: ${SUBSCRIPTION_ID}
    tenant: $(az account show --query tenantId -o tsv)
    location: ${LOCATION}
    resourceGroup: ${RESOURCE_GROUP}
    userAssignedIdentity: $(az identity show -n "${SERVICE_PRINCIPAL_NAME}" -g "${RESOURCE_GROUP}-identity" --query id --out tsv)
    appClientID: $(jq -r '.appId' azureServiceAccountKey.json)
    clientSecretValue: $(jq -r '.password' azureServiceAccountKey.json)"

    Fill the values produced by the script into your configuration file.

    By default, Constellation uses Standard_DC4as_v5 CVMs (4 vCPUs, 16 GB RAM) to create your cluster. Optionally, you can switch to a different VM type by modifying instanceType in the configuration file. For CVMs, any VM type with a minimum of 4 vCPUs from the DCasv5 & DCadsv5 or ECasv5 & ECadsv5 families is supported.

    Run constellation config instance-types to get the list of all supported options.

    info

    In case you don't have access to CVMs on Azure, you may use less secure trusted launch VMs instead. For this, set confidentialVM to false in the configuration file.

  3. Download the trusted measurements for your configured image.

    constellation config fetch-measurements

    For details, see the verification section.

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

  5. Initialize the cluster

    caution

    In this release of Constellation, initialization on Azure might be slow and might take up to 60 minutes to initialize all Kubernetes nodes. This has been fixed in v2.4.

    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.

  6. 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 includes any other Terraform workspace in the current directory.
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.
tip

On Azure, if you have used the az script, you can keep the prerequisite resources and reuse them for a new cluster.

Or you can delete them:

RESOURCE_GROUP=constellation # name of your cluster resource group
APPID=$(jq -r '.appId' azureServiceAccountKey.json)
az ad sp delete --id "${APPID}"
az group delete -g "${RESOURCE_GROUP}-identity" --yes --no-wait
az group delete -g "${RESOURCE_GROUP}" --yes --no-wait