update with master content resolving merge conflicts
This commit is contained in:
MAKOSCAFEE
@@ -17,7 +17,7 @@ Client certificates generated by [kubeadm](/docs/reference/setup-tools/kubeadm/k
|
||||
|
||||
Be familiar with [PKI certificates and requirements in Kubernetes](/docs/setup/certificates/).
|
||||
|
||||
Have a working Kubernetes cluster installed using kubeadm with your certificates stored in `/etc/kubernetes/pki` folder; in case you are using a different location, the following can be adapted accordingly.
|
||||
You should be familiar with [PKI certificates and requirements in Kubernetes](/docs/setup/best-practices/certificates/).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
@@ -89,7 +89,7 @@ If you are running an HA cluster, this command needs to be executed on all the c
|
||||
|
||||
`kubeadm alpha certs renew` provides the following options:
|
||||
|
||||
- `--use-api` allows you to use the Kubernetes certificates API for signing certificates (instead of the local CA/front-proxy-CA); see next paragraphs for more information.
|
||||
The Kubernetes certificates normally reach their expiration date after one year.
|
||||
|
||||
- `--csr-only` can be used to renew certificats with an external CA by generating certificate signing requests (without actually renewing certificates in place); see next paragraph for more information.
|
||||
|
||||
@@ -105,8 +105,10 @@ These are advanced topics for users who need to integrate their organization's c
|
||||
|
||||
### Set up a signer
|
||||
|
||||
The Kubernetes Certificate Authority does not work out of the box.
|
||||
You can configure an external signer such as [cert-manager][cert-manager-issuer], or you can use the build-in signer.
|
||||
The Kubernetes Certificate Authority does not work out of the box.
|
||||
You can configure an external signer such as [cert-manager][cert-manager-issuer], or you can use the build-in signer.
|
||||
The built-in signer is part of [`kube-controller-manager`][kcm].
|
||||
To activate the build-in signer, you pass the `--cluster-signing-cert-file` and `--cluster-signing-key-file` arguments.
|
||||
|
||||
The built-in signer is part of [`kube-controller-manager`][kcm].
|
||||
|
||||
@@ -131,7 +133,9 @@ If you're creating a new cluster, you can use a kubeadm [configuration file][con
|
||||
|
||||
You can create the certificate signing requests for the Kubernetes certificates API with `kubeadm alpha certs renew --use-api`.
|
||||
|
||||
The command outputs the name of the certificate to approve, then blocks and waits for approval to occur. e.g.:
|
||||
If you set up an external signer such as [cert-manager][cert-manager], certificate signing requests (CSRs) are automatically approved.
|
||||
Otherwise, you must manually approve certificates with the [`kubectl certificate`][certs] command.
|
||||
The following kubeadm command outputs the name of the certificate to approve, then blocks and waits for approval to occur:
|
||||
|
||||
```shell
|
||||
sudo kubeadm alpha certs renew apiserver --use-api &
|
||||
@@ -162,13 +166,15 @@ You can view a list of pending certificates with `kubectl get csr`.
|
||||
|
||||
This section provide more details about how to execute manual certificate renewal using an external CA.
|
||||
|
||||
{{< caution >}}
|
||||
These are advanced topics for users who need to integrate their organization's certificate infrastructure into a kubeadm-built cluster. If the default kubeadm configuration satisfies your needs, you should let kubeadm manage certificates instead.
|
||||
{{< /caution >}}
|
||||
To better integrate with external CAs, kubeadm can also produce certificate signing requests (CSRs).
|
||||
A CSR represents a request to a CA for a signed certificate for a client.
|
||||
In kubeadm terms, any certificate that would normally be signed by an on-disk CA can be produced as a CSR instead. A CA, however, cannot be produced as a CSR.
|
||||
|
||||
### Create certificate signing requests (CSR)
|
||||
|
||||
To better integrate with external CAs, kubeadm can produce certificate signing requests (CSRs).
|
||||
You can pass in a directory with `--csr-dir` to output the CSRs to the specified location.
|
||||
If `--csr-dir` is not specified, the default certificate directory (`/etc/kubernetes/pki`) is used.
|
||||
Both the CSR and the accompanying private key are given in the output. After a certificate is signed, the certificate and the private key must be copied to the PKI directory (by default `/etc/kubernetes/pki`).
|
||||
|
||||
A CSR represents a request to a CA for a signed certificate for a client.
|
||||
|
||||
@@ -176,10 +182,13 @@ You can create certificate signing requests with `kubeadm alpha certs renew --cs
|
||||
|
||||
Both the CSR and the accompanying private key are given in the output; you can pass in a directory with `--csr-dir` to output the CSRs to the specified location.
|
||||
|
||||
### Renew certificates
|
||||
Certificates can be renewed with `kubeadm alpha certs renew --csr-only`.
|
||||
As with `kubeadm init`, an output directory can be specified with the `--csr-dir` flag.
|
||||
To use the new certificates, copy the signed certificate and private key into the PKI directory (by default `/etc/kubernetes/pki`)
|
||||
|
||||
A CSR contains a certificate's name, domain(s), and IPs, but it does not specify usages.
|
||||
|
||||
A CSR contains a certificate's name, domains, and IPs, but it does not specify usages.
|
||||
It is the responsibility of the CA to specify [the correct cert usages][cert-table] when issuing a certificate.
|
||||
|
||||
* In `openssl` this is done with the [`openssl ca` command][openssl-ca].
|
||||
@@ -189,11 +198,8 @@ After a certificate is signed using your preferred method, the certificate and t
|
||||
|
||||
[openssl-ca]: https://superuser.com/questions/738612/openssl-ca-keyusage-extension
|
||||
[cfssl-usages]: https://github.com/cloudflare/cfssl/blob/master/doc/cmd/cfssl.txt#L170
|
||||
[certs]: /docs/setup/certificates
|
||||
[cert-cas]: /docs/setup/certificates/#single-root-ca
|
||||
[cert-table]: /docs/setup/certificates/#all-certificates
|
||||
[manage-tls]: /docs/tasks/tls/managing-tls-in-a-cluster/
|
||||
[cert-manager]: https://github.com/jetstack/cert-manager
|
||||
[certs]: /docs/reference/generated/kubectl/kubectl-commands#certificate
|
||||
[certs]: /docs/setup/best-practices/certificates/
|
||||
[cert-cas]: /docs/setup/best-practices/certificates/#single-root-ca
|
||||
[cert-table]: /docs/setup/best-practices/certificates/#all-certificates
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
@@ -0,0 +1,205 @@
|
||||
---
|
||||
reviewers:
|
||||
- sig-cluster-lifecycle
|
||||
title: Certificate Management with kubeadm
|
||||
content_template: templates/task
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
{{< feature-state for_k8s_version="v1.15" state="stable" >}}
|
||||
|
||||
Client certificates generated by [kubeadm](/docs/reference/setup-tools/kubeadm/kubeadm/) expire after 1 year. This page explains how to manage certificate renewals with kubeadm.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
|
||||
Be familiar with [PKI certificates and requirements in Kubernetes](/docs/setup/certificates/).
|
||||
|
||||
You should be familiar with [PKI certificates and requirements in Kubernetes](/docs/setup/best-practices/certificates/).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
|
||||
## Check certificate expiration
|
||||
|
||||
`check-expiration` can be used to check certificate expiration.
|
||||
|
||||
```
|
||||
kubeadm alpha certs check-expiration
|
||||
```
|
||||
|
||||
The output is similar to this:
|
||||
|
||||
```
|
||||
CERTIFICATE EXPIRES RESIDUAL TIME EXTERNALLY MANAGED
|
||||
admin.conf May 15, 2020 13:03 UTC 364d false
|
||||
apiserver May 15, 2020 13:00 UTC 364d false
|
||||
apiserver-etcd-client May 15, 2020 13:00 UTC 364d false
|
||||
apiserver-kubelet-client May 15, 2020 13:00 UTC 364d false
|
||||
controller-manager.conf May 15, 2020 13:03 UTC 364d false
|
||||
etcd-healthcheck-client May 15, 2020 13:00 UTC 364d false
|
||||
etcd-peer May 15, 2020 13:00 UTC 364d false
|
||||
etcd-server May 15, 2020 13:00 UTC 364d false
|
||||
front-proxy-client May 15, 2020 13:00 UTC 364d false
|
||||
scheduler.conf May 15, 2020 13:03 UTC 364d false
|
||||
```
|
||||
|
||||
The command shows expiration/residual time for the client certificates in the `/etc/kubernetes/pki` folder and for the client certificate embedded in the KUBECONFIG files used by kubeadm (`admin.conf`, `controller-manager.conf` and `scheduler.conf`).
|
||||
|
||||
Additionally, kubeadm informs the user if the certificate is externally managed; in this case, the user should take care of managing certificate renewal manually/using other tools.
|
||||
|
||||
{{< warning >}}
|
||||
`kubeadm` cannot manage certificates signed by an external CA.
|
||||
{{< /warning >}}
|
||||
|
||||
{{< note >}}
|
||||
`kubelet.conf` is not included in the list above because kubeadm configures kubelet for automatic certificate renewal.
|
||||
{{< /note >}}
|
||||
|
||||
## Automatic certificate renewal
|
||||
|
||||
`kubeadm` renews all the certificates during control plane [upgrade](/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade-1-15/).
|
||||
|
||||
This feature is designed for addressing the simplest use cases;
|
||||
if you don't have specific requirements on certificate renewal and perform Kubernetes version upgrades regularly (less than 1 year in between each upgrade), kubeadm will take care of keeping your cluster up to date and reasonably secure.
|
||||
|
||||
{{< note >}}
|
||||
It is a best practice to upgrade your cluster frequently in order to stay secure.
|
||||
{{< /note >}}
|
||||
|
||||
If you have more complex requirements for certificate renewal, you can opt out from the default behavior by passing `--certificate-renewal=false` to `kubeadm upgrade apply` or to `kubeadm upgrade node`.
|
||||
|
||||
|
||||
## Manual certificate renewal
|
||||
|
||||
You can renew your certificates manually at any time with the `kubeadm alpha certs renew` command.
|
||||
|
||||
This command performs the renewal using CA (or front-proxy-CA) certificate and key stored in `/etc/kubernetes/pki`.
|
||||
|
||||
{{< warning >}}
|
||||
If you are running an HA cluster, this command needs to be executed on all the control-plane nodes.
|
||||
{{< /warning >}}
|
||||
|
||||
{{< note >}}
|
||||
`alpha certs renew` uses the existing certificates as the authoritative source for attributes (Common Name, Organization, SAN, etc.) instead of the kubeadm-config ConfigMap. It is strongly recommended to keep them both in sync.
|
||||
{{< /note >}}
|
||||
|
||||
`kubeadm alpha certs renew` provides the following options:
|
||||
|
||||
The Kubernetes certificates normally reach their expiration date after one year.
|
||||
|
||||
- `--csr-only` can be used to renew certificats with an external CA by generating certificate signing requests (without actually renewing certificates in place); see next paragraph for more information.
|
||||
|
||||
- It's also possible to renew a single certificate instead of all.
|
||||
|
||||
## Renew certificates with the Kubernetes certificates API
|
||||
|
||||
This section provide more details about how to execute manual certificate renewal using the Kubernetes certificates API.
|
||||
|
||||
{{< caution >}}
|
||||
These are advanced topics for users who need to integrate their organization's certificate infrastructure into a kubeadm-built cluster. If the default kubeadm configuration satisfies your needs, you should let kubeadm manage certificates instead.
|
||||
{{< /caution >}}
|
||||
|
||||
### Set up a signer
|
||||
|
||||
The Kubernetes Certificate Authority does not work out of the box.
|
||||
You can configure an external signer such as [cert-manager][cert-manager-issuer], or you can use the build-in signer.
|
||||
The built-in signer is part of [`kube-controller-manager`][kcm].
|
||||
To activate the build-in signer, you pass the `--cluster-signing-cert-file` and `--cluster-signing-key-file` arguments.
|
||||
|
||||
The built-in signer is part of [`kube-controller-manager`][kcm].
|
||||
|
||||
To activate the build-in signer, you must pass the `--cluster-signing-cert-file` and `--cluster-signing-key-file` flags.
|
||||
|
||||
If you're creating a new cluster, you can use a kubeadm [configuration file][config]:
|
||||
|
||||
```yaml
|
||||
apiVersion: kubeadm.k8s.io/v1beta2
|
||||
kind: ClusterConfiguration
|
||||
controllerManager:
|
||||
extraArgs:
|
||||
cluster-signing-cert-file: /etc/kubernetes/pki/ca.crt
|
||||
cluster-signing-key-file: /etc/kubernetes/pki/ca.key
|
||||
```
|
||||
|
||||
[cert-manager-issuer]: https://cert-manager.readthedocs.io/en/latest/tutorials/ca/creating-ca-issuer.html
|
||||
[kcm]: /docs/reference/command-line-tools-reference/kube-controller-manager/
|
||||
[config]: https://godoc.org/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm/v1beta2
|
||||
|
||||
### Create certificate signing requests (CSR)
|
||||
|
||||
You can create the certificate signing requests for the Kubernetes certificates API with `kubeadm alpha certs renew --use-api`.
|
||||
|
||||
If you set up an external signer such as [cert-manager][cert-manager], certificate signing requests (CSRs) are automatically approved.
|
||||
Otherwise, you must manually approve certificates with the [`kubectl certificate`][certs] command.
|
||||
The following kubeadm command outputs the name of the certificate to approve, then blocks and waits for approval to occur:
|
||||
|
||||
```shell
|
||||
sudo kubeadm alpha certs renew apiserver --use-api &
|
||||
```
|
||||
The output is similar to this:
|
||||
```
|
||||
[1] 2890
|
||||
[certs] certificate request "kubeadm-cert-kube-apiserver-ld526" created
|
||||
```
|
||||
|
||||
### Approve certificate signing requests (CSR)
|
||||
|
||||
If you set up an external signer, certificate signing requests (CSRs) are automatically approved.
|
||||
|
||||
Otherwise, you must manually approve certificates with the [`kubectl certificate`][certs] command. e.g.
|
||||
|
||||
```shell
|
||||
kubectl certificate approve kubeadm-cert-kube-apiserver-ld526
|
||||
```
|
||||
The output is similar to this:
|
||||
```shell
|
||||
certificatesigningrequest.certificates.k8s.io/kubeadm-cert-kube-apiserver-ld526 approved
|
||||
```
|
||||
|
||||
You can view a list of pending certificates with `kubectl get csr`.
|
||||
|
||||
## Renew certificates with external CA
|
||||
|
||||
This section provide more details about how to execute manual certificate renewal using an external CA.
|
||||
|
||||
To better integrate with external CAs, kubeadm can also produce certificate signing requests (CSRs).
|
||||
A CSR represents a request to a CA for a signed certificate for a client.
|
||||
In kubeadm terms, any certificate that would normally be signed by an on-disk CA can be produced as a CSR instead. A CA, however, cannot be produced as a CSR.
|
||||
|
||||
### Create certificate signing requests (CSR)
|
||||
|
||||
You can pass in a directory with `--csr-dir` to output the CSRs to the specified location.
|
||||
If `--csr-dir` is not specified, the default certificate directory (`/etc/kubernetes/pki`) is used.
|
||||
Both the CSR and the accompanying private key are given in the output. After a certificate is signed, the certificate and the private key must be copied to the PKI directory (by default `/etc/kubernetes/pki`).
|
||||
|
||||
A CSR represents a request to a CA for a signed certificate for a client.
|
||||
|
||||
You can create certificate signing requests with `kubeadm alpha certs renew --csr-only`.
|
||||
|
||||
Both the CSR and the accompanying private key are given in the output; you can pass in a directory with `--csr-dir` to output the CSRs to the specified location.
|
||||
|
||||
Certificates can be renewed with `kubeadm alpha certs renew --csr-only`.
|
||||
As with `kubeadm init`, an output directory can be specified with the `--csr-dir` flag.
|
||||
To use the new certificates, copy the signed certificate and private key into the PKI directory (by default `/etc/kubernetes/pki`)
|
||||
|
||||
A CSR contains a certificate's name, domain(s), and IPs, but it does not specify usages.
|
||||
|
||||
A CSR contains a certificate's name, domains, and IPs, but it does not specify usages.
|
||||
It is the responsibility of the CA to specify [the correct cert usages][cert-table] when issuing a certificate.
|
||||
|
||||
* In `openssl` this is done with the [`openssl ca` command][openssl-ca].
|
||||
* In `cfssl` you specify [usages in the config file][cfssl-usages]
|
||||
|
||||
After a certificate is signed using your preferred method, the certificate and the private key must be copied to the PKI directory (by default `/etc/kubernetes/pki`).
|
||||
|
||||
[openssl-ca]: https://superuser.com/questions/738612/openssl-ca-keyusage-extension
|
||||
[cfssl-usages]: https://github.com/cloudflare/cfssl/blob/master/doc/cmd/cfssl.txt#L170
|
||||
[certs]: /docs/setup/best-practices/certificates/
|
||||
[cert-cas]: /docs/setup/best-practices/certificates/#single-root-ca
|
||||
[cert-table]: /docs/setup/best-practices/certificates/#all-certificates
|
||||
|
||||
{{% /capture %}}
|
||||
@@ -285,8 +285,10 @@ A possible workaround is described [here](https://github.com/kubernetes/kubeadm/
|
||||
{{< tabs name="k8s_kubelet_and_kubeadm" >}}
|
||||
{{% tab name="Ubuntu, Debian or HypriotOS" %}}
|
||||
# replace x in 1.13.x-00 with the latest patch version
|
||||
apt-mark unhold kubelet kubeadm
|
||||
apt-get update
|
||||
apt-get install -y kubelet=1.13.x-00 kubeadm=1.13.x-00
|
||||
apt-mark hold kubelet kubeadm
|
||||
{{% /tab %}}
|
||||
{{% tab name="CentOS, RHEL or Fedora" %}}
|
||||
# replace x in 1.13.x-0 with the latest patch version
|
||||
|
||||
@@ -228,9 +228,9 @@ are merged into a single document.
|
||||
{{< tabs name="k8s_install_kubelet" >}}
|
||||
{{% tab name="Ubuntu, Debian or HypriotOS" %}}
|
||||
# replace x in 1.14.x-00 with the latest patch version
|
||||
apt-mark unhold kubelet && \
|
||||
apt-mark unhold kubelet kubectl && \
|
||||
apt-get update && apt-get install -y kubelet=1.14.x-00 kubectl=1.14.x-00 && \
|
||||
apt-mark hold kubelet
|
||||
apt-mark hold kubelet kubectl
|
||||
{{% /tab %}}
|
||||
{{% tab name="CentOS, RHEL or Fedora" %}}
|
||||
# replace x in 1.14.x-0 with the latest patch version
|
||||
@@ -260,7 +260,7 @@ sudo kubeadm upgrade apply
|
||||
|
||||
Also `sudo kubeadm upgrade plan` is not needed.
|
||||
|
||||
## Ugrade worker nodes
|
||||
## Upgrade worker nodes
|
||||
|
||||
The upgrade procedure on worker nodes should be executed one node at a time or few nodes at a time,
|
||||
without compromising the minimum required capacity for running your workloads.
|
||||
@@ -290,16 +290,12 @@ without compromising the minimum required capacity for running your workloads.
|
||||
kubectl drain $NODE --ignore-daemonsets
|
||||
```
|
||||
|
||||
You should see output similar to this:
|
||||
You should see output similar to this:
|
||||
|
||||
```shell
|
||||
kubectl drain ip-172-31-85-18
|
||||
node "ip-172-31-85-18" cordoned
|
||||
error: unable to drain node "ip-172-31-85-18", aborting command...
|
||||
|
||||
There are pending nodes to be drained:
|
||||
ip-172-31-85-18
|
||||
error: DaemonSet-managed pods (use --ignore-daemonsets to ignore): calico-node-5798d, kube-proxy-thjp9
|
||||
node/ip-172-31-85-18 cordoned
|
||||
WARNING: ignoring DaemonSet-managed Pods: kube-system/kube-proxy-dj7d7, kube-system/weave-net-z65qx
|
||||
node/ip-172-31-85-18 drained
|
||||
```
|
||||
|
||||
### Upgrade the kubelet config
|
||||
|
||||
@@ -9,7 +9,7 @@ content_template: templates/task
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
This page explains how to upgrade a highly available (HA) Kubernetes cluster created with `kubeadm` from version 1.12.x to version 1.13.y. In addition to upgrading, you must also follow the instructions in [Creating HA clusters with kubeadm](/docs/setup/independent/high-availability/).
|
||||
This page explains how to upgrade a highly available (HA) Kubernetes cluster created with `kubeadm` from version 1.12.x to version 1.13.y. In addition to upgrading, you must also follow the instructions in [Creating HA clusters with kubeadm](/docs/setup/production-environment/tools/kubeadm/high-availability/).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user