Prepare the cluster

Create your Kubernetes cluster

First, you need a Kubernetes cluster that adheres to conformance testing

We recommend using a tool like Terraform to deploy your Kubernetes cluster.

As an example, we provide two Terraform scripts that can be used for:


Feel free to adapt these scripts to your organizational needs and infrastructure.


Set up your kubeconfig to point to that cluster:

Retrieve the cluster credentials with:

gcloud container clusters get-credentials <cluster-name> --zone <region> --project <project>
aws eks update-kubeconfig --region <region> --name <cluster-name>

Check your kubectl context points to your correct Kubernetes cluster:

kubectl get nodes

Optionally, rename your Kubernetes context to something more meaningful:

kubectl config get-contexts
kubectl config rename-context <current-context> <new-context>

DNS and IP Addresses

During the deployment procedure, voila will ask you about some information. Some are required and some are optional.

The general idea is to determine in advance how you will reach your control plane.

At least:

  • How to reach the web interface: (ex: https://console.mycompany.tld)
  • How to reach the API endpoint (ex: https://api.console.mycompany.tld)


Most Kubernetes providers assign services IP / URL only once they are deployed. You will then need to make the link between the URL above and what is assigned. Voila will help you with that process.

Deploy with voila

Download voila tool

Voila is a toolbox available as a docker container. You can pull it from docker hub:

docker pull

Setup voila environment


The instructions below will set up an environment that uses Aporeto certificate authority by default.

If you want to use a custom certificate authority, check out the advanced configuration.

Run the below command to start the interactive installation.

docker run -ti \
      -v $PWD:/voila-env \
      -v ~/.kube:/root/.kube \ \

The instructions will guide you to:

  1. Create and protect your voila environment
  2. Deploy the control plane within this environment

The deployment can be automatically started after the environment is created:

Your voila environment is now created.
If you are satisfied with this configuration, you can deploy now.

Do you want to start the deployment? (y/n) default is yes:


As the Voila environment contains all the secrets and certificates used by the control plane, it is protected by a generated key that you MUST keep in a safe place.

Without this key you will NEVER be able to load the environment afterward.

This key is ONLY printed ONCE at the end of the Voila environment creation process.

!!! Please save the following shared key in a safe place.           !!!
!!! Don't lose it, or your voila environment will be locked forever !!!

When the installation is done, if some configuration is needed to map the url provided in the first steps. Voila will provide you some information to do so.

Read more about how to make your Voila environment portable and secure


Go to your Voila environment and activate it to have access to all the commands and variables for that particular environment.

cd ./aporeto && ./activate

It will first ask you for the shared key that you kept in a safe place:

🐳 Aporeto voila installer 🐳

    release-3.14.6 v1.2.3 (bc83135b)

Please enter the shared key to unlock this environment:
Docker configuration file updated.

Entering in voila enviromment

Creating helm repository aporeto-svcs pointing to url: in background.

voila - (release-3.14.6) (aporeto)

Your Voila environment is now active.


To exit the environment, you can type either CTRL+D or exit.

Voila main commands

A set of commands is available to perform administrative operations. See all commands available using:


The main command is:

  • doit: This a wrapper tool that will just do it with default configuration

This command will check your current setup and adapt the configuration, apply it and trigger the installation/upgrade if needed. It is idempotent and is calling other commands under the hood like:

  • upconf: This is the tool that maintain your environment settings up to date.
  • snap: Is at tool that will analyze your current deployment and handle the install/update for you.
  • apostate: To check the status of the current deployment

All the settings for your deployment are handled through yaml files that are then feed to the helm charts to generate a Kubernetes resources to create.

There are two commands to help you read and write those configurations:

  • get_value
  • set_value

Operationalize Voila

You may have the need to use Voila in a non-interactive way, for instance:

  • To create a new Voila environment and deploy automatically:

Consult docker run -ti create -h output to see what you can configure using environment variables.

  • To execute a command or a script against an existing Voila environment:

    export VOILA_ENV_KEY=<KEY>
    cd ./aporeto && ./activate run <cmd or script>


  • <KEY> is the Voila environment key used to unlock it.
  • <cmd or script> is a command or script containing commands to run.

About licenses

A license limits the number of enforcers that can be deployed as well as the number of processing units. It is bounded to a control plane and cannot be used on another deployment.

By default, the installation steps installed a trial license limited to two enforcers. To update the license, follow the below steps.

Request a license

Please contact Aporeto sales representative with the following information:

  • Endpoint API URL (ex: https://api.aporeto.mycompany.tld)
  • Contact email: the email address to whom send the license to
  • Contact name: The name of the contact
  • Company: The company name
  • BU: The business unit

Check current license

As of today to check the license you will need to do it from the activated voila environment:

Check Aporeto control plane License

	Valid until 2029-04-19T10:58:07Z
	bu: Engineering
	company: My Company
	contact: John
	email: john@mycompamy.tld
	enforcers: 500
	processingUnits: -1

 ✔ License is valid

Check Aporeto control plane services

 ✔ All core services are up and running.

Check Aporeto control plane public services

 ✔ Check if API is reachable (took 0.7s)
 ✔ Check if UI is reachable (took 0.5s)
 ✔ Check if caching service is reachable (took 0.8s)
 ✔ Check if timeseries database is reachable (took 0.2s)
 ✔ Check if database is reachable (took 0.7s)

Update a license


If you want to deploy a license or update a license on a running system, make sure that the new license is matching the API endpoint.

To update a license, use the following command:

set_value global.license <provided license> override

Then, update the configuration and update the services:

snap -u aporeto-backend --force