Secret management

Overview

Managing sensitive strings such as passwords, API keys, and secret credentials — is just one of the steps in the quest for increasing security in a project. We understand this like no one else and provide an extremely easy and secure way of managing secret variables.
All secret variables are stored in Vault, secret storage from HashiCorp organization, which provides a high-security level thanks to its architecture and secret engines.

Service Secrets

For convenience, all variables that we specify for the service are available as environment variables. In order to add a new variable for the service, you can use the CLI interface, which can be found in Commands section.
Please note, that each operation with a secret (create, update, remove…) will trigger service (container) reboot. Currently, we are working on improving the current secret delivery solution. Soon, secrets variables will deliver to your services on the fly.
Service secrets are secure key-value storage, which syntax is available using cs secret command.

Add a new service secret

To add a new secret variable just execute cs secret:add command with flags which next flags:
  • -k key of the secret variable
  • -v value of the secret variable
  • -s service ID
  • -e service environment
Information about all supported flags can be found on Commands section.
Below is an example of adding the FOO variable with the BAR value to the existing service with ID: MY_SERVICE. For clarity, we will use a service that is deployed in a demo environment.
cs secret:add -s MY_SERVICE -e demo -k FOO -v BAR
Successful result of the command execution will be:
Successfully added a new secret variable FOO
Key Value Source
FOO BAR Environment: demo, ServiceID: 1
That’s it! Now, variable FOO will be available as an environment variable after container reboot. Now, you can access it in your code.

Access a new variable in code

For example, to access variable using TypeScript use process global variable:
process.env.FOO

List service secrets

Update service secret

Remove service secret

Project Service Secrets

Using the same command syntax we can add an environment variable for any project services.
-p flag allows adding a variable on the project level.
cs secret:add -p MY_PROJECT -s MY_SERVICE -e development -k FOO -v BAR
The FOO variable is now available inside the MY_SERVICE service, which is included in the MY_PROJECT project.
Please note: MY_SERVICE service is already included in MY_PROJECT project.
But what if my project includes many services that are deployed in different environments? Would be inconvenient to prescribe a separate set of secret variables for each service, so we implemented inheritance.

Inheritance

There are cases when we need to specify only one secret variable for all services which includes in the whole project. In this case, we can just execute cs secret:add only with -p project flag.
Let's imagine that we have an empty project with ID: MY_PROJECT, which includes three services with ID's: A, B, and C. They, by default, deployed on three project environments: development, staging, production. For more information about environments, see the Environments section.
Project without any secret variable, which includes three services: A, B, C

Project level variables inheritance

Let’s add variable FOO with value BAR to project MY_PROJECT, which will be available for each service on each environment inside MY_PROJECT project.
cs secret:add -p MY_PROJECT -k FOO -v BAR
Successful result of the command execution will be:
Successfully added a new secret variable FOO
Key Value Source
FOO BAR ProjectID: 1
As you can see, the Source of a variable - is a project, where we just added a new variable. From this moment, we can access FOO variable from each service, in each environment, which included in our project. In the diagram below, the services that have access to the value of the FOO variable are highlighted in green:
Services, where available project level FOO variable.

Environments level variables inheritance

We may face a case when you need a different secret variable value on some service or on the whole environment. This isn't a problem, cause we can just override the value of the variable, using the same cs secret:add command, specifying for which environment/or service we should apply it.
For example, if we specify the FOO variable with value BAR2 for a project MY_PROJECT from the previous example and just set flag -e (environment) with value development, we override this value for each service in the development environment.
cs secret:add -p MY_PROJECT -e development -k FOO -v BAR2
Successful result of the command execution will be:
Successfully added a new secret variable FOO
Key Value Source
FOO BAR2 ProjectID: 1, Environment: development
In this case, the Source displays the current variable source and shows that FOO variable has BAR2 value for each service, WHICH includes in the project MY_PROJECT, and deployed on the development environment. In the diagram below, the services that have access to the new value BAR2 of the FOO variable are highlighted in blue:
Services, where available environment level FOO variable with BAR2 value.

Service level variable inheritance

In case, when our service requires another secret variable value - we can just override it. To override it - just specify -s flag with service ID, let it be service A for example, and a new value of FOO variable is BAR3.
cs secret:add -p MY_PROJECT -e development -s A -k FOO -v BAR3
Successful result of the command execution will be:
Successfully added a new secret variable FOO
Key Value Source
FOO BAR3 ProjectID: 1, Environment: development, ServiceID: 1
In this case, service A will obtain a new value of FOO variable. In the diagram below, the services that have access to the new value BAR3 of the FOO variable are highlighted in yellow:
Service A with a new value of FOO variable.
Basically, you can do the same with services, which deployed on demo and private environments. But note, that demo and private - is a non-production service environments, and has many limitations, including "per-request availability". To learn more see Environments section.