The Generic Agent needs access to secrets for authentication (agent token) and optionally for integration credentials and custom CA certificates. There are two approaches for managing these secrets in Kubernetes.

ℹ️

If you deployed using one of the Terraform modules (AWS EKS, Azure AKS, or GCP GKE), the secret store is configured automatically.

This page is for users managing their own Kubernetes infrastructure or customizing the secrets configuration.

Whenever possible it is recommended to use a Secrets Manger.

Kubernetes Secrets (Direct)

The simplest approach is to create Kubernetes secrets directly with kubectl and skip the External Secrets Operator entirely. This is the approach used in the Kubernetes deployment guide.

Set skipExternalSecrets: true in your values.yaml:

skipExternalSecrets: true

Then create the secrets manually:

# Agent token
kubectl create secret generic mcd-agent-token-secret -n mcd-agent \
  --from-file=contents.json=agent-token.json

# Integration credentials (can start empty)
kubectl create secret generic mcd-integrations-secrets -n mcd-agent \
  --from-file=empty.json=<(echo '{}')

This approach is suitable mostly for development and testing. Secrets must be updated manually with kubectl when they change.

Cloud Secret Managers (via External Secrets Operator)

For production environments, the recommended approach is to store secrets in a cloud secret manager and use the External Secrets Operator (ESO) to sync them into Kubernetes. ESO automatically pulls secrets from your cloud provider and creates Kubernetes secrets that the agent can consume.

When using the Terraform modules (AWS EKS, Azure AKS, GCP GKE), ESO is installed automatically by default. To disable it (for example, if ESO is already installed in your cluster), set install_external_secrets_operator to false in the helm variable of the Terraform module. If managing the Helm release manually, install ESO separately before deploying the agent chart.

Configuring the Secret Store

The secretStore value in your values.yaml tells ESO which cloud secret manager to use and how to authenticate. Below are configurations for each supported provider.

AWS Secrets Manager

secretStore:
  provider:
    aws:
      role: "arn:aws:iam::<account-id>:role/<eso-secrets-access-role>"
      region: "us-east-1"
      service: SecretsManager

The IAM role must have permission to read secrets from Secrets Manager:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:GetResourcePolicy",
        "secretsmanager:DescribeSecret",
        "secretsmanager:ListSecretVersionIds"
      ],
      "Resource": "arn:aws:secretsmanager:<region>:<account-id>:secret:mcd/*"
    }
  ]
}

The role must be assumable by ESO via EKS Pod Identity.

Azure Key Vault

secretStore:
  provider:
    azurekv:
      tenantId: "<your-tenant-id>"
      authType: WorkloadIdentity
      vaultUrl: "https://<your-keyvault>.vault.azure.net"
      serviceAccountRef:
        name: mcd-agent-service-account
        namespace: mcd-agent

The agent's managed identity must have the Key Vault Secrets User role on the Key Vault. Authentication uses Azure Workload Identity.

GCP Secret Manager

secretStore:
  provider:
    gcpsm:
      projectID: "<your-gcp-project-id>"
      auth:
        workloadIdentity:
          serviceAccountRef:
            name: mcd-agent-service-account

The GCP service account must have the roles/secretmanager.secretAccessor role. Authentication uses GKE Workload Identity.

Referencing Secrets

Once the secret store is configured, reference your secrets in values.yaml:

Agent Token

tokenSecret:
  remoteRef:
    key: "mcd/agent/token"

The secret value in the cloud secret manager must be a JSON object:

{
  "mcd_id": "<your-mcd-id>",
  "mcd_token": "<your-mcd-token>"
}

Integration Credentials

integrationsSecrets:
  data:
    - secretKey: "<integration>.json"
      remoteRef:
        key: "<secret-name-in-cloud>"

You can reference multiple integration secrets:

integrationsSecrets:
  data:
    - secretKey: postgres.json
      remoteRef:
        key: mcd/integrations/postgres
    - secretKey: snowflake.json
      remoteRef:
        key: mcd/integrations/snowflake

See the Self-Hosted Credentials documentation for the JSON format for each integration type.

Firewall CA Certificate

If your CA certificate is stored in the cloud secret manager, you can reference it via an ExternalSecret instead of inlining the PEM content:

firewallCa:
  externalSecretRef: "<external-secret-name>"

See the Proxies and Traffic Inspection guide for more details on custom CA certificates.