Managing secrets

You can use secrets to interact with external services.

Creating secrets

Creating a secret on the command line

To create a secret, use the union create secret command:

$ union create secret my_secret_name

You’ll be prompted to enter a secret value in the terminal:

Enter secret value: ...

Creating a secret from a file

To create a secret from a file, run the following command:

$ union create secret my_secret_name -f /path/to/secret_file

Scoping secrets

When you create a secret without specifying a project or domain, as we did above, the secret is scoped to the organization level. This means that the secret will be available across all projects and domains in the organization.

You can optionally specify either or both of the --project and --domain flags to restrict the scope of the secret to:

• A specific project (across all domains)
• A specific domain (across all project)
• A specific project and a specific domain.

For example, to create a secret so that it is only available to workflows in my_project/development, you would run:

$ union create secret my_secret_name --project my_project --domain development

Listing secrets

You can list existing secrets with the union get secret command. For example the following command will list all secrets in the organization:

$ union get secret

Specifying either or both of the --project and --domain flags will list the secrets that are only available in that project and/or domain.

For example, to list the secrets that are only available in my_project and domain development, you would run:

$ union get secret --project my_project --domain development

Using secrets in workflow code

Note that a workflow can only access secrets whose scope includes the project and domain of the workflow.

Using a secret created on the command line

To use a secret created on the command line, see the example code below. To run the example code:

1. Create a secret on the command line with the key my_secret.
2. Copy the following example code to a new file and save it as using_secrets.py.
3. Run the script with union run --remote using_secrets.py main.

import union

@union.task(secret_requests=[union.Secret(key="my_secret")])
def t1():
    secret_value = union.current_context().secrets.get(key="my_secret")
    # do something with the secret. For example, communication with an external API.
    ...

With env_var, you can automatically load the secret into the environment. This is useful with libraries that expect the secret to have a specific name:

import union

@union.task(secret_requests=[union.Secret(key="my_union_api_key", env_var="UNION_API_KEY")])
def t1():
    # Authenticates the remote with UNION_API_KEY
    remote = union.UnionRemote(default_project="default", default_domain="development")

Using a secret created from a file

To use a secret created from a file in your workflow code, you must mount it as a file. To run the example code below:

1. Create a secret from a file with the key my_secret.
2. Copy the example code below to a new file and save it as using_secrets_file.py.
3. Run the script with union run --remote using_secrets_file.py main.

import union

@union.task(
    secret_requests=[
        union.Secret(key="my_file_secret", mount_requirement=union.Secret.MountType.FILE),
    ]
)
def t1():
    path_to_secret_file = union.current_context().secrets.get_secrets_file("my_file_secret")
    with open(path_to_secret_file, "r") as f:
        secret_value = f.read()
    # do something with the secret. For example, communication with an external API.
    ...

Updating secrets

To update a secret, run the union update secret command. You will be prompted to enter a new value:

$ union update secret --project my_project --domain my_domain my_secret

Deleting secrets

To delete a secret, use the union delete secret command:

$ union delete secret --project my_project --domain my_domain my_secret