Remove mentions of cluster CA from CSR API docs (#15547)

CSR API isn't guaranteed to use the cluster CA. The CA used to sign
certs using the CSR API depends on the specific cluster stup. Admins can
use a separate CA if they choose to.

Users shouldn't rely on verifying those certs using the CA bundle
mounted with service account secrets.

The doc page is reworded to remove most mentions of cluster CA and
instead focus on API usage specifics.
This commit is contained in:
Andrew Lytvynov
2019-08-04 17:55:48 -07:00
committed by Kubernetes Prow Robot
parent a5cfbae3d9
commit 9fbd001d5c
@@ -9,15 +9,19 @@ reviewers:
{{% capture overview %}} {{% capture overview %}}
Every Kubernetes cluster has a cluster root Certificate Authority (CA). The CA Kubernetes provides a `certificates.k8s.io` API, which lets you provision TLS
is generally used by cluster components to validate the API server's certificates signed by a Certificate Authority (CA) that you control. These CA
certificate, by the API server to validate kubelet client certificates, etc. To and certificates can be used by your workloads to establish trust.
support this, the CA certificate bundle is distributed to every node in the
cluster and is distributed as a secret attached to default service accounts. `certificates.k8s.io` API uses a protocol that is similar to the [ACME
Optionally, your workloads can use this CA to establish trust. Your application draft](https://github.com/ietf-wg-acme/acme/).
can request a certificate signing using the `certificates.k8s.io` API using a
protocol that is similar to the {{< note >}}
[ACME draft](https://github.com/ietf-wg-acme/acme/). Certificates created using the `certificates.k8s.io` API are signed by a
dedicated CA. 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 >}}
{{% /capture %}} {{% /capture %}}
@@ -32,17 +36,16 @@ protocol that is similar to the
## Trusting TLS in a Cluster ## Trusting TLS in a Cluster
Trusting the cluster root CA from an application running as a pod usually Trusting the custom CA from an application running as a pod usually requires
requires some extra application configuration. You will need to add the CA some extra application configuration. You will need to add the CA certificate
certificate bundle to the list of CA certificates that the TLS client or server bundle to the list of CA certificates that the TLS client or server trusts. For
trusts. For example, you would do this with a golang TLS config by parsing the example, you would do this with a golang TLS config by parsing the certificate
certificate chain and adding the parsed certificates to the `RootCAs` field chain and adding the parsed certificates to the `RootCAs` field in the
in the [`tls.Config`](https://godoc.org/crypto/tls#Config) struct. [`tls.Config`](https://godoc.org/crypto/tls#Config) struct.
The CA certificate bundle is automatically mounted into pods using the default You can distribute the CA certificate as a
service account at the path `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`. [ConfigMap](/docs/tasks/configure-pod-container/configure-pod-config) that your
If you are not using the default service account, ask a cluster administrator to pods have access to use.
build a configmap containing the certificate bundle that you have access to use.
## Requesting a Certificate ## Requesting a Certificate
@@ -205,13 +208,11 @@ the CSR and otherwise should deny the CSR.
## A Word of Warning on the Approval Permission ## A Word of Warning on the Approval Permission
The ability to approve CSRs decides who trusts who within the cluster. This The ability to approve CSRs decides who trusts who within your environment. The
includes who the Kubernetes API trusts. The ability to approve CSRs should ability to approve CSRs should not be granted broadly or lightly. The
not be granted broadly or lightly. The requirements of the challenge requirements of the challenge noted in the previous section and the
noted in the previous section and the repercussions of issuing a specific repercussions of issuing a specific certificate should be fully understood
certificate should be fully understood before granting this permission. See before granting this permission.
[here](/docs/reference/access-authn-authz/authentication/#x509-client-certs) for information on how
certificates interact with authentication.
## A Note to Cluster Administrators ## A Note to Cluster Administrators