Secrets and Parameters
Secrets and parameters are project-wide variables that you can use in your Automation scripts:
Parameters – variables that are frequently used throughout your Automation scripts. For example, a URL of an external service.
Secrets – variables stored in the AES-encrypted format. For example, credentials to an external service.
Once you delete a secret from a project, it is instantly deleted from the storage (if there are running jobs that use the secret, it will be deleted once the jobs finish running).
To use secrets and parameters in jobs, you must first create them in the project settings.
Vault parameters – secrets stored in external HashiCorp Vault storage. Before you can use Vault parameters, you must configure a connection to the storage.
Note that Automation hides values of secrets and Vault parameters in job logs for security reasons.
Creating secrets and parameters
Open the desired project.
On the project sidebar menu, choose Settings, then Secrets and Parameters.
Click Create and choose Secret or Parameter.
Specify
Key: a variable name. You will use this name to reference this variable in your scripts.
Value: a variable value.
Note the limitations:
Secrets and parameters exist only in a scope of a particular project. So, if you create a secret or a parameter in one project, you cannot use them in other projects.
Keys of secrets and parameters must be unique within a project. A secret and a parameter with the same key are also not allowed.
A key must be no longer than 128 characters and can only contain alphanumeric characters (
[a-z]
,[A-Z]
,[0-9]
), dashes (-
), or underscores (_
).Keys are case-insensitive.
Max secret's or parameter's value size is 30KB. Note that the max total size of all container arguments, environment variables, secrets, and parameters is also limited by 30KB. For example, if you provide a secret of 30KB and an argument of 1KB to a step, the step will fail.
Creating Vault parameters
In addition to its secret storage, Space also supports external HashiCorp Vault storage. Once you configure a connection to a Vault server, you can use variables from the storage the same way you use project parameters.
- Prerequisites
You have a working Vault server with a configured AppRole. The server stores secrets required by the build script.
To configure connection to a Vault server
Open the desired project.
On the project sidebar menu, choose Settings, then Vault Connections.
Click New connection and specify a connection Name and other settings:
Vault URL: a URL of the Vault server in the
https://vaultserver:port
format.AppRole ID and AppRole Secret ID: credentials used by Space to log in to the Vault server.
Parameters namespace: (optional) an additional connection identifier. If a project has multiple Vault connections, Parameters namespace lets you specify which connection must be used to resolve a particular parameter.
Vault namespace: (optional) a Vault namespace that is used in multi-tenant Vault configurations.
Click Test connection and if connection is successfull, click Create.
To create a Vault parameter
Open the desired project.
On the project sidebar menu, choose Settings, then Secrets and Parameters.
Click Create and choose Vault parameter.
Specify
Key: a variable name. You will use this name to reference this variable in your scripts.
Path: a Vault secret path in the Key/Value v1 or v2 secrets engine format. For example,
/aws/sts/mysecret
.Field: (optional) a field name. If a secret has multiple fields, specify the field which value you want to get in an Automation job. If a secret has multiple fields, but you don't specify a field name, Automation will try to get a field named
value
.Namespace: (optional) an identifier of the Vault connection that must resolve the parameter. The Namespace must match the parameters namespace specified for the Vault connection.
Click Save.
Using secrets and parameters
Use the
Secrets
andParams
functions to assign the value of a secret or a parameter to an environment variable.Use the environment variable inside
shellScript
orkotlinScript
.
For example: