One of the benefits of using Formations and Stencils is that you can define environment variables centrally and then pull them into different configuration files as you need them, using the powerful Stencil Placeholder syntax.
You can create, edit and manage environment variables for each of your applications via your Cloud 66 dashboard.
What you’ll need
Before you start, please check you have the following:
A Cloud 66 Account — If you don't already have one sign up for a Cloud 66 account. Your first server is free, no credit card required.
An existing application set up in Skycap — You can learn how to do that with our Getting started with Skycap guide.
An existing Formation defined in Skycap — You can learn how to do that with our Getting started with Skycap Formations guide.
In this example we’re using the same simple "hello world" project that we used in our Getting Started guides and our other tutorials.
Setting environment variables for an application
Let’s imagine you’ve decided to set the ports for your Hello World service via an environment variable rather than directly in your stencils.
To achieve this, we need to four things:
- Add an environment variable to the application via the Cloud 66 dashboard
- Take a new Snapshot of the application (to enable the new variable to be called)
- Edit the Stencil for the service in question (in our case
- Render the Formation to see that the variable is being pulled through correctly
Adding a custom variable
To add our variable, we:
- Open your Cloud 66 dashboard and click on the Hello World application
- Click on ⚙️ Settings in the left-hand nav
- Click on Environment Variables in the sub-nav that opens
- Add the key name
DEV_PORTand the value
- Click Save Changes
This will add our custom variable to the application as a whole, but it won’t be available to use in our Stencils until we take a new Snapshot
Ingesting new variables via a Snapshot
Before a newly added custom environment variable can be used in your Stencils (or elsewhere in your application), you need to take a fresh Snapshot of your application. This is because Snapshots encapsulate environment variables at a specific point in time (which enables rollbacks and other useful features).
To take a Snapshot, click the green Snapshot button at the top right of the screen and select Snapshot all. Once the build process is complete, we can begin using our new variable in our Stencils.
Calling variables in Stencils
Now we need to pull our new
DEV_PORT variable into our
helloworld_service.yml Stencil. We do this using a snippet of Stencil Placeholder syntax:
- Click on Formations in the left-hand nav Click on the edit icon next to the “Hello World” service Stencil
- Find the
portand replace the hardcoded value (“8080”) with
- Add a commit message and click Save Changes
To see whether our new variable is working correctly, we need to render our Formation and then check the contents of the Stencil we just edited. To do this:
- Ensure you’re on the Formation page for your Hello World application
- Click on the Render Formation button below the Stencil list. This will render out all your stencils
- Scroll down to your
helloworld_service.ymland click the show all link
- Check that the value for port matches our variable (i.e.
Importing multiple variables
It's possible to import multiple environment variables into a Stencil at once, as well as filter which variables are imported, using the
envlist Stencil placeholder.
If you'd like to learn how to do this, follow our dedicated envlist guide.
Uploading and downloading variable files
You can manage your environment variables in bulk by uploading them in a
.txt file with each variable declared on a separate line, and key value pairs separated by
= signs. The Key should always be in uppercase.
DEV_PORT=80 LIVE_PORT=8080 FOO=Bar YES=Green
To upload a file:
- Navigate to the Environment variables page for the application in question (as above)
- At the top of the panel, click the Choose file button and select the file
- Your list of variables will immediately update to reflect the new variables (or changes to existing variables.
- Click Save changes to save them into your application (changes will be discarded unless you do this)
Uploading variable files is additive not subtractive. It will add new variables to your existing list, but will not remove any existing variables. It will, however, update any existing variables if you have changed the value of any of the keys.
Downloading variables as a file
You can also download your existing variables in the same format by clicking the Download file on the same page (below the left-hand nav). This will produce a
.txt file in the same format described above.
You can use this feature to quickly update large numbers of variables, but be wary of accidentally updating any values while doing so.
- How to import entire sets of common variables into Stencils
- Learn how to update an existing service in Skycap.
- Learn how to add new services or components to a service.
- Learn how to roll back to an older version of your application using Snapshots.
- Learn how to set up access control and permissions on your Formations and Stencils
- Learn how to use your Habitus build flow within Skycap.
- Learn how to use validation policies to ensure your Stencils adhere to your standards and conventions.