Reference existing secret manager secrets

If you already have secrets created in a secret manager such as HashiCorp Vault or AWS Secrets Manager, you do not need to re-create the existing secrets in Harness.

Harness does not query the secret manager for existing secrets, but you can create a secret in Harness that references an existing secret in HashiCorp Vault or AWS Secrets Manager. No new secret is created in those providers. If you delete the secret in Harness, it does not delete the secret in the provider.

Before you begin

Option: Vault secrets

You can create a Harness secret that refers to the existing Vault secret using a path and key, such as /path/secret_key#my_key.

In the above example, /path is the pre-existing path, secret_key is the secret name, and my_key is the key used to lookup the secret value.

note

Do not prepend the Vault secrets engine to the path. In the above example, if the secret (/path/secret_key#my_key) had been generated by a Vault secrets engine named harness-engine, it would reside in this full path /harness-engine/path/secret_key#my_key. However, in the Value field, you would enter only /path/secret_key#my_key. For example, if your secret path is https://<vault_url>/ui/vault/secrets/\<SECRET_ENGINE>/show/VAULT/secret_val, then the reference path is VAULT/secret_val.

Also note, Harness supports JSON secrets. For example, if you have a JSON secret named my_secret like the one below defined in vault, you can reference /path/my_secret#password or /path/my_secret#database.password. For more information, go to Reference JSON secrets.

{
  "username": "sample_user",
  "password": "P@ssw0rd!123",
  "database": {
    "username": "db_user",
    "password": "db_P@ssw0rd!789"
  }
}

This Harness secret is simply a reference pointing to an existing Vault secret. Deleting this Harness secret will not delete the Vault secret referred to by this secret.

You can reference pre-existing Vault secrets in the Harness YAML editor.

Option: HashiCorp Vault Secrets

For HashiCorp Vault, you can also use expressions to reference pre-existing secrets in Vault using a fully-qualified path, such as hashicorpvault://LocalVault/foo/bar/mysecret#mykey.

With this type of referencing, you don't need to pre-create secrets.

The scheme hashicorpvault:// is needed to distinguish a Vault secret from other secret references. It is followed by the identifier of the Vault secret manager.

For example, if you have a HashiCorp Vault connector with the identifier myVault in the Account scope and a secret with the name example present in the vault path /harness/testpath with the following values:

{
    "key1": "value one",
    "key2": "value two"
}

You can reference the value of key1 for the secret example using the following expression:

<+secrets.getValue("account.hashicorpvault://myVault/harness/testpath/example#key1")>

For a HashiCorp Vault connector at the Org scope, use the following expression:

<+secrets.getValue("org.hashicorpvault://myVault/harness/testpath/example#key1")>

For a HashiCorp Vault connector at the Project scope, use the following expression:

<+secrets.getValue("hashicorpvault://myVault/harness/testpath/example#key1")>

note

To dynamically reference secrets in HashiCorp Vault, make sure you use the expression in the following format: <+secrets.getValue()>

Option: AWS Secrets Manager secrets

You can create a Harness secret that refers to an existing secret in AWS Secrets Manager using the name of the secret, and a prefix if needed. For example, mySecret.

Referencing secret keys

In AWS Secrets Manager, your secrets are specified as key-value pairs, using a JSON collection:

To reference a specific key in your Harness secret, add the key name following the secret name, like secret_name#key_name. In the above example, the secret is named example4docs. To reference the example1 key, you would enter example4docs#example1.

Referencing pre-existing secrets

For AWS secret manager, you can also use expressions to reference pre-existing secrets using a fully-qualified path, such as awssecretsmanager://<connector_identifier>/<secret>.

With this type of reference, you don't need to pre-create secrets.

The scheme awssecretsmanager:// is needed to distinguish an AWS secret manager secret from other secret references. The identifier of the secret manager follows this.

For example, if you have an AWS secret manager connector with the identifier exampleAWS in the Account scope and a secret with the name example present in it.

You can reference the secret example using the following expression:

<+secrets.getValue("account.awssecretsmanager://exampleAWS/example")>

For an AWS secret manager connector at the Org scope, use the following expression:

<+secrets.getValue("org.awssecretsmanager://exampleAWS/example")>

For an AWS secret manager connector at the Project scope, use the following expression:

<+secrets.getValue("awssecretsmanager://exampleAWS/example")>

note

To dynamically reference secrets in the AWS secret manager, make sure you use the expression in the following format: <+secrets.getValue()>

Option: Azure Key Vault secrets

You can create a Harness secret that refers to an existing secret in Azure Key Vault, using that secret's name (for example: azureSecret). You can also specify the secret's version (for example: azureSecret/05).

Referencing pre-existing secrets

For Azure Key Vault secret manager, you can also use expressions to reference pre-existing secrets using a fully-qualified path, such as azurevault://My_AzureVault/mySecret.

With this type of reference, you don't need to pre-create secrets.

The scheme azurevault:// is needed to distinguish an Azure Key Vault secret from other secret references. The identifier of the secret manager follows this.

For example, if you have an Azure Key Vault connector with the identifier exampleAzureKeyVault in the Account scope and a secret with the name example present in it.

You can reference the secret example using the following expression:

<+secrets.getValue("account.azurevault://exampleAzureKeyVault/example")>

For an Azure Key Vault secret manager connector at the Org scope, use the following expression:

<+secrets.getValue("org.azurevault://exampleAzureKeyVault/example")>

For an Azure Key Vault secret manager at the Project scope, use the following expression:

<+secrets.getValue("azurevault://exampleAzureKeyVault/example")>

note

To dynamically reference secrets in the Azure Key Vault, make sure you use the expression in the following format: <+secrets.getValue()>

Option: GCP Secret Manager

For GCP secret manager, you can also use expressions to reference pre-existing secrets using a fully-qualified path, such as gcpsecretsmanager://My_GoogleSM/mySecret.

With this type of reference, you don't need to pre-create secrets.

The scheme gcpsecretsmanager:// is needed to distinguish a GCP secret manager secret from other secret references. The identifier of the secret manager follows this.

For example, if you have a GCP secret manager connector with the identifier exampleGCP in the Account scope and a secret with the name example present in it.

You can reference the secret example using the following expression:

<+secrets.getValue("account.gcpsecretsmanager://exampleGCP/example")>

You can also reference a specific version of the secret. For example, if you want to reference the version 7 of a secret, use the following expression:

<+secrets.getValue("org.gcpsecretsmanager://exampleGCP/example")>

To reference a specific version of a secret, use the following expression:

<+secrets.getValue("org.gcpsecretsmanager://exampleGCP/example/<version_number>")>

For a GCP secret manager connector at the Project scope, use the following expression:

<+secrets.getValue("gcpsecretsmanager://exampleGCP/example")>

To reference a specific version of a secret, use the following expression:

<+secrets.getValue("gcpsecretsmanager://exampleGCP/example/<version_number>")>

note

To dynamically reference secrets in GCP secret manager, make sure you use the expression in the following format: <+secrets.getValue()>

Option: Reference JSON secrets

Harness supports the ability to reference JSON secrets for the following secret managers.

AWS KMS Secret Manager
AWS Secret Manager
Azure Key Vault Secret Manager
HashiCorp Vault Secret Manager

Harness allows you to manage the lifecycle of your secrets independently by referencing JSON secrets in the vault.

For example, you can store a secret in vault with the following JSON.

{
  "key1": "value1",
  "key2": {
    "key21": "value21",
    "key22": "value22"
  },
  "key3": {
    "key31": {
      "key311": "value311"
    }
  }
}

Here are sample outputs for the respective JSONPath from the above JSON file:

test-secret (without any # key)

{
  "key1": "value1",
  "key2": {
    "key21": "value21",
    "key22": "value22"
  },
  "key3": {
    "key31": {
      "key311": "value311"
    }
  }
}

test-secret#key1

"value1"

test-secret#key2

{
  "key21": "value21",
  "key22": "value22"
}

test-secret#key3

{
  "key31": {
    "key311": "value311"
 }
}

test-secret#key3.key31

{
  "key311": "value311"
}

test-secret#key3.key31.key311

 "value311"

info

You cannot use a JSON XPath for nested keys in expressions. For example, <+secrets.getValue("account.YOUR_SECRET_MANAGER://myVault/harness/testpath/example")>.

Harness provides limited support for keys that include dots. Keys with dots only work when the key is present at first level in the JSON. For example:

{
  "key.abc": "some-value",
  "key": {
    "nested.key1": "some-value"
  },
  "key.pqr": {
    "nestedKey": "some-value"
  },
  "pqr.xyz": "some-value",
  "pqr": {
    "xyz": "some-nested-value"
  }
}

Here are sample outputs for the respective JSONPath from the above JSON file:

/path/to/secret#key.abc returns some-value.
/path/to/secret#key.pqr returns {"nestedKey": "some-value"}.
/path/to/secret#key.nested.key1 and key.pqr.nestedKey are not supported.
/path/to/secret#pqr.xyz returns some-nested-value and not some-value. (Hierarchical paths take precedence over keys with dots.)

warning

Harness does not recommend using keys that include dots and might deprecate support in future releases.

Before you begin​

Option: Vault secrets​

Option: HashiCorp Vault Secrets​

Option: AWS Secrets Manager secrets​

Referencing secret keys​

Referencing pre-existing secrets​

Option: Azure Key Vault secrets​

Referencing pre-existing secrets​

Option: GCP Secret Manager​

Option: Reference JSON secrets​

Before you begin

Option: Vault secrets

Option: HashiCorp Vault Secrets

Option: AWS Secrets Manager secrets

Referencing secret keys

Referencing pre-existing secrets

Option: Azure Key Vault secrets

Referencing pre-existing secrets

Option: GCP Secret Manager

Option: Reference JSON secrets