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 will be available across all projects-domain combinations.
• If you specify only a domain, the secret will be available across all projects, but only in that domain.
• If you specify both a project and a domain, the secret will be available in that project-domain combination only.
• If you specify only a project, you will get an error.

For example, to create a secret so that it is only available 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