CA Injector
cainjector helps to configure the CA certificates for:
Mutating Webhooks,
Validating Webhooks, and
Conversion Webhooks.
In particular, cainjector populates the caBundle field of three API types:
ValidatingWebhookConfiguration,
MutatingWebhookConfiguration, and
CustomResourceDefinition.
These APIs are used to configure how the Kubernetes API server connects to webhooks.
This caBundle data is loaded by the Kubernetes API server and used to verify the serving certificates of webhook API servers.
We will refer to these three API types as the injectable resources.
An injectable resource MUST have one of these annotations:
cert-manager.io/inject-ca-from,
cert-manager.io/inject-ca-from-secret, or
cert-manager.io/inject-apiserver-ca, depending on the injection source.
This is explained in more detail below.
cainjector copies CA data from one of three sources:
a Kubernetes Secret,
a cert-manager Certificate, or from
the Kubernetes API server CA certificate (which cainjector itself uses to verify its TLS connection to the Kubernetes API server).
If the source is a Kubernetes Secret, that resource MUST also have an cert-manager.io/allow-direct-injection: "true" annotation.
The three source types are explained in more detail below.
Examples
Here are examples demonstrating how to use the three cainjector sources.
In each case we use ValidatingWebhookConfiguration as the injectable,
but you can substitute MutatingWebhookConfiguration or CustomResourceDefinition definition instead.
Injecting CA data from a Certificate resource
Here is an example of a ValidatingWebhookConfiguration
configured with the annotation cert-manager.io/inject-ca-from,
which will make cainjector populate the caBundle field using CA data from a cert-manager Certificate.
NOTE: This example does not deploy a webhook server,
it only deploys a partial webhook configuration,
but it should be sufficient to help you understand what cainjector does:
apiVersion: v1
kind: Namespace
metadata:
name: example1
---
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
name: webhook1
annotations:
cert-manager.io/inject-ca-from: example1/webhook1-certificate
webhooks:
- name: webhook1.example.com
admissionReviewVersions:
- v1
clientConfig:
service:
name: webhook1
namespace: example1
path: /validate
port: 443
sideEffects: None
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: webhook1-certificate
namespace: example1
spec:
secretName: webhook1-certificate
dnsNames:
- webhook1.example1
issuerRef:
name: selfsigned
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: selfsigned
namespace: example1
spec:
selfSigned: {}You should find that the caBundle value is now identical to the CA value in the Secret for the Certificate:
kubectl get validatingwebhookconfigurations.admissionregistration.k8s.io webhook1 -o yaml | grep caBundle
kubectl -n example get secret webhook1-certificate -o yaml | grep ca.crt
And after a short time, the Kubernetes API server will read that new caBundle value and use it to verify a TLS connection to the webhook server.
Injecting CA data from a Secret resource
Here is another example of a ValidatingWebhookConfiguration
this time configured with the annotation cert-manager.io/inject-ca-from-secret,
which will make cainjector populate the caBundle field using CA data from a Kubernetes Secret.
NOTE: This example does not deploy a webhook server,
it only deploys a partial webhook configuration,
but it should be sufficient to help you understand what cainjector does:
apiVersion: v1
kind: Namespace
metadata:
name: example2
---
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
name: webhook2
annotations:
cert-manager.io/inject-ca-from-secret: example2/example-ca
webhooks:
- name: webhook2.example.com
admissionReviewVersions:
- v1
clientConfig:
service:
name: webhook2
namespace: example2
path: /validate
port: 443
sideEffects: None
---
apiVersion: v1
kind: Secret
metadata:
name: example-ca
namespace: example2
annotations:
cert-manager.io/allow-direct-injection: "true"
type: kubernetes.io/tls
data:
ca.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM5akNDQWQ2Z0F3SUJBZ0lRTkdJZ24yM3BQYVpNbk9MUjJnVmZHakFOQmdrcWhraUc5dzBCQVFzRkFEQVYKTVJNd0VRWURWUVFERXdwRmVHRnRjR3hsSUVOQk1CNFhEVEl3TURreU5ERTFOREEwTVZvWERUSXdNVEl5TXpFMQpOREEwTVZvd0ZURVRNQkVHQTFVRUF4TUtSWGhoYlhCc1pTQkRRVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFECmdnRVBBRENDQVFvQ2dnRUJBS2F3RzVoMzlreHdyNEl0WCtHaDNYVWQrdTVJc2ZlSFdoTTc4TTRQTmZFeXhQMXoKRmNLN1d0MHJFMkwwNUppYmQ4ZjNpb3k5OXNnQ3I4OEw2SWxYZTB0RnkzNysxenJ4TFluR2hDQnZzZjltd0hLbgpIVTEvNERwQjROZkhPbFllNE9tbHVoNE9HdmZINU1EbDh5OWZGMjhXRXVBQ2dwdmpCUWxvRDNlVjJ5UmJvQ2kyCmtSTDJWYTFZL0FQZEpWK21VYkFvZmg0bllmUmNLRTJsSUg0RG5ZdXFPU3JaaituZUQ2M2RTSktxcHQ5K2luN2YKNHljZ2pQYU93MmdyKzhLK291QTlSQTV1VDI3SVNJcUJDcEV6elRqbVBUUWNvUTYxZGF0aDZkc1lsTEU4aWZWUwp4RWZuVEdQKy94M0FXQXR4eU5lanVuZGFXbVNFL3h5OHh0K0FxblVDQXdFQUFhTkNNRUF3RGdZRFZSMFBBUUgvCkJBUURBZ0trTUE4R0ExVWRFd0VCL3dRRk1BTUJBZjh3SFFZRFZSME9CQllFRkowNkc5eEc2V1VBTHB6T3JYaHAKV2dsTm5qMkFNQTBHQ1NxR1NJYjNEUUVCQ3dVQUE0SUJBUUI3ZG9CZnBLR3o4VlRQSnc0YXhpdisybzJpMHE1SQpSRzU2UE81WnhKQktZQlRROElHQmFOSm1yeGtmNTJCV0ttUGp4cXlNSGRwWjVBU00zOUJkZVUzRGtEWHp4RkgwCjM5RU12UnhIUERyMGQ4cTFFbndQT0xZY1hzNjJhYjdidE11cTJUMFNNZzRYMkY5VmNKTW5YdjlrNnA0VGZNR3MKVThCQnJhVGhUZm53ejBsWXMyblFjdzNmZjZ1bG1wWlk4K3BTak1aVDNJZHZOMFA4Y2hOdUlmUFRHWDJmSlo2NQpxcUUrelRoU3hIeXFTOTVoczhsd1lRRUhGQlVsalRnMCtQZThXL0hOSXZBOU9TYWw1U3UvdlhydmcxN04xdHVyCk5XcWRyZU5OVm1ubXMvTFJodmthWTBGblRvbFNBRkNXWS9GSDY5ZzRPcThiMHVyK3JVMHZOZFFXCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
tls.key: ""
tls.crt: ""You should find that the caBundle value is now identical to the ca.crt value in the Secret:
kubectl get validatingwebhookconfigurations.admissionregistration.k8s.io webhook2 -o yaml | grep caBundle
And after a short time, the Kubernetes API server will read that new caBundle value and use it to verify a TLS connection to the webhook server.
This Secret based injection mechanism can operate independently of the Certificate based mechanism described earlier.
It will work without the cert-manager CRDs installed
and it will work if the cert-manager CRDs and associated webhook servers are not yet configured.
NOTE: For this reason, cert-manager uses the Secret based injection mechanism to bootstrap its own webhook server.
The cert-manager webhook server generates its own private key and self-signed certificate and places them in a Secret when it starts up.
Injecting the Kubernetes API Server CA
Here is another example of a ValidatingWebhookConfiguration
this time configured with the annotation cert-manager.io/inject-apiserver-ca: "true",
which will make cainjector populate the caBundle field using the same CA certificate used by the Kubernetes API server.
NOTE: This example does not deploy a webhook server,
it only deploys a partial webhook configuration,
but it should be sufficient to help you understand what cainjector does:
apiVersion: v1
kind: Namespace
metadata:
name: example3
---
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
name: webhook3
annotations:
cert-manager.io/inject-apiserver-ca: "true"
webhooks:
- name: webhook3.example.com
admissionReviewVersions:
- v1
clientConfig:
service:
name: webhook3
namespace: example3
path: /validate
port: 443
sideEffects: NoneYou should find that the caBundle value is now identical to the CA used in your KubeConfig file:
kubectl get validatingwebhookconfigurations.admissionregistration.k8s.io webhook3 -o yaml | grep caBundle
kubectl config view --minify --raw | grep certificate-authority-data
And after a short time, the Kubernetes API server will read that new caBundle value and use it to verify a TLS connection to the webhook server.
NOTE: In this case you will have to ensure that your webhook is configured to serve a TLS certificate that has been signed by the Kubernetes cluster CA. The disadvantages of this mechanism are that: you will require access to the private key of the Kubernetes cluster CA and you will need to manually rotate the webhook certificate.