Secrets

This guide covers configuring the pgt-secrets Helm chart for managing external secrets in Kubernetes. The chart integrates with External Secrets Operator to sync secrets from cloud providers into Kubernetes Secrets.

Supported Providers

Provider	Service	Authentication
AWS	Secrets Manager	IAM Roles for Service Accounts (IRSA)
Azure	Key Vault	Workload Identity or Managed Identity

Prerequisites

Add the chart as a dependency in your Chart.yaml:

apiVersion: v2
name: my-secrets
version: 0.0.1
dependencies:
  - name: pgt-secrets
    version: 0.0.4
    repository: oci://public.ecr.aws/w9m9e0e9/pgt-helm-charts

After adding the dependency, run:

helm dependency update

How It Works

The chart creates three types of resources:

1. ServiceAccount - Used for authenticating with the cloud provider via IRSA (AWS) or Workload Identity (Azure)

2. SecretStore - Configures the connection to your cloud provider's secret store

3. ExternalSecret - Defines which secrets to fetch and how to map them to Kubernetes Secrets

The External Secrets Operator watches ExternalSecret resources and automatically syncs the referenced secrets into Kubernetes Secrets, refreshing them every minute.

---

AWS Secrets Manager

Basic AWS Configuration

pgt-secrets:
  enabled: true
  organisationName: my-org

  serviceAccount:
    create: true
    name: my-app-secrets-sa
    annotations:
      eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/my-secrets-role

  aws:
    enabled: true
    secretRegion: eu-west-1

  items:
    - secretStoreName: my-secret-store
      kubernetesSecretName: my-app-secrets
      data:
        - secretKey: database-password
          remoteRef:
            key: prod/my-app/database
            property: password

AWS IAM Role Requirements

The IAM role referenced in the ServiceAccount annotation must have:

• A trust policy allowing the Kubernetes ServiceAccount to assume the role via IRSA

• A policy granting secretsmanager:GetSecretValue and secretsmanager:DescribeSecret permissions

For detailed instructions on creating IAM roles, including Terraform examples, see AWS IAM Roles (IRSA).

Fetching Multiple Secrets (AWS)

pgt-secrets:
  enabled: true
  organisationName: my-org

  serviceAccount:
    create: true
    name: my-app-secrets-sa
    annotations:
      eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/my-secrets-role

  aws:
    enabled: true
    secretRegion: eu-west-1

  items:
    # Database credentials
    - secretStoreName: database-store
      kubernetesSecretName: database-credentials
      data:
        - secretKey: username
          remoteRef:
            key: prod/database/credentials
            property: username
        - secretKey: password
          remoteRef:
            key: prod/database/credentials
            property: password
        - secretKey: host
          remoteRef:
            key: prod/database/credentials
            property: host

    # API keys
    - secretStoreName: api-keys-store
      kubernetesSecretName: api-keys
      data:
        - secretKey: stripe-key
          remoteRef:
            key: prod/api-keys/stripe
            property: secret_key
        - secretKey: sendgrid-key
          remoteRef:
            key: prod/api-keys/sendgrid
            property: api_key

---

Azure Key Vault

Basic Azure Configuration (Workload Identity)

pgt-secrets:
  enabled: true
  organisationName: my-org

  serviceAccount:
    create: true
    name: my-app-secrets-sa
    annotations:
      azure.workload.identity/client-id: "00000000-0000-0000-0000-000000000000"
      azure.workload.identity/tenant-id: "00000000-0000-0000-0000-000000000000"

  azure:
    enabled: true
    managedIdentity:
      useWorkloadIdentity: true

  items:
    - secretStoreName: my-secret-store
      kubernetesSecretName: my-app-secrets
      azure:
        vaultUrl: https://my-keyvault.vault.azure.net/
      data:
        - secretKey: database-password
          remoteRef:
            key: database-password

Azure Workload Identity Requirements

The User Assigned Managed Identity referenced in the ServiceAccount annotations must have:

• A federated credential configured for the Kubernetes ServiceAccount

• The Key Vault Secrets User role assignment on the Key Vault

For detailed instructions on creating managed identities, including Terraform examples, see Azure Workload Identity.

Azure Managed Identity (Legacy)

For clusters not using Workload Identity:

pgt-secrets:
  enabled: true
  organisationName: my-org

  serviceAccount:
    create: true
    name: my-app-secrets-sa

  azure:
    enabled: true
    managedIdentity:
      useWorkloadIdentity: false
      clientId: "00000000-0000-0000-0000-000000000000"
      tenantId: "00000000-0000-0000-0000-000000000000"
      kubernetesSecretName: azure-credentials

  items:
    - secretStoreName: my-secret-store
      kubernetesSecretName: my-app-secrets
      azure:
        vaultUrl: https://my-keyvault.vault.azure.net/
      data:
        - secretKey: database-password
          remoteRef:
            key: database-password

Fetching Multiple Secrets (Azure)

pgt-secrets:
  enabled: true
  organisationName: my-org

  serviceAccount:
    create: true
    name: my-app-secrets-sa
    annotations:
      azure.workload.identity/client-id: "00000000-0000-0000-0000-000000000000"
      azure.workload.identity/tenant-id: "00000000-0000-0000-0000-000000000000"

  azure:
    enabled: true
    managedIdentity:
      useWorkloadIdentity: true

  items:
    # Database credentials from one Key Vault
    - secretStoreName: database-store
      kubernetesSecretName: database-credentials
      azure:
        vaultUrl: https://database-keyvault.vault.azure.net/
      data:
        - secretKey: username
          remoteRef:
            key: db-username
        - secretKey: password
          remoteRef:
            key: db-password
        - secretKey: connection-string
          remoteRef:
            key: db-connection-string

    # API keys from another Key Vault
    - secretStoreName: api-keys-store
      kubernetesSecretName: api-keys
      azure:
        vaultUrl: https://apikeys-keyvault.vault.azure.net/
      data:
        - secretKey: stripe-key
          remoteRef:
            key: stripe-secret-key
        - secretKey: sendgrid-key
          remoteRef:
            key: sendgrid-api-key

---

Secret Templates

Use templates to customise the structure of the created Kubernetes Secret. This is useful for creating secrets in specific formats required by applications.

Creating a Docker Registry Secret

pgt-secrets:
  enabled: true
  organisationName: my-org

  serviceAccount:
    create: true
    name: registry-secrets-sa
    annotations:
      eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/registry-secrets-role

  aws:
    enabled: true
    secretRegion: eu-west-1

  items:
    - secretStoreName: registry-store
      kubernetesSecretName: docker-registry-credentials
      template:
        type: kubernetes.io/dockerconfigjson
        data:
          .dockerconfigjson: |
            {
              "auths": {
                "{{ .registry }}": {
                  "username": "{{ .username }}",
                  "password": "{{ .password }}",
                  "auth": "{{ printf "%s:%s" .username .password | b64enc }}"
                }
              }
            }
      data:
        - secretKey: registry
          remoteRef:
            key: prod/docker/registry
            property: registry
        - secretKey: username
          remoteRef:
            key: prod/docker/registry
            property: username
        - secretKey: password
          remoteRef:
            key: prod/docker/registry
            property: password

Creating a TLS Secret

pgt-secrets:
  enabled: true
  organisationName: my-org

  serviceAccount:
    create: true
    name: tls-secrets-sa
    annotations:
      eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/tls-secrets-role

  aws:
    enabled: true
    secretRegion: eu-west-1

  items:
    - secretStoreName: tls-store
      kubernetesSecretName: tls-certificate
      template:
        type: kubernetes.io/tls
        data:
          tls.crt: "{{ .certificate }}"
          tls.key: "{{ .private_key }}"
      data:
        - secretKey: certificate
          remoteRef:
            key: prod/tls/my-domain
            property: certificate
        - secretKey: private_key
          remoteRef:
            key: prod/tls/my-domain
            property: private_key

---

Troubleshooting

Use Argo CD to investigate issues with external secrets. The application tree provides visibility into all resources and their status.

Secret Not Syncing

1. Navigate to your application in the Argo CD UI

2. Locate the ExternalSecret resource in the application tree

3. Click on the ExternalSecret to view its details

4. Check the Status section for sync conditions

Look for these common status conditions:

• SecretSyncedError: The SecretStore cannot connect to the provider

• SecretNotFound: The referenced secret doesn't exist in the provider

Select the Events tab to see detailed error messages from the External Secrets Operator.

SecretStore Connection Issues

1. In the Argo CD application tree, locate the SecretStore resource

2. Click on the SecretStore to view its details

3. Check the Status section - a healthy SecretStore shows Ready: True

4. Select the Events tab for connection error details

Common causes:

• ServiceAccount doesn't have correct IAM role annotation

• IAM role doesn't have permission to access secrets

• Incorrect region or vault URL

ServiceAccount Issues

1. In the Argo CD application tree, locate the ServiceAccount resource

2. Click on the ServiceAccount to view its details

3. Check the Annotations section in the resource manifest

For AWS, verify the eks.amazonaws.com/role-arn annotation is present and correct. For Azure, verify both azure.workload.identity/client-id and azure.workload.identity/tenant-id annotations are present.

Viewing the Created Secret

Once an ExternalSecret syncs successfully, the Kubernetes Secret is created:

1. In the Argo CD application tree, locate the Secret resource

2. Click on the Secret to view its details

3. The Data section shows the secret keys (values are hidden by default)

---

Values Reference

Value	Type	Default	Description
enabled	bool	false	Enable the chart
organisationName	string	""	Organisation name for labeling
serviceAccount.create	bool	false	Create a ServiceAccount
serviceAccount.name	string	""	ServiceAccount name
serviceAccount.annotations	object	{}	ServiceAccount annotations (for IRSA/Workload Identity)
aws.enabled	bool	false	Use AWS Secrets Manager
aws.secretRegion	string	""	AWS region for secrets
azure.enabled	bool	false	Use Azure Key Vault
azure.managedIdentity.useWorkloadIdentity	bool	true	Use Workload Identity (recommended)
azure.managedIdentity.clientId	string	""	Azure client ID (for Managed Identity)
azure.managedIdentity.tenantId	string	""	Azure tenant ID (for Managed Identity)
items	list	[]	List of secret configurations
items[].secretStoreName	string	""	Name of the SecretStore to create
items[].kubernetesSecretName	string	""	Name of the Kubernetes Secret to create
items[].azure.vaultUrl	string	""	Azure Key Vault URL (Azure only)
items[].template	object	{}	Secret template configuration
items[].template.type	string	""	Kubernetes Secret type
items[].template.data	object	{}	Template data mapping
items[].data	list	[]	List of secret key mappings
items[].data[].secretKey	string	""	Key name in Kubernetes Secret
items[].data[].remoteRef.key	string	""	Secret name/path in provider
items[].data[].remoteRef.property	string	""	Property within the secret (AWS only)