diff --git a/docs/helm.md b/docs/helm.md index 870353e8..35db6fec 100644 --- a/docs/helm.md +++ b/docs/helm.md @@ -117,7 +117,9 @@ data: To allow overriding values for packaged components that are deployed as HelmCharts (such as Canal, CoreDNS, Nginx-Ingress, etc), RKE2 supports customizing deployments via a `HelmChartConfig` resources. The `HelmChartConfig` resource must match the name and namespace of its corresponding HelmChart, and supports providing additional `valuesContent`, which is passed to the `helm` command as an additional value file. -> **Note:** HelmChart `spec.set` values override HelmChart and HelmChartConfig `spec.valuesContent` settings. +:::note +HelmChart `spec.set` values override HelmChart and HelmChartConfig `spec.valuesContent` settings. +::: For example, to customize the packaged CoreDNS configuration, you can create a file named `/var/lib/rancher/rke2/server/manifests/rke2-coredns-config.yaml` and populate it with the following content: @@ -134,3 +136,15 @@ spec: ``` You can find all the packaged Helm charts including their documentation and default values in the [RKE2 charts repository](https://github.com/rancher/rke2-charts/tree/main/charts). + +#### File Naming Requirements + +The `AddOn` name for each file in the manifest directory is derived from the file basename. +Ensure that all files within the manifests directory (or within any subdirectories) have names that are unique, and adhere to Kubernetes [object naming restrictions](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/). +Care should also be taken not to conflict with names in use by the default RKE2 packaged components, even if those components are disabled. + +An example of an error that would be reported if the file name contains underscores: +> `Failed to process config: failed to process /var/lib/rancher/rke2/server/manifests/example_manifest.yaml: + Addon.k3s.cattle.io "example_manifest" is invalid: metadata.name: Invalid value: "example_manifest": + a lowercase RFC 1123 subdomain must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character + (e.g. 'example.com', regex used for validation is '[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*')` \ No newline at end of file diff --git a/docs/install/airgap.md b/docs/install/airgap.md index 530a2c1a..885b87c5 100644 --- a/docs/install/airgap.md +++ b/docs/install/airgap.md @@ -2,10 +2,14 @@ title: Air-Gap Install --- -**Important:** If your node has NetworkManager installed and enabled, [ensure that it is configured to ignore CNI-managed interfaces.](../known_issues.md#networkmanager) - RKE2 can be installed in an air-gapped environment with two different methods. You can either deploy via the `rke2-airgap-images` tarball release artifact, or by using a private registry. +## Prerequisites + +:::warning Important +If your node has NetworkManager installed and enabled, [ensure that it is configured to ignore CNI-managed interfaces.](../known_issues.md#networkmanager) +::: + All files mentioned in the steps can be obtained from the assets of the desired released rke2 version [here](https://github.com/rancher/rke2/releases). If running on an air-gapped node with SELinux enabled, you must manually install the necessary SELinux policy RPM before performing these steps. See our [RPM Documentation](../install/methods.md#rpm) to determine what you need. @@ -24,6 +28,14 @@ If running on an air-gapped node with SELinux enabled, the following are require All the steps listed on this document must be run as the root user or through `sudo`. +If your nodes do not have an interface with a default route, a default route must be configured; even a black-hole route via a dummy interface will suffice. RKE2 requires a default route in order to auto-detect the node's primary IP, and for kube-proxy ClusterIP routing to function properly. To add a dummy route, do the following: + ``` + ip link add dummy0 type dummy + ip link set dummy0 up + ip addr add 169.254.255.254/31 dev dummy0 + ip route add default via 169.254.255.255 dev dummy0 metric 1000 + ``` + ## Tarball Method 1. Download the airgap images tarballs from the RKE release artifacts list for the version and platform of RKE2 you are using. diff --git a/docs/install/configuration.md b/docs/install/configuration.md index 2d4ee8f2..dc176386 100644 --- a/docs/install/configuration.md +++ b/docs/install/configuration.md @@ -46,7 +46,9 @@ Finally, the location of the config file can be changed either through the cli a Available as of [v1.21.2+rke2r1](https://github.com/rancher/rke2/releases/tag/v1.21.2%2Brke2r1) ::: -Multiple configuration files are supported. Configuration loads by default from `/etc/rancher/rke2/config.yaml` and `/etc/rancher/rke2/config.yaml.d/*.yaml` in alphabetical order. The last value for a given key will be used. Slices are replaced. +Multiple configuration files are supported. By default, configuration files are read from `/etc/rancher/rke2/config.yaml` and `/etc/rancher/rke2/config.yaml.d/*.yaml` in alphabetical order. + +By default, the last value found for a given key will be used. A `+` can be appended to the key to append the value to the existing string or slice, instead of replacing it. All occurrences of this key in subsequent files will also require a `+` to prevent overwriting the accumulated value. An example of multiple config files is below: @@ -60,14 +62,16 @@ node-label: # config.yaml.d/test1.yaml write-kubeconfig-mode: 600 - +node-taint: + - alice=bob:NoExecute # config.yaml.d/test2.yaml write-kubeconfig-mode: 777 node-label: - other=what - foo=three - +node-taint+: + - charlie=delta:NoSchedule ``` This results in a final configuration of: @@ -78,6 +82,9 @@ token: boop node-label: - other=what - foo=three +node-taint: + - alice=bob:NoExecute + - charlie=delta:NoSchedule ``` ## Configuring the Linux Installation Script diff --git a/docs/install/ha.md b/docs/install/ha.md index 5ee3d27b..a527e684 100644 --- a/docs/install/ha.md +++ b/docs/install/ha.md @@ -8,6 +8,14 @@ This section describes how to install a high availability (HA) RKE2 cluster. An * An odd number (three recommended) of **server nodes** that will run etcd, the Kubernetes API, and other control plane services * Zero or more **agent nodes** that are designated to run your apps and services +
Why An Odd Number Of Server Nodes? +

+An etcd cluster must be comprised of an odd number of server nodes for etcd to maintain quorum. For a cluster with n servers, quorum is (n/2)+1. For any odd-sized cluster, adding one node will always increase the number of nodes necessary for quorum. Although adding a node to an odd-sized cluster appears better since there are more machines, the fault tolerance is worse. Exactly the same number of nodes can fail without losing quorum, but there are now more nodes that can fail. +

+
+ +![High Availability](/img/rke2-production-setup.svg) + Agents register through the fixed registration address. However, when RKE2 launches the kubelet and it must connect to the Kubernetes api-server, it does so through the `rke2 agent` process, which acts as a client-side load balancer. Setting up an HA cluster requires the following steps: @@ -17,6 +25,7 @@ Setting up an HA cluster requires the following steps: 1. Join additional server nodes 1. Join agent nodes + ### 1. Configure the Fixed Registration Address Server nodes beyond the first one and all agent nodes need a URL to register against. This can be the IP or hostname of any of the server nodes, but in many cases those may change over time as nodes are created and destroyed. Therefore, you should have a stable endpoint in front of the server nodes. @@ -65,6 +74,11 @@ Note: The NGINX Ingress and Metrics Server addons will **not** be deployed when ### 3. Launch additional server nodes Additional server nodes are launched much like the first, except that you must specify the `server` and `token` parameters so that they can successfully connect to the initial server node. +:::info Matching Flags +It is important to match critical flags on your server nodes. For example, if you use the flag `--cluster-cidr=10.200.0.0/16` on your first server node, but don't set it on other server nodes, the nodes will fail to join. They will print errors such as: `failed to validate server configuration: critical configuration value mismatch.` +See [Server Configuration](../reference/server_config.md#critical-configuration-values) for more information on which flags must be set identically on server nodes. +::: + Example of RKE2 config file for additional server nodes: ```yaml diff --git a/docs/reference/server_config.md b/docs/reference/server_config.md index d3882dd3..e92f8d00 100644 --- a/docs/reference/server_config.md +++ b/docs/reference/server_config.md @@ -104,3 +104,16 @@ OPTIONS: --etcd-extra-env value (components) etcd extra environment variables [$RKE2_ETCD_EXTRA_ENV] --cloud-controller-manager-extra-env value (components) cloud-controller-manager extra environment variables [$RKE2_CLOUD_CONTROLLER_MANAGER_EXTRA_ENV]``` ``` + +## Critical Configuration Values + +The following options must be set to the same value on all servers in the cluster. Failure to do so will cause new servers to fail to join the cluster. + +* `--agent-token` +* `--cluster-cidr` +* `--cluster-dns` +* `--cluster-domain` +* `--disable-cloud-controller` +* `--disable-kube-proxy` +* `--egress-selector-mode` +* `--service-cidr` \ No newline at end of file diff --git a/static/img/logo-horizontal-rke2.svg b/static/img/logo-horizontal-rke2.svg index 1793b959..3ed8c295 100644 --- a/static/img/logo-horizontal-rke2.svg +++ b/static/img/logo-horizontal-rke2.svg @@ -9,31 +9,12 @@ viewBox="0 0 345.9976501 111.362381" style="enable-background:new 0 0 345.9976501 111.362381;" xml:space="preserve" - sodipodi:docname="logo-horizontal-rke2.svg" - inkscape:version="1.2.2 (732a01da63, 2022-12-09, custom)" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg"> + id="defs181"> + + + - - - - - - - - - diff --git a/static/img/overview.png b/static/img/overview.png index 099bf423..ecb91c3a 100644 Binary files a/static/img/overview.png and b/static/img/overview.png differ diff --git a/static/img/rke2-ha.svg b/static/img/rke2-ha.svg new file mode 100644 index 00000000..c67fc780 --- /dev/null +++ b/static/img/rke2-ha.svg @@ -0,0 +1,1474 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/static/img/rke2-production-setup.svg b/static/img/rke2-production-setup.svg new file mode 100644 index 00000000..5efd3be8 --- /dev/null +++ b/static/img/rke2-production-setup.svg @@ -0,0 +1,815 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +