DOCSEARCHbyAlgolia
Submit Docs

Azure Key Vault to Kubernetes (akv2k8s)

repository·master·Indexed 19 days ago

https://github.com/sparebankenvest/azure-key-vault-to-kubernetes

A bridge between Azure Key Vault and Kubernetes that allows secrets, certificates, and keys to be consumed as native Kubernetes Secrets via the Azure Key Vault Controller, or injected directly as environment variables into containers using the Azure Key Vault Env Injector. It supports multiple Azure cloud environments (public, china, german, us-gov) and provides specialized handlers for various secret types, including TLS, BasicAuth, and multi-value JSON/YAML blobs.

Tokens
6.5K
Snippets
14
Records
37
Agent score
65%

What's inside azure-key-vault-to-kubernetes

  1. Overview of Azure Key Vault to Kubernetes (akv2k8s)

    master

    Azure Key Vault to Kubernetes (akv2k8s) provides a secure way to make Azure Key Vault secrets, certificates, and keys available to applications running in Kubernetes. It achieves this through two primary mechanisms:

    1. Azure Key Vault Controller: Synchronizes objects (Secrets, Certificates, and Keys) from Azure Key Vault into native Kubernetes Secret objects.
    2. Azure Key Vault Env Injector: Transparently injects Azure Key Vault secrets directly into container applications as environment variables. This method avoids writing secrets to disk and avoids exposing the actual secret values as native Kubernetes secrets.

  2. How akv2k8s works: Controller vs. Env Injector

    master

    The project offers two distinct architectural patterns for secret consumption:

    Native Kubernetes Secrets (via Controller)

    Use the Azure Key Vault Controller if your application is designed to read configuration from standard Kubernetes Secret objects. The controller automates the lifecycle of syncing these objects from Azure.

    Direct Environment Injection (via Env Injector)

    Use the Azure Key Vault Env Injector if you want to adhere to the 12-Factor App principle without the overhead or security risk of native Kubernetes secrets. The injector injects secrets directly into the container's environment at runtime, ensuring secrets never touch the Kubernetes disk or the Kubernetes API as Secret objects.

  4. Use Multi-Value Secrets for JSON or YAML blobs

    master

    If your Azure Key Vault secret contains a collection of values (e.g., a JSON or YAML object), use the azureMultiValueSecretHandler. This requires setting the contentType in the Azure Key Vault object specification.

    Requirements

    • Object Type: Must be MultiKeyValueSecret.
    • ContentType: Must be set to either JSON or YAML.

    When configured, the handler will parse the secret and create a separate key in the Kubernetes Secret or ConfigMap for every entry found in the blob.

  5. How secret handlers map Azure Key Vault objects to Kubernetes

    master

    The controller uses specialized handlers to fetch data from Azure Key Vault and format it for Kubernetes Secret or ConfigMap resources. The handler chosen depends on the type of object in Azure Key Vault (Secret, Certificate, or Key) and how you want the output structured.

    Supported Handlers

    1. azureSecretHandler: Used for standard Azure Key Vault Secrets. It supports various Kubernetes secret types, including BasicAuth, DockerConfigJson, Dockercfg, SSHAuth, and TLS (via PFX decoding).
    2. azureCertificateHandler: Used for Azure Key Vault Certificates. It can export public keys as PEM or, if configured, both public and private keys for TLS secrets.
    3. azureKeyHandler: Used for Azure Key Vault Keys. It maps the key directly to a data key in a Secret or ConfigMap.
    4. azureMultiValueSecretHandler: Used when an Azure Key Vault Secret contains multiple key-value pairs stored as a single JSON or YAML blob. It unmarshals the blob and creates individual entries in the Kubernetes resource.

  8. How the VaultEnv CLI works as an entrypoint wrapper

    master

    The azure-keyvault-env binary acts as a wrapper (entrypoint) for your application container. It performs the following lifecycle:

    1. Initialization: Loads configuration from environment variables and initializes logging.
    2. Security Validation: Validates the signature of the original container command and arguments using ENV_INJECTOR_ARGS_SIGNATURE and ENV_INJECTOR_ARGS_KEY to ensure the command hasn't been tampered with.
    3. Authentication: Connects to Azure Key Vault, either locally or via a centralized auth-service.
    4. Secret Extraction: Scans the existing environment variables for references to AzureKeyVaultSecret custom resources. It fetches the actual secret values from Azure Key Vault.
    5. Injection: Replaces the placeholder environment variables with the real secret values.
    6. Execution: Uses syscall.Exec to replace the injector process with the original container command, passing the new environment containing the secrets.

  9. Format Azure Key Vault references in environment variables

    master

    The azure-keyvault-env tool identifies secrets to fetch from Azure Key Vault by parsing specific patterns in environment variable values. To trigger a lookup, an environment variable's value must match the following URI-like format:

    <secret-name>@azurekeyvault?query

    Components:

    • <secret-name>: The name of the secret as it exists in Azure Key Vault. This must follow standard DNS naming conventions (alphanumeric, hyphens, max 255 chars).
    • @azurekeyvault: A required literal suffix that identifies the value as a Key Vault reference.
    • ?query (Optional): An optional query parameter used to refine the secret lookup (e.g., for specific versions or metadata).

    If the value does not match this pattern, the tool treats it as a standard environment variable and does not attempt to fetch a secret from Azure.

    # Example: Basic secret lookup
MY_SECRET=my-secret-name@azurekeyvault

# Example: Secret lookup with a query parameter
DATABASE_PASSWORD=db-password@azurekeyvault?version=1.0

  10. Configure controller to run in a specific namespace

    master
    Starting from version 1.3.0, the controller supports running within a specific namespace rather than across the entire cluster. This is controlled via the watchAllNamespaces setting in the Helm charts. When watchAllNamespaces is set to false, the controller uses RBAC Role instead of ClusterRole to limit its scope.