azure-keyvault-issuer

azure-keyvault-issuer is an external issuer for cert-manager, using an Azure Keyvault "Key" to sign CertificateRequests.

azure-keyvault-issuer is not affiliated with Microsoft.

Architectural high level overview

flowchart TB
  cr[CertificateRequest CR]
  i[Issuer CR]
  key[Azure KeyVault Key]
  aki[azure-keyvault-issuer]
  aki -- "(1) get" --> cr
  aki -- "(2) get keyvault details" --> i
  aki -- "(3) create certificate using" --> key
  aki -- "(4) set certificate" --> cr
  style cr fill:#555
  style i fill:#555
  style key fill:#338

Loading

Tradeoffs / Design decisions

Management of CA and CA certificate

azure-keyvault-issuer does not implement creation of Azure Keyvault Keys and also does not implement creation of a CA certificate. Instead, users have to (1) create the "Key" manually, (2) can utilize hack/create_ca_cert to create a CA certificate using that "Key" and (3) should upload this certificate as Azure Keyvault Secret, so azure-keyvault-issuer can download it from there.

This is intended to make multi-cluster setups easy. If the CA certificate was managed (and not just consumed) in an Issuer resource inside of Kubernetes, distributing it would be more complicated in some/most cases.

Azure Authentication

Authentication works usually by configuring a workload identity for the controller pod.

Getting started

1. Create Azure KeyVault
2. Create "Key" inside of Azure Keyvault (only RSA supported for now)
3. Run hack/create_ca_cert, push resulting CA certificate into Azure Keyvault "Secret" (with the same name as the name of the "Key")
4. Create user assigned identity for azure-keyvault-issuer controller, granting Key/Get, Key/Sign and Secret/Get permissions on the Keyvault
5. Install azure-keyvault-issuer using the kustomize base in config/default, configuring workload identity with user assigned identity mentioned above
6. Create Issuer/ClusterIssuer

   apiVersion: azure-keyvault-issuer.gonicus.de/v1alpha1
   kind: ClusterIssuer
   metadata:
     name: test-clusterissuer
   spec:
     keyVaultBaseURL: 'https://my-cert-manager-vault.vault.azure.net/'
     keyName: test-key
     keyVersion: '<insert key version>'

7. Validate health of Issuer/ClusterIssuer

   kubectl get clusterissuer.azure-keyvault-issuer.gonicus.de test-clusterissuer -oyaml
   

8. Use issuer

   apiVersion: cert-manager.io/v1
   kind: CertificateRequest
   metadata:
     name: test-csr
   spec:
     issuerRef:
       kind: ClusterIssuer
       group: azure-keyvault-issuer.gonicus.de
       name: test-clusterissuer
     request: ...

Full workflow

Participants:

• hack/create_ca_cert: Go command line tool in hack/create_ca_cert
• User: Human operator using tooling like az or terraform
• azure-keyvault-issuer: Kubernetes controller / cert-manager external issuer controller
• IssuerCR: Custom Resource (instance, not definition) of azure-keyvault-issuer Issuer
• CertificateRequestCR: Custom Resource (instance, not definition) of cert-manager CertificateRequest

sequenceDiagram
participant User
participant hack/create_ca_cert
participant AzureKeyVaultKey
participant AzureKeyVaultSecret
participant azure-keyvault-issuer
participant IssuerCR
participant CertificateRequestCR
User->>AzureKeyVaultKey: Create (RSA)
User->>hack/create_ca_cert: Run
hack/create_ca_cert->>hack/create_ca_cert: Setup CA certificate template
hack/create_ca_cert->>AzureKeyVaultKey: Build CA certificate using sign operation
hack/create_ca_cert->>User: Return CA certificate
User->>AzureKeyVaultSecret: Store CA certificate
User->>IssuerCR: Create (keyvault, keyName, keyVersion)
loop Issuer reconcile interval
    azure-keyvault-issuer->>IssuerCR: Get
    azure-keyvault-issuer->>AzureKeyVaultSecret: Get CA certificate
    azure-keyvault-issuer->>IssuerCR: Set Ready condition and CA certificate in status
end
loop CertificateRequest reconcile interval
    azure-keyvault-issuer->>CertificateRequestCR: Get
    azure-keyvault-issuer->>azure-keyvault-issuer: Verify CertificateRequest is suitable for signing
    azure-keyvault-issuer->>IssuerCR: Get
    azure-keyvault-issuer->>azure-keyvault-issuer: Configure AzureKeyVault client using IssuerCR spec
    azure-keyvault-issuer->>AzureKeyVaultKey: Build certificate using CA certificate from IssuerCR status and Sign operation
    azure-keyvault-issuer->>CertificateRequestCR: Set certificate in status
end

Loading

Attribution

This issuer was built using the instructions in the cert-manager sample-external-issuer repo and contains much code from there.

Security

For security vulnerabilities, please contact TBD.