Configuring integrations to use Hashicorp Vault for credentials

Edit online

Most host agent configurations are applied by using the agent configuration file (<instana-agent-dir>/etc/instana/configuration.yaml). You can configure a host agent by editing the agent configuration file.

Note: The format of the agent configuration file is YAML, which is sensitive to white space. All indention levels allow only two blank spaces.

Integrating the host agent with secret managers

Instana doesn't support encrypt confidential data such as password directly in the agent configuration file. However, the host agent can retrieve confidential data like credentials or other information that you do not want to put in clear text in the

configuration.yaml

file from secret managers.

IBM Cloud Secrets Manager

The IBM Cloud Secrets Manager is based on open-source HashiCorp Vault and provides the same API and the same configuration as HashiCorp Vault. For more information about configuring the integration, see the HashiCorp Vault section.

Starting with version 1.0.11 of the Vault component, the IBM Cloud Secrets Manager SDK with IAM Keys are supported to be used in Vault.

com.instana.configuration.integration.vault:
  connection_url: <secrets-manager-address> # The address (URL) of the IBM Cloud Secrets Manager server instance(e.g. https://f022446e-1024-4aa9-a00c-72bf15aa9e7b.us-south.secrets-manager.appdomain.cloud)
  ibm_secrets_manager: <iam_key> # IAM Key that can be used to create access tokens
  secret_refresh_rate: 24 # This configuration option allows you to account for rotating credentials, refresh rate in hours, default 24

Endpoint descriptions are available in IBM Cloud Docs - Secrets Manager or within the IBM Secrets Manager dashboard. To create an IAM key, see IBM Cloud - IAM Keys.

To use the secrets inside IBM Cloud Secret Manager in Instana, see the configuration as follows:

com.instana.example:
  test:
    configuration_from:
      type: vault
      secret_key:
        path: <secret-id> # The id of the Secret within the IBM Secrets Manager, (e.g. cc32688d-89c0-6fa8-c0b4-6cc88c232e66)
        key: <kv-key-entry> # The Key inside the Secret Object of type KV (e.g. login)
      poll_rate: 300 # seconds

HashiCorp Vault

Note: The Vault integration requires the agent bootstrap version 1.2.9 or later.

Instana agent uses HashiCorp Vault to securely obtain values for sensitive settings in the agent configuration file.

You need to provide the Vault integration configuration parameters to the host agent by adding the following lines to the agent configuration file:

com.instana.configuration.integration.vault:
  connection_url: <vault_server_base_url> # The address (URL) of the Vault server instance(e.g. http://127.0.0.1:8200 or https://exapmle.com:8200)
  prefix: <optional_prefix> # Optional prefix path required if kv_version 2 is used and the /data/ must be injected further down
  token: <vault_access_token> # Vault access token with assigned, at least, `read` access policy to relevant Vault paths, optional if other auth providers are present
  github: # Optional auth method if Vault access token is not provided, has higher priority than approle if present
    github_token: <github_token> # Personal Access Token, must provide at least read:org scope, must be present if github is used as an auth provider
    auth_mount: github # Optional mount path for GitHub Auth, defaults to github
  approle: # Optional auth method if Vault access token or github auth is not provided
    role_id: <roleId> # AppRole RoleId, must be present if approle is used as an auth provider
    secret_id: <secretId> # AppRole SecretId, must be present if approle is used as an auth provider
    auth_mount: approle # Optional mount path for AppRole Auth, defaults to approle
  path_to_pem_file: <path_to_X.509_CA_certificate> # X.509 CA certificate (UTF8 encoded) in unencrypted PEM format, used by the Agent when communicating with Vault over HTTPS
  secret_refresh_rate: 24 # This configuration option allows you to account for rotating credentials, refresh rate in hours, default 24
  kv_version: 2 # The Key/Value secrets engine version, default is 2

After the initial Vault configuring, you can specify the retrieval of secrets for various sensors as follows:

com.instana.plugin.mysql:
  user: 'instana'
  password:
    configuration_from:
      type: vault
      secret_key:
        path: <vault_path>
        key: <vault_secret_key>

For comparison, configure the password in plain-text in the agent configuration file as follows:

com.instana.plugin.mysql:
  user: 'instana'
  password: <my_password>

That is, you can swap out the string value for the YAML structure that specifies the Vault coordinates, and the host agent automatically does the rest.

Also, you are not limited to using the Vault integration with a field that contains the password, but you can use it for every configuration that has a string as value in the <instana-agent-dir>/etc/instana/configuration.yaml file.

For more information, see the following Vault concepts that are relevant for the Instana agent integration:

Kubernetes secrets

To get sensitive information from Kubernetes secrets into the agent's sensor configuration, combine the following two basic concepts:

Configure your workloads to mount Kubernetes secrets into environment variables or files within the workload's pod.
Adopt the agent's configuration.yaml file to read configuration values from process-specific environment variables or files.

By combining these two concepts, your workloads can carry sensitive information in pod-specific or process-specific environment variables or files. In addition, the agent can get these environment variables or files to read the sensitive information and apply the information to the workload-specific configuration.