​
AWS Secrets Manager Provider

This provider allows for the expansion of environment variables from an AWS key-value secret or a literal one.

​
Credentials Configuration

It requires an instance profile in the agent with the permissions below:

Required IAM Roles

  • secretsmanager:GetSecretValue
  • secretsmanager:GetResourcePolicy
  • secretsmanager:DescribeSecret
  • secretsmanager:ListSecretVersionIds

​
Syntax

  • _aws:SECRET-NAME:SECRET-KEY

A secret configured as:

cat - > /tmp/pgconfig.json <<EOF
{
  "PG_HOST": "127.0.0.1",
  "PG_PORT": "3306"
}
EOF
aws secretsmanager create-secret --name pgprod \
    --secret-string file:///tmp/pgconfig.json

Can be exposed to an environment variable in a connection as:

  • _aws:pgprod:PG_HOST
  • _aws:pgprod:PG_PORT

Example:

  • MYSECRET=_aws:prod-secret-name:MYSECRET

The environment key value will be replaced when the user opens a session with the agent.

​
Testing It

Create a bash connection.

hoop admin create connection bash --agent test-agent \
    -e PG_HOST=_aws:pgprod:PG_HOST \
    --overwrite -- /bin/bash

Then, execute the env command to dump the environment variables of a session.

hoop exec bash -i 'env' |grep PG_HOST

​
HashiCorp Vault Provider

This provider expands environment variables from an Vault Key Value Secrets Engine. It supports versions 1 and 2.

​
Configuration

It requires the environment variables exported in the machine running the agent. The implementation follows the specification of the Vault Cli and it’s limited to the configuration below:

NameRequiredDescription
VAULT_ADDRyesAddress of the Vault server expressed as a URL and port, for example: https://127.0.0.1:8200/.
VAULT_TOKENyes*Vault authentication token. Conceptually similar to a session token on a website, the VAULT_TOKEN environment variable holds the contents of the token. It’s required if App Role authentication is not being used.
VAULT_APP_ROLE_IDnoThe Role ID in case App Role Authentication is used.
VAULT_APP_ROLE_SECRET_IDnoThe Secret ID in case App Role Authentication is used.
VAULT_CACERTnoPath or inline base64 content of PEM-encoded CA certificate file on the local disk. This file is used to verify the Vault server’s SSL certificate.

Example of how to define expose the env VAULT_CACERT

# load from /tmp/ca.pem file
export VAULT_CACERT=file:///tmp/ca.pem
# load from inline base64 content
export VAULT_CACERT=base64://<inline-base64-content>

​
App Role Authentication

The approle auth method allows machines or apps to authenticate with Vault-defined roles. This auth method is oriented to automated workflows (machines and services), and is less useful for human operators.

The agent will perform a request to POST /auth/approle/login and obtain a valid token to access secrets in Vault Key Value store.

Make sure to configure the environment variables when deploying the agent:

export VAULT_APP_ROLE_ID=<role-id>
export VAULT_APP_ROLE_SECRET_ID=<secret-id>

It’s important to use batch tokens when using the App Role method. Refer to Vault App Role documentation for more information.

​
Testing the Connection

1

Install Vault

This step requires a Vault installation, for the sake of this documentation we recommend using a Vault development server. Check the getting started with dev server

You can use the option -dev-listen-address="0.0.0.0:8200" to expose the Vault Server to your host network.

2

Configure Secrets

  • The command below will enable and configure a secret in a KV version 1
vault secrets enable -version=1 kv
vault kv put kv/pgprod \
    DBHOST=mydbhost.tld \
    DBUSER=dbuser \
    DBPASSWD=dbsupersecret \
    DBPORT=5432

A connection could be mapped using the following syntax:

  • _vaultkv1:SECRETNAME:SECRET-KEY
3

Testing

Go to the Webapp and run a query in this Connection.

​
Env Json Provider

This provider allows the exposure of environment variables from an agent by exposing a JSON environment variable. It is useful for maintaining compatibility with older runops agents.

​
Syntax

  • _envjson:MYJSON_ENV:ENVKEY

So an environment variable configured in an agent:

  • ENV_CONFIG='{"PG_HOST": "127.0.0.1", "PG_DB": "testdb"}'

Can be exposed to an environment variable in a connection as:

  • _envjson:ENVCONFIG:PG_HOST

​
Testing It

Create a bash connection.

hoop admin create connection bash --agent test-agent \
    -e PG_HOST=_envjson:ENV_CONFIG:PG_HOST \
    --overwrite -- /bin/bash

Then, execute the env command to dump the environment variables of a session.

hoop exec bash -i 'env' |grep PG_HOST
RunbooksSession Recording