For the complete documentation index, see llms.txt. This page is also available as Markdown.

Secrets

Read connection credentials from 1Password, AWS, Azure, GCP, Vault and other secret managers.

Keep credentials in your secret manager. Put a secret reference in place of the value. Sling reads the secret when a run uses it. The secret value does not go to disk, to the logs, or to the Sling Platform.

This is available in v1.6.5+.

connections:
  MY_PG:
    type: postgres
    host: db.acme.com
    user: etl
    password: ref+vault://secret/data/postgres#/password     # HashiCorp Vault
    database: analytics

  MY_MD:
    type: motherduck
    database: my_database
    motherduck_token: ref+azurekeyvault://my-vault/motherduck-token     # Azure Key Vault

  MY_RDS:
    type: postgres
    from: ref+awssecrets://prod/rds     # AWS Secrets Manager: all keys from one secret

Reference Forms

A reference has this form:

Part
Rule
Example

kind

The provider kind. See Providers.

awssecrets

path

The secret. Specific to the provider.

prod/postgres

params

Options. Specific to the provider, plus the common params below.

?provider=aws_eu

pointer

A JSON pointer into a JSON or YAML secret. #key is short for #/key.

#/password

Common params and rules
Param
Meaning

provider=<name>

Use the named instance from secret_providers:.

trim=false

Keep a trailing newline. By default, Sling removes one trailing newline.

Rules:

  • A value can be a whole reference: password: ref+op://Data/pg/password.

  • A reference can be part of a longer value. End it with +:

  • Sling expands ${VAR} first. Thus password: ${PG_PASSWORD} with PG_PASSWORD=ref+op://Data/pg/password also works.

  • A pointer to an object is valid only in from:. A field needs a string.

Native forms (alternatives)

Sling also accepts some native forms with no ref+<kind>:// prefix. Each one is the same as the ref+ form.

Provider
Native form
Same as

1Password

op://Data/pg/password

ref+op://Data/pg/password

Keeper

keeper://<uid>/field/password

ref+keeper://<uid>/field/password

Azure Key Vault

https://my-vault.vault.azure.net/secrets/pg-password[/<version>]

ref+azurekeyvault://my-vault/pg-password

AWS Secrets Manager

arn:aws:secretsmanager:eu-west-2:123456789012:secret:prod/pg-a1b2c3

ref+awssecrets://arn:aws:secretsmanager:...

AWS SSM Parameter Store

arn:aws:ssm:eu-west-2:123456789012:parameter/prod/pg/password

ref+awsssm://arn:aws:ssm:...

GCP Secret Manager

projects/my-project[/locations/<region>]/secrets/pg-password[/versions/5]

ref+gcpsecrets://my-project/pg-password?version=5

CyberArk Conjur

myorg:variable:prod/db/password

ref+conjur://prod/db/password

  • Use a native form when you copy an identifier from the console of the secret manager.

  • A native form must be the whole value. In a longer value, use the ref+ form.

  • Params and a pointer can follow a native form: arn:aws:secretsmanager:...:secret:prod/pg-a1b2c3#/password.

  • Sling resolves each value that has a native form, also in env: values.

Where References Work

Place
Example
Sling reads the secret

A string value of a connection, also nested values such as API secrets:

password: ref+op://Data/pg/password

When the connection opens

from: of a connection

from: ref+awssecrets://prod/postgres

When the connection opens

env: of env.yaml

API_TOKEN: ref+op://Data/acme/token

When a connection uses it

env: of a replication or a pipeline

API_TOKEN: ref+op://Data/acme/token

When Sling loads the file

The secret() function in hooks and pipeline steps

{secret("ref+op://Data/acme/token")}

When the step runs

Examples

An API connection:

The env: of a replication:

The secret() function in a pipeline:

Load a Connection with from:

from: loads a JSON or YAML object from one secret. Its keys become the keys of the connection.

  • Keys that you write in the connection win over keys from the secret.

  • Sling changes username to user, and dbname to database. Thus AWS RDS secrets work as they are.

Connections without type

type is optional with from:. Without it, Sling finds the type when a run uses the connection. It looks in this sequence:

  1. The type key of the secret.

  2. The engine key of the secret (AWS RDS secrets).

  3. The scheme of the url key.

Until a run uses the connection, sling conns list shows Unknown. We recommend that you write type. Then Sling knows the type with no call to the secret manager.

Read Values that Sling Has

The sling provider reads a field of a connection that Sling knows, or an environment variable.

Rules
  • Any field is available, a secret or not. url is the full connection URL.

  • If the field holds a reference, Sling resolves it first.

  • The environment includes the env: values of env.yaml.

  • Sling redacts all values that come from a reference, also values that are not secret. Thus log output shows *** for a host from ref+sling://.

  • If a reference points to itself, directly or through other references, Sling shows a circular reference error.

Configure Providers

Most providers need no configuration. They use the default credentials of the host, such as the AWS credential chain or az login.

To set credentials, or to use two accounts of one provider, add a secret_providers: block to env.yaml:

  • Config values accept ${VAR}. They do not accept secret references.

  • Each config key has an environment variable as a fallback. See each provider below.

How Sling selects the instance
  1. ?provider=<name> in the reference.

  2. The only instance of the provider kind.

  3. The instance named default, when there are more instances of the kind. Else Sling shows an error.

  4. With no instance of the kind, Sling uses the provider with no configuration.

Providers

Provider
Kind (aliases)
Reference

op (1password, onepassword, onepasswordconnect)

ref+op://Data/pg/password

awssecrets (aws_secrets_manager)

ref+awssecrets://prod/pg#/password

awsssm (aws_ssm)

ref+awsssm:///prod/pg/password

azurekeyvault (azure_key_vault)

ref+azurekeyvault://my-vault/pg-password

gcpsecrets (gcp_secret_manager)

ref+gcpsecrets://my-project/pg-password

vault (hashicorp_vault)

ref+vault://secret/data/pg#/password

openbao (bao)

ref+openbao://secret/pg#/password

infisical

ref+infisical://<project>/<env>/<KEY>

doppler

ref+doppler://<project>/<config>/<NAME>

bws (bitwarden_secrets_manager)

ref+bws://<secret-uuid>

bw (bitwarden)

ref+bw://<item-id>/password

keeper

ref+keeper://<uid>/field/password

conjur

ref+conjur://prod/db/password

tss (delinea, thycotic)

ref+tss://<id>/password

akeyless

ref+akeyless:///prod/db/password

sops

ref+sops://secrets.enc.yaml#/pg/password

k8s (kubernetes)

ref+k8s://v1/Secret/<ns>/<name>/<key>

file

ref+file://./secrets.yaml#/pg/password

exec

ref+exec://my-tool?arg=get

httpjson

ref+httpjson://config.acme.com/pg#/password

sling

ref+sling://connections/my_pg/password

1Password

Example and configuration

Reference: ref+op://<vault>/<item>[/<section>]/<field>. Vault and item accept names or IDs.

Alternative: the native form op://<vault>/<item>[/<section>]/<field>.

Sling uses the first transport that is available:

Transport
Config
Environment variable

op CLI (service account, or op signin)

token, account

OP_SERVICE_ACCOUNT_TOKEN, OP_ACCOUNT

1Password Connect server

connect_host, connect_token, ca_cert, skip_verify

OP_CONNECT_HOST, OP_CONNECT_TOKEN

  • Set mode: cli or mode: connect to select one transport.

  • With the CLI, Sling reads all 1Password references of a run in one op inject call.

AWS Secrets Manager

Example and configuration

Reference: ref+awssecrets://<name or ARN>[#/<key>].

Alternative: the secret ARN, arn:aws:secretsmanager:eu-west-2:123456789012:secret:prod/rds/etl-a1b2c3. Sling reads the region from the ARN.

Config
Environment variable
Meaning

region

AWS_REGION, AWS_DEFAULT_REGION

Region. Sling reads it from an ARN first.

profile

AWS_PROFILE

Named profile.

role_arn, external_id

Role to assume.

endpoint

Custom endpoint, such as a VPC endpoint.

  • Credentials come from the AWS default chain: environment, profile, SSO, instance or task role.

  • Params: ?region=, ?version_id=, ?version_stage= (default AWSCURRENT).

AWS SSM Parameter Store

Example and configuration

Reference: ref+awsssm://<parameter name or ARN>.

Alternative: the parameter ARN, arn:aws:ssm:eu-west-2:123456789012:parameter/prod/pg/password.

Azure Key Vault

Example and configuration

Reference: ref+azurekeyvault://<vault>/<name>[/<version>]. <vault> is the vault name, or its full DNS name.

Alternative: the secret identifier from the portal, https://my-vault.vault.azure.net/secrets/motherduck-token[/<version>].

Config
Environment variable
Meaning

tenant_id, client_id, client_secret

AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET

Service principal.

cloud

public (default), usgov or china. Also a ?cloud= param.

vault_url

Full vault URL, for other clouds.

  • Without a service principal, Sling uses the Azure default credential: environment, workload identity, managed identity, or az login.

  • Without a version, Sling reads the latest version.

GCP Secret Manager

Example and configuration

Reference: ref+gcpsecrets://<project>/<name>[?version=<v>]. The default version is latest.

Alternative: the resource name, projects/<p>[/locations/<region>]/secrets/<name>[/versions/<v>], also with the //secretmanager.googleapis.com/ prefix. Use it for regional secrets.

Config
Meaning

credentials_json

Service account key JSON.

impersonate_service_account

Service account to impersonate.

endpoint

Custom endpoint.

  • Without credentials_json, Sling uses the application default credentials (gcloud auth application-default login, or the attached service account).

  • Sling sends a regional secret to its regional endpoint.

HashiCorp Vault and OpenBao

Example and configuration

Reference: ref+vault://<path>[#/<key>]. For OpenBao, use ref+openbao://. OpenBao reads BAO_* in place of VAULT_* variables.

Config
Environment variable
Meaning

address

VAULT_ADDR

Server URL.

namespace

VAULT_NAMESPACE

Enterprise namespace.

auth

VAULT_AUTH_METHOD

token (default), approle, jwt, kubernetes or aws.

token, token_file

VAULT_TOKEN, VAULT_TOKEN_FILE

For auth: token. Also reads ~/.vault-token (OpenBao: ~/.bao-token).

role_id, secret_id

VAULT_ROLE_ID, VAULT_SECRET_ID

For auth: approle.

role, jwt, jwt_file

For auth: jwt.

role, token_file

For auth: kubernetes. The default token file is the pod service account token.

role, region, header_value

For auth: aws. Uses the AWS default chain.

mount

Auth mount path, when it is not the default.

ca_cert, skip_verify

VAULT_CACERT, VAULT_SKIP_VERIFY

TLS.

renew_leases

false stops lease renewal.

  • KV v1 and v2 are both supported. Sling finds the version of the mount. Add ?kv=1 or ?kv=2 to set it.

  • ?version=<n> reads an old version of a KV v2 secret.

  • For dynamic secrets, Sling renews the lease during long tasks.

Infisical

Example and configuration

References:

  • ref+infisical://<project id>/<env>/<folder path>/<KEY>.

  • ref+infisical://<KEY>?project=<id>&environment=<env>&path=<folder>.

Config
Environment variable
Meaning

client_id, client_secret

INFISICAL_UNIVERSAL_AUTH_CLIENT_ID, INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET

Universal auth.

token

INFISICAL_TOKEN

Access token.

site_url

INFISICAL_API_URL

Self-hosted server.

  • ?type=personal reads a personal secret. The default is shared.

Doppler

Example and configuration
Config
Environment variable
Meaning

token

DOPPLER_TOKEN

Service token or personal token.

project, config

DOPPLER_PROJECT, DOPPLER_CONFIG

Defaults for ref+doppler://<NAME>.

api_url

DOPPLER_API_ADDR

Custom API URL.

Bitwarden Secrets Manager

Example and configuration
Config
Environment variable
Meaning

token

BWS_ACCESS_TOKEN

Machine account access token.

server_url

BWS_SERVER_URL

Self-hosted or EU server.

Bitwarden Password Manager

Example and configuration
Config
Environment variable
Meaning

session

BW_SESSION

Session key from bw unlock.

  • Needs the bw CLI. The vault must be unlocked.

Keeper

Example and configuration

Reference: ref+keeper://<record UID or title>/field/<name>. The path uses Keeper notation.

Alternative: the native form keeper://<record UID or title>/field/<name>.

Config
Environment variable
Meaning

config

KSM_CONFIG

Base64 Secrets Manager configuration.

CyberArk Conjur

Example and configuration
Config
Environment variable
Meaning

appliance_url

CONJUR_APPLIANCE_URL

Server URL.

account

CONJUR_ACCOUNT

Account.

login, api_key

CONJUR_AUTHN_LOGIN, CONJUR_AUTHN_API_KEY

Host or user identity.

ca_cert

CONJUR_SSL_CERTIFICATE, CONJUR_CERT_FILE

CA certificate.

skip_verify

Do not verify TLS.

Reference: ref+conjur://<variable ID>.

Alternative: the resource ID, myorg:variable:prod/db/password. Its account must be the configured account.

Delinea Secret Server

Example and configuration
Config
Environment variable
Meaning

server_url

TSS_SERVER_URL

Server URL.

username, password, domain

TSS_USERNAME, TSS_PASSWORD, TSS_DOMAIN

Application account.

token

TSS_TOKEN

Access token, in place of username and password.

skip_verify

TLS.

Akeyless

Example and configuration
Config
Environment variable
Meaning

access_id, access_key

AKEYLESS_ACCESS_ID, AKEYLESS_ACCESS_KEY

API key auth.

gateway_url

AKEYLESS_GATEWAY_URL

Gateway URL. The default is the Akeyless public API.

SOPS

Example and configuration
  • Needs the sops CLI and its keys (age, PGP, AWS KMS, GCP KMS or Azure Key Vault).

  • Files can be YAML, JSON or .env.

  • A relative path starts at the env.yaml folder.

  • Sling decrypts each file one time for a run.

Kubernetes

Example and configuration
Config
Meaning

kubeconfig, context

Outside a cluster. Also ?kubeConfigPath= and ?kubeContext= params.

host, token_file, ca_file

In a cluster, to change the defaults.

  • In a pod, Sling calls the API server with the service account token.

  • Outside a cluster, Sling uses kubectl.

Local File

Example and configuration
  • A relative path starts at the env.yaml folder. ~/ is the home folder.

  • Use a pointer to read one key of a JSON or YAML file.

Command

Example and configuration
  • Sling runs the command with no shell and reads its standard output.

  • Each arg param is one argument.

HTTP JSON

Example and configuration
Config
Meaning

headers

Headers for each request.

ca_cert, skip_verify

TLS.

  • Sling uses HTTPS. ?insecure=true uses plain HTTP.

When Sling Reads a Secret

  • Sling reads a secret only when a run, a test or a query uses the connection. sling conns list does not read secrets.

  • Each run is a new process. Thus a run gets the latest version of a rotated secret.

  • In one run, Sling keeps a value for 5 minutes. Two fields that read keys of one secret share one fetch.

  • A fetch stops after 30 seconds.

Security

  • Sling keeps resolved values in memory only.

  • Log output and error messages show *** in place of each value. Sling does not hide values shorter than 4 characters.

  • On the Sling Platform, the platform stores only the reference text. The agent reads the secret, so the value stays on the agent host.

Test the References

sling conns test resolves the references of a connection, then connects:

If a reference fails, the error names the reference and the provider. It does not show the value:

Last updated

Was this helpful?