Skip to content

Latest commit

 

History

History
124 lines (104 loc) · 4.9 KB

README.md

File metadata and controls

124 lines (104 loc) · 4.9 KB
Raw

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.