Azure Key Vault Secret Store extension configuration reference

The SSE can be configured in four places: Configuration settings provided to Arc infrastructure when creating or updating the extension, AKVSync resources, SecretSync kubernetes resources, and SecretProviderClass kubernetes resources.

Arc extension configuration settings

Configuration settings can be set when the SSE Arc extension instance is created, or they can be updated later. Use --configuration-settings <setting>=<value> with az k8s-extension create ... or az k8s-extension update ... to create or update an SSE instance respectively.

SSE accepts the following Arc extension configuration parameters:

AKVSync resources (preview)

AKVSync resources simplify the most common SSE use cases by consolidating configuration into a single resource. This single resource is easier for a human to configure and is less prone to inconsistencies. When applied, AKVSync resources are translated to their equivalent SecretSync and SecretProviderClass resources. Don't modify the autogenerated SecretSync and SecretProviderClass resources; they will be updated as needed automatically.

The simplified configuration is a preview feature and may benefit from minor changes in upcoming versions. The direct configuration style remains available for all deployments.

Example

kind: AKVSync
apiVersion: secret-sync.x-k8s.io/v1alpha1
metadata:
  name: my-akv-secrets
  namespace: workload-namespace
spec:
  keyvaultName: exampleKeyvault
  clientID:  "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
  tenantID:  "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
  serviceAccountName: workload-serviceaccountname
  objects:
    - secretInAKV: "secret-A"
    - secretInAKV: "secret-B"
      kubernetesSecretName: "k8s-secret-b"
      labels:
        - test-label-0: "label-value-0"
      annotations:
        - test-annotation-0: "annotation-value-0"
      versionHistory: 3
    - kubernetesSecretName: "compound-secret"
      mapping:
        - dataKey: "username"
          secretInAKV: secret-A
        - dataKey: "password"
          secretInAKV: secret-B
          version: 1

Values

• metadata.name (required): The name of this AKVSync resource.

Within .spec:

• serviceAccountName (required): The Kubernetes service account used to access the Kubernetes secret store. This service account should be federated with the managed identity with access to the secrets in Azure Key Vault.

• clientID (required): The clientID for the managed identity with access to the required secrets. This managed identity must have a federated credential associated with the named service account.

• tenantID (required): The ID of the Azure tenant containing the AKV instance.

• keyvaultName (required): The name of the key vault.

• objects (required): A list of items (secretInAKV or kubernetesSecretName). Items can be secrets to fetch from AKV, or more complex 'compound secrets' that may contain many items from AKV.

  • secretInAKV (optional): The name of a secret that should be fetched from AKV.

    • kubernetesSecretName (optional): The name of the new Kubernetes secret.
    • labels (optional): A list of key-value pairs of additional labels to apply to the secret object.
    • annotations (optional): A list of key-value pairs of additional annotations to apply to the secret object.
    • versionHistory (optional): Defaults to 1. SSE downloads this many versions of the secret from AKV. The versions are stored in the Kubernetes secret in keys named "v0", "v1", "v2" etc. "v0" is the latest version.

  • kubernetesSecretName (optional): Defines the name for a compound secret in Kubernetes, which can have any number of items. versionHistory can't be used in this situation. If multiple versions are needed, they must be explicitly enumerated. You can optionally specify labels and annotations.

    • mapping (required): A list of data keys and their AKV sources. There are no default keys.

      • dataKey (required): The name of the data key within the Kubernetes secret that holds the secret fetched from AKV.

      • secretInAKV (required): The name of a secret that should be fetched from AKV and stored in the nominated data key.

      • version (optional): The version of the secret to fetch from AKV. 0 is the latest version, 1 is the second latest, etc.

SecretSync resources

SecretSync resources configure how SSE stores secrets and certificates into the Kubernetes secret store. Each SecretSync resource defines one Kubernetes secret, although it may contain more than one secret.

Example

apiVersion: secret-sync.x-k8s.io/v1alpha1
kind: SecretSync
metadata:
  name: secret-sync-name
  namespace: workload-namespace
spec:
  serviceAccountName: workload-serviceaccountname
  secretProviderClassName: secret-provider-class-name
  secretObject:
    type: Opaque
    data:
    - sourcePath: aSecret/0
      targetKey: aSecret-data-key0
    - sourcePath: aSecret/1
      targetKey: aSecret-data-key1
    labels:
      - fromExample: absolutelyYes
    annotations:
      - exampleAnnotation: annotationValue 
  forceSynchronization: ArbitraryValue12354

Values

• metadata.name (required): The name of this SecretSync resource. Note: The automatically created Secret resource has the same name as this resource.

Within .spec:

• serviceAccountName (required): The Kubernetes service account used to access the Kubernetes secret store. This service account should be federated with the managed identity with access to the secrets in Azure Key Vault.
• secretProviderClassName (required): The name of the SecretProviderClass resource that defines which secrets to fetch from Azure Key Vault.
• secretObject (required): Defines how the stored secret resource should be structured.
  • type (required): The type of the Kubernetes secret object. Set this field to Opaque for a general purpose secret with no imposed structure. See Types of Kubernetes secrets for guidance on how the special purpose secret types need to be structured.
  • data (required): A list of data items within the secret resource. There must be at least one item. Each data item must contain these two fields:
    • sourcePath (required): The path to an item fetched from AKV. When only one version of the named secret is fetched from AKV, the path is simply <secret name>.
      If more than one version of the named secret is fetched from AKV, then the latest version's sourcePath is <secret name>/0, second latest is <secret name>/1, etc.
      When a certificate is fetched from AKV, the sourcePaths depend on the value of objectType in the SecretProviderClass. When the objectType in the SPC is "secret" then both a certificate and private key are available at sourcePaths of <secret name>/tls.crt and <secret name>/tls.key respectively.
    • targetKey (required): The key in the Kubernetes secret object to store the data into.
  • labels (optional): A list of key-value pairs of additional labels to apply to the secret object.
  • annotations (optional): A list of key-value pairs of additional annotations to apply to the secret object.
  • forceSynchronization (optional): Changes to this field trigger SSE to recheck AKV for changes. Kubernetes is updated as usual if SSE finds updated data. The value of this field does not affect how the SSE behaves.

SecretProviderClass resources

SecretProviderClass resources configure what and how to fetch from an Azure Key Vault. This reference only covers the fields necessary for the SSE use cases of the SecretProviderClass.

Example

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: secret-provider-class-name
  namespace: workload-namespace
spec:
  provider: azure
  parameters:
    clientID: "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
    tenantID: "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
    keyvaultName: exampleKeyvault
    objects: |
      array:
        - |
          objectName: aSecret
          objectType: secret
          objectVersionHistory: 2
        - |
          objectName: aCertificate
          objectType: secret

Values

Within .spec:

• provider (required): Set this field to azure when using SSE to fetch secrets from Azure Key Vault.
• parameters (required): Defines how and where to fetch AKV secrets from.
  • clientID (required): The clientID for the managed identity with access to the required secrets. This managed identity must have a federated credential associated with the service account named in the SecretSync resource that uses this SecretProviderClass.
  • tenantID (required): The ID of the Azure tenant containing the AKV instance.
  • keyvaultName (required): The name of the keyvault.
  • objects (required): A string containing a YAML fragment representing the items to be fetched from this AKV. Pay close attention to the example to see how the objects field is constructed. Additional examples of SecretProviderClass resources for use with Azure Key Vault may be found in the AKV provider docs. objects must contain at least one item within the "array" sub-object.
    • objectName (required): The name of the secret or certificate to fetch from AKV.
    • objectType (required): Set this field to secret when fetching a secret from AKV.
      When fetching a certificate, set this field to:
      • cert to fetch only the certificate.
      • key to fetch only the public key of the certificate.
      • secret to fetch the certificate and the private key.
    • objectVersionHistory (optional): If present and greater than one, this many versions are fetched from AKV, starting with the latest.