mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-26 13:08:11 +00:00
Merge branch 'master' into rke-macports
This commit is contained in:
Catherine Luse
@@ -12,9 +12,9 @@ Certificates are an important part of Kubernetes clusters and are used for all K
|
||||
|
||||
## Generating Certificate Signing Requests (CSRs) and Keys
|
||||
|
||||
If you want to create and sign the certificates by a real Certificate Authority (CA), you can use RKE to [generate a set of Certificate Signing Requests (CSRs) and keys]({{< baseurl >}}/rke/latest/en/installation/certs/#generating-certificate-signing-requests-csrs-and-keys).
|
||||
If you want to create and sign the certificates by a real Certificate Authority (CA), you can use RKE to [generate a set of Certificate Signing Requests (CSRs) and keys]({{<baseurl>}}/rke/latest/en/installation/certs/#generating-certificate-signing-requests-csrs-and-keys).
|
||||
|
||||
You can use the CSRs and keys to sign the certificates by a real CA. After the certificates are signed, these custom certificates can be used by RKE to as [custom certificates]({{< baseurl >}}/rke/latest/en/installation/certs/) for the Kubernetes cluster.
|
||||
You can use the CSRs and keys to sign the certificates by a real CA. After the certificates are signed, these custom certificates can be used by RKE to as [custom certificates]({{<baseurl>}}/rke/latest/en/installation/certs/) for the Kubernetes cluster.
|
||||
|
||||
## Certificate Rotation
|
||||
|
||||
|
||||
@@ -6,35 +6,35 @@ weight: 200
|
||||
|
||||
When setting up your `cluster.yml` for RKE, there are a lot of different options that can be configured to control the behavior of how RKE launches Kubernetes.
|
||||
|
||||
There are several options that can be configured in cluster configuration option. There are several [example yamls]({{< baseurl >}}/rke/latest/en/example-yamls/) that contain all the options.
|
||||
There are several options that can be configured in cluster configuration option. There are several [example yamls]({{<baseurl>}}/rke/latest/en/example-yamls/) that contain all the options.
|
||||
|
||||
### Configuring Nodes
|
||||
* [Nodes]({{< baseurl >}}/rke/latest/en/config-options/nodes/)
|
||||
* [Nodes]({{<baseurl>}}/rke/latest/en/config-options/nodes/)
|
||||
* [Ignoring unsupported Docker versions](#supported-docker-versions)
|
||||
* [Private Registries]({{< baseurl >}}/rke/latest/en/config-options/private-registries/)
|
||||
* [Private Registries]({{<baseurl>}}/rke/latest/en/config-options/private-registries/)
|
||||
* [Cluster Level SSH Key Path](#cluster-level-ssh-key-path)
|
||||
* [SSH Agent](#ssh-agent)
|
||||
* [Bastion Host]({{< baseurl >}}/rke/latest/en/config-options/bastion-host/)
|
||||
* [Bastion Host]({{<baseurl>}}/rke/latest/en/config-options/bastion-host/)
|
||||
|
||||
### Configuring Kubernetes Cluster
|
||||
* [Cluster Name](#cluster-name)
|
||||
* [Kubernetes Version](#kubernetes-version)
|
||||
* [Prefix Path](#prefix-path)
|
||||
* [System Images]({{< baseurl >}}/rke/latest/en/config-options/system-images/)
|
||||
* [Services]({{< baseurl >}}/rke/latest/en/config-options/services/)
|
||||
* [Extra Args and Binds and Environment Variables]({{< baseurl >}}/rke/latest/en/config-options/services/services-extras/)
|
||||
* [External Etcd]({{< baseurl >}}/rke/latest/en/config-options/services/external-etcd/)
|
||||
* [Authentication]({{< baseurl >}}/rke/latest/en/config-options/authentication/)
|
||||
* [Authorization]({{< baseurl >}}/rke/latest/en/config-options/authorization/)
|
||||
* [System Images]({{<baseurl>}}/rke/latest/en/config-options/system-images/)
|
||||
* [Services]({{<baseurl>}}/rke/latest/en/config-options/services/)
|
||||
* [Extra Args and Binds and Environment Variables]({{<baseurl>}}/rke/latest/en/config-options/services/services-extras/)
|
||||
* [External Etcd]({{<baseurl>}}/rke/latest/en/config-options/services/external-etcd/)
|
||||
* [Authentication]({{<baseurl>}}/rke/latest/en/config-options/authentication/)
|
||||
* [Authorization]({{<baseurl>}}/rke/latest/en/config-options/authorization/)
|
||||
* [Rate Limiting]({{<baseurl>}}/rke/latest/en/config-options/rate-limiting/)
|
||||
* [Cloud Providers]({{< baseurl >}}/rke/latest/en/config-options/cloud-providers/)
|
||||
* [Cloud Providers]({{<baseurl>}}/rke/latest/en/config-options/cloud-providers/)
|
||||
* [Audit Log]({{<baseurl>}}/rke/latest/en/config-options/audit-log)
|
||||
* [Add-ons]({{< baseurl >}}/rke/latest/en/config-options/add-ons/)
|
||||
* [Network Plug-ins]({{< baseurl >}}/rke/latest/en/config-options/add-ons/network-plugins/)
|
||||
* [DNS providers]({{< baseurl >}}/rke/latest/en/config-options/add-ons/dns/)
|
||||
* [Ingress Controllers]({{< baseurl >}}/rke/latest/en/config-options/add-ons/ingress-controllers/)
|
||||
* [Metrics Server]({{< baseurl >}}/rke/latest/en/config-options/add-ons/metrics-server/)
|
||||
* [User-Defined Add-ons]({{< baseurl >}}/rke/latest/en/config-options/add-ons/user-defined-add-ons/)
|
||||
* [Add-ons]({{<baseurl>}}/rke/latest/en/config-options/add-ons/)
|
||||
* [Network Plug-ins]({{<baseurl>}}/rke/latest/en/config-options/add-ons/network-plugins/)
|
||||
* [DNS providers]({{<baseurl>}}/rke/latest/en/config-options/add-ons/dns/)
|
||||
* [Ingress Controllers]({{<baseurl>}}/rke/latest/en/config-options/add-ons/ingress-controllers/)
|
||||
* [Metrics Server]({{<baseurl>}}/rke/latest/en/config-options/add-ons/metrics-server/)
|
||||
* [User-Defined Add-ons]({{<baseurl>}}/rke/latest/en/config-options/add-ons/user-defined-add-ons/)
|
||||
* [Add-ons Job Timeout](#add-ons-job-timeout)
|
||||
|
||||
|
||||
@@ -79,7 +79,7 @@ prefix_path: /opt/custom_path
|
||||
|
||||
### Cluster Level SSH Key Path
|
||||
|
||||
RKE connects to host(s) using `ssh`. Typically, each node will have an independent path for each ssh key, i.e. `ssh_key_path`, in the `nodes` section, but if you have a SSH key that is able to access **all** hosts in your cluster configuration file, you can set the path to that ssh key at the top level. Otherwise, you would set the ssh key path in the [nodes]({{< baseurl >}}/rke/latest/en/config-options/nodes/).
|
||||
RKE connects to host(s) using `ssh`. Typically, each node will have an independent path for each ssh key, i.e. `ssh_key_path`, in the `nodes` section, but if you have a SSH key that is able to access **all** hosts in your cluster configuration file, you can set the path to that ssh key at the top level. Otherwise, you would set the ssh key path in the [nodes]({{<baseurl>}}/rke/latest/en/config-options/nodes/).
|
||||
|
||||
If ssh key paths are defined at the cluster level and at the node level, the node-level key will take precedence.
|
||||
|
||||
@@ -109,4 +109,4 @@ $ echo $SSH_AUTH_SOCK
|
||||
|
||||
### Add-ons Job Timeout
|
||||
|
||||
You can define [add-ons]({{< baseurl >}}/rke/latest/en/config-options/add-ons/) to be deployed after the Kubernetes cluster comes up, which uses Kubernetes [jobs](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/). RKE will stop attempting to retrieve the job status after the timeout, which is in seconds. The default timeout value is `30` seconds.
|
||||
You can define [add-ons]({{<baseurl>}}/rke/latest/en/config-options/add-ons/) to be deployed after the Kubernetes cluster comes up, which uses Kubernetes [jobs](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/). RKE will stop attempting to retrieve the job status after the timeout, which is in seconds. The default timeout value is `30` seconds.
|
||||
|
||||
@@ -5,12 +5,12 @@ weight: 260
|
||||
|
||||
RKE supports configuring pluggable add-ons in the cluster YML. Add-ons are used to deploy several cluster components including:
|
||||
|
||||
* [Network plug-ins]({{< baseurl >}}/rke/latest/en/config-options/add-ons/network-plugins/)
|
||||
* [Ingress controller]({{< baseurl >}}/rke/latest/en/config-options/add-ons/ingress-controllers/)
|
||||
* [DNS provider]({{< baseurl >}}/rke/latest/en/config-options/add-ons/dns/)
|
||||
* [Metrics Server]({{< baseurl >}}/rke/latest/en/config-options/add-ons/metrics-server/)
|
||||
* [Network plug-ins]({{<baseurl>}}/rke/latest/en/config-options/add-ons/network-plugins/)
|
||||
* [Ingress controller]({{<baseurl>}}/rke/latest/en/config-options/add-ons/ingress-controllers/)
|
||||
* [DNS provider]({{<baseurl>}}/rke/latest/en/config-options/add-ons/dns/)
|
||||
* [Metrics Server]({{<baseurl>}}/rke/latest/en/config-options/add-ons/metrics-server/)
|
||||
|
||||
These add-ons require images that can be found under the [`system_images` directive]({{< baseurl >}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there are default images associated with each add-on, but these can be overridden by changing the image tag in `system_images`.
|
||||
These add-ons require images that can be found under the [`system_images` directive]({{<baseurl>}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there are default images associated with each add-on, but these can be overridden by changing the image tag in `system_images`.
|
||||
|
||||
There are a few things worth noting:
|
||||
|
||||
@@ -25,7 +25,7 @@ As of version v0.1.7, add-ons are split into two categories:
|
||||
- **Critical add-ons:** If these add-ons fail to deploy for any reason, RKE will error out.
|
||||
- **Non-critical add-ons:** If these add-ons fail to deploy, RKE will only log a warning and continue deploying any other add-ons.
|
||||
|
||||
Currently, only the [network plug-in]({{< baseurl >}}/rke/latest/en/config-options/add-ons/network-plugins/) is considered critical. KubeDNS, [ingress controllers]({{< baseurl >}}/rke/latest/en/config-options/add-ons/ingress-controllers/) and [user-defined add-ons]({{< baseurl >}}/rke/latest/en/config-options/add-ons/user-defined-add-ons/) are considered non-critical.
|
||||
Currently, only the [network plug-in]({{<baseurl>}}/rke/latest/en/config-options/add-ons/network-plugins/) is considered critical. KubeDNS, [ingress controllers]({{<baseurl>}}/rke/latest/en/config-options/add-ons/ingress-controllers/) and [user-defined add-ons]({{<baseurl>}}/rke/latest/en/config-options/add-ons/user-defined-add-ons/) are considered non-critical.
|
||||
|
||||
## Add-on deployment jobs
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ CoreDNS can only be used on Kubernetes v1.12.0 and higher.
|
||||
|
||||
RKE will deploy CoreDNS as a Deployment with the default replica count of 1. The pod consists of 1 container: `coredns`. RKE will also deploy coredns-autoscaler as a Deployment, which will scale the coredns Deployment by using the number of cores and nodes. Please see [Linear Mode](https://github.com/kubernetes-incubator/cluster-proportional-autoscaler#linear-mode) for more information about this logic.
|
||||
|
||||
The images used for CoreDNS are under the [`system_images` directive]({{< baseurl >}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there are default images associated with CoreDNS, but these can be overridden by changing the image tag in `system_images`.
|
||||
The images used for CoreDNS are under the [`system_images` directive]({{<baseurl>}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there are default images associated with CoreDNS, but these can be overridden by changing the image tag in `system_images`.
|
||||
|
||||
## Scheduling CoreDNS
|
||||
|
||||
@@ -66,7 +66,7 @@ dns:
|
||||
|
||||
RKE will deploy kube-dns as a Deployment with the default replica count of 1. The pod consists of 3 containers: `kubedns`, `dnsmasq` and `sidecar`. RKE will also deploy kube-dns-autoscaler as a Deployment, which will scale the kube-dns Deployment by using the number of cores and nodes. Please see [Linear Mode](https://github.com/kubernetes-incubator/cluster-proportional-autoscaler#linear-mode) for more information about this logic.
|
||||
|
||||
The images used for kube-dns are under the [`system_images` directive]({{< baseurl >}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there are default images associated with kube-dns, but these can be overridden by changing the image tag in `system_images`.
|
||||
The images used for kube-dns are under the [`system_images` directive]({{<baseurl>}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there are default images associated with kube-dns, but these can be overridden by changing the image tag in `system_images`.
|
||||
|
||||
## Scheduling kube-dns
|
||||
|
||||
@@ -116,3 +116,36 @@ You can disable the default DNS provider by specifying `none` to the dns `provi
|
||||
dns:
|
||||
provider: none
|
||||
```
|
||||
|
||||
# NodeLocal DNS
|
||||
|
||||
_Available as of v1.1.0_
|
||||
|
||||
> **Note:** The option to enable NodeLocal DNS is available for:
|
||||
>
|
||||
> * Kubernetes v1.15.11 and up
|
||||
> * Kubernetes v1.16.8 and up
|
||||
> * Kubernetes v1.17.4 and up
|
||||
|
||||
NodeLocal DNS is an additional component that can be deployed on each node to improve DNS performance. It is not a replacement for the `provider` parameter, you will still need to have one of the available DNS providers configured. See [Using NodeLocal DNSCache in Kubernetes clusters](https://kubernetes.io/docs/tasks/administer-cluster/nodelocaldns/) for more information on how NodeLocal DNS works.
|
||||
|
||||
Enable NodeLocal DNS by configuring an IP address.
|
||||
|
||||
## Configuring NodeLocal DNS
|
||||
|
||||
The `ip_address` parameter is used to configure what link-local IP address will be configured one each host to listen on, make sure this IP address is not already configured on the host.
|
||||
|
||||
```yaml
|
||||
dns:
|
||||
provider: coredns
|
||||
nodelocal:
|
||||
ip_address: "169.254.20.10"
|
||||
```
|
||||
|
||||
> **Note:** When enabling NodeLocal DNS on an existing cluster, pods that are currently running will not be modified, the updated `/etc/resolv.conf` configuration will take effect only for pods started after enabling NodeLocal DNS.
|
||||
|
||||
## Removing NodeLocal DNS
|
||||
|
||||
By removing the `ip_address` value, NodeLocal DNS will be removed from the cluster.
|
||||
|
||||
> **Warning:** When removing NodeLocal DNS, a disruption to DNS can be expected. The updated `/etc/resolv.conf` configuration will take effect only for pods that are started after removing NodeLocal DNS. In general pods using the default `dnsPolicy: ClusterFirst` will need to be re-deployed.
|
||||
|
||||
@@ -10,7 +10,7 @@ By default, RKE deploys the NGINX ingress controller on all schedulable nodes.
|
||||
|
||||
RKE will deploy the ingress controller as a DaemonSet with `hostnetwork: true`, so ports `80`, and `443` will be opened on each node where the controller is deployed.
|
||||
|
||||
The images used for ingress controller is under the [`system_images` directive]({{< baseurl >}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there are default images associated with the ingress controller, but these can be overridden by changing the image tag in `system_images`.
|
||||
The images used for ingress controller is under the [`system_images` directive]({{<baseurl>}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there are default images associated with the ingress controller, but these can be overridden by changing the image tag in `system_images`.
|
||||
|
||||
## Scheduling Ingress Controllers
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ By default, RKE deploys [Metrics Server](https://github.com/kubernetes-incubator
|
||||
|
||||
RKE will deploy Metrics Server as a Deployment.
|
||||
|
||||
The image used for Metrics Server is under the [`system_images` directive]({{< baseurl >}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there is a default image associated with the Metrics Server, but these can be overridden by changing the image tag in `system_images`.
|
||||
The image used for Metrics Server is under the [`system_images` directive]({{<baseurl>}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there is a default image associated with the Metrics Server, but these can be overridden by changing the image tag in `system_images`.
|
||||
|
||||
## Disabling the Metrics Server
|
||||
|
||||
|
||||
@@ -20,7 +20,7 @@ network:
|
||||
plugin: flannel
|
||||
```
|
||||
|
||||
The images used for network plug-ins are under the [`system_images` directive]({{< baseurl >}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there are default images associated with each network plug-in, but these can be overridden by changing the image tag in `system_images`.
|
||||
The images used for network plug-ins are under the [`system_images` directive]({{<baseurl>}}/rke/latest/en/config-options/system-images/). For each Kubernetes version, there are default images associated with each network plug-in, but these can be overridden by changing the image tag in `system_images`.
|
||||
|
||||
# Disabling Deployment of a Network Plug-in
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ title: User-Defined Add-Ons
|
||||
weight: 263
|
||||
---
|
||||
|
||||
Besides the [network plug-in]({{< baseurl >}}/rke/latest/en/config-options/add-ons/network-plugins) and [ingress controllers]({{< baseurl >}}/rke/latest/en/config-options/add-ons/ingress-controllers/), you can define any add-on that you want deployed after the Kubernetes cluster is deployed.
|
||||
Besides the [network plug-in]({{<baseurl>}}/rke/latest/en/config-options/add-ons/network-plugins) and [ingress controllers]({{<baseurl>}}/rke/latest/en/config-options/add-ons/ingress-controllers/), you can define any add-on that you want deployed after the Kubernetes cluster is deployed.
|
||||
|
||||
There are two ways that you can specify an add-on.
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ title: Bastion/Jump Host Configuration
|
||||
weight: 220
|
||||
---
|
||||
|
||||
Since RKE uses `ssh` to connect to [nodes]({{< baseurl >}}/rke/latest/en/config-options/nodes/), you can configure the `cluster.yml` so RKE will use a bastion host. Keep in mind that the [port requirements]({{< baseurl >}}/rke/latest/en/os/#ports) for the RKE node move to the configured bastion host. Our private SSH key(s) only needs to reside on the host running RKE. You do not need to copy your private SSH key(s) to the bastion host.
|
||||
Since RKE uses `ssh` to connect to [nodes]({{<baseurl>}}/rke/latest/en/config-options/nodes/), you can configure the `cluster.yml` so RKE will use a bastion host. Keep in mind that the [port requirements]({{<baseurl>}}/rke/latest/en/os/#ports) for the RKE node move to the configured bastion host. Our private SSH key(s) only needs to reside on the host running RKE. You do not need to copy your private SSH key(s) to the bastion host.
|
||||
|
||||
```yaml
|
||||
bastion_host:
|
||||
|
||||
@@ -6,9 +6,9 @@ weight: 250
|
||||
RKE supports the ability to set your specific [cloud provider](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/) for your Kubernetes cluster. There are specific cloud configurations for these cloud providers.
|
||||
To enable a cloud provider its name as well as any required configuration options must be provided under the `cloud_provider` directive in the cluster YML.
|
||||
|
||||
* [AWS]({{< baseurl >}}/rke/latest/en/config-options/cloud-providers/aws)
|
||||
* [Azure]({{< baseurl >}}/rke/latest/en/config-options/cloud-providers/azure)
|
||||
* [OpenStack]({{< baseurl >}}/rke/latest/en/config-options/cloud-providers/openstack)
|
||||
* [vSphere]({{< baseurl >}}/rke/latest/en/config-options/cloud-providers/vsphere)
|
||||
* [AWS]({{<baseurl>}}/rke/latest/en/config-options/cloud-providers/aws)
|
||||
* [Azure]({{<baseurl>}}/rke/latest/en/config-options/cloud-providers/azure)
|
||||
* [OpenStack]({{<baseurl>}}/rke/latest/en/config-options/cloud-providers/openstack)
|
||||
* [vSphere]({{<baseurl>}}/rke/latest/en/config-options/cloud-providers/vsphere)
|
||||
|
||||
Outside of this list, RKE also supports the ability to handle any [custom cloud provider]({{< baseurl >}}/rke/latest/en/config-options/cloud-providers/custom).
|
||||
Outside of this list, RKE also supports the ability to handle any [custom cloud provider]({{<baseurl>}}/rke/latest/en/config-options/cloud-providers/custom).
|
||||
|
||||
+2
-2
@@ -8,11 +8,11 @@ If you are experiencing issues while provisioning a cluster with enabled vSphere
|
||||
- controller-manager (Manages volumes in vCenter)
|
||||
- kubelet: (Mounts vSphere volumes to pods)
|
||||
|
||||
If your cluster is not configured with external [Cluster Logging]({{< baseurl >}}/rancher/v2.x/en/tools/logging/), you will need to SSH into nodes to get the logs of the `kube-controller-manager` (running on one of the control plane nodes) and the `kubelet` (pertaining to the node where the stateful pod has been scheduled).
|
||||
If your cluster is not configured with external [Cluster Logging]({{<baseurl>}}/rancher/v2.x//en/cluster-admin/tools//logging/), you will need to SSH into nodes to get the logs of the `kube-controller-manager` (running on one of the control plane nodes) and the `kubelet` (pertaining to the node where the stateful pod has been scheduled).
|
||||
|
||||
The easiest way to create a SSH session with a node is the Rancher CLI tool.
|
||||
|
||||
1. [Configure the Rancher CLI]({{< baseurl >}}/rancher/v2.x/en/cli/) for your cluster.
|
||||
1. [Configure the Rancher CLI]({{<baseurl>}}/rancher/v2.x/en/cli/) for your cluster.
|
||||
2. Run the following command to get a shell to the corresponding nodes:
|
||||
|
||||
```sh
|
||||
|
||||
@@ -116,7 +116,7 @@ The `internal_address` provides the ability to have nodes with multiple addresse
|
||||
|
||||
The `hostname_override` is used to be able to provide a friendly name for RKE to use when registering the node in Kubernetes. This hostname doesn't need to be a routable address, but it must be a valid [Kubernetes resource name](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names). If the `hostname_override` isn't set, then the `address` directive is used when registering the node in Kubernetes.
|
||||
|
||||
> **Note:** When [cloud providers]({{< baseurl >}}/rke/latest/en/config-options/cloud-providers/) are configured, you may need to override the hostname in order to use the cloud provider correctly. There is an exception for the [AWS cloud provider](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/#aws), where the `hostname_override` field will be explicitly ignored.
|
||||
> **Note:** When [cloud providers]({{<baseurl>}}/rke/latest/en/config-options/cloud-providers/) are configured, you may need to override the hostname in order to use the cloud provider correctly. There is an exception for the [AWS cloud provider](https://kubernetes.io/docs/concepts/cluster-administration/cloud-providers/#aws), where the `hostname_override` field will be explicitly ignored.
|
||||
|
||||
### SSH Port
|
||||
|
||||
@@ -130,7 +130,7 @@ For each node, you specify the `user` to be used when connecting to this node. T
|
||||
|
||||
For each node, you specify the path, i.e. `ssh_key_path`, for the SSH private key to be used when connecting to this node. The default key path for each node is `~/.ssh/id_rsa`.
|
||||
|
||||
> **Note:** If you have a private key that can be used across all nodes, you can set the [SSH key path at the cluster level]({{< baseurl >}}/rke/latest/en/config-options/#cluster-level-ssh-key-path). The SSH key path set in each node will always take precedence.
|
||||
> **Note:** If you have a private key that can be used across all nodes, you can set the [SSH key path at the cluster level]({{<baseurl>}}/rke/latest/en/config-options/#cluster-level-ssh-key-path). The SSH key path set in each node will always take precedence.
|
||||
|
||||
### SSH Key
|
||||
|
||||
@@ -150,7 +150,7 @@ If the Docker socket is different than the default, you can set the `docker_sock
|
||||
|
||||
### Labels
|
||||
|
||||
You have the ability to add an arbitrary map of labels for each node. It can be used when using the [ingress controller's]({{< baseurl >}}/rke/latest/en/config-options/add-ons/ingress-controllers/) `node_selector` option.
|
||||
You have the ability to add an arbitrary map of labels for each node. It can be used when using the [ingress controller's]({{<baseurl>}}/rke/latest/en/config-options/add-ons/ingress-controllers/) `node_selector` option.
|
||||
|
||||
### Taints
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ private_registries:
|
||||
|
||||
### Default Registry
|
||||
|
||||
As of v0.1.10, RKE supports specifying a default registry from the list of private registries to be used with all [system images]({{< baseurl >}}/rke/latest/en/config-options/system-images/) . In this example .RKE will use `registry.com` as the default registry for all system images, e.g. `rancher/rke-tools:v0.1.14` will become `registry.com/rancher/rke-tools:v0.1.14`.
|
||||
As of v0.1.10, RKE supports specifying a default registry from the list of private registries to be used with all [system images]({{<baseurl>}}/rke/latest/en/config-options/system-images/) . In this example .RKE will use `registry.com` as the default registry for all system images, e.g. `rancher/rke-tools:v0.1.14` will become `registry.com/rancher/rke-tools:v0.1.14`.
|
||||
|
||||
```yaml
|
||||
private_registries:
|
||||
@@ -31,9 +31,9 @@ private_registries:
|
||||
|
||||
### Air-gapped Setups
|
||||
|
||||
By default, all system images are being pulled from DockerHub. If you are on a system that does not have access to DockerHub, you will need to create a private registry that is populated with all the required [system images]({{< baseurl >}}/rke/latest/en/config-options/system-images/).
|
||||
By default, all system images are being pulled from DockerHub. If you are on a system that does not have access to DockerHub, you will need to create a private registry that is populated with all the required [system images]({{<baseurl>}}/rke/latest/en/config-options/system-images/).
|
||||
|
||||
As of v0.1.10, you have to configure your private registry credentials, but you can specify this registry as a default registry so that all [system images]({{< baseurl >}}/rke/latest/en/config-options/system-images/) are pulled from the designated private registry. You can use the command `rke config --system-images` to get the list of default system images to populate your private registry.
|
||||
As of v0.1.10, you have to configure your private registry credentials, but you can specify this registry as a default registry so that all [system images]({{<baseurl>}}/rke/latest/en/config-options/system-images/) are pulled from the designated private registry. You can use the command `rke config --system-images` to get the list of default system images to populate your private registry.
|
||||
|
||||
Prior to v0.1.10, you had to configure your private registry credentials **and** update the names of all the [system images]({{< baseurl >}}/rke/latest/en/config-options/system-images/) in the `cluster.yml` so that the image names would have the private registry URL appended before each image name.
|
||||
Prior to v0.1.10, you had to configure your private registry credentials **and** update the names of all the [system images]({{<baseurl>}}/rke/latest/en/config-options/system-images/) in the `cluster.yml` so that the image names would have the private registry URL appended before each image name.
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ weight: 230
|
||||
|
||||
To deploy Kubernetes, RKE deploys several core components or services in Docker containers on the nodes. Based on the roles of the node, the containers deployed may be different.
|
||||
|
||||
**All services support additional [custom arguments, Docker mount binds and extra environment variables]({{< baseurl >}}/rke/latest/en/config-options/services/services-extras/).**
|
||||
**All services support additional [custom arguments, Docker mount binds and extra environment variables]({{<baseurl>}}/rke/latest/en/config-options/services/services-extras/).**
|
||||
|
||||
| Component | Services key name in cluster.yml |
|
||||
|-------------------------|----------------------------------|
|
||||
@@ -23,13 +23,13 @@ Kubernetes uses [etcd](https://etcd.io/) as a store for cluster state and data.
|
||||
|
||||
RKE supports running etcd in a single node mode or in HA cluster mode. It also supports adding and removing etcd nodes to the cluster.
|
||||
|
||||
You can enable etcd to [take recurring snapshots]({{< baseurl >}}/rke/latest/en/etcd-snapshots/#recurring-snapshots). These snapshots can be used to [restore etcd]({{< baseurl >}}/rke/latest/en/etcd-snapshots/#etcd-disaster-recovery).
|
||||
You can enable etcd to [take recurring snapshots]({{<baseurl>}}/rke/latest/en/etcd-snapshots/#recurring-snapshots). These snapshots can be used to [restore etcd]({{<baseurl>}}/rke/latest/en/etcd-snapshots/#etcd-disaster-recovery).
|
||||
|
||||
By default, RKE will deploy a new etcd service, but you can also run Kubernetes with an [external etcd service]({{< baseurl >}}/rke/latest/en/config-options/services/external-etcd/).
|
||||
By default, RKE will deploy a new etcd service, but you can also run Kubernetes with an [external etcd service]({{<baseurl>}}/rke/latest/en/config-options/services/external-etcd/).
|
||||
|
||||
## Kubernetes API Server
|
||||
|
||||
> **Note for Rancher 2 users** If you are configuring Cluster Options using a [Config File]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#config-file) when creating [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), the names of services should contain underscores only: `kube_api`. This only applies to Rancher v2.0.5 and v2.0.6.
|
||||
> **Note for Rancher 2 users** If you are configuring Cluster Options using a [Config File]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#config-file) when creating [Rancher Launched Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), the names of services should contain underscores only: `kube_api`. This only applies to Rancher v2.0.5 and v2.0.6.
|
||||
|
||||
The [Kubernetes API](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/) REST service, which handles requests and data for all Kubernetes objects and provide shared state for all the other Kubernetes components.
|
||||
|
||||
@@ -58,10 +58,10 @@ RKE supports the following options for the `kube-api` service :
|
||||
- **Pod Security Policy** (`pod_security_policy`) - An option to enable the [Kubernetes Pod Security Policy](https://kubernetes.io/docs/concepts/policy/pod-security-policy/). By default, we do not enable pod security policies as it is set to `false`.
|
||||
> **Note:** If you set `pod_security_policy` value to `true`, RKE will configure an open policy to allow any pods to work on the cluster. You will need to configure your own policies to fully utilize PSP.
|
||||
- **Always Pull Images** (`always_pull_images`) - Enable `AlwaysPullImages` Admission controller plugin. Enabling `AlwaysPullImages` is a security best practice. It forces Kubernetes to validate the image and pull credentials with the remote image registry. Local image layer cache will still be used, but it does add a small bit of overhead when launching containers to pull and compare image hashes. _Note: Available as of v0.2.0_
|
||||
- **Secrets Encryption Config** (`secrets_encryption_config`) - Manage Kubernetes at-rest data encryption. Documented [here]({{< baseurl >}}//rke/latest/en/config-options/secrets-encryption)
|
||||
- **Secrets Encryption Config** (`secrets_encryption_config`) - Manage Kubernetes at-rest data encryption. Documented [here]({{<baseurl>}}//rke/latest/en/config-options/secrets-encryption)
|
||||
## Kubernetes Controller Manager
|
||||
|
||||
> **Note for Rancher 2 users** If you are configuring Cluster Options using a [Config File]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#config-file) when creating [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), the names of services should contain underscores only: `kube_controller`. This only applies to Rancher v2.0.5 and v2.0.6.
|
||||
> **Note for Rancher 2 users** If you are configuring Cluster Options using a [Config File]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#config-file) when creating [Rancher Launched Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), the names of services should contain underscores only: `kube_controller`. This only applies to Rancher v2.0.5 and v2.0.6.
|
||||
|
||||
The [Kubernetes Controller Manager](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/) service is the component responsible for running Kubernetes main control loops. The controller manager monitors the cluster desired state through the Kubernetes API server and makes the necessary changes to the current state to reach the desired state.
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ weight: 232
|
||||
|
||||
By default, RKE will launch etcd servers, but RKE also supports being able to use an external etcd. RKE only supports connecting to a TLS enabled etcd setup.
|
||||
|
||||
> **Note:** RKE will not accept having external etcd servers in conjunction with [nodes]({{< baseurl >}}/rke/latest/en/config-options/nodes/) with the `etcd` role.
|
||||
> **Note:** RKE will not accept having external etcd servers in conjunction with [nodes]({{<baseurl>}}/rke/latest/en/config-options/nodes/) with the `etcd` role.
|
||||
|
||||
```yaml
|
||||
services:
|
||||
|
||||
@@ -75,4 +75,4 @@ system_images:
|
||||
|
||||
### Air-gapped Setups
|
||||
|
||||
If you have an air-gapped setup and cannot access `docker.io`, you will need to set up your [private registry]({{< baseurl >}}/rke/latest/en/config-options/private-registries/) in your cluster configuration file. After you set up private registry, you will need to update these images to pull from your private registry.
|
||||
If you have an air-gapped setup and cannot access `docker.io`, you will need to set up your [private registry]({{<baseurl>}}/rke/latest/en/config-options/private-registries/) in your cluster configuration file. After you set up private registry, you will need to update these images to pull from your private registry.
|
||||
|
||||
@@ -13,7 +13,7 @@ _Available as of v0.2.0_
|
||||
|
||||
RKE can upload your snapshots to a S3 compatible backend.
|
||||
|
||||
**Note:** As of RKE v0.2.0, the `pki.bundle.tar.gz` file is no longer required because of a change in how the [Kubernetes cluster state is stored]({{< baseurl >}}/rke/latest/en/installation/#kubernetes-cluster-state).
|
||||
**Note:** As of RKE v0.2.0, the `pki.bundle.tar.gz` file is no longer required because of a change in how the [Kubernetes cluster state is stored]({{<baseurl>}}/rke/latest/en/installation/#kubernetes-cluster-state).
|
||||
|
||||
# Backing Up a Cluster
|
||||
|
||||
|
||||
@@ -54,8 +54,8 @@ $ rke etcd snapshot-save \
|
||||
| `--bucket-name` value | Specify s3 bucket name | * |
|
||||
| `--folder` value | Specify folder inside bucket where backup will be stored. This is optional. _Available as of v0.3.0_ | * |
|
||||
| `--region` value | Specify the s3 bucket location (optional) | * |
|
||||
| `--ssh-agent-auth` | [Use SSH Agent Auth defined by SSH_AUTH_SOCK]({{< baseurl >}}/rke/latest/en/config-options/#ssh-agent) | |
|
||||
| `--ignore-docker-version` | [Disable Docker version check]({{< baseurl >}}/rke/latest/en/config-options/#supported-docker-versions) |
|
||||
| `--ssh-agent-auth` | [Use SSH Agent Auth defined by SSH_AUTH_SOCK]({{<baseurl>}}/rke/latest/en/config-options/#ssh-agent) | |
|
||||
| `--ignore-docker-version` | [Disable Docker version check]({{<baseurl>}}/rke/latest/en/config-options/#supported-docker-versions) |
|
||||
|
||||
The `--access-key` and `--secret-key` options are not required if the `etcd` nodes are AWS EC2 instances that have been configured with a suitable IAM instance profile.
|
||||
|
||||
@@ -116,8 +116,8 @@ $ rke etcd snapshot-save --config cluster.yml --name snapshot-name
|
||||
| --- | --- |
|
||||
| `--name` value | Specify snapshot name |
|
||||
| `--config` value | Specify an alternate cluster YAML file (default: `cluster.yml`) [$RKE_CONFIG] |
|
||||
| `--ssh-agent-auth` | [Use SSH Agent Auth defined by SSH_AUTH_SOCK]({{< baseurl >}}/rke/latest/en/config-options/#ssh-agent) |
|
||||
| `--ignore-docker-version` | [Disable Docker version check]({{< baseurl >}}/rke/latest/en/config-options/#supported-docker-versions) |
|
||||
| `--ssh-agent-auth` | [Use SSH Agent Auth defined by SSH_AUTH_SOCK]({{<baseurl>}}/rke/latest/en/config-options/#ssh-agent) |
|
||||
| `--ignore-docker-version` | [Disable Docker version check]({{<baseurl>}}/rke/latest/en/config-options/#supported-docker-versions) |
|
||||
|
||||
{{% /tab %}}
|
||||
{{% /tabs %}}
|
||||
|
||||
@@ -33,7 +33,7 @@ $ rke etcd snapshot-restore --config cluster.yml --name mysnapshot
|
||||
|
||||
The snapshot is assumed to be located in `/opt/rke/etcd-snapshots`.
|
||||
|
||||
**Note:** The `pki.bundle.tar.gz` file is not needed because RKE v0.2.0 changed how the [Kubernetes cluster state is stored]({{< baseurl >}}/rke/latest/en/installation/#kubernetes-cluster-state).
|
||||
**Note:** The `pki.bundle.tar.gz` file is not needed because RKE v0.2.0 changed how the [Kubernetes cluster state is stored]({{<baseurl>}}/rke/latest/en/installation/#kubernetes-cluster-state).
|
||||
|
||||
### Example of Restoring from a Snapshot in S3
|
||||
|
||||
@@ -67,8 +67,8 @@ $ rke etcd snapshot-restore \
|
||||
| `--bucket-name` value | Specify s3 bucket name | *|
|
||||
| `--folder` value | Specify folder inside bucket where backup will be stored. This is optional. This is optional. _Available as of v0.3.0_ | *|
|
||||
| `--region` value | Specify the s3 bucket location (optional) | *|
|
||||
| `--ssh-agent-auth` | [Use SSH Agent Auth defined by SSH_AUTH_SOCK]({{< baseurl >}}/rke/latest/en/config-options/#ssh-agent) | |
|
||||
| `--ignore-docker-version` | [Disable Docker version check]({{< baseurl >}}/rke/latest/en/config-options/#supported-docker-versions) |
|
||||
| `--ssh-agent-auth` | [Use SSH Agent Auth defined by SSH_AUTH_SOCK]({{<baseurl>}}/rke/latest/en/config-options/#ssh-agent) | |
|
||||
| `--ignore-docker-version` | [Disable Docker version check]({{<baseurl>}}/rke/latest/en/config-options/#supported-docker-versions) |
|
||||
|
||||
{{% /tab %}}
|
||||
{{% tab "RKE prior to v0.2.0"%}}
|
||||
@@ -109,8 +109,8 @@ The `pki.bundle.tar.gz` file is also expected to be in the same location.
|
||||
| --- | --- |
|
||||
| `--name` value | Specify snapshot name |
|
||||
| `--config` value | Specify an alternate cluster YAML file (default: `cluster.yml`) [$RKE_CONFIG] |
|
||||
| `--ssh-agent-auth` | [Use SSH Agent Auth defined by SSH_AUTH_SOCK]({{< baseurl >}}/rke/latest/en/config-options/#ssh-agent) |
|
||||
| `--ignore-docker-version` | [Disable Docker version check]({{< baseurl >}}/rke/latest/en/config-options/#supported-docker-versions) |
|
||||
| `--ssh-agent-auth` | [Use SSH Agent Auth defined by SSH_AUTH_SOCK]({{<baseurl>}}/rke/latest/en/config-options/#ssh-agent) |
|
||||
| `--ignore-docker-version` | [Disable Docker version check]({{<baseurl>}}/rke/latest/en/config-options/#supported-docker-versions) |
|
||||
|
||||
{{% /tab %}}
|
||||
{{% /tabs %}}
|
||||
|
||||
@@ -5,9 +5,9 @@ aliases:
|
||||
- /rke/latest/en/config-options/example-yamls/
|
||||
---
|
||||
|
||||
There are lots of different [configuration options]({{< baseurl >}}/rke/latest/en/config-options/) that can be set in the cluster configuration file for RKE. Here are some examples of files:
|
||||
There are lots of different [configuration options]({{<baseurl>}}/rke/latest/en/config-options/) that can be set in the cluster configuration file for RKE. Here are some examples of files:
|
||||
|
||||
> **Note for Rancher 2 users** If you are configuring Cluster Options using a [Config File]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#config-file) when creating [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), the names of services should contain underscores only: `kube_api` and `kube_controller`. This only applies to Rancher v2.0.5 and v2.0.6.
|
||||
> **Note for Rancher 2 users** If you are configuring Cluster Options using a [Config File]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#config-file) when creating [Rancher Launched Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), the names of services should contain underscores only: `kube_api` and `kube_controller`. This only applies to Rancher v2.0.5 and v2.0.6.
|
||||
|
||||
## Minimal `cluster.yml` example
|
||||
|
||||
|
||||
@@ -7,8 +7,8 @@ weight: 50
|
||||
RKE is a fast, versatile Kubernetes installer that you can use to install Kubernetes on your Linux hosts. You can get started in a couple of quick and easy steps:
|
||||
|
||||
1. [Download the RKE Binary](#download-the-rke-binary)
|
||||
1. [Alternative RKE macOS Install - Homebrew](#alternative-rke-macos-install---homebrew)
|
||||
1. [Alternative RKE macOS Install - MacPorts](#alternative-rke-macos-install---macports)
|
||||
1. [Alternative RKE macOS Install - Homebrew](#alternative-rke-macos-x-install-homebrew)
|
||||
1. [Alternative RKE macOS Install - MacPorts](#alternative-rke-macos-install-macports)
|
||||
1. [Prepare the Nodes for the Kubernetes Cluster](#prepare-the-nodes-for-the-kubernetes-cluster)
|
||||
1. [Creating the Cluster Configuration File](#creating-the-cluster-configuration-file)
|
||||
1. [Deploying Kubernetes with RKE](#deploying-kubernetes-with-rke)
|
||||
@@ -93,20 +93,20 @@ $ port upgrade rke
|
||||
|
||||
The Kubernetes cluster components are launched using Docker on a Linux distro. You can use any Linux you want, as long as you can install Docker on it.
|
||||
|
||||
Review the [OS requirements]({{< baseurl >}}/rke/latest/en/installation/os/) and configure each node appropriately.
|
||||
Review the [OS requirements]({{<baseurl>}}/rke/latest/en/installation/os/) and configure each node appropriately.
|
||||
|
||||
## Creating the Cluster Configuration File
|
||||
|
||||
RKE uses a cluster configuration file, referred to as `cluster.yml` to determine what nodes will be in the cluster and how to deploy Kubernetes. There are [many configuration options]({{< baseurl >}}/rke/latest/en/config-options/) that can be set in the `cluster.yml`. In our example, we will be assuming the minimum of one [node]({{< baseurl >}}/rke/latest/en/config-options/nodes) for your Kubernetes cluster.
|
||||
RKE uses a cluster configuration file, referred to as `cluster.yml` to determine what nodes will be in the cluster and how to deploy Kubernetes. There are [many configuration options]({{<baseurl>}}/rke/latest/en/config-options/) that can be set in the `cluster.yml`. In our example, we will be assuming the minimum of one [node]({{<baseurl>}}/rke/latest/en/config-options/nodes) for your Kubernetes cluster.
|
||||
|
||||
There are two easy ways to create a `cluster.yml`:
|
||||
|
||||
- Using our [minimal `cluster.yml`]({{< baseurl >}}/rke/latest/en/example-yamls/#minimal-cluster-yml-example) and updating it based on the node that you will be using.
|
||||
- Using our [minimal `cluster.yml`]({{<baseurl>}}/rke/latest/en/example-yamls/#minimal-cluster-yml-example) and updating it based on the node that you will be using.
|
||||
- Using `rke config` to query for all the information needed.
|
||||
|
||||
### Using `rke config`
|
||||
|
||||
Run `rke config` to create a new `cluster.yml` in the current directory. This command will prompt you for all the information needed to build a cluster. See [cluster configuration options]({{< baseurl >}}/rke/latest/en/config-options/) for details on the various options.
|
||||
Run `rke config` to create a new `cluster.yml` in the current directory. This command will prompt you for all the information needed to build a cluster. See [cluster configuration options]({{<baseurl>}}/rke/latest/en/config-options/) for details on the various options.
|
||||
|
||||
```
|
||||
rke config --name cluster.yml
|
||||
@@ -136,7 +136,7 @@ To create an HA cluster, specify more than one host with role `controlplane`.
|
||||
|
||||
_Available as of v0.2.0_
|
||||
|
||||
By default, Kubernetes clusters require certificates and RKE auto-generates the certificates for all cluster components. You can also use [custom certificates]({{< baseurl >}}/rke/latest/en/installation/certs/). After the Kubernetes cluster is deployed, you can [manage these auto-generated certificates]({{< baseurl >}}/rke/latest/en/cert-mgmt/#certificate-rotation).
|
||||
By default, Kubernetes clusters require certificates and RKE auto-generates the certificates for all cluster components. You can also use [custom certificates]({{<baseurl>}}/rke/latest/en/installation/certs/). After the Kubernetes cluster is deployed, you can [manage these auto-generated certificates]({{<baseurl>}}/rke/latest/en/cert-mgmt/#certificate-rotation).
|
||||
|
||||
## Deploying Kubernetes with RKE
|
||||
|
||||
@@ -165,9 +165,11 @@ The last line should read `Finished building Kubernetes cluster successfully` to
|
||||
Save a copy of the following files in a secure location:
|
||||
|
||||
- `cluster.yml`: The RKE cluster configuration file.
|
||||
- `kube_config_cluster.yml`: The [Kubeconfig file]({{< baseurl >}}/rke/latest/en/kubeconfig/) for the cluster, this file contains credentials for full access to the cluster.
|
||||
- `kube_config_cluster.yml`: The [Kubeconfig file]({{<baseurl>}}/rke/latest/en/kubeconfig/) for the cluster, this file contains credentials for full access to the cluster.
|
||||
- `cluster.rkestate`: The [Kubernetes Cluster State file](#kubernetes-cluster-state), this file contains credentials for full access to the cluster.<br/><br/>_The Kubernetes Cluster State file is only created when using RKE v0.2.0 or higher._
|
||||
|
||||
> **Note:** The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.
|
||||
|
||||
### Kubernetes Cluster State
|
||||
|
||||
The Kubernetes cluster state, which consists of the cluster configuration file `cluster.yml` and components certificates in Kubernetes cluster, is saved by RKE, but depending on your RKE version, the cluster state is saved differently.
|
||||
@@ -178,9 +180,9 @@ Prior to v0.2.0, RKE saved the Kubernetes cluster state as a secret. When updati
|
||||
|
||||
## Interacting with your Kubernetes cluster
|
||||
|
||||
After your cluster is up and running, you can start using the [generated kubeconfig file]({{< baseurl >}}/rke/latest/en/kubeconfig) to start interacting with your Kubernetes cluster using `kubectl`.
|
||||
After your cluster is up and running, you can start using the [generated kubeconfig file]({{<baseurl>}}/rke/latest/en/kubeconfig) to start interacting with your Kubernetes cluster using `kubectl`.
|
||||
|
||||
After installation, there are several maintenance items that might arise:
|
||||
|
||||
* [Certificate Management]({{< baseurl >}}/rke/latest/en/cert-mgmt/)
|
||||
* [Adding and Removing Nodes in the cluster]({{< baseurl >}}/rke/latest/en/managing-clusters)
|
||||
* [Certificate Management]({{<baseurl>}}/rke/latest/en/cert-mgmt/)
|
||||
* [Adding and Removing Nodes in the cluster]({{<baseurl>}}/rke/latest/en/managing-clusters)
|
||||
|
||||
@@ -7,7 +7,7 @@ _Available as of v0.2.0_
|
||||
|
||||
By default, Kubernetes clusters require certificates and RKE auto-generates the certificates for all the Kubernetes services. RKE can also use custom certificates for these Kubernetes services.
|
||||
|
||||
When [deploying Kubernetes with RKE]({{< baseurl >}}/rke/latest/en/installation/#deploying-kubernetes-with-rke), there are two additional options that can be used with `rke up` so that RKE uses custom certificates.
|
||||
When [deploying Kubernetes with RKE]({{<baseurl>}}/rke/latest/en/installation/#deploying-kubernetes-with-rke), there are two additional options that can be used with `rke up` so that RKE uses custom certificates.
|
||||
|
||||
| Option | Description |
|
||||
| --- | --- |
|
||||
@@ -45,7 +45,7 @@ The following certificates must exist in the certificate directory.
|
||||
|
||||
If you want to create and sign the certificates by a real Certificate Authority (CA), you can use RKE to generate a set of Certificate Signing Requests (CSRs) and keys. Using the `rke cert generate-csr` command, you can generate the CSRs and keys.
|
||||
|
||||
1. Set up your `cluster.yml` with the [node information]({{< baseurl >}}/rke/latest/en/config-options/nodes/).
|
||||
1. Set up your `cluster.yml` with the [node information]({{<baseurl>}}/rke/latest/en/config-options/nodes/).
|
||||
|
||||
2. Run `rke cert generate-csr` to generate certificates for the node(s) in the `cluster.yml`. By default, the CSRs and keys will be saved in `./cluster_certs`. To have them saved in a different directory, use `--cert-dir` to define what directory to have them saved in.
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ aliases:
|
||||
|
||||
### Adding/Removing Nodes
|
||||
|
||||
RKE supports adding/removing [nodes]({{< baseurl >}}/rke/latest/en/config-options/nodes/) for worker and controlplane hosts.
|
||||
RKE supports adding/removing [nodes]({{<baseurl>}}/rke/latest/en/config-options/nodes/) for worker and controlplane hosts.
|
||||
|
||||
In order to add additional nodes, you update the original `cluster.yml` file with any additional nodes and specify their role in the Kubernetes cluster.
|
||||
|
||||
@@ -20,11 +20,13 @@ After you've made changes to add/remove nodes, run `rke up` with the updated `cl
|
||||
|
||||
You can add/remove only worker nodes, by running `rke up --update-only`. This will ignore everything else in the `cluster.yml` except for any worker nodes.
|
||||
|
||||
> **Note:** When using `--update-only`, other actions that do not specifically relate to nodes may be deployed or updated, for example [addons]({{< baseurl >}}/rke/latest/en/config-options/add-ons).
|
||||
|
||||
### Removing Kubernetes Components from Nodes
|
||||
|
||||
In order to remove the Kubernetes components from nodes, you use the `rke remove` command.
|
||||
|
||||
> **Warning:** This command is irreversible and will destroy the Kubernetes cluster, including etcd snapshots on S3. If there is a disaster and your cluster is inaccessible, refer to the process for [restoring your cluster from a snapshot]({{< baseurl >}}/rke/latest/en/etcd-snapshots/#etcd-disaster-recovery).
|
||||
> **Warning:** This command is irreversible and will destroy the Kubernetes cluster, including etcd snapshots on S3. If there is a disaster and your cluster is inaccessible, refer to the process for [restoring your cluster from a snapshot]({{<baseurl>}}rke/latest/en/etcd-snapshots/#etcd-disaster-recovery).
|
||||
|
||||
The `rke remove` command does the following to each node in the `cluster.yml`:
|
||||
|
||||
|
||||
@@ -31,7 +31,7 @@ weight: 5
|
||||
|
||||
RKE runs on almost any Linux OS with Docker installed. Most of the development and testing of RKE occurred on Ubuntu 16.04. However, some OS's have restrictions and specific requirements.
|
||||
|
||||
- [SSH user]({{< baseurl >}}/rke/latest/en/config-options/nodes/#ssh-user) - The SSH user used for node access must be a member of the `docker` group on the node:
|
||||
- [SSH user]({{<baseurl>}}/rke/latest/en/config-options/nodes/#ssh-user) - The SSH user used for node access must be a member of the `docker` group on the node:
|
||||
|
||||
```
|
||||
usermod -aG docker <user_name>
|
||||
@@ -100,7 +100,7 @@ net.bridge.bridge-nf-call-iptables=1
|
||||
|
||||
### Red Hat Enterprise Linux (RHEL) / Oracle Enterprise Linux (OEL) / CentOS
|
||||
|
||||
If using Red Hat Enterprise Linux, Oracle Enterprise Linux or CentOS, you cannot use the `root` user as [SSH user]({{< baseurl >}}/rke/latest/en/config-options/nodes/#ssh-user) due to [Bugzilla 1527565](https://bugzilla.redhat.com/show_bug.cgi?id=1527565). Please follow the instructions below how to setup Docker correctly, based on the way you installed Docker on the node.
|
||||
If using Red Hat Enterprise Linux, Oracle Enterprise Linux or CentOS, you cannot use the `root` user as [SSH user]({{<baseurl>}}/rke/latest/en/config-options/nodes/#ssh-user) due to [Bugzilla 1527565](https://bugzilla.redhat.com/show_bug.cgi?id=1527565). Please follow the instructions below how to setup Docker correctly, based on the way you installed Docker on the node.
|
||||
|
||||
#### Using upstream Docker
|
||||
If you are using upstream Docker, the package name is `docker-ce` or `docker-ee`. You can check the installed package by executing:
|
||||
|
||||
@@ -3,5 +3,5 @@ title: Troubleshooting
|
||||
weight: 400
|
||||
---
|
||||
|
||||
* [SSH Connectivity Errors]({{< baseurl >}}/rke/latest/en/troubleshooting/ssh-connectivity-errors/)
|
||||
* [Provisioning Errors]({{< baseurl >}}/rke/latest/en/troubleshooting/provisioning-errors/)
|
||||
* [SSH Connectivity Errors]({{<baseurl>}}/rke/latest/en/troubleshooting/ssh-connectivity-errors/)
|
||||
* [Provisioning Errors]({{<baseurl>}}/rke/latest/en/troubleshooting/provisioning-errors/)
|
||||
|
||||
@@ -5,7 +5,7 @@ weight: 200
|
||||
|
||||
### Failed to get job complete status
|
||||
|
||||
Most common reason for this error is that a node is having issues that block the deploy job from completing successfully. See [Get node conditions]({{< baseurl >}}/rancher/v2.x/en/troubleshooting/kubernetes-resources/#get-node-conditions) how to check node conditions.
|
||||
Most common reason for this error is that a node is having issues that block the deploy job from completing successfully. See [Get node conditions]({{<baseurl>}}/rancher/v2.x/en/troubleshooting/kubernetes-resources/#get-node-conditions) how to check node conditions.
|
||||
|
||||
You can also retrieve the log from the job to see if it has an indication of the error, make sure you replace `rke-network-plugin-deploy-job` with the job name from the error:
|
||||
|
||||
|
||||
@@ -3,31 +3,40 @@ title: Upgrades
|
||||
weight: 100
|
||||
---
|
||||
|
||||
After RKE has deployed Kubernetes, you can upgrade the versions of the components in your Kubernetes cluster, the [definition of the Kubernetes services]({{< baseurl >}}/rke/latest/en/config-options/services/) or the [add-ons]({{< baseurl >}}/rke/latest/en/config-options/add-ons/).
|
||||
After RKE has deployed Kubernetes, you can upgrade the versions of the components in your Kubernetes cluster, the [definition of the Kubernetes services]({{<baseurl>}}/rke/latest/en/config-options/services/) or the [add-ons]({{<baseurl>}}/rke/latest/en/config-options/add-ons/).
|
||||
|
||||
The default Kubernetes version for each RKE version can be found in [the RKE release notes](https://github.com/rancher/rke/releases/).
|
||||
|
||||
You can also select a newer version of Kubernetes to install for your cluster. Downgrading Kubernetes is not supported.
|
||||
You can also select a newer version of Kubernetes to install for your cluster.
|
||||
|
||||
Each version of RKE has a specific [list of supported Kubernetes versions.](#listing-supported-kubernetes-versions)
|
||||
|
||||
In case the Kubernetes version is defined in the `kubernetes_version` directive and under the `system-images` directive are defined, the `system-images` configuration will take precedence over `kubernetes_version`.
|
||||
In case the Kubernetes version is defined in the `kubernetes_version` directive and under the `system-images` directive, the `system-images` configuration will take precedence over the `kubernetes_version`.
|
||||
|
||||
This page covers the following topics:
|
||||
|
||||
- [How upgrades work](#how-upgrades-work)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Upgrading Kubernetes](#upgrading-kubernetes)
|
||||
- [Configuring the upgrade strategy](#configuring-the-upgrade-strategy)
|
||||
- [Maintaining availability for applications during upgrades](#maintaining-availability-for-applications-during-upgrades)
|
||||
- [Listing supported Kubernetes versions](#listing-supported-kubernetes-versions)
|
||||
- [Kubernetes version precedence](#kubernetes-version-precedence)
|
||||
- [Using an unsupported Kubernetes version](#using-an-unsupported-kubernetes-version)
|
||||
- [Mapping the Kubernetes version to services](#mapping-the-kubernetes-version-to-services)
|
||||
- [Service upgrades](#service-upgrades)
|
||||
- [Add-ons upgrades](#add-ons-upgrades)
|
||||
- [Upgrading Nodes Manually](#upgrading-nodes-manually)
|
||||
- [Rolling Back the Kubernetes Version](#rolling-back-the-kubernetes-version)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
### How Upgrades Work
|
||||
|
||||
In [this section,]({{<baseurl>}}/rke/latest/en/upgrades/how-upgrades-work) you'll learn what happens when you edit or upgrade your RKE Kubernetes cluster.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Ensure that any `system_images` configuration is absent from the `cluster.yml`. The Kubernetes version should only be listed under the `system_images` directive if an [unsupported version](#using-an-unsupported-kubernetes-version) is being used. Refer to [Kubernetes version precedence](#kubernetes-version-precedence) for more information.
|
||||
- Ensure that the correct files to manage [Kubernetes cluster state]({{< baseurl >}}/rke/latest/en/installation/#kubernetes-cluster-state) are present in the working directory. Refer to the tabs below for the required files, which differ based on the RKE version.
|
||||
- Ensure that the correct files to manage [Kubernetes cluster state]({{<baseurl>}}/rke/latest/en/installation/#kubernetes-cluster-state) are present in the working directory. Refer to the tabs below for the required files, which differ based on the RKE version.
|
||||
|
||||
{{% tabs %}}
|
||||
{{% tab "RKE v0.2.0+" %}}
|
||||
@@ -46,8 +55,6 @@ RKE saves the Kubernetes cluster state as a secret. When updating the state, RKE
|
||||
|
||||
### Upgrading Kubernetes
|
||||
|
||||
> **Note:** RKE does not support rolling back to previous versions.
|
||||
|
||||
To upgrade the Kubernetes version of an RKE-provisioned cluster, set the `kubernetes_version` string in the `cluster.yml` to the desired version from the [list of supported Kubernetes versions](#listing-supported-kubernetes-versions) for the specific version of RKE:
|
||||
|
||||
```yaml
|
||||
@@ -60,6 +67,18 @@ Then invoke `rke up`:
|
||||
$ rke up --config cluster.yml
|
||||
```
|
||||
|
||||
### Configuring the Upgrade Strategy
|
||||
|
||||
As of v0.1.8, upgrades to add-ons are supported. [Add-ons]({{<baseurl>}}/rke/latest/en/config-options/add-ons/) can also be upgraded by changing any of the add-ons and running `rke up` again with the updated configuration file.
|
||||
|
||||
As of v1.1.0, additional upgrade options became available to give you more granular control over the upgrade process. These options can be used to maintain availability of your applications during a cluster upgrade.
|
||||
|
||||
For details on upgrade configuration options, refer to [Configuring the Upgrade Strategy.]({{<baseurl>}}/rke/latest/en/upgrades/configuring-strategy)
|
||||
|
||||
### Maintaining Availability for Applications During Upgrades
|
||||
|
||||
In [this section,]({{<baseurl>}}/rke/latest/en/upgrades/maintaining-availability/) you'll learn the requirements to prevent downtime for your applications when you upgrade the cluster using `rke up`.
|
||||
|
||||
### Listing Supported Kubernetes Versions
|
||||
|
||||
Please refer to the [release notes](https://github.com/rancher/rke/releases) of the RKE version that you are running, to find the list of supported Kubernetes versions as well as the default Kubernetes version.
|
||||
@@ -86,7 +105,7 @@ As of v0.2.0, if a version is defined in `kubernetes_version` and is not found i
|
||||
|
||||
Prior to v0.2.0, if a version is defined in `kubernetes_version` and is not found in the specific list of supported Kubernetes versions, the default version from the supported list is used.
|
||||
|
||||
If you want to use a different version from the supported list, please use the [system images]({{< baseurl >}}/rke/latest/en/config-options/system-images/) option.
|
||||
If you want to use a different version from the supported list, please use the [system images]({{<baseurl>}}/rke/latest/en/config-options/system-images/) option.
|
||||
|
||||
### Mapping the Kubernetes Version to Services
|
||||
|
||||
@@ -98,12 +117,40 @@ For RKE prior to v0.3.0, the service defaults are located [here](https://github.
|
||||
|
||||
### Service Upgrades
|
||||
|
||||
[Services]({{< baseurl >}}/rke/latest/en/config-options/services/) can be upgraded by changing any of the services arguments or `extra_args` and running `rke up` again with the updated configuration file.
|
||||
[Services]({{<baseurl>}}/rke/latest/en/config-options/services/) can be upgraded by changing any of the services arguments or `extra_args` and running `rke up` again with the updated configuration file.
|
||||
|
||||
> **Note:** The following arguments, `service_cluster_ip_range` or `cluster_cidr`, cannot be changed as any changes to these arguments will result in a broken cluster. Currently, network pods are not automatically upgraded.
|
||||
|
||||
### Add-Ons Upgrades
|
||||
### Upgrading Nodes Manually
|
||||
|
||||
As of v0.1.8, upgrades to add-ons are supported.
|
||||
_Available as of v1.1.0_
|
||||
|
||||
[Add-ons]({{< baseurl >}}/rke/latest/en/config-options/add-ons/) can also be upgraded by changing any of the add-ons and running `rke up` again with the updated configuration file.
|
||||
You can manually update each type of node separately. As a best practice, upgrade the etcd nodes first, followed by controlplane and then worker nodes.
|
||||
|
||||
### Rolling Back the Kubernetes Version
|
||||
|
||||
_Available as of v1.1.0_
|
||||
|
||||
A cluster can be restored back to a snapshot that uses a previous Kubernetes version.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
_Applies to v1.1.0+_
|
||||
|
||||
If a node doesn't come up after an upgrade, the `rke up` command errors out.
|
||||
|
||||
No upgrade will proceed if the number of unavailable nodes exceeds the configured maximum.
|
||||
|
||||
If an upgrade stops, you may need to fix an unavailable node or remove it from the cluster before the upgrade can continue.
|
||||
|
||||
A failed node could be in many different states:
|
||||
|
||||
- Powered off
|
||||
- Unavailable
|
||||
- User drains a node while upgrade is in process, so there are no kubelets on the node
|
||||
- The upgrade itself failed
|
||||
|
||||
Some expected failure scenarios include the following:
|
||||
|
||||
- If the maximum unavailable number of nodes is reached during an upgrade, the RKE CLI will error out and exit the CLI with a failure code.
|
||||
- If some nodes fail to upgrade, but the number of failed nodes doesn't reach the maximum unavailable number of nodes, the RKE CLI logs the nodes that were unable to upgrade and continues to upgrade the add-ons. After the add-ons are upgraded, RKE will error out and exit the CLI with a failure code regardless of add-on upgrade status.
|
||||
@@ -0,0 +1,171 @@
|
||||
---
|
||||
title: Configuring the Upgrade Strategy
|
||||
weight: 2
|
||||
---
|
||||
|
||||
In this section, you'll learn how to configure the maximum number of unavailable controlplane and worker nodes, how to drain nodes before upgrading them, and how to configure the replicas for addons such as Ingress.
|
||||
|
||||
- [Maximum Unavailable Nodes](#maximum-unavailable-nodes)
|
||||
- [Draining Nodes](#draining-nodes)
|
||||
- [Replicas for Ingress and Networking Addons](#replicas-for-ingress-and-networking-addons)
|
||||
- [Replicas for DNS and Monitoring Addons](#replicas-for-dns-and-monitoring-addons)
|
||||
- [Example cluster.yml](#example-cluster-yml)
|
||||
|
||||
### Maximum Unavailable Nodes
|
||||
|
||||
The maximum number of unavailable controlplane and worker nodes can be configured in the `cluster.yml` before upgrading the cluster:
|
||||
|
||||
- **max_unavailable_controlplane:** The maximum number of controlplane nodes that can fail without causing the cluster upgrade to fail. By default, `max_unavailable_controlplane` is defined as one node.
|
||||
- **max_unavailable_worker:** The maximum number of worker nodes that can fail without causing the cluster upgrade to fail. By default, `max_unavailable_worker` is defined as 10 percent of all worker nodes.*
|
||||
|
||||
/* This number can be configured as a percentage or as an integer. When defined as a percentage, the batch size is rounded down to the nearest node, with a minimum of one node per batch.
|
||||
|
||||
An example configuration of the cluster upgrade strategy is shown below:
|
||||
|
||||
```yaml
|
||||
upgrade_strategy:
|
||||
max_unavailable_worker: 10%
|
||||
max_unavailable_controlplane: 1
|
||||
```
|
||||
|
||||
### Draining Nodes
|
||||
|
||||
By default, nodes are cordoned first before upgrading. Each node should always be cordoned before starting its upgrade so that new pods will not be scheduled to it, and traffic will not reach the node. In addition to cordoning each node, RKE can also be configured to drain each node before starting its upgrade. Draining a node will evict all the pods running on the computing resource.
|
||||
|
||||
For information on draining and how to safely drain a node, refer to the [Kubernetes documentation.](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/)
|
||||
|
||||
If the `drain` directive is set to `true` in the `cluster.yml`, worker nodes will be drained before they are upgraded. The default value is false:
|
||||
|
||||
```yaml
|
||||
upgrade_strategy:
|
||||
max_unavailable_worker: 10%
|
||||
max_unavailable_controlplane: 1
|
||||
drain: false
|
||||
node_drain_input:
|
||||
force: false
|
||||
ignore_daemonsets: true
|
||||
delete_local_data: false
|
||||
grace_period: -1 // grace period specified for each pod spec will be used
|
||||
timeout: 60
|
||||
```
|
||||
|
||||
### Replicas for Ingress and Networking Addons
|
||||
|
||||
The Ingress and network addons are launched as Kubernetes [daemonsets.](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) If no value is given for the [update strategy,](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy) Kubernetes sets the update strategy to `rollingUpdate` by default, with `maxUnavailable` set to 1.
|
||||
|
||||
An example configuration of the Ingress and network addons is shown below:
|
||||
|
||||
```yaml
|
||||
ingress:
|
||||
provider: nginx
|
||||
update_strategy:
|
||||
strategy: RollingUpdate
|
||||
rollingUpdate:
|
||||
maxUnavailable: 5
|
||||
network:
|
||||
plugin: canal
|
||||
update_strategy:
|
||||
strategy: RollingUpdate
|
||||
rollingUpdate:
|
||||
maxUnavailable: 6
|
||||
```
|
||||
|
||||
### Replicas for DNS and Monitoring Addons
|
||||
|
||||
The DNS and monitoring addons are launched as Kubernetes [deployments.](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) These addons include `coredns`, `kubedns`, and `metrics-server`, the monitoring deployment.
|
||||
|
||||
If no value is configured for their [update strategy](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy) in the `cluster.yml`, Kubernetes sets the update strategy to `rollingUpdate` by default, with `maxUnavailable` set to 25% and `maxSurge` set to 25%.
|
||||
|
||||
The DNS addons use `cluster-proportional-autoscaler`, which is an [open-source container image](https://github.com/kubernetes-incubator/cluster-proportional-autoscaler) that watches over the number of schedulable nodes and cores of the cluster and resizes the number of replicas for the required resource. This functionality is useful for applications that need to be autoscaled with the number of nodes in the cluster. For the DNS addon, the fields needed for the `cluster-proportional-autoscaler` are made configurable.
|
||||
|
||||
The following table shows the default values for these fields:
|
||||
|
||||
Field Name | Default Value
|
||||
-----------|--------------
|
||||
coresPerReplica | 128
|
||||
nodesPerReplica | 4
|
||||
min | 1
|
||||
preventSinglePointFailure | true
|
||||
|
||||
The `cluster-proportional-autoscaler` uses this formula to calculate the number of replicas:
|
||||
|
||||
```plain
|
||||
replicas = max( ceil( cores * 1/coresPerReplica ) , ceil( nodes * 1/nodesPerReplica ) )
|
||||
replicas = min(replicas, max)
|
||||
replicas = max(replicas, min)
|
||||
```
|
||||
|
||||
An example configuration of the DNS and monitoring addons is shown below:
|
||||
|
||||
```yaml
|
||||
dns:
|
||||
provider: coredns
|
||||
update_strategy:
|
||||
strategy: RollingUpdate
|
||||
rollingUpdate:
|
||||
maxUnavailable: 20%
|
||||
maxSurge: 15%
|
||||
linear_autoscaler_params:
|
||||
cores_per_replica: 0.34
|
||||
nodes_per_replica: 4
|
||||
prevent_single_point_failure: true
|
||||
min: 2
|
||||
max: 3
|
||||
monitoring:
|
||||
provider: metrics-server
|
||||
update_strategy:
|
||||
strategy: RollingUpdate
|
||||
rollingUpdate:
|
||||
maxUnavailable: 8
|
||||
```
|
||||
|
||||
### Example cluster.yml
|
||||
|
||||
```yaml
|
||||
# If you intened to deploy Kubernetes in an air-gapped environment,
|
||||
# please consult the documentation on how to configure custom RKE images.
|
||||
nodes:
|
||||
# At least three etcd nodes, two controlplane nodes, and two worker nodes,
|
||||
# nodes skipped for brevity
|
||||
upgrade_strategy:
|
||||
max_unavailable_worker: 10%
|
||||
max_unavailable_controlplane: 1
|
||||
drain: false
|
||||
node_drain_input:
|
||||
force: false
|
||||
ignore_daemonsets: true
|
||||
delete_local_data: false
|
||||
grace_period: -1 // grace period specified for each pod spec will be used
|
||||
timeout: 60
|
||||
ingress:
|
||||
provider: nginx
|
||||
update_strategy: # Available in v2.4
|
||||
strategy: RollingUpdate
|
||||
rollingUpdate:
|
||||
maxUnavailable: 5
|
||||
network:
|
||||
plugin: canal
|
||||
update_strategy: # Available in v2.4
|
||||
strategy: RollingUpdate
|
||||
rollingUpdate:
|
||||
maxUnavailable: 6
|
||||
dns:
|
||||
provider: coredns
|
||||
update_strategy: # Available in v2.4
|
||||
strategy: RollingUpdate
|
||||
rollingUpdate:
|
||||
maxUnavailable: 20%
|
||||
maxSurge: 15%
|
||||
linear_autoscaler_params:
|
||||
cores_per_replica: 0.34
|
||||
nodes_per_replica: 4
|
||||
prevent_single_point_failure: true
|
||||
min: 2
|
||||
max: 3
|
||||
monitoring:
|
||||
provider: metrics-server
|
||||
update_strategy: # Available in v2.4
|
||||
strategy: RollingUpdate
|
||||
rollingUpdate:
|
||||
maxUnavailable: 8
|
||||
```
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: How Upgrades Work
|
||||
weight: 1
|
||||
---
|
||||
|
||||
In this section, you'll learn what happens when you edit or upgrade your RKE Kubernetes cluster. The below sections describe how each type of node is upgraded by default when a cluster is upgraded using `rke up`.
|
||||
|
||||
{{% tabs %}}
|
||||
{{% tab "RKE v1.1.0+" %}}
|
||||
|
||||
The following features are new in RKE v1.1.0:
|
||||
|
||||
- The ability to upgrade or edit a cluster without downtime for your applications.
|
||||
- The ability to manually upgrade nodes of a certain role without upgrading others.
|
||||
- The ability to restore a Kubernetes cluster to an older Kubernetes version by restoring it to a snapshot that includes the older Kubernetes version. This capability allows you to safely upgrade one type of node at a time, because if an upgrade cannot be completed by all nodes in the cluster, you can downgrade the Kubernetes version of the nodes that were already upgraded.
|
||||
|
||||
When a cluster is upgraded with `rke up`, using the default options, the following process is used:
|
||||
|
||||
1. The etcd plane gets get updated, one node at a time.
|
||||
1. Controlplane nodes get updated, one node at a time. This includes the controlplane components and worker plane components of the controlplane nodes.
|
||||
1. Worker plane components of etcd nodes get updated, one node at a time.
|
||||
1. Worker nodes get updated in batches of a configurable size. The default configuration for the maximum number of unavailable nodes is ten percent, rounded down to the nearest node, with a minimum batch size of one node.
|
||||
1. [Addons]({{<baseurl>}}/rke/latest/en/config-options/add-ons/) get upgraded one by one.
|
||||
|
||||
The following sections break down in more detail what happens when etcd nodes, controlplane nodes, worker nodes, and addons are upgraded. This information is intended to be used to help you understand the update strategy for the cluster, and may be useful when troubleshooting problems with upgrading the cluster.
|
||||
|
||||
### Upgrades of etcd Nodes
|
||||
|
||||
A cluster upgrade begins by upgrading the etcd nodes one at a time.
|
||||
|
||||
If an etcd node fails at any time, the upgrade will fail and no more nodes will be upgraded. The cluster will be stuck in an updating state and not move forward to upgrading controlplane or worker nodes.
|
||||
|
||||
### Upgrades of Controlplane Nodes
|
||||
|
||||
Controlplane nodes are upgraded one at a time by default. The maximum number of unavailable controlplane nodes can also be configured, so that they can be upgraded in batches.
|
||||
|
||||
As long as the maximum unavailable number or percentage of controlplane nodes has not been reached, Rancher will continue to upgrade other controlplane nodes, then the worker nodes.
|
||||
|
||||
If any controlplane nodes were unable to be upgraded, the upgrade will not proceed to the worker nodes.
|
||||
|
||||
### Upgrades of Worker Nodes
|
||||
|
||||
By default, worker nodes are upgraded in batches. The size of the batch is determined by the maximum number of unavailable worker nodes, configured as the `max_unavailable_worker` directive in the `cluster.yml`.
|
||||
|
||||
By default, the `max_unavailable_worker` nodes is defined as 10 percent of all worker nodes. This number can be configured as a percentage or as an integer. When defined as a percentage, the batch size is rounded down to the nearest node, with a minimum of one node.
|
||||
|
||||
For example, if you have 11 worker nodes and `max_unavailable_worker` is 25%, two nodes will be upgraded at once because 25% of 11 is 2.75. If you have two worker nodes and `max_unavailable_worker` is 1%, the worker nodes will be upgraded one at a time because the minimum batch size is one.
|
||||
|
||||
When each node in a batch returns to a Ready state, the next batch of nodes begins to upgrade. If `kubelet` and `kube-proxy` have started, the node is Ready. As long as the `max_unavailable_worker` number of nodes have not failed, Rancher will continue to upgrade other worker nodes.
|
||||
|
||||
RKE scans the cluster before starting the upgrade to find the powered down or unreachable hosts. The upgrade will stop if that number matches or exceeds the maximum number of unavailable nodes.
|
||||
|
||||
RKE will cordon each node before upgrading it, and uncordon the node afterward. RKE can also be configured to [drain](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/) nodes before upgrading them.
|
||||
|
||||
RKE will handle all worker node upgrades before upgrading any add-ons. As long as the maximum number of unavailable worker nodes is not reached, RKE will attempt to upgrade the [addons.](#upgrades-of-addons) For example, if a cluster has two worker nodes and one worker node fails, but the maximum unavailable worker nodes is greater than one, the addons will still be upgraded.
|
||||
|
||||
### Upgrades of Addons
|
||||
|
||||
The availability of your applications partly depends on the availability of [RKE addons.]({{<baseurl>}}/rke/latest/en/config-options/add-ons/) Addons are used to deploy several cluster components, including network plug-ins, the Ingress controller, DNS provider, and metrics server.
|
||||
|
||||
Because RKE addons are necessary for allowing traffic into the cluster, they will need to be updated in batches to maintain availability. You will need to configure the maximum number of unavailable replicas for each addon in the `cluster.yml` to ensure that your cluster will retain enough available replicas during an upgrade.
|
||||
|
||||
For more information on configuring the number of replicas for each addon, refer to [this section.](#replicas-for-rke-addons)
|
||||
|
||||
For an example showing how to configure the addons, refer to the [example cluster.yml.]({{<baseurl>}}/rke/latest/en/upgrades/configuring-strategy/#example-cluster-yml)
|
||||
|
||||
{{% /tab %}}
|
||||
{{% tab "RKE prior to v1.1.0" %}}
|
||||
|
||||
When a cluster is upgraded with `rke up`, using the default options, the following process is used:
|
||||
|
||||
- etcd nodes get updated first, one at a time.
|
||||
- Controlplane nodes get updated second, one at a time.
|
||||
- Worker nodes and addons get updated third, in batches of 50 or the total number of worker nodes, whichever is lower.
|
||||
- Addons get upgraded one by one.
|
||||
|
||||
### Upgrades of Controlplane and etcd Nodes
|
||||
|
||||
Controlplane and etcd nodes would be upgraded in batches of 50 nodes or the total number of controlplane nodes, whichever is lower.
|
||||
|
||||
If a node fails at any time, the upgrade will stop upgrading any other nodes and fail.
|
||||
|
||||
### Upgrades of Worker Nodes
|
||||
|
||||
Worker nodes are upgraded simultaneously, in batches of either 50 or the total number of worker nodes, whichever is lower. If a worker node fails at any time, the upgrade stops.
|
||||
|
||||
When a worker node is upgraded, it restarts several Docker processes, including the `kubelet` and `kube-proxy`. When `kube-proxy` comes up, it flushes `iptables`. When this happens, pods on this node can’t be accessed, resulting in downtime for the applications.
|
||||
|
||||
{{% /tab %}}
|
||||
{{% /tabs %}}
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Maintaining Availability for Applications During Upgrades
|
||||
weight: 1
|
||||
---
|
||||
_Available as of v1.1.0_
|
||||
|
||||
In this section, you'll learn the requirements to prevent downtime for your applications when you upgrade the cluster using `rke up`.
|
||||
|
||||
An upgrade without downtime is one in which your workloads are available on at least a single node, and all critical addon services, such as Ingress and DNS, are available during the upgrade.
|
||||
|
||||
The way that clusters are upgraded changed in RKE v1.1.0. For details, refer to [How Upgrades Work.]({{<baseurl>}}/rke/latest/en/upgrades/how-upgrades-work)
|
||||
|
||||
This availability is achieved by upgrading worker nodes in batches of a configurable size, and ensuring that your workloads run on a number of nodes that exceeds that maximum number of unavailable worker nodes.
|
||||
|
||||
To avoid downtime for your applications during an upgrade, you will need to configure your workloads to continue running despite the rolling upgrade of worker nodes. There are also requirements for the cluster architecture and Kubernetes target version.
|
||||
|
||||
1. [Kubernetes Version Requirement](#1-kubernetes-version-requirement)
|
||||
2. [Cluster Requirements](#2-cluster-requirements)
|
||||
3. [Workload Requirements](#3-workload-requirements)
|
||||
|
||||
### 1. Kubernetes Version Requirement
|
||||
|
||||
When upgrading to a newer Kubernetes version, the upgrade must be from a minor release to the next minor version, or to within the same patch release series.
|
||||
|
||||
### 2. Cluster Requirements
|
||||
|
||||
The following must be true of the cluster that will be upgraded:
|
||||
|
||||
1. The cluster has three or more etcd nodes.
|
||||
1. The cluster has two or more controlplane nodes.
|
||||
1. The cluster has two or more worker nodes.
|
||||
1. The Ingress, DNS, and other addons are schedulable to a number of nodes that exceeds the maximum number of unavailable worker nodes, also called the batch size. By default, the minimum number of unavailable worker nodes is 10 percent of worker nodes, rounded down to the nearest node, with a minimum batch size of one node.
|
||||
|
||||
### 3. Workload Requirements
|
||||
|
||||
The following must be true of the cluster's applications:
|
||||
|
||||
1. The application and Ingress are deployed across a number of nodes exceeding the maximum number of unavailable worker nodes, also called the batch size. By default, the minimum number of unavailable worker nodes is 10 percent of worker nodes, rounded down to the nearest node, with a minimum batch size of one node.
|
||||
1. The applications must make use of liveness and readiness probes.
|
||||
|
||||
For information on how to use node selectors to assign pods to nodes, refer to the [official Kubernetes documentation.](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/)
|
||||
|
||||
For information on configuring the number of replicas for each addon, refer to [this section.]({{<baseurl>}}/rke/latest/en/upgrades/configuring-strategy/)
|
||||
Reference in New Issue
Block a user