Configuring some components, like receivers or exporters, might require
you to provide secrets, such as passwords. You can includes these secrets as
plaintext in the Collector's configuration files. However, these secrets are
included in system logs written by the Collector and transmitted to
Cloud Logging, exposing the secrets beyond the node or virtual machine (VM)
where the Collector is running.

Starting with the Google-built Collector version
0.126.0,
you can use an OpenTelemetry provider integrated with [Secret Manager](https://docs.cloud.google.com/secret-manager/docs/overview.md.txt) to
eliminate plaintext secrets in your configuration files.

A *provider* is an OpenTelemetry configuration component,
analogous to the receiver and processor components. Each provider has a
type, and each type of provider maps a specific identifier in the
configuration to a value.

The `googlesecretmanager` provider maps Secret Manager
identifiers to the secrets, like passwords, tokens, and API keys, that you've
stored in Secret Manager. Using the
`googlesecretmanager` provider offers the following benefits:

- **Enhanced security** : Your configuration files don't contain sensitive information like passwords. The actual secrets are stored in [Secret Manager](https://docs.cloud.google.com/secret-manager/docs/overview.md.txt), a service designed specifically for securely storing, accessing, and managing sensitive data.
- **Reduced risk of exposure**: Secret Manager fetches secrets during initialization of the Google-Built OpenTelemetry Collector, which prevents plaintext secrets from accidentally being recorded in logs.

## Before you begin

To use the `googlesecretmanager` provider, you must enable the
Secret Manager API and permit access to the API,
as described in the following steps:

1.
   [Install](https://docs.cloud.google.com/sdk/docs/install) the Google Cloud CLI.

   After installation,
   [initialize](https://docs.cloud.google.com/sdk/docs/initializing) the Google Cloud CLI by running the following command:

   ```bash
   gcloud init
   ```


   If you're using an external identity provider (IdP), you must first
   [sign in to the gcloud CLI with your federated identity](https://docs.cloud.google.com/iam/docs/workforce-log-in-gcloud.md.txt).
2. Set the default project for Google Cloud CLI:

   ```
   gcloud config set project PROJECT_ID
   ```

   Before you run the previous command, replace the <var translate="no">PROJECT_ID</var>
   variable with the identifier of your Google Cloud project.
3.


   Enable the Secret Manager API, if it is not already enabled:


   **Roles required to enable APIs**


   To enable APIs, you need the `serviceusage.services.enable` permission. If you
   created the project, then you likely already have this permission through the
   Owner role (`roles/owner`). Otherwise, you can get this permission through the
   Service Usage Admin role (`roles/serviceusage.serviceUsageAdmin`).
   [Learn how to grant roles](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).

   ```bash
   gcloud services enable secretmanager.googleapis.com
   ```
4. Update the OAuth access scopes for your instance to include the required scope for Secret Manager, `https://www.googleapis.com/auth/cloud-platform`:

   ```
   gcloud compute instances set-service-account "INSTANCE_ID" \
     --service-account "SERVICE_ACCT_EMAIL" \
     --scopes "https://www.googleapis.com/auth/cloud-platform"
   ```

   Before you run the previous command, replace the following variables:
   - <var translate="no">INSTANCE_ID</var>: the identifier of your VM.
   - <var translate="no">SERVICE_ACCT_EMAIL</var>: the address of the service account associated with the VM.

   For more information, see
   [Access the Secret Manager API](https://docs.cloud.google.com/secret-manager/docs/accessing-the-api.md.txt).
5. Grant the user who manages the Google-Built OpenTelemetry Collector configurations the permissions needed to create and manage secrets. The Identity and Access Management role `roles/secretManager.secretAdmin` includes the necessary permissions:

   ```
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="user:USER_EMAIL" \
     --role=roles/secretManager.secretAdmin
   ```

   Before you run the previous command, replace the following variables:
   - <var translate="no">PROJECT_ID</var>: the identifier of your Google Cloud project.
   - <var translate="no">USER_EMAIL</var>: the address of the user being granted the role.
6. Grant the service account associated with the VM the permissions it needs to access the secrets. The Identity and Access Management role `roles/secretManager.secretAccessor` includes the necessary permissions:

   ```
   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:SERVICE_ACCT_EMAIL" \
     --role=roles/secretManager.secretAccessor
   ```

   Before you run the previous command, replace the following variables:
   - <var translate="no">PROJECT_ID</var>: the identifier of your Google Cloud project.
   - <var translate="no">SERVICE_ACCT_EMAIL</var>: the address of the service account associated with the VM.

## Replace plaintext secrets with managed secrets

To eliminate the use of plaintext secrets in your configuration files by
using Secret Manager and the `googlesecretmanager`
provider, do the following:

1. Create a secret in Secret Manager for each plaintext secret in your configuration files.
2. Replace each plaintext secret in your configuration files with a reference to the corresponding secret in Secret Manager.

For example, if you are using an `http` exporter,
your configuration file might include an entry like the following:

```
exporters:
  logging:
    loglevel: debug
  http:
    endpoint: "https://example.com/api/metrics"
    headers:
      X-API-Key: plaintext-secret
```

In this example, you want to place the `plaintext-secret`
string into Secret Manager and then replace
the plaintext secret with a reference to the managed secret.

### Create Secret Manager secrets
for plaintext secrets

To create a Secret Manager secret containing the plaintext secret `plaintext-secret`, run the following command:

```
echo -n "plaintext-secret" | gcloud secrets create SECRET_NAME \
    --replication-policy="automatic" \
    --data-file=-
```

Before you run the previous command, replace the following variables:

- <var translate="no">plaintext-secret</var>: Replace with your plaintext secret.
- <var translate="no">SECRET_NAME</var>: Replace with a meaningful name for your secret.

The fully qualified resource name of your new secret has the following
format, with a <var translate="no">VERSION</var> of `1`:

```
projects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION
```

For more information about storing, versioning, and accessing secrets in
Secret Manager, see
[Create a secret](https://docs.cloud.google.com/secret-manager/docs/creating-and-accessing-secrets.md.txt).

### Replace plaintext secrets

To update your configuration files, replace each plaintext secret
with a reference to the `googlesecretmanager` provider and the resource
name of the managed secret, as shown in the following example:

```
exporters:
  logging:
    loglevel: debug
  http:
    endpoint: "https://example.com/api/metrics"
    headers:
      X-API-Key: ${googlesecretmanager:projects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION}
```

### Learn more

For more information about using the `googlesecretmanager` provider, visit the [`opentelemetry-collector-contrib` repository](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/confmap/provider/googlesecretmanagerprovider).