Setting and managing environment variables
Overview
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.
Sample project
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
helloworld_service.yml
) - 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_PORT
and the value80
- 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
port
and replace the hardcoded value (“8080”) with${env("DEV_PORT")}
- Add a commit message and click Save Changes
Rendering variables
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.yml
and click the show all link - Check that the value for port matches our variable (i.e.
80
)
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.
For example:
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 variables
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.
Be careful
You can use this feature to quickly update large numbers of variables, but be wary of accidentally updating any values while doing so.
What’s next?
- 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.