Skip to main content
Version: 3.0.0

Secrets

This guide shows you how to manage and use secrets in Ascend.

Prerequisites​

Create a secret​

To use a secret in Ascend, you must first store it in a Vault that has been configured for the Environment you are working in.

For Ascend-managed Vaults:

  1. Navigate to Settings > Secrets & Vaults
  2. Choose the Vault where you want to add a secret (Instance Vault or Environment Vault)
  3. Click Add Secret
  4. Enter a Name for your secret and paste the value in the Value field

Your secret is now ready to use!

tip

Secrets stored in the Instance Vault are available throughout the entire Instance, while secrets in an Environment Vault are scoped only to that specific Environment.

Reference a secret in YAML files​

Secrets are commonly used in Connections to store passwords, tokens, or other sensitive information for authenticating to external systems.

The syntax for referencing a secret is:

${vaults.<vault-name>.<secret-name>}

Secrets can be stored as JSON objects in the vault, and child values can be accessed using dot notation:

${vaults.<vault-name>.<secret-name>.<path.to.secret>}

Reference a secret in Python files​

Secrets can be accessed by referencing them from the context object passed to the Python function:

from ascend.application.context import ComponentExecutionContext
from ascend.resources import custom_python
from ascend.vault.vault import Vault

@custom_python()
def custom_python_vault(context: ComponentExecutionContext):
  vault: Vault = context.vaults["<vault-name>"]
  vault.get("<secret-name>")
  # for accessing child values in a json object
  vault.get("<secret-name>.<path.to.secret>")

Examples​

With this project structure:

  foo_project/
  ├── ascend_project.yaml
  ├── connections/
  ├── flows/
  ├── profiles/
  └── vaults/
      └── foo_vault.yaml

Example 1: MySQL Connection​

This secret in the foo_vault:

foo_secret
"mysql_password_value"

The secret can be referenced in a MySQL connection:

connections/mysql_example.yaml
connection:
  mysql:
    host: mysql.hostname
    port: 3306
    database: some_database
    user: mysql_user
    password: "${vaults.foo_vault.foo_secret}"

Example 2: Nested Values​

If the secret is a string-encoded JSON object:

foo_secret
{
    "mysql": {
        "password": "mysql_password_value"
    }
}

The secret can be accessed by appending the path to the secret:

connections/mysql_example.yaml
connection:
  mysql:
    host: mysql.hostname
    port: 3306
    database: some_database
    user: mysql_user
    password: "${vaults.foo_vault.foo_secret.mysql.password}"

Example 3: API Key in Custom Python Read Component​

Secrets can also be accessed in custom Python read components. Here's an example of using an API key stored in a Vault to authenticate to an API and return a DataFrame:

api_key
"abc123"
flows/foo_flow/components/read_api.py
import pandas as pd
import requests
from ascend.application.context import ComponentExecutionContext
from ascend.resources import custom_python
from ascend.vault.vault import Vault


@custom_python()
def custom_python_vault(context: ComponentExecutionContext):
    vault: Vault = context.vaults["foo_vault"]
    vault.get("api_key")

    response = requests.get("https://api.example.com", headers={"Authorization": f"Bearer {vault.get('api_key')}"})
    return pd.DataFrame(response.json())

Next steps​

Last updated on