366 lines
12 KiB
Markdown
366 lines
12 KiB
Markdown
---
|
|
title: Manage TLS Certificates in a Cluster
|
|
content_type: task
|
|
reviewers:
|
|
- mikedanese
|
|
- beacham
|
|
- liggit
|
|
---
|
|
|
|
<!-- overview -->
|
|
|
|
Kubernetes provides a `certificates.k8s.io` API, which lets you provision TLS
|
|
certificates signed by a Certificate Authority (CA) that you control. These CA
|
|
and certificates can be used by your workloads to establish trust.
|
|
|
|
`certificates.k8s.io` API uses a protocol that is similar to the [ACME
|
|
draft](https://github.com/ietf-wg-acme/acme/).
|
|
|
|
{{< note >}}
|
|
Certificates created using the `certificates.k8s.io` API are signed by a
|
|
[dedicated CA](#configuring-your-cluster-to-provide-signing). It is possible to configure your cluster to use the cluster root
|
|
CA for this purpose, but you should never rely on this. Do not assume that
|
|
these certificates will validate against the cluster root CA.
|
|
{{< /note >}}
|
|
|
|
|
|
|
|
|
|
## {{% heading "prerequisites" %}}
|
|
|
|
|
|
{{< include "task-tutorial-prereqs.md" >}}
|
|
|
|
You need the `cfssl` tool. You can download `cfssl` from
|
|
[https://github.com/cloudflare/cfssl/releases](https://github.com/cloudflare/cfssl/releases).
|
|
|
|
Some steps in this page use the `jq` tool. If you don't have `jq`, you can
|
|
install it via your operating system's software sources, or fetch it from
|
|
[https://jqlang.github.io/jq/](https://jqlang.github.io/jq/).
|
|
|
|
<!-- steps -->
|
|
|
|
## Trusting TLS in a cluster
|
|
|
|
Trusting the [custom CA](#configuring-your-cluster-to-provide-signing) from an application running as a pod usually requires
|
|
some extra application configuration. You will need to add the CA certificate
|
|
bundle to the list of CA certificates that the TLS client or server trusts. For
|
|
example, you would do this with a golang TLS config by parsing the certificate
|
|
chain and adding the parsed certificates to the `RootCAs` field in the
|
|
[`tls.Config`](https://pkg.go.dev/crypto/tls#Config) struct.
|
|
|
|
{{< note >}}
|
|
Even though the custom CA certificate may be included in the filesystem (in the
|
|
ConfigMap `kube-root-ca.crt`),
|
|
you should not use that certificate authority for any purpose other than to verify internal
|
|
Kubernetes endpoints. An example of an internal Kubernetes endpoint is the
|
|
Service named `kubernetes` in the default namespace.
|
|
|
|
If you want to use a custom certificate authority for your workloads, you should generate
|
|
that CA separately, and distribute its CA certificate using a
|
|
[ConfigMap](/docs/tasks/configure-pod-container/configure-pod-configmap) that your pods
|
|
have access to read.
|
|
{{< /note >}}
|
|
|
|
## Requesting a certificate
|
|
|
|
The following section demonstrates how to create a TLS certificate for a
|
|
Kubernetes service accessed through DNS.
|
|
|
|
{{< note >}}
|
|
This tutorial uses CFSSL: Cloudflare's PKI and TLS toolkit [click here](https://blog.cloudflare.com/introducing-cfssl/) to know more.
|
|
{{< /note >}}
|
|
|
|
## Create a certificate signing request
|
|
|
|
Generate a private key and certificate signing request (or CSR) by running
|
|
the following command:
|
|
|
|
```shell
|
|
cat <<EOF | cfssl genkey - | cfssljson -bare server
|
|
{
|
|
"hosts": [
|
|
"my-svc.my-namespace.svc.cluster.local",
|
|
"my-pod.my-namespace.pod.cluster.local",
|
|
"192.0.2.24",
|
|
"10.0.34.2"
|
|
],
|
|
"CN": "my-pod.my-namespace.pod.cluster.local",
|
|
"key": {
|
|
"algo": "ecdsa",
|
|
"size": 256
|
|
}
|
|
}
|
|
EOF
|
|
```
|
|
|
|
Where `192.0.2.24` is the service's cluster IP,
|
|
`my-svc.my-namespace.svc.cluster.local` is the service's DNS name,
|
|
`10.0.34.2` is the pod's IP and `my-pod.my-namespace.pod.cluster.local`
|
|
is the pod's DNS name. You should see the output similar to:
|
|
|
|
```
|
|
2022/02/01 11:45:32 [INFO] generate received request
|
|
2022/02/01 11:45:32 [INFO] received CSR
|
|
2022/02/01 11:45:32 [INFO] generating key: ecdsa-256
|
|
2022/02/01 11:45:32 [INFO] encoded CSR
|
|
```
|
|
|
|
This command generates two files; it generates `server.csr` containing the PEM
|
|
encoded [PKCS#10](https://tools.ietf.org/html/rfc2986) certification request,
|
|
and `server-key.pem` containing the PEM encoded key to the certificate that
|
|
is still to be created.
|
|
|
|
## Create a CertificateSigningRequest object to send to the Kubernetes API
|
|
|
|
Generate a CSR manifest (in YAML), and send it to the API server. You can do that by
|
|
running the following command:
|
|
|
|
```shell
|
|
cat <<EOF | kubectl apply -f -
|
|
apiVersion: certificates.k8s.io/v1
|
|
kind: CertificateSigningRequest
|
|
metadata:
|
|
name: my-svc.my-namespace
|
|
spec:
|
|
request: $(cat server.csr | base64 | tr -d '\n')
|
|
signerName: example.com/serving
|
|
usages:
|
|
- digital signature
|
|
- key encipherment
|
|
- server auth
|
|
EOF
|
|
```
|
|
|
|
Notice that the `server.csr` file created in step 1 is base64 encoded
|
|
and stashed in the `.spec.request` field. You are also requesting a
|
|
certificate with the "digital signature", "key encipherment", and "server
|
|
auth" key usages, signed by an example `example.com/serving` signer.
|
|
A specific `signerName` must be requested.
|
|
View documentation for [supported signer names](/docs/reference/access-authn-authz/certificate-signing-requests/#signers)
|
|
for more information.
|
|
|
|
The CSR should now be visible from the API in a Pending state. You can see
|
|
it by running:
|
|
|
|
```shell
|
|
kubectl describe csr my-svc.my-namespace
|
|
```
|
|
|
|
```none
|
|
Name: my-svc.my-namespace
|
|
Labels: <none>
|
|
Annotations: <none>
|
|
CreationTimestamp: Tue, 01 Feb 2022 11:49:15 -0500
|
|
Requesting User: yourname@example.com
|
|
Signer: example.com/serving
|
|
Status: Pending
|
|
Subject:
|
|
Common Name: my-pod.my-namespace.pod.cluster.local
|
|
Serial Number:
|
|
Subject Alternative Names:
|
|
DNS Names: my-pod.my-namespace.pod.cluster.local
|
|
my-svc.my-namespace.svc.cluster.local
|
|
IP Addresses: 192.0.2.24
|
|
10.0.34.2
|
|
Events: <none>
|
|
```
|
|
|
|
## Get the CertificateSigningRequest approved {#get-the-certificate-signing-request-approved}
|
|
|
|
Approving the [certificate signing request](/docs/reference/access-authn-authz/certificate-signing-requests/)
|
|
is either done by an automated approval process or on a one off basis by a cluster
|
|
administrator. If you're authorized to approve a certificate request, you can do that
|
|
manually using `kubectl`; for example:
|
|
|
|
```shell
|
|
kubectl certificate approve my-svc.my-namespace
|
|
```
|
|
|
|
```none
|
|
certificatesigningrequest.certificates.k8s.io/my-svc.my-namespace approved
|
|
```
|
|
|
|
You should now see the following:
|
|
|
|
```shell
|
|
kubectl get csr
|
|
```
|
|
|
|
```none
|
|
NAME AGE SIGNERNAME REQUESTOR REQUESTEDDURATION CONDITION
|
|
my-svc.my-namespace 10m example.com/serving yourname@example.com <none> Approved
|
|
```
|
|
|
|
This means the certificate request has been approved and is waiting for the
|
|
requested signer to sign it.
|
|
|
|
## Sign the CertificateSigningRequest {#sign-the-certificate-signing-request}
|
|
|
|
Next, you'll play the part of a certificate signer, issue the certificate, and upload it to the API.
|
|
|
|
A signer would typically watch the CertificateSigningRequest API for objects with its `signerName`,
|
|
check that they have been approved, sign certificates for those requests,
|
|
and update the API object status with the issued certificate.
|
|
|
|
### Create a Certificate Authority
|
|
|
|
You need an authority to provide the digital signature on the new certificate.
|
|
|
|
First, create a signing certificate by running the following:
|
|
|
|
```shell
|
|
cat <<EOF | cfssl gencert -initca - | cfssljson -bare ca
|
|
{
|
|
"CN": "My Example Signer",
|
|
"key": {
|
|
"algo": "rsa",
|
|
"size": 2048
|
|
}
|
|
}
|
|
EOF
|
|
```
|
|
|
|
You should see output similar to:
|
|
|
|
```none
|
|
2022/02/01 11:50:39 [INFO] generating a new CA key and certificate from CSR
|
|
2022/02/01 11:50:39 [INFO] generate received request
|
|
2022/02/01 11:50:39 [INFO] received CSR
|
|
2022/02/01 11:50:39 [INFO] generating key: rsa-2048
|
|
2022/02/01 11:50:39 [INFO] encoded CSR
|
|
2022/02/01 11:50:39 [INFO] signed certificate with serial number 263983151013686720899716354349605500797834580472
|
|
```
|
|
|
|
This produces a certificate authority key file (`ca-key.pem`) and certificate (`ca.pem`).
|
|
|
|
### Issue a certificate
|
|
|
|
{{% code_sample file="tls/server-signing-config.json" %}}
|
|
|
|
Use a `server-signing-config.json` signing configuration and the certificate authority key file
|
|
and certificate to sign the certificate request:
|
|
|
|
```shell
|
|
kubectl get csr my-svc.my-namespace -o jsonpath='{.spec.request}' | \
|
|
base64 --decode | \
|
|
cfssl sign -ca ca.pem -ca-key ca-key.pem -config server-signing-config.json - | \
|
|
cfssljson -bare ca-signed-server
|
|
```
|
|
|
|
You should see the output similar to:
|
|
|
|
```
|
|
2022/02/01 11:52:26 [INFO] signed certificate with serial number 576048928624926584381415936700914530534472870337
|
|
```
|
|
|
|
This produces a signed serving certificate file, `ca-signed-server.pem`.
|
|
|
|
### Upload the signed certificate
|
|
|
|
Finally, populate the signed certificate in the API object's status:
|
|
|
|
```shell
|
|
kubectl get csr my-svc.my-namespace -o json | \
|
|
jq '.status.certificate = "'$(base64 ca-signed-server.pem | tr -d '\n')'"' | \
|
|
kubectl replace --raw /apis/certificates.k8s.io/v1/certificatesigningrequests/my-svc.my-namespace/status -f -
|
|
```
|
|
|
|
{{< note >}}
|
|
This uses the command line tool [`jq`](https://jqlang.github.io/jq/) to populate the base64-encoded
|
|
content in the `.status.certificate` field.
|
|
If you do not have `jq`, you can also save the JSON output to a file, populate this field manually, and
|
|
upload the resulting file.
|
|
{{< /note >}}
|
|
|
|
Once the CSR is approved and the signed certificate is uploaded, run:
|
|
|
|
```shell
|
|
kubectl get csr
|
|
```
|
|
|
|
The output is similar to:
|
|
```none
|
|
NAME AGE SIGNERNAME REQUESTOR REQUESTEDDURATION CONDITION
|
|
my-svc.my-namespace 20m example.com/serving yourname@example.com <none> Approved,Issued
|
|
```
|
|
|
|
## Download the certificate and use it
|
|
|
|
Now, as the requesting user, you can download the issued certificate
|
|
and save it to a `server.crt` file by running the following:
|
|
|
|
```shell
|
|
kubectl get csr my-svc.my-namespace -o jsonpath='{.status.certificate}' \
|
|
| base64 --decode > server.crt
|
|
```
|
|
|
|
Now you can populate `server.crt` and `server-key.pem` in a
|
|
{{< glossary_tooltip text="Secret" term_id="secret" >}}
|
|
that you could later mount into a Pod (for example, to use with a webserver
|
|
that serves HTTPS).
|
|
|
|
```shell
|
|
kubectl create secret tls server --cert server.crt --key server-key.pem
|
|
```
|
|
|
|
```none
|
|
secret/server created
|
|
```
|
|
|
|
Finally, you can populate `ca.pem` into a {{< glossary_tooltip text="ConfigMap" term_id="configmap" >}}
|
|
and use it as the trust root to verify the serving certificate:
|
|
|
|
```shell
|
|
kubectl create configmap example-serving-ca --from-file ca.crt=ca.pem
|
|
```
|
|
|
|
```none
|
|
configmap/example-serving-ca created
|
|
```
|
|
|
|
## Approving CertificateSigningRequests {#approving-certificate-signing-requests}
|
|
|
|
A Kubernetes administrator (with appropriate permissions) can manually approve
|
|
(or deny) CertificateSigningRequests by using the `kubectl certificate
|
|
approve` and `kubectl certificate deny` commands. However if you intend
|
|
to make heavy usage of this API, you might consider writing an automated
|
|
certificates controller.
|
|
|
|
{{< caution >}}
|
|
The ability to approve CSRs decides who trusts whom within your environment. The
|
|
ability to approve CSRs should not be granted broadly or lightly.
|
|
|
|
You should make sure that you confidently understand both the verification requirements
|
|
that fall on the approver **and** the repercussions of issuing a specific certificate
|
|
before you grant the `approve` permission.
|
|
{{< /caution >}}
|
|
|
|
Whether a machine or a human using kubectl as above, the role of the _approver_ is
|
|
to verify that the CSR satisfies two requirements:
|
|
|
|
1. The subject of the CSR controls the private key used to sign the CSR. This
|
|
addresses the threat of a third party masquerading as an authorized subject.
|
|
In the above example, this step would be to verify that the pod controls the
|
|
private key used to generate the CSR.
|
|
2. The subject of the CSR is authorized to act in the requested context. This
|
|
addresses the threat of an undesired subject joining the cluster. In the
|
|
above example, this step would be to verify that the pod is allowed to
|
|
participate in the requested service.
|
|
|
|
If and only if these two requirements are met, the approver should approve
|
|
the CSR and otherwise should deny the CSR.
|
|
|
|
For more information on certificate approval and access control, read
|
|
the [Certificate Signing Requests](/docs/reference/access-authn-authz/certificate-signing-requests/)
|
|
reference page.
|
|
|
|
## Configuring your cluster to provide signing
|
|
|
|
This page assumes that a signer is set up to serve the certificates API. The
|
|
Kubernetes controller manager provides a default implementation of a signer. To
|
|
enable it, pass the `--cluster-signing-cert-file` and
|
|
`--cluster-signing-key-file` parameters to the controller manager with paths to
|
|
your Certificate Authority's keypair.
|
|
|