Skip to main content
Version: 3.0.0

Secrets

This guide will show you how to manage and use a secret in Ascend.

Prerequisites​

  • A Workspace
  • An Environment Vault
  • An Ascend project
  • A Vault is setup in the Project

Create a secret​

To use a secret in Ascend, you must first store it in a vault that has been set up for the Environment you are working in. See here for more information on Environment Vaults.

See the instructions here for adding a secret to GCP Secret Manager. If you are using a prefix to delineate between environment and instance secrets, make sure to include the prefix in the secret name.

Reference a secret in a YAML file​

Generally secrets are used in connections to store passwords, tokens, or other sensitive information that authenticates to external systems.

The syntax for referencing a secret is:

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

Secrets can be stored as json objects in the vault, and child values can be accessed by dot notation.

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

Reference a secret in a Python file​

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:

  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: ${secret.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: ${secret.foo_vault.foo_secret.mysql.password}

Example 3: API Key in Custom Python Read Connector​

Secrets can also be accessed in custom Python read connectors. 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 requests
import pandas as pd

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())
Last updated on