public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-09-28 22:18:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into patch-32

Browse Source
This commit is contained in:
dnoland1
2019-10-21 15:29:37 -07:00
committed by GitHub
parent fdc004bc8a 17104eef21
commit 2443d01ba1
181 changed files with 1262 additions and 712 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/k3s/latest/en/_index.md
+2 -2
View File
@@ -1,6 +1,6 @@
---
title: "K3S - 5 less than k8s"
shortTitle: K3S
title: "k3s - 5 less than k8s"
shortTitle: k3s
date: 2019-02-05T09:52:46-07:00
name: "menu"
---
content/k3s/latest/en/running/_index.md → content/k3s/latest/en/advanced/_index.md
+4 -80
View File
@@ -1,9 +1,11 @@
---
title: "Running K3S"
title: "Advanced Options"
weight: 3
aliases:
- /k3s/latest/en/running/
---
This section contains information for running k3s in various environments.
This section contains advanced information describing the different ways you can run and manage k3s.
Starting the Server
------------------
@@ -36,84 +38,6 @@ INFO[2019-01-22T15:16:20.541049100-07:00] Run: k3s kubectl
The output will likely be much longer as the agent will create a lot of logs. By default the server
will register itself as a node (run the agent).
It is common and almost required these days that the control plane be part of the cluster.
To disable the agent when running the server use the `--disable-agent` flag, the agent can then be run as a separate process.
Joining Nodes
-------------
When the server starts it creates a file `/var/lib/rancher/k3s/server/node-token`.
Using the contents of that file as `K3S_TOKEN` and setting `K3S_URL` allows the node
to join as an agent using the install script:
curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=XXX sh -
When using the install script openrc logs will be created at `/var/log/k3s-agent.log`, or with systemd in `/var/log/syslog` and viewed using `journalctl -u k3s-agent`.
Or running k3s manually with the token as `NODE_TOKEN`:
k3s agent --server https://myserver:6443 --token ${NODE_TOKEN}
SystemD
-------
If you are using systemd here is a sample unit `k3s.service`:
```ini
[Unit]
Description=Lightweight Kubernetes
Documentation=https://k3s.io
After=network-online.target
[Service]
Type=notify
EnvironmentFile=/etc/systemd/system/k3s.service.env
ExecStart=/usr/local/bin/k3s server
KillMode=process
Delegate=yes
LimitNOFILE=infinity
LimitNPROC=infinity
LimitCORE=infinity
TasksMax=infinity
TimeoutStartSec=0
Restart=always
RestartSec=5s
[Install]
WantedBy=multi-user.target
```
OpenRC
------
And an example openrc `/etc/init.d/k3s`:
```bash
#!/sbin/openrc-run
depend() {
after net-online
need net
}
start_pre() {
rm -f /tmp/k3s.*
}
supervisor=supervise-daemon
name="k3s"
command="/usr/local/bin/k3s"
command_args="server >>/var/log/k3s.log 2>&1"
pidfile="/var/run/k3s.pid"
respawn_delay=5
set -o allexport
if [ -f /etc/environment ]; then source /etc/environment; fi
if [ -f /etc/rancher/k3s/k3s.env ]; then source /etc/rancher/k3s/k3s.env; fi
set +o allexport
```
Alpine Linux
------------
content/k3s/latest/en/configuration/_index.md
+4 -12
View File
@@ -86,18 +86,16 @@ password file should be recreated for the agent, or the entry removed from the s
Containerd and Docker
----------
k3s includes and defaults to containerd. Why? Because it's just plain better. If you want to
run with Docker first stop and think, "Really? Do I really want more headache?" If still
yes then you just need to run the agent with the `--docker` flag.
k3s includes and defaults to containerd. If you want to use Docker instead of containerd then you simply need to run the agent with the `--docker` flag.
k3s will generate config.toml for containerd in `/var/lib/rancher/k3s/agent/etc/containerd/config.toml`, for advanced customization for this file you can create another file called `config.toml.tmpl` in the same directory and it will be used instead.
The `config.toml.tmpl` will be treated as a Golang template file, and the `config.Node` structure is being passed to the template, the following is an example on how to use the structure to customize the configuration file https://github.com/rancher/k3s/blob/master/pkg/agent/templates/templates.go#L16-L32
Rootless
Rootless (Experimental)
--------
_**WARNING**:_ Some advanced magic, user beware
_**WARNING**:_ Experimental feature
Initial rootless support has been added but there are a series of significant usability issues surrounding it.
We are releasing the initial support for those interested in rootless and hopefully some people can help to
@@ -185,15 +183,11 @@ this should be edited as appropriate for your architecture. As of this writing m
the following images relevant to k3s: `amd64:v0.3.3`, `arm64:v0.3.2`, and `arm:v0.3.2`. Further information
on the images provided through gcr.io can be found at https://console.cloud.google.com/gcr/images/google-containers/GLOBAL.
Storage Backends
Storage Backends (Experimental)
----------------
As of version 0.6.0, k3s can support various storage backends including: SQLite (default), MySQL, Postgres, and etcd, this enhancement depends on the following arguments that can be passed to k3s server:
* `--storage-backend` _value_
Specify storage type etcd3 or kvsql [$`K3S_STORAGE_BACKEND`]
* `--storage-endpoint` _value_
Specify etcd, Mysql, Postgres, or Sqlite (default) data source name [$`K3S_STORAGE_ENDPOINT`]
@@ -271,13 +265,11 @@ The above command will use these certificates to generate the tls config to comm
Connection to etcd3 can be established using the following command:
```
--storage-backend=etcd3 \
--storage-endpoint="https://127.0.0.1:2379"
```
The above command will attempt to connect insecurely to etcd on localhost with port `2379`, you can connect securely to etcd using the following command:
```
--storage-backend=etcd3 \
--storage-endpoint="https://127.0.0.1:2379" \
--storage-cafile ca.crt \
--storage-certfile etcd.crt \
content/k3s/latest/en/installation/_index.md
+6 -339
View File
@@ -3,347 +3,14 @@ title: "Installation Options"
weight: 2
---
This section contains information on flags and environment variables used for starting a k3s cluster.
This section contains instructions for installing k3s in testing and production environments. Please ensure you have met the [Node Requirements]({{< baseurl >}}/k3s/latest/en/installation/node-requirements/) before you begin installing k3s.
Install Script
--------------
### Installation Options
The install script will attempt to download the latest release, to specify a specific
version for download we can use the `INSTALL_K3S_VERSION` environment variable, for example:
```sh
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=vX.Y.Z-rc1 sh -
```
* [Single Master Installation]({{< baseurl >}}/k3s/latest/en/installation/single-server/)
To install just the server without an agent we can add a `INSTALL_K3S_EXEC`
environment variable to the command:
```sh
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable-agent" sh -
```
Install k3s on a single Linux host. Single master installs are recommended for development and test environments, as setup is simple and the cluster doesn't have to be readily available for a user-base.
The installer can also be run without performing downloads by setting `INSTALL_K3S_SKIP_DOWNLOAD=true`, for example:
```sh
curl -sfL https://github.com/rancher/k3s/releases/download/vX.Y.Z/k3s -o /usr/local/bin/k3s
chmod 0755 /usr/local/bin/k3s
* [High Availability (HA) Installation]({{< baseurl >}}/k3s/latest/en/installation/ha/)
curl -sfL https://get.k3s.io -o install-k3s.sh
chmod 0755 install-k3s.sh
export INSTALL_K3S_SKIP_DOWNLOAD=true
./install-k3s.sh
```
The full help text for the install script environment variables are as follows:
- `K3S_*`
Environment variables which begin with `K3S_` will be preserved for the
systemd service to use. Setting `K3S_URL` without explicitly setting
a systemd exec command will default the command to "agent", and we
enforce that `K3S_TOKEN` or `K3S_CLUSTER_SECRET` is also set.
- `INSTALL_K3S_SKIP_DOWNLOAD`
If set to true will not download k3s hash or binary.
- INSTALL_K3S_SYMLINK
If set to 'skip' will not create symlinks, 'force' will overwrite,
default will symlink if command does not exist in path.
- `INSTALL_K3S_VERSION`
Version of k3s to download from github. Will attempt to download the
latest version if not specified.
- `INSTALL_K3S_BIN_DIR`
Directory to install k3s binary, links, and uninstall script to, or use
/usr/local/bin as the default
- `INSTALL_K3S_SYSTEMD_DIR`
Directory to install systemd service and environment files to, or use
/etc/systemd/system as the default
- `INSTALL_K3S_EXEC` or script arguments
Command with flags to use for launching k3s in the systemd service, if
the command is not specified will default to "agent" if `K3S_URL` is set
or "server" if not. The final systemd command resolves to a combination
of EXEC and script args ($@).
The following commands result in the same behavior:
```sh
curl ... | INSTALL_K3S_EXEC="--disable-agent" sh -s -
curl ... | INSTALL_K3S_EXEC="server --disable-agent" sh -s -
curl ... | INSTALL_K3S_EXEC="server" sh -s - --disable-agent
curl ... | sh -s - server --disable-agent
curl ... | sh -s - --disable-agent
```
- `INSTALL_K3S_NAME`
Name of systemd service to create, will default from the k3s exec command
if not specified. If specified the name will be prefixed with 'k3s-'.
- `INSTALL_K3S_TYPE`
Type of systemd service to create, will default from the k3s exec command
if not specified.
Server Options
--------------
The following information on server options is also available through `k3s server --help` :
* `--bind-address` _value_
k3s bind address (default: localhost)
* `--https-listen-port` _value_
HTTPS listen port (default: 6443)
* `--http-listen-port` _value_
HTTP listen port (for /healthz, HTTPS redirect, and port for TLS terminating LB) (default: 0)
* `--data-dir` _value_, `-d` _value_
Folder to hold state default /var/lib/rancher/k3s or ${HOME}/.rancher/k3s if not root
* `--disable-agent`
Do not run a local agent and register a local kubelet
* `--log` _value_, `-l` _value_
Log to file
* `--cluster-cidr` _value_
Network CIDR to use for pod IPs (default: "10.42.0.0/16")
* `--cluster-secret` _value_
Shared secret used to bootstrap a cluster [$`K3S_CLUSTER_SECRET`]
* `--service-cidr` _value_
Network CIDR to use for services IPs (default: "10.43.0.0/16")
* `--cluster-dns` _value_
Cluster IP for coredns service. Should be in your service-cidr range
* `--cluster-domain` _value_
Cluster Domain (default: "cluster.local")
* `--no-deploy` _value_
Do not deploy packaged components (valid items: coredns, servicelb, traefik)
* `--write-kubeconfig` _value_, `-o` _value_
Write kubeconfig for admin client to this file [$`K3S_KUBECONFIG_OUTPUT`]
* `--write-kubeconfig-mode` _value_
Write kubeconfig with this mode [$`K3S_KUBECONFIG_MODE`]
* `--tls-san` _value_
Add additional hostname or IP as a Subject Alternative Name in the TLS cert
* `--kube-apiserver-arg` _value_
Customized flag for kube-apiserver process
* `--kube-scheduler-arg` _value_
Customized flag for kube-scheduler process
* `--kube-controller-arg` _value_
Customized flag for kube-controller-manager process
* `--rootless`
(experimental) Run rootless
* `--storage-backend` _value_
Specify storage type etcd3 or kvsql [$`K3S_STORAGE_BACKEND`]
* `--storage-endpoint` _value_
Specify etcd, Mysql, Postgres, or Sqlite (default) data source name [$`K3S_STORAGE_ENDPOINT`]
* `--storage-cafile` _value_
SSL Certificate Authority file used to secure storage backend communication [$`K3S_STORAGE_CAFILE`]
* `--storage-certfile` _value_
SSL certification file used to secure storage backend communication [$`K3S_STORAGE_CERTFILE`]
* `--storage-keyfile` _value_
SSL key file used to secure storage backend communication [$`K3S_STORAGE_KEYFILE`]
* `--node-ip` _value_, `-i` _value_
(agent) IP address to advertise for node
* `--node-name` _value_
(agent) Node name [$`K3S_NODE_NAME`]
* `--docker`
(agent) Use docker instead of containerd
* `--no-flannel`
(agent) Disable embedded flannel
* `--flannel-iface` _value_
(agent) Override default flannel interface
* `--container-runtime-endpoint` _value_
(agent) Disable embedded containerd and use alternative CRI implementation
* `--pause-image` _value_
(agent) Customized pause image for containerd sandbox
* `--resolv-conf` _value_
(agent) Kubelet resolv.conf file [$`K3S_RESOLV_CONF`]
* `--kubelet-arg` _value_
(agent) Customized flag for kubelet process
* `--kube-proxy-arg` _value_
(agent) Customized flag for kube-proxy process
* `--node-label` _value_
(agent) Registering kubelet with set of labels
* `--node-taint` _value_
(agent) Registering kubelet with set of taints
Agent Options
------------------
The following information on agent options is also available through `k3s agent --help` :
* `--token` _value_, `-t` _value_
Token to use for authentication [$`K3S_TOKEN`]
* `--token-file` _value_
Token file to use for authentication [$`K3S_TOKEN_FILE`]
* `--server` _value_, `-s` _value_
Server to connect to [$`K3S_URL`]
* `--data-dir` _value_, `-d` _value_
Folder to hold state (default: "/var/lib/rancher/k3s")
* `--cluster-secret` _value_
Shared secret used to bootstrap a cluster [$`K3S_CLUSTER_SECRET`]
* `--rootless`
(experimental) Run rootless
* `--docker`
(agent) Use docker instead of containerd
* `--no-flannel`
(agent) Disable embedded flannel
* `--flannel-iface` _value_
(agent) Override default flannel interface
* `--node-name` _value_
(agent) Node name [$`K3S_NODE_NAME`]
* `--node-ip` _value_, `-i` _value
(agent) IP address to advertise for node
* `--container-runtime-endpoint` _value_
(agent) Disable embedded containerd and use alternative CRI implementation
* `--pause-image` _value_
(agent) Customized pause image for containerd sandbox
* `--resolv-conf` _value_
(agent) Kubelet resolv.conf file [$`K3S_RESOLV_CONF`]
* `--kubelet-arg` _value_
(agent) Customized flag for kubelet process
* `--kube-proxy-arg` _value_
(agent) Customized flag for kube-proxy process
* `--node-label` _value_
(agent) Registering kubelet with set of labels
* `--node-taint` _value_
(agent) Registering kubelet with set of taints
Customizing components
----------------------
As of v0.3.0 any of the following processes can be customized with extra flags:
* `--kube-apiserver-arg` _value_
(server) [kube-apiserver options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/)
* `--kube-controller-arg` _value_
(server) [kube-controller-manager options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/)
* `--kube-scheduler-arg` _value_
(server) [kube-scheduler options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-scheduler/)
* `--kubelet-arg` _value_
(agent) [kubelet options](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/)
* `--kube-proxy-arg` _value_
(agent) [kube-proxy options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-proxy/)
Adding extra arguments can be done by passing the following flags to server or agent.
For example to add the following arguments `-v=9` and `log-file=/tmp/kubeapi.log` to the kube-apiserver, you should add the following options to k3s server:
```
--kube-apiserver-arg v=9 --kube-apiserver-arg log-file=/tmp/kubeapi.log
```
Install k3s on two or more Linux hosts. High Availability installs are recommended for production environments.
content/k3s/latest/en/installation/ha/_index.md
+54
View File
@@ -0,0 +1,54 @@
---
title: "High Availability (HA) Install (Experimental)"
weight: 30
---
>**Important:** High-Availability (HA) was introduced in the v0.10.0 release of k3s and is _experimental_. Our next release plans to support HA in production environments. HA should currently only be used for testing purposes in non-production environments.
>**Note:** k3s does not utilize etcd by default so only a 2-node cluster is needed for HA at a minimum. The following will guide you through setting up a 2-node cluster with PostgreSQL. You could optionally add one or more nodes for additional redundancy. In the future we plan to add support for additional database providers.
For production environments, we recommend installing k3s in a high-availability configuration so that you can always access your cluster. This procedure walks you through setting up a 2-node cluster with k3s with an external PostgreSQL database. As of v0.10.0 release (Experimental HA) we are supporting PostgreSQL 10.7-R1 thru 11.5-R1
Installation Outline
--------------------
1. Create backend database (PostgreSQL)
2. Create master nodes
3. Create a load balancer for the master nodes
4. Join worker nodes
### Create Database
The first step for setting up High Availability (HA) is to create the database for the backend. As of v0.10.0 release (Experimental HA) we are currently supporting PostgreSQL 10.7-R1 thru 11.5-R1
### Create Master Nodes
Following the [Node Requirements]({{< baseurl >}}/k3s/latest/en/installation/node-requirements/) page, provision at least two machines.
On the first machine, run the following command to install k3s and connect it to the database.
>**Note:** You may wish to taint the master nodes. They will run the kubelet by default and be scheduleable. You can only add node labels and taints during the install process. If you wish to do this, use the `--node-taint` flag. For example `--node-taint key1=value1:NoExecute` the following examples do not include this flag.
```
curl -fL https://get.k3s.io | sh -s - server --storage-endpoint='postgres://username:password@hostname:5432/dbname' --bootstrap-save
```
Note: You may want to provide the password temporarily via a file or environment variable then destroy it or clear your bash history so the password is no longer exposed in plain text on the machine.
On the second machine, run the following command. Since we ran the first node with the `--bootstrap-save` flag the second and any additional machines will now automatically bootstrap HA.
```
curl -fL https://get.k3s.io | sh -s - server --storage-endpoint='postgres://username:password@hostname:5432/dbname'
```
Ensure that both of the nodes in a Ready state such as with `k3s kubectl get nodes`
### Create the Load Balancer
You should create a TCP Load Balancer for the master nodes. This will allow worker nodes to address any master node should one of them fail. The Load Balancer should point to each of the master nodes on port 6443 (Default port for the server).
### Join Worker Nodes
Following the [Node Requirements]({{< baseurl >}}/k3s/latest/en/installation/node-requirements/) page, provision one or more machines to fill the role of the worker node(s).
Run the following command to join a worker node to the master nodes. You can get the node-token from any of the servers at `/var/lib/rancher/k3s/server/node-token`
```
curl -sfL https://get.k3s.io | K3S_URL=https:/<FQDN_of_LB>:6443 K3S_TOKEN=XXX sh-
```
Provide the FQDN of the Load Balancer for the master nodes.
content/k3s/latest/en/installation/node-requirements/_index.md
+33
View File
@@ -0,0 +1,33 @@
---
title: Node Requirements
weight: 1
---
k3s is very lightweight, but has some minimum requirements as outlined below.
Whether you're configuring a k3s cluster to run in a single-node or high-availability (HA) setup, each node running k3s should meet the following minimum requirements. You may need more resources to fit your needs.
## Operating Systems
k3s should run on just about any flavor of Linux. However, k3s is tested on the following operating systems and their subsequent non-major releases.
* Ubuntu 16.04 (amd64)
* Ubuntu 18.04 (amd64)
* Raspian Buster (armhf)
## Hardware
Hardware requirements scale based on the size of your deployments. Minimum recommendations are outlined here.
* RAM: 512MB Minimum
* CPU: 1 Minimum
#### Disks
k3s performance depends on the performance of the database. To ensure optimal speed, we recommend using an SSD when possible. Disk performance will vary on ARM devices utilizing an SD card or eMMC.
## Networking
The k3s server needs port 6443 to be accessible by the nodes. The nodes need to be able to reach other nodes over UDP port 8472 (Flannel VXLAN). If you do not use flannel and provide your own custom CNI, then port 8472 is not needed by k3s. The node should not listen on any other port. k3s uses reverse tunneling such that the nodes make outbound connections to the server and all kubelet traffic runs through that tunnel.
IMPORTANT: The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disabled access to port 8472.
content/k3s/latest/en/installation/single-server/_index.md
+357
View File
@@ -0,0 +1,357 @@
---
title: "Single Master Install"
weight: 20
---
>**Note:** This section contains information on flags and environment variables used for starting a single-master
(non-HA) k3s cluster. A High-Availability (HA) k3s cluster is required for production. A single server install is
intended only for development and testing environments.
Installation
------------
k3s is easy to install. To install the latest version, simply run the following:
```sh
curl -sfL https://get.k3s.io
```
The install script will attempt to download the latest release, to specify a specific
version for download we can use the `INSTALL_K3S_VERSION` environment variable, for example:
```sh
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=vX.Y.Z-rc1 sh -
```
To install with a specific flag we can use the `INSTALL_K3S_EXEC`
environment variable like in this example shown below:
```sh
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--no-flannel" sh -
```
The installer can also be run without performing downloads by setting `INSTALL_K3S_SKIP_DOWNLOAD=true`, for example:
```sh
curl -sfL https://github.com/rancher/k3s/releases/download/vX.Y.Z/k3s -o /usr/local/bin/k3s
chmod 0755 /usr/local/bin/k3s
curl -sfL https://get.k3s.io -o install-k3s.sh
chmod 0755 install-k3s.sh
export INSTALL_K3S_SKIP_DOWNLOAD=true
./install-k3s.sh
```
The full help text for the install script environment variables are as follows:
- `K3S_*`
Environment variables which begin with `K3S_` will be preserved for the
systemd service to use. Setting `K3S_URL` without explicitly setting
a systemd exec command will default the command to "agent", and we
enforce that `K3S_TOKEN` or `K3S_CLUSTER_SECRET` is also set.
- `INSTALL_K3S_SKIP_DOWNLOAD`
If set to true will not download k3s hash or binary.
- `INSTALL_K3S_SYMLINK`
If set to 'skip' will not create symlinks, 'force' will overwrite,
default will symlink if command does not exist in path.
- `INSTALL_K3S_VERSION`
Version of k3s to download from github. Will attempt to download the
latest version if not specified.
- `INSTALL_K3S_BIN_DIR`
Directory to install k3s binary, links, and uninstall script to, or use
/usr/local/bin as the default
- `INSTALL_K3S_SYSTEMD_DIR`
Directory to install systemd service and environment files to, or use
/etc/systemd/system as the default
- `INSTALL_K3S_EXEC` or script arguments
Command with flags to use for launching k3s in the systemd service, if
the command is not specified will default to "agent" if `K3S_URL` is set
or "server" if not. The final systemd command resolves to a combination
of EXEC and script args ($@).
The following commands result in the same behavior:
```sh
curl ... | INSTALL_K3S_EXEC="--no-flannel" sh -s -
curl ... | INSTALL_K3S_EXEC="server --no-flannel" sh -s -
curl ... | INSTALL_K3S_EXEC="server" sh -s - --no-flannel
curl ... | sh -s - server --no-flannel
curl ... | sh -s - --no-flannel
```
- `INSTALL_K3S_NAME`
Name of systemd service to create, will default from the k3s exec command
if not specified. If specified the name will be prefixed with 'k3s-'.
- `INSTALL_K3S_TYPE`
Type of systemd service to create, will default from the k3s exec command
if not specified.
Server Options
--------------
The following information on server options is also available through `k3s server --help` :
* `--bind-address` _value_
k3s bind address (default: localhost)
* `--https-listen-port` _value_
HTTPS listen port (default: 6443)
* `--http-listen-port` _value_
HTTP listen port (for /healthz, HTTPS redirect, and port for TLS terminating LB) (default: 0)
* `--data-dir` _value_, `-d` _value_
Folder to hold state default /var/lib/rancher/k3s or ${HOME}/.rancher/k3s if not root
* `--log` _value_, `-l` _value_
Log to file
* `--cluster-cidr` _value_
Network CIDR to use for pod IPs (default: "10.42.0.0/16")
* `--cluster-secret` _value_
Shared secret used to bootstrap a cluster [$`K3S_CLUSTER_SECRET`]
* `--service-cidr` _value_
Network CIDR to use for services IPs (default: "10.43.0.0/16")
* `--cluster-dns` _value_
Cluster IP for coredns service. Should be in your service-cidr range
* `--cluster-domain` _value_
Cluster Domain (default: "cluster.local")
* `--no-deploy` _value_
Do not deploy packaged components (valid items: coredns, servicelb, traefik)
* `--write-kubeconfig` _value_, `-o` _value_
Write kubeconfig for admin client to this file [$`K3S_KUBECONFIG_OUTPUT`]
* `--write-kubeconfig-mode` _value_
Write kubeconfig with this mode [$`K3S_KUBECONFIG_MODE`]
* `--tls-san` _value_
Add additional hostname or IP as a Subject Alternative Name in the TLS cert
* `--kube-apiserver-arg` _value_
Customized flag for kube-apiserver process
* `--kube-scheduler-arg` _value_
Customized flag for kube-scheduler process
* `--kube-controller-arg` _value_
Customized flag for kube-controller-manager process
* `--rootless`
(experimental) Run rootless
* `--storage-endpoint` _value_
Specify etcd, Mysql, Postgres, or Sqlite (default) data source name [$`K3S_STORAGE_ENDPOINT`]
* `--storage-cafile` _value_
SSL Certificate Authority file used to secure storage backend communication [$`K3S_STORAGE_CAFILE`]
* `--storage-certfile` _value_
SSL certification file used to secure storage backend communication [$`K3S_STORAGE_CERTFILE`]
* `--storage-keyfile` _value_
SSL key file used to secure storage backend communication [$`K3S_STORAGE_KEYFILE`]
* `--disable-cloud-controller`
Disable k3s default cloud controller manager
* `--node-ip` _value_, `-i` _value_
(agent) IP address to advertise for node
* `--node-name` _value_
(agent) Node name [$`K3S_NODE_NAME`]
* `--docker`
(agent) Use docker instead of containerd
* `--no-flannel`
(agent) Disable embedded flannel
* `--flannel-iface` _value_
(agent) Override default flannel interface
* `--flannel-backend` _value_
(agent) Specify the flannel backend you would like to use: vxlan (default), ipsec, or wireguard
* `--container-runtime-endpoint` _value_
(agent) Disable embedded containerd and use alternative CRI implementation
* `--pause-image` _value_
(agent) Customized pause image for containerd sandbox
* `--resolv-conf` _value_
(agent) Kubelet resolv.conf file [$`K3S_RESOLV_CONF`]
* `--kubelet-arg` _value_
(agent) Customized flag for kubelet process
* `--kube-proxy-arg` _value_
(agent) Customized flag for kube-proxy process
* `--node-label` _value_
(agent) Registering kubelet with set of labels
* `--node-taint` _value_
(agent) Registering kubelet with set of taints
Agent Options
------------------
The following information on agent options is also available through `k3s agent --help` :
* `--token` _value_, `-t` _value_
Token to use for authentication [$`K3S_TOKEN`]
* `--token-file` _value_
Token file to use for authentication [$`K3S_TOKEN_FILE`]
* `--server` _value_, `-s` _value_
Server to connect to [$`K3S_URL`]
* `--data-dir` _value_, `-d` _value_
Folder to hold state (default: "/var/lib/rancher/k3s")
* `--cluster-secret` _value_
Shared secret used to bootstrap a cluster [$`K3S_CLUSTER_SECRET`]
* `--rootless`
(experimental) Run rootless
* `--docker`
(agent) Use docker instead of containerd
* `--no-flannel`
(agent) Disable embedded flannel
* `--flannel-iface` _value_
(agent) Override default flannel interface
* `--node-name` _value_
(agent) Node name [$`K3S_NODE_NAME`]
* `--node-ip` _value_, `-i` _value
(agent) IP address to advertise for node
* `--container-runtime-endpoint` _value_
(agent) Disable embedded containerd and use alternative CRI implementation
* `--pause-image` _value_
(agent) Customized pause image for containerd sandbox
* `--resolv-conf` _value_
(agent) Kubelet resolv.conf file [$`K3S_RESOLV_CONF`]
* `--kubelet-arg` _value_
(agent) Customized flag for kubelet process
* `--kube-proxy-arg` _value_
(agent) Customized flag for kube-proxy process
* `--node-label` _value_
(agent) Registering kubelet with set of labels
* `--node-taint` _value_
(agent) Registering kubelet with set of taints
Customizing components
----------------------
As of v0.3.0 any of the following processes can be customized with extra flags:
* `--kube-apiserver-arg` _value_
(server) [kube-apiserver options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/)
* `--kube-controller-arg` _value_
(server) [kube-controller-manager options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/)
* `--kube-scheduler-arg` _value_
(server) [kube-scheduler options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-scheduler/)
* `--kubelet-arg` _value_
(agent) [kubelet options](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/)
* `--kube-proxy-arg` _value_
(agent) [kube-proxy options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-proxy/)
Adding extra arguments can be done by passing the following flags to server or agent.
For example to add the following arguments `-v=9` and `log-file=/tmp/kubeapi.log` to the kube-apiserver, you should add the following options to k3s server:
```
--kube-apiserver-arg v=9 --kube-apiserver-arg log-file=/tmp/kubeapi.log
```
content/k3s/latest/en/quick-start/_index.md
+5 -24
View File
@@ -1,10 +1,9 @@
---
title: "Quick-Start"
title: "Quick-Start Guide"
weight: 1
---
There are many ways to run k3s, we cover a couple easy ways to get started in this section.
The [installation options](../installation) section will cover in greater detail how k3s can be setup.
>**Note:** The intent of this guide is to quickly launch a cluster that you can use to evaluate k3s. This guide is not intended for production environments. Production environments should utilize a High-Availability solution. The [installation options](../installation) section covers in greater detail how k3s can be setup.
Install Script
--------------
@@ -15,30 +14,12 @@ curl -sfL https://get.k3s.io | sh -
```
A kubeconfig file is written to `/etc/rancher/k3s/k3s.yaml` and the service is automatically started or restarted.
The install script will install k3s and additional utilities, such as `kubectl`, `crictl`, `k3s-killall.sh`, and `k3s-uninstall.sh`, for example:
The install script will install k3s and additional utilities, such as `kubectl`, `crictl`, `ctr`, `k3s-killall.sh`, and `k3s-uninstall.sh`.
```bash
sudo kubectl get nodes
```
To install on worker nodes and add them to the cluster, we should pass `K3S_URL` along with `K3S_TOKEN` or `K3S_CLUSTER_SECRET` environment variables. `K3S_TOKEN` is created at `/var/lib/rancher/k3s/server/node-token` on your server. Here is an example showing how to join a node:
`K3S_TOKEN` is created at `/var/lib/rancher/k3s/server/node-token` on your server.
To install on worker nodes we should pass `K3S_URL` along with
`K3S_TOKEN` or `K3S_CLUSTER_SECRET` environment variables, for example:
```bash
curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=XXX sh -
```
Manual Download
---------------
1. Download `k3s` from latest [release](https://github.com/rancher/k3s/releases/latest), x86_64, armhf, and arm64 are supported.
2. Run server.
```bash
sudo k3s server &
# Kubeconfig is written to /etc/rancher/k3s/k3s.yaml
sudo k3s kubectl get nodes
# On a different node run the below. NODE_TOKEN comes from
# /var/lib/rancher/k3s/server/node-token on your server
sudo k3s agent --server https://myserver:6443 --token ${NODE_TOKEN}
```
Note: Each machine must have a unique hostname. If your machines do not have unique hostnames, pass the `K3S_NODE_NAME` environment variable and provide a value with a valid and unique hostname for each node.
content/os/v1.x/en/_index.md
+1 -1
View File
@@ -35,7 +35,7 @@ System Docker runs a special container called **Docker**, which is another Docke
We created this separation not only for the security benefits, but also to make sure that commands like `docker rm -f $(docker ps -qa)` don't delete the entire OS.
![How it works]({{< baseurl >}}/img/os/rancheroshowitworks.png)
{{< img "/img/os/rancheroshowitworks.png" "How it works">}}
### Running RancherOS
content/os/v1.x/en/about/security/_index.md
+1 -1
View File
@@ -33,7 +33,7 @@ weight: 303
| [CVE-2017-5715](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-5715) | Systems with microprocessors utilizing speculative execution and indirect branch prediction may allow unauthorized disclosure of information to an attacker with local user access via a side-channel analysis | 6 Feb 2018 | [RancherOS v1.1.4](https://github.com/rancher/os/releases/tag/v1.1.4) using Linux v4.9.78 with the Retpoline support |
| [CVE-2017-5753](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-5753) | Systems with microprocessors utilizing speculative execution and branch prediction may allow unauthorized disclosure of information to an attacker with local user access via a side-channel analysis. | 31 May 2018 | [RancherOS v1.4.0](https://github.com/rancher/os/releases/tag/v1.4.0) using Linux v4.14.32 |
| [CVE-2018-8897](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-8897) | A statement in the System Programming Guide of the Intel 64 and IA-32 Architectures Software Developer's Manual (SDM) was mishandled in the development of some or all operating-system kernels, resulting in unexpected behavior for #DB exceptions that are deferred by MOV SS or POP SS, as demonstrated by (for example) privilege escalation in Windows, macOS, some Xen configurations, or FreeBSD, or a Linux kernel crash. | 31 May 2018 | [RancherOS v1.4.0](https://github.com/rancher/os/releases/tag/v1.4.0) using Linux v4.14.32 |
| [L1 Terminal Fault](https://www.kernel.org/doc/html/latest/admin-guide/l1tf.html) | L1 Terminal Fault is a hardware vulnerability which allows unprivileged speculative access to data which is available in the Level 1 Data Cache when the page table entry controlling the virtual address, which is used for the access, has the Present bit cleared or other reserved bits set. | 19 Sep 2018 | [RancherOS v1.4.1](https://github.com/rancher/os/releases/tag/v1.4.1) using Linux v4.14.67 |
| [CVE-2018-3620](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-3620) | L1 Terminal Fault is a hardware vulnerability which allows unprivileged speculative access to data which is available in the Level 1 Data Cache when the page table entry controlling the virtual address, which is used for the access, has the Present bit cleared or other reserved bits set. | 19 Sep 2018 | [RancherOS v1.4.1](https://github.com/rancher/os/releases/tag/v1.4.1) using Linux v4.14.67 |
| [CVE-2018-3639](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-3639) | Systems with microprocessors utilizing speculative execution and speculative execution of memory reads before the addresses of all prior memory writes are known may allow unauthorized disclosure of information to an attacker with local user access via a side-channel analysis, aka Speculative Store Bypass (SSB), Variant 4. | 19 Sep 2018 | [RancherOS v1.4.1](https://github.com/rancher/os/releases/tag/v1.4.1) using Linux v4.14.67 |
| [CVE-2018-17182](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-17182) | The vmacache_flush_all function in mm/vmacache.c mishandles sequence number overflows. An attacker can trigger a use-after-free (and possibly gain privileges) via certain thread creation, map, unmap, invalidation, and dereference operations. | 18 Oct 2018 | [RancherOS v1.4.2](https://github.com/rancher/os/releases/tag/v1.4.2) using Linux v4.14.73 |
| [CVE-2019-5736](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-5736) | runc through 1.0-rc6, as used in Docker before 18.09.2 and other products, allows attackers to overwrite the host runc binary (and consequently obtain host root access) by leveraging the ability to execute a command as root within one of these types of containers: (1) a new container with an attacker-controlled image, or (2) an existing container, to which the attacker previously had write access, that can be attached with docker exec. This occurs because of file-descriptor mishandling, related to /proc/self/exe. | 12 Feb 2019 | [RancherOS v1.5.1](https://github.com/rancher/os/releases/tag/v1.5.1) |
content/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/_index.md
+1 -1
View File
@@ -64,7 +64,7 @@ $ USER_DOCKER_VERSION=17.03.2 make release
_Available as of v1.5.0_
When building RancherOS, you have the ability to automatically start in a supported [console]({{< baseurl >}}/os/v1.x/en/installation/switching-consoles/) instead of booting into the default console and switching to your desired one.
When building RancherOS, you have the ability to automatically start in a supported console instead of booting into the default console and switching to your desired one.
Here is an example of building RancherOS and having the `alpine` console enabled:
content/os/v1.x/en/installation/running-rancheros/cloud/aws/_index.md
+6 -6
View File
@@ -25,17 +25,17 @@ Let’s walk through how to import and create a RancherOS on EC2 machine using t
1. First login to your AWS console, and go to the EC2 dashboard, click on **Launch Instance**:
![RancherOS on AWS 1]({{< baseurl >}}/img/os/Rancher_aws1.png)
{{< img "/img/os/Rancher_aws1.png" "RancherOS on AWS 1">}}
2. Select the **Community AMIs** on the sidebar and search for **RancherOS**. Pick the latest version and click **Select**.
![RancherOS on AWS 2]({{< baseurl >}}/img/os/Rancher_aws2.png)
{{< img "/img/os/Rancher_aws2.png" "RancherOS on AWS 2">}}
3. Go through the steps of creating the instance type through the AWS console. If you want to pass in a [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) file during boot of RancherOS, you'd pass in the file as **User data** by expanding the **Advanced Details** in **Step 3: Configure Instance Details**. You can pass in the data as text or as a file.
![RancherOS on AWS 6]({{< baseurl >}}/img/os/Rancher_aws6.png)
{{< img "/img/os/Rancher_aws6.png" "RancherOS on AWS 6">}}
After going through all the steps, you finally click on **Launch**, and either create a new key pair or choose an existing key pair to be used with the EC2 instance. If you have created a new key pair, download the key pair. If you have chosen an existing key pair, make sure you have the key pair accessible. Click on **Launch Instances**.
![RancherOS on AWS 3]({{< baseurl >}}/img/os/Rancher_aws3.png)
{{< img "/img/os/Rancher_aws3.png" "RancherOS on AWS 3">}}
4. Your instance will be launching and you can click on **View Instances** to see it's status.
![RancherOS on AWS 4]({{< baseurl >}}/img/os/Rancher_aws4.png)
{{< img "/img/os/Rancher_aws4.png" "RancherOS on AWS 4">}}
Your instance is now running!
![RancherOS on AWS 5]({{< baseurl >}}/img/os/Rancher_aws5.png)
{{< img "/img/os/Rancher_aws5.png" "RancherOS on AWS 5">}}
## Logging into RancherOS
content/os/v1.x/en/installation/system-services/environment/_index.md
+1 -1
View File
@@ -3,7 +3,7 @@ title: Environment
weight: 143
---
The [environment key](https://docs.docker.com/compose/yml/#environment) can be used to customize system services. When a value is not assigned, RancherOS looks up the value from the `rancher.environment` key.
The [environment key](https://docs.docker.com/compose/compose-file/#environment) can be used to customize system services. When a value is not assigned, RancherOS looks up the value from the `rancher.environment` key.
In the example below, `ETCD_DISCOVERY` will be set to `https://discovery.etcd.io/d1cd18f5ee1c1e2223aed6a1734719f7` for the `etcd` service.
content/os/v1.x/en/overview/_index.md
+1 -1
View File
@@ -35,7 +35,7 @@ System Docker runs a special container called **Docker**, which is another Docke
We created this separation not only for the security benefits, but also to make sure that commands like `docker rm -f $(docker ps -qa)` don't delete the entire OS.
![How it works]({{< baseurl >}}/img/os/rancheroshowitworks.png)
{{< img "/img/os/rancheroshowitworks.png" "How it works">}}
### Running RancherOS
content/os/v1.x/en/quick-start-guide/_index.md
+1 -1
View File
@@ -92,7 +92,7 @@ $ sudo system-docker run -d --net=host --name busydash husseingalal/busydash
```
In the command, we used `--net=host` to tell System Docker not to containerize the container's networking, and use the host’s networking instead. After running the container, you can see the monitoring server by accessing `http://<IP_OF_MACHINE>`.
![System Docker Container]({{< baseurl >}}/img/os/Rancher_busydash.png)
{{< img "/img/os/Rancher_busydash.png" "System Docker Container">}}
To make the container survive during the reboots, you can create the `/opt/rancher/bin/start.sh` script, and add the Docker start line to launch the Docker at each startup.
content/rancher/v2.x/en/admin-settings/authentication/ad/_index.md
+2 -2
View File
@@ -146,7 +146,7 @@ $ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \
This command performs an LDAP search with the search base set to the domain root (`-b "dc=acme,dc=com"`) and a filter targeting the user account (`sAMAccountNam=jdoe`), returning the attributes for said user:
![LDAP User]({{< baseurl >}}/img/rancher/ldapsearch-user.png)
{{< img "/img/rancher/ldapsearch-user.png" "LDAP User">}}
Since in this case the user's DN is `CN=John Doe,CN=Users,DC=acme,DC=com` [5], we should configure the **User Search Base** with the parent node DN `CN=Users,DC=acme,DC=com`.
@@ -179,7 +179,7 @@ $ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \
This command will inform us on the attributes used for group objects:
![LDAP Group]({{< baseurl >}}/img/rancher/ldapsearch-group.png)
{{< img "/img/rancher/ldapsearch-group.png" "LDAP Group">}}
Again, this allows us to determine the correct values to enter in the group schema configuration:
content/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup/_index.md
+14 -14
View File
@@ -9,57 +9,57 @@ Before configuring Rancher to support AD FS users, you must add Rancher as a [re
1. Open the **AD FS Management** console. Select **Add Relying Party Trust...** from the **Actions** menu and click **Start**.
<img src="{{< baseurl >}}/img/rancher/adfs/adfs-overview.png" style="width:800px;"/>
{{< img "/img/rancher/adfs/adfs-overview.png" "">}}
1. Select **Enter data about the relying party manually** as the option for obtaining data about the relying party.
<img src="{{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-2.png" style="width:600px;"/>
{{< img "/img/rancher/adfs/adfs-add-rpt-2.png" "">}}
1. Enter your desired **Display name** for your Relying Party Trust. For example, `Rancher`.
<img src="{{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-3.png" style="width:600px;"/>
{{< img "/img/rancher/adfs/adfs-add-rpt-3.png" "">}}
1. Select **AD FS profile** as the configuration profile for your relying party trust.
<img src="{{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-4.png" style="width:600px;"/>
{{< img "/img/rancher/adfs/adfs-add-rpt-4.png" "">}}
1. Leave the **optional token encryption certificate** empty, as Rancher AD FS will not be using one.
<img src="{{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-5.png" style="width:600px;"/>
{{< img "/img/rancher/adfs/adfs-add-rpt-5.png" "">}}
1. Select **Enable support for the SAML 2.0 WebSSO protocol**
and enter `https://<rancher-server>/v1-saml/adfs/saml/acs` for the service URL.
<img src="{{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-6.png" style="width:600px;"/>
{{< img "/img/rancher/adfs/adfs-add-rpt-6.png" "">}}
1. Add `https://<rancher-server>/v1-saml/adfs/saml/metadata` as the **Relying party trust identifier**.
<img src="{{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-7.png" style="width:600px;"/>
{{< img "/img/rancher/adfs/adfs-add-rpt-7.png" "">}}
1. This tutorial will not cover multi-factor authentication; please refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/configure-additional-authentication-methods-for-ad-fs) if you would like to configure multi-factor authentication.
<img src="{{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-8.png" style="width:600px;"/>
{{< img "/img/rancher/adfs/adfs-add-rpt-8.png" "">}}
1. From **Choose Issuance Authorization RUles**, you may select either of the options available according to use case. However, for the purposes of this guide, select **Permit all users to access this relying party**.
<img src="{{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-9.png" style="width:600px;"/>
{{< img "/img/rancher/adfs/adfs-add-rpt-9.png" "">}}
1. After reviewing your settings, select **Next** to add the relying party trust.
<img src="{{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-10.png" style="width:600px;"/>
{{< img "/img/rancher/adfs/adfs-add-rpt-10.png" "">}}
1. Select **Open the Edit Claim Rules...** and click **Close**.
<img src="{{< baseurl >}}/img/rancher/adfs/adfs-add-rpt-11.png" style="width:600px;"/>
{{< img "/img/rancher/adfs/adfs-add-rpt-11.png" "">}}
1. On the **Issuance Transform Rules** tab, click **Add Rule...**.
<img src="{{< baseurl >}}/img/rancher/adfs/adfs-edit-cr.png" style="width:450px;"/>
{{< img "/img/rancher/adfs/adfs-edit-cr.png" "">}}
1. Select **Send LDAP Attributes as Claims** as the **Claim rule template**.
<img src="{{< baseurl >}}/img/rancher/adfs/adfs-add-tcr-1.png" style="width:600px;"/>
{{< img "/img/rancher/adfs/adfs-add-tcr-1.png" "">}}
1. Set the **Claim rule name** to your desired name (for example, `Rancher Attributes`) and select **Active Directory** as the **Attribute store**. Create the following mapping to reflect the table below:
@@ -70,7 +70,7 @@ Before configuring Rancher to support AD FS users, you must add Rancher as a [re
| Token-Groups - Qualified by Long Domain Name | Group |
| SAM-Account-Name | Name |
<br/>
<img src="{{< baseurl >}}/img/rancher/adfs/adfs-add-tcr-2.png" style="width:600px;"/>
{{< img "/img/rancher/adfs/adfs-add-tcr-2.png" "">}}
1. Download the `federationmetadata.xml` from your AD server at:
```
content/rancher/v2.x/en/admin-settings/k8s-metadata/_index.md
+4 -4
View File
@@ -7,7 +7,7 @@ _Available as of v2.3.0_
The RKE metadata feature allows you to provision clusters with new versions of Kubernetes as soon as they are released, without upgrading Rancher. This feature is useful for taking advantage of patch versions of Kubernetes, for example, if you want to upgrade to Kubernetes v1.14.7 when your Rancher server originally supported v1.14.6.
**Note:** The Kubernetes API can change between minor versions. Therefore, we don't support introducing minor Kubernetes versions, such as introducing v1.15 when Rancher currently supports v1.14. You would need to upgrade Rancher to add support for minor Kubernetes versions.
> **Note:** The Kubernetes API can change between minor versions. Therefore, we don't support introducing minor Kubernetes versions, such as introducing v1.15 when Rancher currently supports v1.14. You would need to upgrade Rancher to add support for minor Kubernetes versions.
Rancher's Kubernetes metadata contains information specific to the Kubernetes version that Rancher uses to provision [RKE clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/). Rancher syncs the data periodically and creates custom resource definitions (CRDs) for **system images,** **service options** and **addon templates.** Consequently, when a new Kubernetes version is compatible with the Rancher server version, the Kubernetes metadata makes the new version available to Rancher for provisioning clusters. The metadata gives you an overview of the information that the [Rancher Kubernetes Engine]({{<baseurl>}}/rke/latest/en/) (RKE) uses for deploying various Kubernetes versions.
@@ -27,13 +27,13 @@ Administrators might configure the RKE metadata settings to do the following:
- Change the metadata URL that Rancher uses to sync the metadata, which is useful for air gap setups if you need to sync Rancher locally instead of with GitHub
- Prevent Rancher from auto-syncing the metadata, which is one way to prevent new and unsupported Kubernetes versions from being available in Rancher
# Refresh Kubernetes Metadata
### Refresh Kubernetes Metadata
The option to refresh the Kubernetes metadata is available for administrators by default, or for any user who has the **Manage Cluster Drivers** [global role.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
To force Rancher to refresh the Kubernetes metadata, a manual refresh action is available under **Tools > Drivers > Refresh Kubernetes Metadata** on the right side corner.
# Configuring the Metadata Synchronization
### Configuring the Metadata Synchronization
> Only administrators can change these settings.
@@ -53,7 +53,7 @@ If you don't have an air gap setup, you don't need to specify the URL or Git bra
However, if you have an [air gap setup,](#air-gap-setups) you will need to mirror the Kubernetes metadata repository in a location available to Rancher. Then you need to change the URL and Git branch in the `rke-metadata-config` settings to point to the new location of the repository.
# Air Gap Setups
### Air Gap Setups
Rancher relies on a periodic refresh of the `rke-metadata-config` to download new Kubernetes version metadata if it is supported with the current version of the Rancher server. For a table of compatible Kubernetes and Rancher versions, refer to the [service terms section.](https://rancher.com/support-maintenance-terms/all-supported-versions/rancher-v2.2.8/)
content/rancher/v2.x/en/admin-settings/rbac/locked-roles/_index.md
+1 -1
View File
@@ -27,7 +27,7 @@ If you want to prevent a role from being assigned to users, you can set it to a
You can lock roles in two contexts:
- When you're [adding a custom role](({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/).
- When you're [adding a custom role]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/).
- When you editing an existing role (see below).
1. From the **Global** view, select **Security** > **Roles**.
content/rancher/v2.x/en/admin-settings/rke-templates/enforcement/_index.md
+3 -3
View File
@@ -22,7 +22,7 @@ You might want to require new clusters to use a template to ensure that any clus
To require new clusters to use an RKE template, administrators can turn on RKE template enforcement with the following steps:
1. From the **Global** view, click the **Settings** tab.
1. Go to the `rke-template-enforcement` setting. Click the vertical **Ellipsis (...)** and click **Edit.**
1. Go to the `cluster-template-enforcement` setting. Click the vertical **Ellipsis (...)** and click **Edit.**
1. Set the value to **True** and click **Save.**
**Result:** All clusters provisioned by Rancher must use a template, unless the creator is an administrator.
@@ -32,7 +32,7 @@ To require new clusters to use an RKE template, administrators can turn on RKE t
To allow new clusters to be created without an RKE template, administrators can turn off RKE template enforcement with the following steps:
1. From the **Global** view, click the **Settings** tab.
1. Go to the `rke-template-enforcement` setting. Click the vertical **Ellipsis (...)** and click **Edit.**
1. Go to the `cluster-template-enforcement` setting. Click the vertical **Ellipsis (...)** and click **Edit.**
1. Set the value to **False** and click **Save.**
**Result:** When clusters are provisioned by Rancher, they don't need to use a template.
**Result:** When clusters are provisioned by Rancher, they don't need to use a template.
content/rancher/v2.x/en/best-practices/containers/_index.md
+1 -1
View File
@@ -32,7 +32,7 @@ When possible, use a non-privileged user when running processes within your cont
### Define Resource Limits
Apply CPU and memory limits to your pods. This can help manage the resources on your worker nodes and avoid a malfunctioning microservice from impacting other microservices.
In standard Kubernetes, you can set resource limits on the namespace level. In Rancher, you can set resource limits on the project level and they will propagate to all the namespaces within the project. For details, refer to the [Rancher docs]({{<baseurl>}}rancher/v2.x/en/project-admin/resource-quotas/).
In standard Kubernetes, you can set resource limits on the namespace level. In Rancher, you can set resource limits on the project level and they will propagate to all the namespaces within the project. For details, refer to the [Rancher docs]({{<baseurl>}}/rancher/v2.x/en/project-admin/resource-quotas/).
When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project or namespace, all containers will require a respective CPU or Memory field set during creation. To avoid setting these limits on each and every container during workload creation, a default container resource limit can be specified on the namespace.
content/rancher/v2.x/en/best-practices/deployment-strategies/_index.md
+2 -2
View File
@@ -13,7 +13,7 @@ There are two recommended deployment strategies. Each one has its own pros and c
In this deployment scenario, there is a single Rancher control plane managing Kubernetes clusters across the globe. The control plane would be run in an HA (high-availability) configuration, and there would be impact due to latencies.
![Hub and Spoke Deployment]({{< baseurl >}}/img/rancher/bpg/hub-and-spoke.png)
{{< img "/img/rancher/bpg/hub-and-spoke.png" "Hub and Spoke Deployment">}}
### Pros
@@ -30,7 +30,7 @@ In this deployment scenario, there is a single Rancher control plane managing Ku
---
In the regional deployment model a control plane is deployed in close proximity to the compute nodes.
![Regional Deployment]({{< baseurl >}}/img/rancher/bpg/regional.png)
{{< img "/img/rancher/bpg/regional.png" "Regional Deployment">}}
### Pros
content/rancher/v2.x/en/cluster-admin/editing-clusters/_index.md
+4 -2
View File
@@ -61,9 +61,11 @@ When editing clusters, clusters that are [launched using RKE]({{< baseurl >}}/ra
### Upgrading Kubernetes
Following an upgrade to the latest version of Rancher, you can update your existing clusters to use the latest supported version of Kubernetes. Before a new version of Rancher is released, it's tested with the latest versions of Kubernetes to ensure compatibility.
Following an upgrade to the latest version of Rancher, you can update your existing clusters to use the latest supported version of Kubernetes.
As of Rancher v2.3.0, the Kubernetes metadata feature was added, which allows you to use newer Kubernetes versions as soon as they are released, without upgrading Rancher. For details, refer to the [section on Kubernetes metadata.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/k8s-metadata)
Before a new version of Rancher is released, it's tested with the latest minor versions of Kubernetes to ensure compatibility. For example, Rancher v2.3.0 is was tested with Kubernetes v1.15.4, v1.14.7, and v1.13.11. For details on which versions of Kubernetes were tested on each Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/all-supported-versions/rancher-v2.3.0/)
As of Rancher v2.3.0, the Kubernetes metadata feature was added, which allows Rancher to ship Kubernetes patch versions without upgrading Rancher. For details, refer to the [section on Kubernetes metadata.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/k8s-metadata)
>**Recommended:** Before upgrading Kubernetes, [backup your cluster]({{< baseurl >}}/rancher/v2.x/en/backups).
content/rancher/v2.x/en/cluster-admin/tools/istio/setup/_index.md
+2 -2
View File
@@ -14,7 +14,7 @@ If you use Istio for traffic management, you will need to allow external traffic
1. [Enable Istio in the cluster.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-cluster)
1. [Enable Istio in all the namespaces where you want to use it.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-namespace)
1. [Select the nodes where the main Istio components will be deployed.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/node-selectors)
1. [Add deployments and services that have the Istio sidecar injected.](#deploy-workloads-in-the-cluster)
1. [Add deployments and services that have the Istio sidecar injected.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/deploy-workloads)
1. [Set up the Istio gateway. ]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/gateway)
1. [Set up Istio's components for traffic management.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/set-up-traffic-management)
1. [Generate traffic and see Istio in action.](#generate-traffic-and-see-istio-in-action)
@@ -25,4 +25,4 @@ This guide assumes you have already [installed Rancher,]({{<baseurl>}}/rancher/v
The nodes in your cluster must meet the [CPU and memory requirements.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/istio/#cpu-and-memory-requirements)
The workloads and services that you want to be controlled by Istio must meet [Istio's requirements.](https://istio.io/docs/setup/additional-setup/requirements/)
The workloads and services that you want to be controlled by Istio must meet [Istio's requirements.](https://istio.io/docs/setup/additional-setup/requirements/)
content/rancher/v2.x/en/cluster-admin/tools/istio/setup/gateway/_index.md
+28 -1
View File
@@ -53,6 +53,33 @@ spec:
protocol: HTTP
hosts:
- "*"
---
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
name: bookinfo
spec:
hosts:
- "*"
gateways:
- bookinfo-gateway
http:
- match:
- uri:
exact: /productpage
- uri:
prefix: /static
- uri:
exact: /login
- uri:
exact: /logout
- uri:
prefix: /api/v1/products
route:
- destination:
host: productpage
port:
number: 9080
```
**Result:** You have configured your gateway resource so that Istio can receive traffic from outside the cluster.
@@ -100,4 +127,4 @@ In the gateway resource, the selector refers to Istio's default ingress controll
1. Within `istio-system`, there is a workload named `istio-ingressgateway`.
1. Click the name of this workload and go to the **Labels and Annotations** section. You should see that it has the key `istio` and the value `ingressgateway`. This confirms that the selector in the Gateway resource matches Istio's default ingress controller.
### [Next: Set up Istio's Components for Traffic Management]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/set-up-traffic-management)
### [Next: Set up Istio's Components for Traffic Management]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/set-up-traffic-management)
content/rancher/v2.x/en/cluster-admin/tools/notifiers/_index.md
+1
View File
@@ -65,6 +65,7 @@ _Available as of v2.2.0_
1. Select the **Recipient Type** and then enter a corresponding id to **Default Recipient** field, for example, the party id, tag id or user account that you want to receive the notification. You could get contact information from [Contacts page](https://work.weixin.qq.com/wework_admin/frame#contacts).
{{% /accordion %}}
1. _Available as of v2.3.0_ - Select **Enable** for **Send Resolved Alerts** if you wish to notify about resolved alerts.
1. Click **Add** to complete adding the notifier.
**Result:** Your notifier is added to Rancher.
content/rancher/v2.x/en/cluster-admin/volumes-and-storage/examples/vsphere/_index.md
+2 -2
View File
@@ -23,7 +23,7 @@ In order to provision vSphere volumes in a cluster created with the [Rancher Kub
3. Enter a **Name** for the class.
4. Under **Provisioner**, select **VMWare vSphere Volume**.
![vsphere-storage-class]({{< baseurl >}}/img/rancher/vsphere-storage-class.png)
{{< img "/img/rancher/vsphere-storage-class.png" "vsphere-storage-class">}}
5. Optionally, specify additional properties for this storage class under **Parameters**. Refer to the [vSphere storage documentation](https://vmware.github.io/vsphere-storage-for-kubernetes/documentation/storageclass.html) for details.
5. Click **Save**.
@@ -37,7 +37,7 @@ In order to provision vSphere volumes in a cluster created with the [Rancher Kub
5. Assign a **Name** for the claim, ie. `test-volume` and select the vSphere storage class created in the previous step.
6. Enter the required **Capacity** for the volume. Then click **Define**.
![workload-add-volume]({{< baseurl >}}/img/rancher/workload-add-volume.png)
{{< img "/img/rancher/workload-add-volume.png" "workload-add-volume">}}
7. Assign a path in the **Mount Point** field. This is the full path where the volume will be mounted in the container file system, e.g. `/persistent`.
8. Click **Launch** to create the workload.
content/rancher/v2.x/en/cluster-provisioning/rancher-agents/_index.md
+1 -1
View File
@@ -14,7 +14,7 @@ The `cattle-cluster-agent` is used to connect to the Kubernetes API of [Rancher
### cattle-node-agent
The `cattle-node-agent` is used to interact with nodes in a [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) cluster when performing cluster operations. Examples of cluster operations are upgrading Kubernetes version and creating/restoring etcd snapshots. The `cattle-node-agent` is deployed using a DaemonSet resource to make sure it runs on every node. The `cattle-node-agent` is used as fallback option to connect to the Kubernets API of [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) clusters when `cattle-cluster-agent` is unavailable.
The `cattle-node-agent` is used to interact with nodes in a [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) cluster when performing cluster operations. Examples of cluster operations are upgrading Kubernetes version and creating/restoring etcd snapshots. The `cattle-node-agent` is deployed using a DaemonSet resource to make sure it runs on every node. The `cattle-node-agent` is used as fallback option to connect to the Kubernetes API of [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) clusters when `cattle-cluster-agent` is unavailable.
> **Note:** In Rancher v2.2.4 and lower, the `cattle-node-agent` pods did not tolerate all taints, causing Kubernetes upgrades to fail on these nodes. The fix for this has been included in Rancher v2.2.5 and higher.
content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/_index.md
+44 -1
View File
@@ -10,9 +10,10 @@ Use {{< product >}} to create a Kubernetes cluster in Amazon EC2.
## Prerequisites
- AWS EC2 Access Key and Secret key that will be used to create the instances. See [Amazon Documentation: Creating Access Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) how to create an Access Key and Secret Key.
- IAM Policy created to add to the user of the Access Key And Secret Key. See [Amazon Documentation: Creating IAM Policies (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) how to create an IAM policy. See our two example JSON policies below:
- IAM Policy created to add to the user of the Access Key And Secret Key. See [Amazon Documentation: Creating IAM Policies (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) how to create an IAM policy. See our three example JSON policies below:
- [Example IAM Policy](#example-iam-policy)
- [Example IAM Policy with PassRole](#example-iam-policy-with-passrole) (needed if you want to use [Kubernetes Cloud Provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers) or want to pass an IAM Profile to an instance)
- [Example IAM Policy to allow encrypted EBS volumes](#example-iam-policy-to-allow-encrypted-ebs-volumes)
- IAM Policy added as Permission to the user. See [Amazon Documentation: Adding Permissions to a User (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) how to attach it to an user.
@@ -157,3 +158,45 @@ Use {{< product >}} to create a Kubernetes cluster in Amazon EC2.
]
}
```
### Example IAM Policy to allow encrypted EBS volumes
``` json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKeyWithoutPlaintext",
"kms:Encrypt",
"kms:DescribeKey",
"kms:CreateGrant",
"ec2:DetachVolume",
"ec2:AttachVolume",
"ec2:DeleteSnapshot",
"ec2:DeleteTags",
"ec2:CreateTags",
"ec2:CreateVolume",
"ec2:DeleteVolume",
"ec2:CreateSnapshot"
],
"Resource": [
"arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*",
"arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*",
"arn:aws:ec2:REGION:AWS_ACCOUNT_ID:snapshot/*",
"arn:aws:kms:REGION:AWS_ACCOUNT_ID:key/KMS_KEY_ID"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:DescribeInstances",
"ec2:DescribeTags",
"ec2:DescribeVolumes",
"ec2:DescribeSnapshots"
],
"Resource": "*"
}
]
}
```
content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/vsphere/_index.md
+7 -7
View File
@@ -38,21 +38,21 @@ The following steps create a role with the required privileges and then assign i
3. Create a new role. Give it a name and select the privileges listed in the [permissions table](#annex-vsphere-permissions).
![image]({{< baseurl >}}/img/rancher/rancherroles1.png)
{{< img "/img/rancher/rancherroles1.png" "image">}}
4. Go to the **Users and Groups** tab.
5. Create a new user. Fill out the form and then click **OK**. Make sure to note the username and password, as you will need it when configuring node templates in Rancher.
![image]({{< baseurl >}}/img/rancher/rancheruser.png)
{{< img "/img/rancher/rancheruser.png" "image">}}
6. Go to the **Global Permissions** tab.
7. Create a new Global Permission. Add the user you created earlier and assign it the role you created earlier. Click **OK**.
![image]({{< baseurl >}}/img/rancher/globalpermissionuser.png)
{{< img "/img/rancher/globalpermissionuser.png" "image">}}
![image]({{< baseurl >}}/img/rancher/globalpermissionrole.png)
{{< img "/img/rancher/globalpermissionrole.png" "image">}}
## Creating vSphere Clusters
@@ -79,13 +79,13 @@ To create a cluster, you need to create at least one vSphere [node template]({{<
7. Ensure that the [OS ISO URL](#instance-options) contains the URL of a VMware ISO release for RancherOS (`rancheros-vmware.iso`).
![image]({{< baseurl >}}/img/rancher/vsphere-node-template-1.png)
{{< img "/img/rancher/vsphere-node-template-1.png" "image">}}
8. **Optional:** Provide a set of [Configuration Parameters](#instance-options) for the VMs.
9. Under **Scheduling**, enter the name/path of the **Data Center** to create the VMs in, the name of the **VM Network** to attach to, and the name/path of the **Datastore** to store the disks in.
![image]({{< baseurl >}}/img/rancher/vsphere-node-template-2.png)
{{< img "/img/rancher/vsphere-node-template-2.png" "image">}}
10. **Optional:** Assign labels to the VMs that can be used as a base for scheduling rules in the cluster.
@@ -111,7 +111,7 @@ After you've created a template, you can use it stand up the vSphere cluster its
6. {{< step_create-cluster_node-pools >}}
![image]({{< baseurl >}}/img/rancher/vsphere-cluster-create-1.png)
{{< img "/img/rancher/vsphere-cluster-create-1.png" "Image">}}
7. Review your configuration, then click **Create**.
content/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/_index.md
+1 -1
View File
@@ -63,7 +63,7 @@ The registry configuration here is applied during the provisioning of the cluste
- **System images** are components needed to maintain the Kubernetes cluster.
- **Add-ons** are used to deploy several cluster components, including network plug-ins, the ingress controller, the DNS provider, or the metrics server.
To deploy workloads that pull images from a private registry, you will need to [set up your own Kubernetes registry]({{<baseurl>}}rancher/v2.x/en/k8s-in-rancher/registries/) for your project.
To deploy workloads that pull images from a private registry, you will need to [set up your own Kubernetes registry]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/registries/) for your project.
See the [RKE documentation on private registries]({{< baseurl >}}/rke/latest/en/config-options/private-registries/) for more information on the private registry for components applied during the provisioning of the cluster.
content/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/_index.md
+31 -27
View File
@@ -18,6 +18,7 @@ For a summary of Kubernetes features supported in Windows, see the Kubernetes do
This guide covers the following topics:
<!-- TOC -->
- [Prerequisites](#prerequisites)
- [Requirements](#requirements-for-windows-clusters)
- [OS and Docker](#os-and-docker-requirements)
@@ -27,7 +28,7 @@ This guide covers the following topics:
- [Containers](#container-requirements)
- [Tutorial: How to Create a Cluster with Windows Support](#tutorial-how-to-create-a-cluster-with-windows-support)
- [Configuration for Storage Classes in Azure](#configuration-for-storage-classes-in-azure)
<!-- /TOC -->
<!-- /TOC -->
# Prerequisites
@@ -41,7 +42,10 @@ For a custom cluster, the general node requirements for networking, operating sy
### OS and Docker Requirements
In order to add Windows worker nodes to a cluster, the node must be running Windows Server 2019 (i.e. core version 1903 or above) and [Docker 19.03.]({{<baseurl>}}/rancher/v2.x/en/installation/requirements/)
In order to add Windows worker nodes to a cluster, the node must be running one of the following Windows Server versions and the corresponding version of Docker:
- Windows Server core version 1809 and Docker 18.09
- Windows server core version 1903 and Docker 19.03
The nodes must run Docker Engine - Enterprise Edition (EE).
@@ -49,10 +53,10 @@ Nodes with Windows Server core version 1809 should use Docker EE-basic 18.09.
Nodes with Windows Server core version 1903 should use Docker EE-basic 19.03.
>**Notes:**
> **Notes:**
>
>- If you are using AWS, Rancher recommends *Microsoft Windows Server 2019 Base with Containers* as the Amazon Machine Image (AMI).
>- If you are using GCE, Rancher recommends *Windows Server 2019 Datacenter for Containers* as the OS image.
> - If you are using AWS, Rancher recommends _Microsoft Windows Server 2019 Base with Containers_ as the Amazon Machine Image (AMI).
> - If you are using GCE, Rancher recommends _Windows Server 2019 Datacenter for Containers_ as the OS image.
### Node Requirements
@@ -84,15 +88,15 @@ We recommend the minimum three-node architecture listed in the table below, but
<a id="guide-architecture"></a>
Node | Operating System | Kubernetes Cluster Role(s) | Purpose
--------|------------------|----------------------------|--------
Node 1 | Linux (Ubuntu Server 18.04 recommended) | [Control Plane]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#control-plane-nodes), [etcd]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#etcd-nodes), [Worker]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#worker-nodes) | Manage the Kubernetes cluster
Node 2 | Linux (Ubuntu Server 18.04 recommended) | [Worker]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#worker-nodes) | Support the Rancher Cluster agent, Metrics server, DNS, and Ingress for the cluster
Node 3 | Windows (Windows Server 2019 required) | [Worker]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#worker-nodes) | Run your Windows containers
| Node | Operating System | Kubernetes Cluster Role(s) | Purpose |
| ------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Node 1 | Linux (Ubuntu Server 18.04 recommended) | [Control Plane]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#control-plane-nodes), [etcd]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#etcd-nodes), [Worker]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#worker-nodes) | Manage the Kubernetes cluster |
| Node 2 | Linux (Ubuntu Server 18.04 recommended) | [Worker]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#worker-nodes) | Support the Rancher Cluster agent, Metrics server, DNS, and Ingress for the cluster |
| Node 3 | Windows (Windows Server core version 1809 or above) | [Worker]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#worker-nodes) | Run your Windows containers |
### Container Requirements
Windows requires that containers must be built on the same Windows Server version that they are being deployed on. Therefore, containers must be built on Windows Server 2019 core version 1903. If you have existing containers built for an earlier Windows Server 2019 core version, they must be re-built on Windows Server 2019 core version 1903.
Windows requires that containers must be built on the same Windows Server version that they are being deployed on. Therefore, containers must be built on Windows Server core version 1809 or above. If you have existing containers built for an earlier Windows Server core version, they must be re-built on Windows Server core version 1809 or above.
# Tutorial: How to Create a Cluster with Windows Support
@@ -103,11 +107,12 @@ When you provision a custom cluster with Rancher, you will add nodes to the clus
To set up a custom cluster with support for Windows nodes and containers, you will need to complete the tasks below.
<!-- TOC -->
1. [Provision Hosts](#1-provision-hosts)
1. [Create the Custom Cluster](#2-create-the-custom-cluster)
1. [Add Nodes to the Cluster](#3-add-nodes-to-the-cluster)
1. [Optional: Configuration for Azure Files](#5-optional-configuration-for-azure-files)
<!-- /TOC -->
<!-- /TOC -->
# 1. Provision Hosts
@@ -125,11 +130,11 @@ You will provision three nodes:
- A second Linux node, which will be another worker node
- The Windows node, which will run your Windows containers as a worker node
Node | Operating System
-----|-----------------
Node 1 | Linux (Ubuntu Server 18.04 recommended)
Node 2 | Linux (Ubuntu Server 18.04 recommended)
Node 3 | Windows (Windows Server 2019 required)
| Node | Operating System |
| ------ | ------------------------------------------------------------ |
| Node 1 | Linux (Ubuntu Server 18.04 recommended) |
| Node 2 | Linux (Ubuntu Server 18.04 recommended) |
| Node 3 | Windows (Windows Server core version 1809 or above required) |
If your nodes are hosted by a **Cloud Provider** and you want automation support such as loadbalancers or persistent storage devices, your nodes have additional configuration requirements. For details, see [Selecting Cloud Providers.]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers)
@@ -185,8 +190,7 @@ It may take a few minutes for the node to be registered in your cluster.
### Add Linux Worker Node
After the initial provisioning of your custom cluster, your cluster only has a single Linux host. Next, we add another Linux `worker` host, which will be used to support *Rancher cluster agent*, *Metrics server*, *DNS* and *Ingress* for your cluster.
After the initial provisioning of your custom cluster, your cluster only has a single Linux host. Next, we add another Linux `worker` host, which will be used to support _Rancher cluster agent_, _Metrics server_, _DNS_ and _Ingress_ for your cluster.
1. From the **Global** view, click **Clusters.**
@@ -206,11 +210,11 @@ After the initial provisioning of your custom cluster, your cluster only has a s
> **Note:** Taints on Linux Worker Nodes
>
>For each Linux worker node added into the cluster, the following taints will be added to Linux worker node. By adding this taint to the Linux worker node, any workloads added to the windows cluster will be automatically scheduled to the Windows worker node. If you want to schedule workloads specifically onto the Linux worker node, you will need to add tolerations to those workloads.
> For each Linux worker node added into the cluster, the following taints will be added to Linux worker node. By adding this taint to the Linux worker node, any workloads added to the windows cluster will be automatically scheduled to the Windows worker node. If you want to schedule workloads specifically onto the Linux worker node, you will need to add tolerations to those workloads.
>Taint Key | Taint Value | Taint Effect
>---|---|---
>`cattle.io/os` | `linux` | `NoSchedule`
> | Taint Key | Taint Value | Taint Effect |
> | -------------- | ----------- | ------------ |
> | `cattle.io/os` | `linux` | `NoSchedule` |
### Add a Windows Worker Node
@@ -238,11 +242,11 @@ If you are using Azure VMs for your nodes, you can use [Azure files](https://doc
In order to have the Azure platform create the required storage resources, follow these steps:
1. [Configure the Azure cloud provider.]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/#azure)
1. [Configure the Azure cloud provider.]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/#azure)
1. Configure `kubectl` to connect to your cluster.
1. Configure `kubectl` to connect to your cluster.
1. Copy the `ClusterRole` and `ClusterRoleBinding` manifest for the service account:
1. Copy the `ClusterRole` and `ClusterRoleBinding` manifest for the service account:
---
apiVersion: rbac.authorization.k8s.io/v1
@@ -267,7 +271,7 @@ In order to have the Azure platform create the required storage resources, follo
name: persistent-volume-binder
namespace: kube-system
1. Create these in your cluster using one of the follow command.
1. Create these in your cluster using one of the follow command.
```
# kubectl create -f <MANIFEST>
content/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/docs-for-2.1-and-2.2/_index.md
+3 -5
View File
@@ -23,8 +23,8 @@ For a summary of Kubernetes features supported in Windows, see [Using Windows in
## OS and Container Requirements
- For clusters provisioned with Rancher v2.1.x and v2.2.x, containers must run on Windows Server 1803.
- You must build containers on Windows Server 1803 to run these containers on Windows Server 1803.
- For clusters provisioned with Rancher v2.1.x and v2.2.x, containers must run on Windows Server 1809 or above.
- You must build containers on a Windows Server core version 1809 or above to run these containers on the same server version.
## Objectives for Creating Cluster with Windows Support
@@ -55,7 +55,7 @@ Node | Operating System | Future Cluster Role(s)
--------|------------------|------
Node 1 | Linux (Ubuntu Server 16.04 recommended) | [Control Plane]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#control-plane-nodes), [etcd]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#etcd), [Worker]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#worker-nodes)
Node 2 | Linux (Ubuntu Server 16.04 recommended) | [Worker]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#worker-nodes) (This node is used for Ingress support)
Node 3 | Windows (*Windows Server 1803 required*) | [Worker]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#worker-nodes)
Node 3 | Windows (Windows Server core version 1809 or above) | [Worker]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/#worker-nodes)
### Requirements
@@ -103,8 +103,6 @@ Option | Setting
Node Operating System | Linux
Node Roles | etcd <br/> Control Plane <br/> Worker
![Recommended Linux Control Plane Configuration]({{< baseurl >}}/img/rancher/linux-control-plane.png)
When you're done with these configurations, resume [Creating a Cluster with Custom Nodes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/#create-the-custom-cluster) from [step 8]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/#step-8).
content/rancher/v2.x/en/faq/_index.md
+36 -91
View File
@@ -7,121 +7,66 @@ aliases:
This FAQ is a work in progress designed to answers the questions our users most frequently ask about Rancher v2.x.
See [Technical FAQ]({{< baseurl >}}/rancher/v2.x/en/faq/technical/), for frequently asked technical questions.
See [Technical FAQ]({{<baseurl>}}/rancher/v2.x/en/faq/technical/), for frequently asked technical questions.
### Kubernetes
<br>
#### What does it mean when you say Rancher v2.x is built on Kubernetes?
Rancher v2.x is a complete container management platform built 100% on Kubernetes leveraging its Custom Resource and Controller framework. All features are written as a CustomResourceDefinition (CRD) which extends the existing Kubernetes API and can leverage native features such as RBAC.
#### Do you plan to implement upstream Kubernetes, or continue to work on your own fork?
We're still going to provide our distribution when you select the default option of having us create your Kubernetes cluster, but it will be very close to upstream.
#### Does this release mean that we need to re-train our support staff in Kubernetes?
Yes. Rancher will offer the native Kubernetes functionality via `kubectl` but will also offer our own UI dashboard to allow you to deploy Kubernetes workload without having to understand the full complexity of Kubernetes. However, to fully leverage Kubernetes, we do recommend understanding Kubernetes. We do plan on improving our UX with subsequent releases to make Kubernetes easier to use.
#### So, wait. Is a Rancher compose going to make a Kubernetes pod? Do we have to learn both now? We usually use the filesystem layer of files, not the UI.
No. Unfortunately, the differences were enough such that we cannot support Rancher compose anymore in 2.x. We will be providing both a tool and guides to help with this migration.
### Cattle
### How does Rancher v2.x affect Cattle?
Cattle will not supported in v2.x as Rancher has been re-architected to be based on Kubernetes. You can, however, expect majority of Cattle features you use will exist and function similarly on Kubernetes. We will develop migration tools in Rancher v2.1 to help you transform your existing Rancher Compose files into Kubernetes YAML files.
#### Can I migrate existing Cattle workloads into Kubernetes?
Yes. In the upcoming Rancher v2.1 release we will provide a tool to help translate existing Cattle workloads in Compose format to Kubernetes YAML format. You will then be able to deploy those workloads on the v2.x platform.
### Environments & Clusters
#### Can I still create templates for environments and clusters?
Starting with 2.0, the concept of an environment has now been changed to a Kubernetes cluster as going forward, only the Kubernetes orchestration engine is supported.
Kubernetes RKE Templates is on our roadmap for 2.x. Please refer to our Release Notes and documentation for all the features that we currently support.
#### Can you still add an existing host to an environment? (i.e. not provisioned directly from Rancher)
Yes. We still provide you with the same way of executing our Rancher agents directly on hosts.
### Upgrading/Migrating
#### How would the migration from v1.x to v2.x work?
Due to the technical difficulty in transforming a Docker container into a pod running Kubernetes, upgrading will require users to "replay" those workloads from v1.x into new v2.x environments. We plan to ship with a tool in v2.1 to translate existing Rancher Compose files into Kubernetes YAML files. You will then be able to deploy those workloads on the v2.x platform.
#### Is it possible to upgrade from Rancher v1.x to v2.x without any disruption to Cattle and Kubernetes clusters?
At this time, we are still exploring this scenario and taking feedback. We anticipate that you will need to launch a new Rancher instance and then relaunch on v2.x. Once you've moved to v2.x, upgrades will be in place, as they are in v1.6.
#### Can I import OpenShift Kubernetes clusters into v2.x?
Our goal is to run any upstream Kubernetes clusters. Therefore, Rancher v2.x should work with OpenShift, but we haven't tested it yet.
### Support
#### What about Rancher v1.6? Are you planning some long-term support releases?
That is definitely the focus of the v1.6 stream. We're continuing to improve that release, fix bugs, and maintain it for the next 12 months at a minimum. We will extend that time period, if necessary, depending on how quickly users move to v2.1.
#### Does Rancher v2.x support Docker Swarm and Mesos as environment types?
**Does Rancher v2.x support Docker Swarm and Mesos as environment types?**
When creating an environment in Rancher v2.x, Swarm and Mesos will no longer be standard options you can select. However, both Swarm and Mesos will continue to be available as Catalog applications you can deploy. It was a tough decision to make but, in the end, it came down to adoption. For example, out of more than 15,000 clusters, only about 200 or so are running Swarm.
#### Is it possible to manage Azure Kubernetes Services with Rancher v2.x?
<br>
**Is it possible to manage Azure Kubernetes Services with Rancher v2.x?**
Yes.
#### What about Windows support?
<br>
With [Rancher 2.3.0 Preview 1](https://forums.rancher.com/t/rancher-release-v2-3-0-alpha3-preview-of-windows-containers/14260), we have enabled the support for Windows Server 2019 containers. The technology is in preview mode but we intend to make it GA later this year. Please refer to our documentation and Release Notes to get the latest information on this feature.
**Does Rancher support Windows?**
#### Are you planning on supporting Istio in Rancher v2.x?
As of Rancher 2.3.0, we support Windows Server 1809 containers. For details on how to set up a cluster with Windows worker nodes, refer to the section on [configuring custom clusters for Windows.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/)
[Rancher 2.3.0 Preview 2](https://forums.rancher.com/t/rancher-release-v2-3-0-alpha5-preview-of-istio/14585/2) has support for Istio. Please refer to our documentation and Release Notes to get the latest information on this feature.
Furthermore, Istio is implemented in our micro-PaaS "Rio", which works on Rancher 2.x along wtih any CNCF compliant Kubernetes cluster. You can read more about it [here](https://rio.io/).
<br>
#### Will Rancher v2.x support Hashicorp's Vault for storing secrets?
**Does Rancher support Istio?**
As of Rancher 2.3.0, we support [Istio.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/)
Furthermore, Istio is implemented in our micro-PaaS "Rio", which works on Rancher 2.x along with any CNCF compliant Kubernetes cluster. You can read more about it [here](https://rio.io/)
<br>
**Will Rancher v2.x support Hashicorp's Vault for storing secrets?**
Secrets management is on our roadmap but we haven't assigned it to a specific release yet.
#### Does Rancher v2.x support RKT containers as well?
<br>
**Does Rancher v2.x support RKT containers as well?**
At this time, we only support Docker.
#### Will Rancher v2.x support Calico, Contiv, Contrail, Flannel, Weave net, etc., for embedded and imported Kubernetes?
<br>
We will provide the ability to use Calico, Canal, and Flannel, but always refer to the [Rancher Support Matrix](https://rancher.com/support-maintenance-terms/) on what is officially supported.
**Does Rancher v2.x support Calico, Contiv, Contrail, Flannel, Weave net, etc., for embedded and imported Kubernetes?**
#### Are you planning on supporting Traefik for existing setups?
Out-of-the-box, Rancher provides the following CNI network providers for Kubernetes clusters: Canal, Flannel, Calico and Weave (Weave is available as of v2.2.0). Always refer to the [Rancher Support Matrix](https://rancher.com/support-maintenance-terms/) for details about what is officially supported.
<br>
**Are you planning on supporting Traefik for existing setups?**
We don't currently plan on providing embedded Traefik support, but we're still exploring load-balancing approaches.
### General
<br>
#### Can we still add our own infrastructure services, which had a separate view/filter in 1.6.x?
**Can I import OpenShift Kubernetes clusters into v2.x?**
Yes. We plan to eventually enhance this feature so you can manage Kubernetes storage, networking, and its vast ecosystem of add-ons.
Our goal is to run any upstream Kubernetes clusters. Therefore, Rancher v2.x should work with OpenShift, but we haven't tested it yet.
#### Are you going to integrate Longhorn?
<br>
Yes. Longhorn was on a bit of a hiatus while we were working on v2.0. We plan to re-engage on the project once v2.0 reaches GA (general availability).
**Are you going to integrate Longhorn?**
#### Are there changes to default roles available now or going forward? Will the Kubernetes alignment impact plans for roles/RBAC?
The default roles will be expanded to accommodate the new Rancher 2.x features, and will also take advantage of the Kubernetes RBAC (Role-Based Access Control) capabilities to give you more flexibility.
#### Will there be any functions like network policies to separate a front-end container from a back-end container through some kind of firewall in v2.x?
Yes. You can do so by leveraging Kubernetes' network policies.
#### What about the CLI? Will that work the same way with the same features?
Yes. Definitely.
#### If we use Kubernetes native YAML files for creating resources, should we expect that to work as expected, or do we need to use Rancher/Docker compose files to deploy infrastructure?
Absolutely.
Yes. Longhorn was on a bit of a hiatus while we were working on v2.0. We plan to re-engage on the project.
content/rancher/v2.x/en/faq/networking/cni-providers/_index.md
+1 -1
View File
@@ -55,7 +55,7 @@ In Rancher, Canal is the default CNI network provider combined with Flannel and
Kubernetes workers should open UDP port `8472` (VXLAN) and TCP port `9099` (healthcheck). See [Port Requirements]({{< baseurl >}}/rancher/v2.x/en/installation/references/) for more details.
![Canal Diagram]({{< baseurl >}}/img/rancher/canal-diagram.png)
{{< img "/img/rancher/canal-diagram.png" "Canal Diagram">}}
For more information, see the [Canal GitHub Page](https://github.com/projectcalico/canal).
content/rancher/v2.x/en/faq/security/_index.md
+4 -2
View File
@@ -4,10 +4,12 @@ weight: 8007
---
### Is there a Hardening Guide?
**Is there a Hardening Guide?**
The Hardening Guide is now located in the main [Security]({{< baseurl >}}/rancher/v2.x/en/security/) section.
### What are the results of Rancher's Kubernetes cluster when it is CIS benchmarked?
<br>
**What are the results of Rancher's Kubernetes cluster when it is CIS benchmarked?**
We have run the CIS Kubernetes benchmark against a hardened Rancher Kubernetes cluster. The results of that assessment can be found in the main [Security]({{< baseurl >}}/rancher/v2.x/en/security/) section.
content/rancher/v2.x/en/faq/upgrades-to-2x/_index.md
+104
View File
@@ -0,0 +1,104 @@
---
title: Questions about Upgrading to Rancher v2.x
weight: 1
---
This page contains frequently asked questions about the changes between Rancher v1.x and v2.x, and how to upgrade from Rancher v1.x to v2.x.
# Kubernetes
**What does it mean when you say Rancher v2.x is built on Kubernetes?**
Rancher v2.x is a complete container management platform built 100% on Kubernetes leveraging its Custom Resource and Controller framework. All features are written as a CustomResourceDefinition (CRD) which extends the existing Kubernetes API and can leverage native features such as RBAC.
<br>
**Do you plan to implement upstream Kubernetes, or continue to work on your own fork?**
We're still going to provide our distribution when you select the default option of having us create your Kubernetes cluster, but it will be very close to upstream.
<br>
**Does this release mean that we need to re-train our support staff in Kubernetes?**
Yes. Rancher will offer the native Kubernetes functionality via `kubectl` but will also offer our own UI dashboard to allow you to deploy Kubernetes workload without having to understand the full complexity of Kubernetes. However, to fully leverage Kubernetes, we do recommend understanding Kubernetes. We do plan on improving our UX with subsequent releases to make Kubernetes easier to use.
<br>
**Is a Rancher compose going to make a Kubernetes pod? Do we have to learn both now? We usually use the filesystem layer of files, not the UI.**
No. Unfortunately, the differences were enough such that we cannot support Rancher compose anymore in 2.x. We will be providing both a tool and guides to help with this migration.
<br>
**If we use Kubernetes native YAML files for creating resources, should we expect that to work as expected, or do we need to use Rancher/Docker compose files to deploy infrastructure?**
Absolutely.
# Cattle
**How does Rancher v2.x affect Cattle?**
Cattle will not supported in v2.x as Rancher has been re-architected to be based on Kubernetes. You can, however, expect majority of Cattle features you use will exist and function similarly on Kubernetes. We will develop migration tools in Rancher v2.1 to help you transform your existing Rancher Compose files into Kubernetes YAML files.
<br>
**Can I migrate existing Cattle workloads into Kubernetes?**
Yes. In the upcoming Rancher v2.1 release we will provide a tool to help translate existing Cattle workloads in Compose format to Kubernetes YAML format. You will then be able to deploy those workloads on the v2.x platform.
# Feature Changes
**Can we still add our own infrastructure services, which had a separate view/filter in 1.6.x?**
Yes. You can manage Kubernetes storage, networking, and its vast ecosystem of add-ons.
<br>
**Are there changes to default roles available now or going forward? Will the Kubernetes alignment impact plans for roles/RBAC?**
The default roles will be expanded to accommodate the new Rancher 2.x features, and will also take advantage of the Kubernetes RBAC (Role-Based Access Control) capabilities to give you more flexibility.
<br>
**Will there be any functions like network policies to separate a front-end container from a back-end container through some kind of firewall in v2.x?**
Yes. You can do so by leveraging Kubernetes' network policies.
<br>
**What about the CLI? Will that work the same way with the same features?**
Yes. Definitely.
# Environments & Clusters
**Can I still create templates for environments and clusters?**
Starting with 2.0, the concept of an environment has now been changed to a Kubernetes cluster as going forward, only the Kubernetes orchestration engine is supported.
Kubernetes RKE Templates is on our roadmap for 2.x. Please refer to our Release Notes and documentation for all the features that we currently support.
<br>
**Can you still add an existing host to an environment? (i.e. not provisioned directly from Rancher)**
Yes. We still provide you with the same way of executing our Rancher agents directly on hosts.
# Upgrading/Migrating
**How would the migration from v1.x to v2.x work?**
Due to the technical difficulty in transforming a Docker container into a pod running Kubernetes, upgrading will require users to "replay" those workloads from v1.x into new v2.x environments. We plan to ship with a tool in v2.1 to translate existing Rancher Compose files into Kubernetes YAML files. You will then be able to deploy those workloads on the v2.x platform.
<br>
**Is it possible to upgrade from Rancher v1.x to v2.x without any disruption to Cattle and Kubernetes clusters?**
At this time, we are still exploring this scenario and taking feedback. We anticipate that you will need to launch a new Rancher instance and then relaunch on v2.x. Once you've moved to v2.x, upgrades will be in place, as they are in v1.6.
# Support
**Are you planning some long-term support releases for Rancher v1.6?**
That is definitely the focus of the v1.6 stream. We're continuing to improve that release, fix bugs, and maintain it. New releases of the v1.6 stream are announced in the [Rancher forums.](https://forums.rancher.com/c/announcements) The Rancher wiki contains the [v1.6 release notes.](https://github.com/rancher/rancher/wiki/Rancher-1.6)
content/rancher/v2.x/en/installation/air-gap/populate-private-registry/_index.md
+1 -1
View File
@@ -125,7 +125,7 @@ D. Populate the private registry
### Prerequisites
These steps expect you to use a Windows 1903 Server workstation that has internet access, access to your private registry, and at least 50 GB of disk space.
These steps expect you to use a Windows Server 1809 workstation that has internet access, access to your private registry, and at least 50 GB of disk space.
The workstation must have Docker 18.02+ in order to support manifests, which are required when provisioning Windows clusters.
content/rancher/v2.x/en/installation/ha/_index.md
+2 -1
View File
@@ -30,7 +30,8 @@ The following CLI tools are required for this install. Please make sure these to
* [rke]({{< baseurl >}}/rke/latest/en/installation/) - Rancher Kubernetes Engine, cli for building Kubernetes clusters.
* [helm](https://docs.helm.sh/using_helm/#installing-helm) - Package management for Kubernetes.
> **Important:** Due to an issue with Helm v2.12.0 and cert-manager, please use Helm v2.12.1 or higher.
> **Known issues:**
> Do not use Helm v2.15.0 (issue with converting/comparing numbers)
## Installation Outline
content/rancher/v2.x/en/installation/ha/create-nodes-lb/nlb/_index.md
+8 -8
View File
@@ -28,7 +28,7 @@ Log into the [Amazon AWS Console](https://console.aws.amazon.com/ec2/) to get st
The Target Groups configuration resides in the **Load Balancing** section of the **EC2** service. Select **Services** and choose **EC2**, find the section **Load Balancing** and open **Target Groups**.
![EC2 Load Balancing section]({{< baseurl >}}/img/rancher/ha/nlb/ec2-loadbalancing.png)
{{< img "/img/rancher/ha/nlb/ec2-loadbalancing.png" "EC2 Load Balancing section">}}
Click **Create target group** to create the first target group, regarding TCP port 443.
@@ -54,11 +54,11 @@ Success codes | `200-399`
<hr>
**Screenshot Target group TCP port 443 settings**<br/>
![Target group 443]({{< baseurl >}}/img/rancher/ha/nlb/create-targetgroup-443.png)
{{< img "/img/rancher/ha/nlb/create-targetgroup-443.png" "Target group 443">}}
<hr>
**Screenshot Target group TCP port 443 Advanced settings**<br/>
![Target group 443 Advanced]({{< baseurl >}}/img/rancher/ha/nlb/create-targetgroup-443-advanced.png)
{{< img "/img/rancher/ha/nlb/create-targetgroup-443-advanced.png" "Target group 443 Advanced">}}
<hr>
@@ -86,11 +86,11 @@ Success codes | `200-399`
<hr>
**Screenshot Target group TCP port 80 settings**<br/>
![Target group 80]({{< baseurl >}}/img/rancher/ha/nlb/create-targetgroup-80.png)
{{< img "/img/rancher/ha/nlb/create-targetgroup-80.png" "Target group 80">}}
<hr>
**Screenshot Target group TCP port 80 Advanced settings**<br/>
![Target group 80 Advanced]({{< baseurl >}}/img/rancher/ha/nlb/create-targetgroup-80-advanced.png)
{{< img "/img/rancher/ha/nlb/create-targetgroup-80-advanced.png" "Target group 80 Advanced">}}
<hr>
@@ -100,19 +100,19 @@ Next, add your Linux nodes to both target groups.
Select the target group named **rancher-tcp-443**, click the tab **Targets** and choose **Edit**.
![Edit target group 443]({{< baseurl >}}/img/rancher/ha/nlb/edit-targetgroup-443.png)
{{< img "/img/rancher/ha/nlb/edit-targetgroup-443.png" "Edit target group 443">}}
Select the instances (Linux nodes) you want to add, and click **Add to registered**.
<hr>
**Screenshot Add targets to target group TCP port 443**<br/>
![Add targets to target group 443]({{< baseurl >}}/img/rancher/ha/nlb/add-targets-targetgroup-443.png)
{{< img "/img/rancher/ha/nlb/add-targets-targetgroup-443.png" "Add targets to target group 443">}}
<hr>
**Screenshot Added targets to target group TCP port 443**<br/>
![Added targets to target group 443]({{< baseurl >}}/img/rancher/ha/nlb/added-targets-targetgroup-443.png)
{{< img "/img/rancher/ha/nlb/added-targets-targetgroup-443.png" "Added targets to target group 443">}}
When the instances are added, click **Save** on the bottom right of the screen.
content/rancher/v2.x/en/installation/ha/rke-add-on/layer-4-lb/nlb/_index.md
+8 -8
View File
@@ -36,7 +36,7 @@ Log into the [Amazon AWS Console](https://console.aws.amazon.com/ec2/) to get st
The Target Groups configuration resides in the **Load Balancing** section of the **EC2** service. Select **Services** and choose **EC2**, find the section **Load Balancing** and open **Target Groups**.
![EC2 Load Balancing section]({{< baseurl >}}/img/rancher/ha/nlb/ec2-loadbalancing.png)
{{< img "/img/rancher/ha/nlb/ec2-loadbalancing.png" "EC2 Load Balancing section">}}
Click **Create target group** to create the first target group, regarding TCP port 443.
@@ -62,11 +62,11 @@ Success codes | `200-399`
<hr>
**Screenshot Target group TCP port 443 settings**<br/>
![Target group 443]({{< baseurl >}}/img/rancher/ha/nlb/create-targetgroup-443.png)
{{< img "/img/rancher/ha/nlb/create-targetgroup-443.png" "Target group 443">}}
<hr>
**Screenshot Target group TCP port 443 Advanced settings**<br/>
![Target group 443 Advanced]({{< baseurl >}}/img/rancher/ha/nlb/create-targetgroup-443-advanced.png)
{{< img "/img/rancher/ha/nlb/create-targetgroup-443-advanced.png" "Target group 443 Advanced">}}
<hr>
@@ -94,11 +94,11 @@ Success codes | `200-399`
<hr>
**Screenshot Target group TCP port 80 settings**<br/>
![Target group 80]({{< baseurl >}}/img/rancher/ha/nlb/create-targetgroup-80.png)
{{< img "/img/rancher/ha/nlb/create-targetgroup-80.png" "Target group 80">}}
<hr>
**Screenshot Target group TCP port 80 Advanced settings**<br/>
![Target group 80 Advanced]({{< baseurl >}}/img/rancher/ha/nlb/create-targetgroup-80-advanced.png)
{{< img "/img/rancher/ha/nlb/create-targetgroup-80-advanced.png" "Target group 80 Advanced">}}
<hr>
@@ -108,19 +108,19 @@ Next, add your Linux nodes to both target groups.
Select the target group named **rancher-tcp-443**, click the tab **Targets** and choose **Edit**.
![Edit target group 443]({{< baseurl >}}/img/rancher/ha/nlb/edit-targetgroup-443.png)
{{< img "/img/rancher/ha/nlb/edit-targetgroup-443.png" "Edit target group 443">}}
Select the instances (Linux nodes) you want to add, and click **Add to registered**.
<hr>
**Screenshot Add targets to target group TCP port 443**<br/>
![Add targets to target group 443]({{< baseurl >}}/img/rancher/ha/nlb/add-targets-targetgroup-443.png)
{{< img "/img/rancher/ha/nlb/add-targets-targetgroup-443.png" "Add targets to target group 443">}}
<hr>
**Screenshot Added targets to target group TCP port 443**<br/>
![Added targets to target group 443]({{< baseurl >}}/img/rancher/ha/nlb/added-targets-targetgroup-443.png)
{{< img "/img/rancher/ha/nlb/added-targets-targetgroup-443.png" "Added targets to target group 443">}}
When the instances are added, click **Save** on the bottom right of the screen.
content/rancher/v2.x/en/installation/options/local-system-charts/_index.md
+3 -3
View File
@@ -52,11 +52,11 @@ In the catalog management page in the Rancher UI, follow these steps:
1. Open `https://<your-rancher-server>/v3/catalogs/system-library` in your browser.
![Open]({{< baseurl >}}/img/rancher/airgap/system-charts-setting.png)
{{< img "/img/rancher/airgap/system-charts-setting.png" "Open">}}
1. Click **Edit** on the upper right corner and update the value for **url** to the location of the Git mirror of the `system-charts` repository.
![Update]({{< baseurl >}}/img/rancher/airgap/system-charts-update.png)
{{< img "/img/rancher/airgap/system-charts-update.png" "Update">}}
1. Click **Show Request**
@@ -65,4 +65,4 @@ In the catalog management page in the Rancher UI, follow these steps:
**Result:** Rancher is configured to download all the required catalog items from your `system-charts` repository.
{{% /tab %}}
{{% /tabs %}}
{{% /tabs %}}
content/rancher/v2.x/en/installation/references/_index.md
+1 -1
View File
@@ -13,7 +13,7 @@ The following table lists the ports that need to be open to and from nodes that
{{< ports-rancher-nodes >}}
**Note** Rancher nodes may also require additional outbound access for any external [authentication provider]({{< baseurl >}}rancher/v2.x/en/admin-settings/authentication/) which is configured (LDAP for example).
**Note** Rancher nodes may also require additional outbound access for any external [authentication provider]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/) which is configured (LDAP for example).
## Kubernetes Cluster Nodes
content/rancher/v2.x/en/installation/requirements/_index.md
+27 -26
View File
@@ -11,22 +11,23 @@ Whether you're configuring Rancher to run in a single-node or high-availability
<br>
Rancher is tested on the following operating systems and their subsequent non-major releases with a supported version of [Docker](https://www.docker.com/).
* Ubuntu 16.04 (64-bit x86)
* Docker 17.03.x, 18.06.x, 18.09.x
* Ubuntu 18.04 (64-bit x86)
* Docker 18.06.x, 18.09.x
* Red Hat Enterprise Linux (RHEL)/CentOS 7.6 (64-bit x86)
* RHEL Docker 1.13
* Docker 17.03.x, 18.06.x, 18.09.x
* RancherOS 1.5.1 (64-bit x86)
* Docker 17.03.x, 18.06.x, 18.09.x
* Windows Server 2019 (64-bit x86)
* Requires Docker Engine - Enterprise Edition (EE)
* Nodes with Windows Server core version 1809 should use Docker EE-basic 18.09
* Nodes with Windows Server core version 1903 should use Docker EE-basic 19.03
* Supported for worker nodes only. See [Configuring Custom Clusters for Windows]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/)
- Ubuntu 16.04 (64-bit x86)
- Docker 17.03.x, 18.06.x, 18.09.x
- Ubuntu 18.04 (64-bit x86)
- Docker 18.06.x, 18.09.x
- Red Hat Enterprise Linux (RHEL)/CentOS 7.6 (64-bit x86)
- RHEL Docker 1.13
- Docker 17.03.x, 18.06.x, 18.09.x
- RancherOS 1.5.1 (64-bit x86)
- Docker 17.03.x, 18.06.x, 18.09.x
- Windows Server 2019 (64-bit x86)
- Requires Docker Engine - Enterprise Edition (EE)
- Nodes with Windows Server core version 1809 should use Docker EE-basic 18.09
- Nodes with Windows Server core version 1903 should use Docker EE-basic 19.03
- Supported for worker nodes only. See [Configuring Custom Clusters for Windows]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/)
If you are using RancherOS, make sure you switch the Docker engine to a supported version using:<br>
```
# Look up available versions
sudo ros engine list
@@ -34,6 +35,7 @@ sudo ros engine list
# Switch to a supported version
sudo ros engine switch docker-18.09.2
```
See [Running on ARM64 (Experimental)]({{< baseurl >}}/rancher/v2.x/en/installation/arm64-platform/) if you plan to run Rancher on ARM64.
<br>
<br>
@@ -45,25 +47,24 @@ See [Running on ARM64 (Experimental)]({{< baseurl >}}/rancher/v2.x/en/installati
<br>
Hardware requirements scale based on the size of your Rancher deployment. Provision each individual node according to the requirements.
**[HA Node]({{< baseurl >}}/rancher/v2.x/en/installation/ha/create-nodes-lb/) Requirements**
Deployment Size | Clusters | Nodes | vCPUs | RAM |
--- | --- | --- | --- | --- |
Small | Up to 5 | Up to 50 | 2 | 8 GB |
Medium | Up to 15 | Up to 200 | 4 | 16 GB |
Large | Up to 50 | Up to 500 | 8 | 32 GB |
X-Large | Up to 100 | Up to 1000 | 32 | 128 GB |
XX-Large | 100+ | 1000+ | [Contact Rancher](https://rancher.com/contact/) | [Contact Rancher](https://rancher.com/contact/) |
| Deployment Size | Clusters | Nodes | vCPUs | RAM |
| --------------- | --------- | ---------- | ----------------------------------------------- | ----------------------------------------------- |
| Small | Up to 5 | Up to 50 | 2 | 8 GB |
| Medium | Up to 15 | Up to 200 | 4 | 16 GB |
| Large | Up to 50 | Up to 500 | 8 | 32 GB |
| X-Large | Up to 100 | Up to 1000 | 32 | 128 GB |
| XX-Large | 100+ | 1000+ | [Contact Rancher](https://rancher.com/contact/) | [Contact Rancher](https://rancher.com/contact/) |
<br>
**[Single Node]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/) Requirements**
Deployment Size | Clusters | Nodes | vCPUs | RAM |
--- | --- | --- | --- | --- |
Small | Up to 5 | Up to 50 | 1 | 4 GB |
Medium | Up to 15 | Up to 200 | 2 | 8 GB |
| Deployment Size | Clusters | Nodes | vCPUs | RAM |
| --------------- | -------- | --------- | ----- | ---- |
| Small | Up to 5 | Up to 50 | 1 | 4 GB |
| Medium | Up to 15 | Up to 200 | 2 | 8 GB |
<br/>
content/rancher/v2.x/en/k8s-in-rancher/configmaps/_index.md
+1 -1
View File
@@ -34,7 +34,7 @@ ConfigMaps store general configuration information for an application, such as c
>
>**Tip:** You can add multiple key value pairs to the ConfigMap by copying and pasting.
>
> ![Bulk Key Value Pair Copy/Paste]({{< baseurl >}}/img/rancher/bulk-key-values.gif)
> {{< img "/img/rancher/bulk-key-values.gif" "Bulk Key Value Pair Copy/Paste">}}
**Result:** Your ConfigMap is added to the namespace. You can view it in the Rancher UI from the **Resources > Config Maps** view.
content/rancher/v2.x/en/k8s-in-rancher/secrets/_index.md
+1 -1
View File
@@ -27,7 +27,7 @@ When creating a secret, you can make it available for any deployment within a pr
>**Tip:** You can add multiple key value pairs to the secret by copying and pasting.
>
> ![Bulk Key Value Pair Copy/Paste]({{< baseurl >}}/img/rancher/bulk-key-values.gif)
> {{< img "/img/rancher/bulk-key-values.gif" "Bulk Key Value Pair Copy/Paste">}}
1. Click **Save**.
content/rancher/v2.x/en/project-admin/tools/alerts/_index.md
+1 -1
View File
@@ -165,7 +165,7 @@ If you enable [project monitoring]({{< baseurl >}}/rancher/v2.x/en/project-admin
1. Continue adding more **Alert Rule** to the group.
1. Finally, choose the [notifiers]({{< baseurl >}}/rancher/v2.x/en/cluster-admin/notifiers/) that send you alerts.
1. Finally, choose the [notifiers]({{< baseurl >}}//rancher/v2.x/en/cluster-admin/tools/notifiers/) that send you alerts.
- You can set up multiple notifiers.
- You can change notifier recipients on the fly.
content/rancher/v2.x/en/security/hardening-2.3/_index.md
+1 -1
View File
@@ -526,7 +526,7 @@ Enabling the `DenyEscalatingExec` admission control plugin will prevent the 'Lau
To pass the following controls for the kube-api server ensure RKE configuration passes the appropriate options.
- 1.1.1 - Ensure that the `--anonymous-auth` argument is set to false (Scored)
- 1.1.8 - Ensure that the `--profiling argument` is set to false (Scored)
- 1.1.8 - Ensure that the `--profiling` argument is set to false (Scored)
- 1.1.11 - Ensure that the admission control plugin `AlwaysPullImages` is set (Scored)
- 1.1.12 - Ensure that the admission control plugin `DenyEscalatingExec` is set (Scored)
- 1.1.14 - Ensure that the admission control plugin `NamespaceLifecycle` is set (Scored)
content/rancher/v2.x/en/v1.6-migration/discover-services/_index.md
+12
View File
@@ -7,6 +7,10 @@ Service discovery is one of the core functionalities of any container-based envi
This document will also show you how to link the workloads and services that you migrated into Rancher v2.x. When you parsed your services from v1.6 using migration-tools CLI, it output two files for each service: one deployment manifest and one service manifest. You'll have to link these two files together before the deployment works correctly in v2.x.
<figcaption>Resolve the <code>output.txt</code> Link Directive</figcaption>
![Resolve Link Directive]({{< baseurl >}}/img/rancher/resolve-links.png)
## In This Document
<!-- TOC -->
@@ -58,6 +62,11 @@ When you migrate v1.6 services to v2.x, Rancher does not automatically create a
In the image below, the `web-deployment.yml` and `web-service.yml` files [created after parsing]({{< baseurl >}}/rancher/v2.x/en/v1.6-migration/run-migration-tool/#migration-example-file-output) our [migration example services]({{< baseurl >}}/rancher/v2.x/en/v1.6-migration/#migration-example-files) are linked together.
<figcaption>Linked Workload and Kubernetes Service</figcaption>
![Linked Workload and Kubernetes Service]({{< baseurl >}}/img/rancher/linked-service-workload.png)
### Service Name Alias Creation
Just as you can create an alias for Rancher v1.6 services, you can do the same for Rancher v2.x workloads. Similarly, you can also create DNS records pointing to services running externally, using either their hostname or IP address. These DNS records are Kubernetes service objects.
@@ -66,6 +75,9 @@ Using the v2.x UI, use the context menu to navigate to the `Project` view. Then
Click **Add Record** to create new DNS records. Then view the various options supported to link to external services or to create aliases for another workload, DNS record, or set of pods.
<figcaption>Add Service Discovery Record</figcaption>
![Add Service Discovery Record]({{< baseurl >}}/img/rancher/add-record.png)
The following table indicates which alias options are implemented natively by Kubernetes and which options are implemented by Rancher leveraging Kubernetes.
Option | Kubernetes-implemented? | Rancher-implemented?
content/rancher/v2.x/en/v1.6-migration/expose-services/_index.md
+1 -1
View File
@@ -61,7 +61,7 @@ For example, for the web-deployment.yml file parsed from v1.6 that we've been us
<figcaption>Port Mapping: Setting HostPort</figcaption>
![Set HostPort]({{< baseurl >}}/img/rancher/set-hostport.gif)
{{< img "/img/rancher/set-hostport.gif" "Set HostPort">}}
## NodePort
content/rancher/v2.x/en/v1.6-migration/get-started/_index.md
+4
View File
@@ -40,6 +40,10 @@ After provisioning your node(s), install Rancher:
After your Rancher v2.x Server is installed, we recommend configuring external authentication (like Active Directory or GitHub) so that users can log into Rancher using their single sign-on. For a full list of supported authentication providers and instructions on how to configure them, see [Authentication]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication).
<figcaption>Rancher v2.x Authentication</figcaption>
![Rancher v2.x Authentication]({{< baseurl >}}/img/rancher/auth-providers.svg)
### Local Users
Although we recommend using an external authentication provider, Rancher v1.6 and v2.x both offer support for users local to Rancher. However, these users cannot be migrated from Rancher v1.6 to v2.x. If you used local users in Rancher v1.6 and want to continue this practice in v2.x, you'll need to [manually recreate these user accounts]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/) and assign them access rights.
content/rancher/v2.x/en/v1.6-migration/load-balancing/_index.md
+37 -1
View File
@@ -9,6 +9,10 @@ As outlined in [its documentation]({{< baseurl >}}/rancher/v1.6/en/cattle/adding
If you encounter the `output.txt` text below after parsing your v1.6 Compose files to Kubernetes manifests, you'll have to resolve it by manually creating a load balancer in v2.x.
<figcaption><code>output.txt</code> Load Balancer Directive</figcaption>
![Resolve Load Balancer Directive]({{< baseurl >}}/img/rancher/resolve-load-balancer.png)
## In This Document
<!-- TOC -->
@@ -35,7 +39,7 @@ In Rancher v1.6, you could add port/service rules for configuring your HAProxy t
Rancher v2.x offers similar functionality, but load balancing is instead handled by Ingress. An Ingress is a specification of rules that a controller component applies to your load balancer. The actual load balancer can run outside of your cluster or within it.
By default, Rancher v2.x deploys NGINX Ingress Controller on clusters provisioned using RKE (Rancher's own Kubernetes installer) to process the Kubernetes Ingress rules. The NGINX Ingress Controller is installed by default only in clusters provisioned by RKE. Clusters provisioned by cloud providers like GKE have their own Ingress Controllers that configure the load balancer. For this document, our scope is limited to the RKE-installed NGINX Ingress Controller only, but you can read about cloud providers in [our documentation]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/).
By default, Rancher v2.x deploys NGINX Ingress Controller on clusters provisioned using RKE (Rancher's own Kubernetes installer) to process the Kubernetes Ingress rules. The NGINX Ingress Controller is installed by default only in clusters provisioned by RKE. Clusters provisioned by cloud providers like GKE have their own Ingress Controllers that configure the load balancer. For this document, our scope is limited to the RKE-installed NGINX Ingress Controller only.
RKE deploys NGINX Ingress Controller as a [Kubernetes DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/), meaning that an NGINX instance is deployed on every node in the cluster. NGINX acts like an Ingress Controller listening to Ingress creation within your entire cluster, and it also configures itself as the load balancer to satisfy the Ingress rules. The DaemonSet is configured with hostNetwork to expose two ports: 80 and 443.
@@ -49,8 +53,16 @@ In Rancher v1.6 you could deploy a scalable load balancer service within your st
<!-- add comparison table-->
<figcaption>Rancher v1.6 Load Balancing Architecture</figcaption>
![Rancher v1.6 Load Balancing]({{< baseurl >}}/img/rancher/cattle-load-balancer.svg)
The Rancher v2.x Ingress Controller is a DaemonSet, it is globally deployed on all schedulable nodes to serve your entire Kubernetes Cluster. Therefore, when you program the Ingress rules, you must use a unique hostname and path to point to your workloads, as the load balancer node IP addresses and ports 80 and 443 are common access points for all workloads.
<figcaption>Rancher v2.x Load Balancing Architecture</figcaption>
![Rancher v2.x Load Balancing]({{< baseurl >}}/img/rancher/kubernetes-load-balancer.svg)
## Ingress Caveats
Although Rancher v2.x supports HTTP and HTTPS hostname and path-based load balancing, you must use unique host names and paths when configuring your workloads. This limitation derives from:
@@ -67,8 +79,14 @@ You can launch a new load balancer to replace your load balancer from v1.6. Usin
>**Prerequisite:** Before deploying Ingress, you must have a workload deployed that's running a scale of two or more pods.
>
![Workload Scale]({{< baseurl >}}/img/rancher/workload-scale.png)
For balancing between these two pods, you must create a Kubernetes Ingress rule. To create this rule, navigate to your cluster and project, and click **Resources > Workloads > Load Balancing.** (In versions prior to v2.3.0, click **Workloads > Load Balancing.**) Then click **Add Ingress**. This GIF below depicts how to add Ingress to one of your projects.
<figcaption>Browsing to Load Balancer Tab and Adding Ingress</figcaption>
![Adding Ingress]({{< baseurl >}}/img/rancher/add-ingress.gif)
Similar to a service/port rules in Rancher v1.6, here you can specify rules targeting your workload's container port. The sections below demonstrate how to create Ingress rules.
### Configuring Host- and Path-Based Routing
@@ -77,8 +95,16 @@ Using Rancher v2.x, you can add Ingress rules that are based on host names or a
For example, let's say you have multiple workloads deployed to a single namespace. You can add an Ingress to route traffic to these two workloads using the same hostname but different paths, as depicted in the image below. URL requests to `foo.com/name.html` will direct users to the `web` workload, and URL requests to `foo.com/login` will direct users to the `chat` workload.
<figcaption>Ingress: Path-Based Routing Configuration</figcaption>
![Ingress: Path-Based Routing Configuration]({{< baseurl >}}/img/rancher/add-ingress-form.png)
Rancher v2.x also places a convenient link to the workloads on the Ingress record. If you configure an external DNS to program the DNS records, this hostname can be mapped to the Kubernetes Ingress address.
<figcaption>Workload Links</figcaption>
![Load Balancer Links to Workloads]({{< baseurl >}}/img/rancher/load-balancer-links.png)
The Ingress address is the IP address in your cluster that the Ingress Controller allocates for your workload. You can reach your workload by browsing to this IP address. Use `kubectl` command below to see the Ingress address assigned by the controller:
```
@@ -92,6 +118,10 @@ Rancher v2.x Ingress functionality supports the HTTPS protocol, but if you want
- We recommend [uploading a certificate]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/certificates/) from a known certificate authority (you'll have to do this before configuring Ingress). Then, while configuring your load balancer, use the **Choose a certificate** option and select the uploaded certificate that you want to use.
- If you have configured [NGINX default certificate]({{< baseurl >}}/rke/latest/en/config-options/add-ons/ingress-controllers/#configuring-an-nginx-default-certificate), you can select **Use default ingress controller certificate**.
<figcaption>Load Balancer Configuration: SSL/TLS Certificate Section</figcaption>
![SSL/TLS Certificates Section]({{< baseurl >}}/img/rancher/load-balancer-ssl-certs.png)
### TCP Load Balancing Options
#### Layer-4 Load Balancer
@@ -100,6 +130,10 @@ For the TCP protocol, Rancher v2.x supports configuring a Layer 4 load balancer
For example, if we create a deployment named `myapp` and specify a Layer 4 load balancer in the **Port Mapping** section, Rancher will automatically add an entry to the **Load Balancer** tab named `myapp-loadbalancer`.
<figcaption>Workload Deployment: Layer 4 Load Balancer Creation</figcaption>
![Deploy Layer-4 Load Balancer]({{< baseurl >}}/img/rancher/deploy-workload-load-balancer.png)
Once configuration of the load balancer succeeds, the Rancher UI provides a link to your workload's public endpoint.
#### NGINX Ingress Controller TCP Support by ConfigMaps
@@ -110,6 +144,8 @@ However, there is a workaround to use NGINX's TCP balancing by creating a Kubern
To configure NGINX to expose your services via TCP, you can add the ConfigMap `tcp-services` that should exist in the `ingress-nginx` namespace. This namespace also contains the NGINX Ingress Controller pods.
![Layer-4 Load Balancer: ConfigMap Workaround]({{< baseurl >}}/img/rancher/layer-4-lb-config-map.png)
The key in the ConfigMap entry should be the TCP port that you want to expose for public access: `<namespace/service name>:<service port>`. As shown above, two workloads are listed in the `Default` namespace. For example, the first entry in the ConfigMap above instructs NGINX to expose the `myapp` workload (the one in the `default` namespace that's listening on private port 80) over external port `6790`. Adding these entries to the ConfigMap automatically updates the NGINX pods to configure these workloads for TCP balancing. The workloads exposed should be available at `<NodeIP>:<TCP Port>`. If they are not accessible, you might have to expose the TCP port explicitly using a NodePort service.
## Rancher v2.x Load Balancing Limitations
content/rancher/v2.x/en/v1.6-migration/monitor-apps/_index.md
+20
View File
@@ -11,6 +11,10 @@ Use this document to correct Rancher v2.x workloads and services that list `heal
For example, for the image below, we would configure liveness probes for the `web` and `weblb` workloads (i.e., the Kubernetes manifests output by migration-tools CLI).
<figcaption>Resolve <code>health_check</code> for the <code>web</code> and <code>webLB</code> Workloads</figcaption>
![Resolve health_check]({{< baseurl >}}/img/rancher/resolve-health-checks.png)
## In This Document
<!-- TOC -->
@@ -37,6 +41,8 @@ The health check microservice features two types of health checks, which have a
The following diagram displays the health check microservice evaluating a container running Nginx. Notice that the microservice is making its check across nodes.
![Rancher v1.6 Health Checks]({{<baseurl>}}/img/rancher/healthcheck.svg)
## Rancher v2.x Health Checks
In Rancher v2.x, the health check microservice is replaced with Kubernete's native health check mechanisms, called _probes_. These probes, similar to the Rancher v1.6 health check microservice, monitor the health of pods over TCP and HTTP.
@@ -63,6 +69,8 @@ Kubernetes includes two different _types_ of probes: liveness checks and readine
The following diagram displays kubelets running probes on containers they are monitoring ([kubelets](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/) are the primary "agent" running on each node). The node on the left is running a liveness probe, while the one of the right is running a readiness check. Notice that the kubelet is scanning containers on its host node rather than across nodes, as in Rancher v1.6.
![Rancher v2.x Probes]({{<baseurl>}}/img/rancher/probes.svg)
## Configuring Probes in Rancher v2.x
The [migration-tool CLI]({{< baseurl >}}/rancher/v2.x/en/v1.6-migration/run-migration-tool/) cannot parse health checks from Compose files to Kubernetes manifest. Therefore, if want you to add health checks to your Rancher v2.x workloads, you'll have to add them manually.
@@ -73,6 +81,10 @@ If the probe fails, the container is restarted per the restartPolicy defined in
Configure probes by using the **Health Check** section while editing deployments called out in `output.txt`.
<figcaption>Edit Deployment: Health Check Section</figcaption>
![Health Check Section]({{< baseurl >}}/img/rancher/health-check-section.png)
### Configuring Checks
While you create a workload using Rancher v2.x, we recommend configuring a check that monitors the health of the deployment's pods.
@@ -85,6 +97,8 @@ TCP checks monitor your deployment's health by attempting to open a connection t
You can configure the probe along with values for specifying its behavior by selecting the **TCP connection opens successfully** option in the **Health Check** section. For more information, see [Deploying Workloads]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/workloads/deploy-workloads/). For help setting probe timeout and threshold values, see [Health Check Parameter Mappings](#health-check-parameter-mappings).
![TCP Check]({{<baseurl>}}/img/rancher/readiness-check-tcp.png)
When you configure a readiness check using Rancher v2.x, the `readinessProbe` directive and the values you've set are added to the deployment's Kubernetes manifest. Configuring a readiness check also automatically adds a liveness check (`livenessProbe`) to the deployment.
<!--
@@ -121,6 +135,8 @@ HTTP checks monitor your deployment's health by sending an HTTP GET request to a
You can configure the probe along with values for specifying its behavior by selecting the **HTTP returns successful status** or **HTTPS returns successful status**. For more information, see [Deploying Workloads]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/workloads/deploy-workloads/). For help setting probe timeout and threshold values, see [Health Check Parameter Mappings](#healthcheck-parameter-mappings).
![HTTP Check]({{<baseurl>}}/img/rancher/readiness-check-http.png)
When you configure a readiness check using Rancher v2.x, the `readinessProbe` directive and the values you've set are added to the deployment's Kubernetes manifest. Configuring a readiness check also automatically adds a liveness check (`livenessProbe`) to the deployment.
{{% /tab %}}
@@ -131,12 +147,16 @@ When you configure a readiness check using Rancher v2.x, the `readinessProbe` di
While configuring a readiness check for either the TCP or HTTP protocol, you can configure a separate liveness check by clicking the **Define a separate liveness check**. For help setting probe timeout and threshold values, see [Health Check Parameter Mappings](#health-check-parameter-mappings).
![Separate Liveness Check]({{<baseurl>}}/img/rancher/separate-check.png)
### Additional Probing Options
Rancher v2.x, like v1.6, lets you perform health checks using the TCP and HTTP protocols. However, Rancher v2.x also lets you check the health of a pod by running a command inside of it. If the container exits with a code of `0` after running the command, the pod is considered healthy.
You can configure a liveness or readiness check that executes a command that you specify by selecting the `Command run inside the container exits with status 0` option from **Health Checks** while [deploying a workload]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/workloads/deploy-workloads/).
![Healthcheck Execute Command]({{<baseurl>}}/img/rancher/healthcheck-cmd-exec.png)
#### Health Check Parameter Mappings
While configuring readiness checks and liveness checks, Rancher prompts you to fill in various timeout and threshold values that determine whether the probe is a success or failure. The reference table below shows you the equivalent health check values from Rancher v1.6.
content/rancher/v2.x/en/v1.6-migration/run-migration-tool/_index.md
+16
View File
@@ -242,6 +242,10 @@ You can deploy the Kubernetes manifests created by migration-tools by importing
>
>Delete the YAML directive listed in the error message. These are YAML directives from your v1.6 services that Kubernetes can't read.
<figcaption>Deploy Services: Import Kubernetes Manifest</figcaption>
![Deploy Services]({{< baseurl >}}/img/rancher/deploy-service.gif)
{{% /tab %}}
{{% tab "Rancher CLI" %}}
@@ -261,14 +265,26 @@ Use the following Rancher CLI commands to deploy your application using Rancher
Following importation, you can view your v1.6 services in the v2.x UI as Kubernetes manifests by using the context menu to select `<CLUSTER> > <PROJECT>` that contains your services. The imported manifests will display on the **Resources > Workloads** and on the tab at **Resources > Workloads > Service Discovery.** (In Rancher v2.x prior to v2.3.0, these are on the **Workloads** and **Service Discovery** tabs in the top navigation bar.)
<figcaption>Imported Services</figcaption>
![Imported Services]({{< baseurl >}}/img/rancher/imported-workloads.png)
## What Now?
Although the migration-tool CLI parses your Rancher v1.6 Compose files to Kubernetes manifests, there are discrepancies between v1.6 and v2.x that you must address by manually editing your parsed [Kubernetes manifests](#output). In other words, you need to edit each workload and service imported into Rancher v2.x, as displayed below.
<figcaption>Edit Migrated Services</figcaption>
![Edit Migrated Workload]({{< baseurl >}}/img/rancher/edit-migration-workload.gif)
As mentioned in [Migration Tools CLI Output](#migration-tools-cli-output), the `output.txt` files generated during parsing lists the manual steps you must make for each deployment. Review the upcoming topics for more information on manually editing your Kubernetes specs.
Open your `output.txt` file and take a look at its contents. When you parsed your Compose files into Kubernetes manifests, migration-tools CLI output a manifest for each workload that it creates for Kubernetes. For example, our when our [Migration Example Files]({{< baseurl >}}/rancher/v2.x/en/v1.6-migration/#migration-example-files) are parsed into Kubernetes manifests, `output.txt` lists each resultant parsed [Kubernetes manifest file](#migration-example-file-output) (i.e., workloads). Each workload features a list of action items to restore operations for the workload in v2.x.
<figcaption>Output.txt Example</figcaption>
![output.txt]({{< baseurl >}}/img/rancher/output-dot-text.png)
The following table lists possible directives that may appear in `output.txt`, what they mean, and links on how to resolve them.
Directive | Instructions
content/rancher/v2.x/en/v1.6-migration/schedule-workloads/_index.md
+38
View File
@@ -13,6 +13,7 @@ You can schedule your migrated v1.6 services while editing a deployment. Schedul
<figcaption>Editing Workloads: Workload Type and Node Scheduling Sections</figcaption>
![Workload Type and Node Scheduling Sections]({{< baseurl >}}/img/rancher/migrate-schedule-workloads.png)
## In This Document
@@ -38,6 +39,7 @@ Rancher v2.x retains _all_ methods available in v1.6 for scheduling your service
In v1.6, you would schedule a service to a host while adding a service to a Stack. In Rancher v2.x., the equivalent action is to schedule a workload for deployment. The following composite image shows a comparison of the UI used for scheduling in Rancher v2.x versus v1.6.
![Node Scheduling: Rancher v2.x vs v1.6]({{< baseurl >}}/img/rancher/node-scheduling.png)
## Node Scheduling Options
@@ -62,8 +64,14 @@ Option | v1.6 Feature | v2.x Feature
In v1.6, you could control the number of container replicas deployed for a service. You can schedule pods the same way in v2.x, but you'll have to set the scale manually while editing a workload.
![Resolve Scale]({{< baseurl >}}/img/rancher/resolve-scale.png)
During migration, you can resolve `scale` entries in `output.txt` by setting a value for the **Workload Type** option **Scalable deployment** depicted below.
<figcaption>Scalable Deployment Option</figcaption>
![Workload Scale]({{< baseurl >}}/img/rancher/workload-type-option.png)
### Scheduling Pods to a Specific Node
Just as you could schedule containers to a single host in Rancher v1.6, you can schedule pods to single node in Rancher v2.x
@@ -71,12 +79,18 @@ Just as you could schedule containers to a single host in Rancher v1.6, you can
As you deploy a workload, use the **Node Scheduling** section to choose a node to run your pods on. The workload below is being scheduled to deploy an Nginx image with a scale of two pods on a specific node.
<!-- Question: What would be a good use case for use of a scheduling pods on the same node?-->
<figcaption>Rancher v2.x: Workload Deployment</figcaption>
![Workload Tab and Group by Node Icon]({{< baseurl >}}/img/rancher/schedule-specific-node.png)
Rancher schedules pods to the node you select if 1) there are compute resource available for the node and 2) you've configured port mapping to use the HostPort option, that there are no port conflicts.
If you expose the workload using a NodePort that conflicts with another workload, the deployment gets created successfully, but no NodePort service is created. Therefore, the workload isn't exposed outside of the cluster.
After the workload is created, you can confirm that the pods are scheduled to your chosen node. From the project view, click **Resources > Workloads.** (In versions prior to v2.3.0, click the **Workloads** tab.) Click the **Group by Node** icon to sort your workloads by node. Note that both Nginx pods are scheduled to the same node.
![Pods Scheduled to Same Node]({{< baseurl >}}/img/rancher/scheduled-nodes.png)
<!--
If you export the workload's manifest for Rancher v2.x, you can see in the pod spec that the workload is scheduled to the node that you selected (`nodeName: mark-do1`).
@@ -141,6 +155,10 @@ To apply labels to pods, make additions to the **Labels and Annotations** sectio
Some of the most-used scheduling features in v1.6 were affinity and anti-affinity rules.
<figcaption><code>output.txt</code> Affinity Label</figcaption>
![Affinity Label]({{< baseurl >}}/img/rancher/resolve-affinity.png)
- **Affinity**
Any pods that share the same label are scheduled to the same node. Affinity can be configured in one of two ways:
@@ -152,6 +170,9 @@ Some of the most-used scheduling features in v1.6 were affinity and anti-affinit
<br/>
<figcaption>Affinity Rules: Hard and Soft</figcaption>
![Affinity Rules]({{< baseurl >}}/img/rancher/node-scheduling-affinity.png)
- **AntiAffinity**
@@ -161,7 +182,9 @@ Some of the most-used scheduling features in v1.6 were affinity and anti-affinit
For anti-affinity rules, we recommend using labels with phrases like `NotIn` and `DoesNotExist`, as these terms are more intuitive when users are applying anti-affinity rules.
<figcaption>AntiAffinity Operators</figcaption>
![AntiAffinity ]({{< baseurl >}}/img/rancher/node-schedule-antiaffinity.png)
Detailed documentation for affinity/anti-affinity is available in the [Kubernetes Documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity).
@@ -174,6 +197,9 @@ In Rancher v1.6 setups, you could prevent services from being scheduled to speci
In Rancher v2.x, you can prevent pods from being scheduled to specific nodes by applying _taints_ to a node. Pods will not be scheduled to a tainted node unless it has special permission, called a _toleration_. A toleration is a special label that allows a pod to be deployed to a tainted node. While editing a workload, you can apply tolerations using the **Node Scheduling** section. Click **Show advanced options**.
<figcaption>Applying Tolerations</figcaption>
![Tolerations]({{< baseurl >}}/img/rancher/node-schedule-advanced-options.png)
For more information, see the Kubernetes documentation on [taints and tolerations](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/).
@@ -181,10 +207,18 @@ For more information, see the Kubernetes documentation on [taints and toleration
Rancher v1.6 included the ability to deploy [global services]({{< baseurl >}}/rancher/v1.6/en/cattle/scheduling/#global-service), which are services that deploy duplicate containers to each host in the environment (i.e., nodes in your cluster using Rancher v2.x terms). If a service has the `io.rancher.scheduler.global: 'true'` label declared, then Rancher v1.6 schedules a service container on each host in the environment.
<figcaption><code>output.txt</code> Global Service Label</figcaption>
![Global Service Label]({{< baseurl >}}/img/rancher/resolve-global.png)
In Rancher v2.x, you can schedule a pod to each node using a [Kubernetes DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/), which is a specific type of workload <!-- link -->). A _DaemonSet_ functions exactly like a Rancher v1.6 global service. The Kubernetes scheduler deploys a pod on each node of the cluster, and as new nodes are added, the scheduler will start new pods on them provided they match the scheduling requirements of the workload. Additionally, in v2.x, you can also limit a DaemonSet to be deployed to nodes that have a specific label.
To create a daemonset while configuring a workload, choose **Run one pod on each node** from the **Workload Type** options.
<figcaption>Workload Configuration: Choose run one pod on each node to configure daemonset</figcaption>
![choose Run one pod on each node]({{< baseurl >}}/img/rancher/workload-type.png)
### Scheduling Pods Using Resource Constraints
While creating a service in the Rancher v1.6 UI, you could schedule its containers to hosts based on hardware requirements that you choose. The containers are then scheduled to hosts based on which ones have bandwidth, memory, and CPU capacity.
@@ -204,6 +238,10 @@ To declare resource constraints, edit your migrated workloads, editing the **Sec
- Memory Limit
- CPU Limit
<figcaption>Scheduling: Resource Constraint Settings</figcaption>
![Resource Constraint Settings]({{< baseurl >}}/img/rancher/resource-constraint-settings.png)
You can find more detail about these specs and how to use them in the [Kubernetes Documentation](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container).
### [Next: Service Discovery]({{< baseurl >}}/rancher/v2.x/en/v1.6-migration/discover-services/)
content/rke/latest/en/config-options/add-ons/_index.md
+7 -9
View File
@@ -3,22 +3,20 @@ title: Add-Ons
weight: 260
---
RKE supports pluggable add-ons. Add-ons are used to deploy several cluster components including:
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/)
The images used for these add-ons 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`.
In addition to these pluggable add-ons, you can specify an add-on that you want deployed after the cluster deployment is complete.
RKE only adds additional add-ons when using `rke up` multiple times. RKE does **not** support removing of cluster add-ons when doing `rke up` with a different list of add-ons.
As of v0.1.8, RKE will update an add-on if it is the same name.
Prior to v0.1.8, update any add-ons by using `kubectl edit`.
There are a few things worth noting:
* In addition to these pluggable add-ons, you can specify an add-on that you want deployed after the cluster deployment is complete.
* RKE only adds additional add-ons when using `rke up` multiple times. RKE does **not** support removing of cluster add-ons when doing `rke up` with a different list of add-ons.
* As of v0.1.8, RKE will update an add-on if it is the same name.
* Prior to v0.1.8, update any add-ons by using `kubectl edit`.
## Critical and Non-Critical Add-ons
content/rke/latest/en/config-options/authorization/_index.md
+1 -1
View File
@@ -5,7 +5,7 @@ weight: 240
Kubernetes supports multiple [Authorization Modules](https://kubernetes.io/docs/reference/access-authn-authz/authorization/#authorization-modules). Currently, RKE only supports the [RBAC module](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).
By default, RBAC is already enabled. If you wanted to turn off RBAC support, **which isn't recommended**, you set the authorization mode to `none`.
By default, RBAC is already enabled. If you wanted to turn off RBAC support, **which isn't recommended**, you set the authorization mode to `none` in your `cluster.yml`.
```yaml
authorization:
content/rke/latest/en/config-options/bastion-host/_index.md
+1 -1
View File
@@ -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 to 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. Your 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:
content/rke/latest/en/config-options/cloud-providers/vsphere/_index.md
+3 -3
View File
@@ -29,7 +29,7 @@ When provisioning clusters in Rancher using the [vSphere node driver]({{< baseur
6. Expand **Cluster Options** and configure as required.
7. Set **Cloud Provider** option to `Custom`.
![vsphere-node-driver-cloudprovider]({{< baseurl >}}/img/rancher/vsphere-node-driver-cloudprovider.png)
{{< img "/img/rancher/vsphere-node-driver-cloudprovider.png" "vsphere-node-driver-cloudprovider">}}
8. Click on **Edit as YAML**
9. Insert the following top-level structure to the pre-populated cluster YAML. Note that the `name` *must* be set to `vsphere`. Refer to the [configuration reference](#configuration-reference) to learn about the properties of the `vsphereCloudProvider` directive.
@@ -200,7 +200,7 @@ The required property can be set while creating or modifying VMs in the vSphere
1. For each VM navigate to the tab **VM Options** and click on **Edit Configuration**.
2. Add the parameter `disk.EnableUUID` with a value of **TRUE**.
![vsphere-advanced-parameters]({{< baseurl >}}/img/rke/vsphere-advanced-parameters.png)
{{< img "/img/rke/vsphere-advanced-parameters.png" "vsphere-advanced-parameters">}}
#### Using the GOVC CLI tool
@@ -222,7 +222,7 @@ When creating new clusters in Rancher using vSphere node templates, you can conf
4. Enter `disk.enableUUID` as key with a value of **TRUE**.
![vsphere-nodedriver-enable-uuid]({{< baseurl >}}/img/rke/vsphere-nodedriver-enable-uuid.png)
{{< img "/img/rke/vsphere-nodedriver-enable-uuid.png" "vsphere-nodedriver-enable-uuid">}}
5. Click **Create** or **Save**.
content/rke/latest/en/config-options/nodes/_index.md
-1
View File
@@ -7,7 +7,6 @@ The `nodes` directive is the only required section in the `cluster.yml` file. It
```yaml
nodes:
nodes:
- address: 1.1.1.1
user: ubuntu
role:
content/rke/latest/en/config-options/private-registries/_index.md
+1 -1
View File
@@ -3,7 +3,7 @@ title: Private Registries
weight: 215
---
RKE supports the ability to configure multiple private Docker registries. By passing in your registry and credentials, it allows the nodes to pull images from these private registries.
RKE supports the ability to configure multiple private Docker registries in the `cluster.yml`. By passing in your registry and credentials, it allows the nodes to pull images from these private registries.
```yaml
private_registries:
content/rke/latest/en/config-options/system-images/_index.md
+1 -1
View File
@@ -6,7 +6,7 @@ When RKE is deploying Kubernetes, there are several images that are pulled. Thes
As of `v0.1.6`, the functionality of a couple of the system images were consolidated into a single `rancher/rke-tools` image to simplify and speed the deployment process.
You can configure the [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/) and [dns provider]({{<baseurl>}}/rke/latest/en/config-options/add-ons/dns/) as well as the options for these add-ons separately.
You can configure the [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/) and [dns provider]({{<baseurl>}}/rke/latest/en/config-options/add-ons/dns/) as well as the options for these add-ons separately in the `cluster.yml`.
Below is an example of the list of system images used to deploy Kubernetes through RKE. The default versions of Kubernetes are tied to specific versions of system images.
content/rke/latest/en/etcd-snapshots/_index.md
+250
View File
@@ -25,7 +25,257 @@ You can use RKE to [restore your cluster from backup]({{<baseurl>}}/rke/latest/e
# Example Scenarios
<<<<<<< Updated upstream
These [example scenarios]({{<baseurl>}}/rke/latest/en/etcd-snapshots/example-scenarios) for backup and restore are different based on your version of RKE.
=======
### IAM Support for Storing Snapshots in S3
In addition to API access keys, RKE supports using IAM roles for S3 authentication. The cluster etcd nodes must be assigned an IAM role that has read/write access to the designated backup bucket on S3. Also, the nodes must have network access to the S3 endpoint specified.
To give an application access to S3, refer to the AWS documentation on [Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances.](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html)
### Local One-Time Snapshot Example
```
$ rke etcd snapshot-save --config cluster.yml --name snapshot-name
```
The snapshot is saved in `/opt/rke/etcd-snapshots`
### One-Time Snapshots uploaded to S3 Example
_Available as of v0.2.0_
```
$ rke etcd snapshot-save --config cluster.yml --name snapshot-name \
--s3 --access-key S3_ACCESS_KEY --secret-key S3_SECRET_KEY \
--bucket-name s3-bucket-name --s3-endpoint s3.amazonaws.com
```
The snapshot is saved in `/opt/rke/etcd-snapshots` as well as uploaded to the S3 backend.
## Recurring Snapshots
To schedule automatic recurring etcd snapshots, you can enable the `etcd-snapshot` service with [extra configuration options the etcd service](#options-for-the-etcd-snapshot-service). `etcd-snapshot` runs in a service container alongside the `etcd` container. By default, the `etcd-snapshot` service takes a snapshot for every node that has the `etcd` role and stores them to local disk in `/opt/rke/etcd-snapshots`. If you set up the [options for S3](#options-for-the-etcd-snapshot-service), the snapshot will also be uploaded to the S3 backend.
Prior to v0.2.0, along with the snapshots, RKE saves a backup of the certificates, i.e. a file named `pki.bundle.tar.gz`, in the same location. The snapshot and pki bundle file are required for the restore process in versions prior to v0.2.0.
When a cluster is launched with the `etcd-snapshot` service enabled, you can view the `etcd-rolling-snapshots` logs to confirm backups are being created automatically.
```
$ docker logs etcd-rolling-snapshots
time="2018-05-04T18:39:16Z" level=info msg="Initializing Rolling Backups" creation=1m0s retention=24h0m0s
time="2018-05-04T18:40:16Z" level=info msg="Created backup" name="2018-05-04T18:40:16Z_etcd" runtime=108.332814ms
time="2018-05-04T18:41:16Z" level=info msg="Created backup" name="2018-05-04T18:41:16Z_etcd" runtime=92.880112ms
time="2018-05-04T18:42:16Z" level=info msg="Created backup" name="2018-05-04T18:42:16Z_etcd" runtime=83.67642ms
time="2018-05-04T18:43:16Z" level=info msg="Created backup" name="2018-05-04T18:43:16Z_etcd" runtime=86.298499ms
```
### Options for the `Etcd-Snapshot` Service
Depending on your version of RKE, the options used to configure recurring snapshots may be different.
_Available as of v0.2.0_
|Option|Description| S3 Specific |
|---|---| --- |
|**interval_hours**| The duration in hours between recurring backups. This supercedes the `creation` option and will override it if both are specified.| |
|**retention**| The number of snapshots to retain before rotation. This supercedes the `retention` option and will override it if both are specified.| |
|**bucket_name**| S3 bucket name where backups will be stored| * |
|**access_key**| S3 access key with permission to access the backup bucket.| * |
|**secret_key** |S3 secret key with permission to access the backup bucket.| * |
|**region** |S3 region for the backup bucket. This is optional.| * |
|**endpoint** |S3 regions endpoint for the backup bucket.| * |
<br>
```yaml
services:
etcd:
backup_config:
interval_hours: 12
retention: 6
s3backupconfig:
access_key: S3_ACCESS_KEY
secret_key: S3_SECRET_KEY
bucket_name: s3-bucket-name
region: ""
endpoint: s3.amazonaws.com
```
#### Prior to v0.2.0
|Option|Description|
|---|---|
|**Snapshot**|By default, the recurring snapshot service is disabled. To enable the service, you need to define it as part of `etcd` and set it to `true`.|
|**Creation**|By default, the snapshot service will take snapshots every 5 minutes (`5m0s`). You can change the time between snapshots as part of the `creation` directive for the `etcd` service.|
|**Retention**|By default, all snapshots are saved for 24 hours (`24h`) before being deleted and purged. You can change how long to store a snapshot as part of the `retention` directive for the `etcd` service.|
```yaml
services:
etcd:
snapshot: true
creation: 5m0s
retention: 24h
```
## Etcd Disaster Recovery
If there is a disaster with your Kubernetes cluster, you can use `rke etcd snapshot-restore` to recover your etcd. This command reverts etcd to a specific snapshot. RKE also removes the old `etcd` container before creating a new `etcd` cluster using the snapshot that you have chosen.
>**Warning:** Restoring an etcd snapshot deletes your current etcd cluster and replaces it with a new one. Before you run the `rke etcd snapshot-restore` command, you should back up any important data in your cluster.
The snapshot used to restore your etcd cluster can either be stored locally in `/opt/rke/etcd-snapshots` or from a S3 compatible backend. The S3 backend option is available as of v0.2.0.
### Options for `rke etcd snapshot-restore`
| Option | Description | S3 Specific |
| --- | --- | ---|
| `--name` value | Specify snapshot name | |
| `--config` value | Specify an alternate cluster YAML file (default: "cluster.yml") [$RKE_CONFIG] | |
| `--s3` | Enabled backup to s3 |* |
| `--s3-endpoint` value | Specify s3 endpoint url (default: "s3.amazonaws.com") | * |
| `--access-key` value | Specify s3 accessKey | *|
| `--secret-key` value | Specify s3 secretKey | *|
| `--bucket-name` value | Specify s3 bucket name | *|
| `--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) |
### Example of Restoring from a Local Snapshot
When restoring etcd from a local snapshot, the snapshot is assumed to be located in `/opt/rke/etcd-snapshots`. In versions prior to v0.2.0, the `pki.bundle.tar.gz` file is also expected to be in the same location. As of v0.2.0, this file is no longer needed as v0.2.0 has changed how the [Kubernetes cluster state is stored]({{< baseurl >}}/rke/latest/en/installation/#kubernetes-cluster-state).
```
$ rke etcd snapshot-restore --config cluster.yml --name mysnapshot
```
### Example of Restoring from a Snapshot in S3
_Available as of v0.2.0_
> **Note:** Ensure your `cluster.rkestate` is present before starting the restore, as this contains your certificate data for the cluster
When restoring etcd from a snapshot located in S3, the command needs the S3 information in order to connect to the S3 backend and retrieve the snapshot.
```shell
$ rke etcd snapshot-restore --config cluster.yml --name snapshot-name \
--s3 --access-key S3_ACCESS_KEY --secret-key S3_SECRET_KEY \
--bucket-name s3-bucket-name --s3-endpoint s3.amazonaws.com
```
> **Note:** if you were restoring a cluster that had rancher installed the UI should start-up after a few minutes; you don't need to re-run helm.
### Example Scenario of restoring from a Local Snapshot
In this example, the Kubernetes cluster was deployed on two AWS nodes.
| Name | IP | Role |
|:-----:|:--------:|:----------------------:|
| node1 | 10.0.0.1 | [controlplane, worker] |
| node2 | 10.0.0.2 | [etcd] |
### Back up the `etcd` cluster
Take a local snapshot of the Kubernetes cluster. As of v0.2.0, you can also upload this snapshot directly to a S3 backend with the [S3 options](#options-for-rke-etcd-snapshot-save).
```
$ rke etcd snapshot-save --name snapshot.db --config cluster.yml
```
{{< img "/img/rke/rke-etcd-backup.png" "etcd snapshot">}}
### Store the Snapshot Externally in S3
As of v0.2.0, this step is no longer required, as RKE can upload and download snapshots automatically from S3 by adding in [S3 options](#options-for-rke-etcd-snapshot-save) when running the `rke etcd snapshot-save` command.
After taking the etcd snapshot on `node2`, we recommend saving this backup in a persistence place. One of the options is to save the backup and `pki.bundle.tar.gz` file on a S3 bucket or tape backup.
> **Note:** As of v0.2.0, the file **pki.bundle.tar.gz** is no longer required for the restore process.
```
# If you're using an AWS host and have the ability to connect to S3
root@node2:~# s3cmd mb s3://rke-etcd-backup
root@node2:~# s3cmd /opt/rke/etcd-snapshots/snapshot.db /opt/rke/etcd-snapshots/pki.bundle.tar.gz s3://rke-etcd-backup/
```
### Place the backup on a new node
To simulate the failure, let's power down `node2`.
```
root@node2:~# poweroff
```
| Name | IP | Role |
|:-----:|:--------:|:----------------------:|
| node1 | 10.0.0.1 | [controlplane, worker] |
| ~~node2~~ | ~~10.0.0.2~~ | ~~[etcd]~~ |
| node3 | 10.0.0.3 | [etcd] |
| | | |
Before restoring etcd and running `rke up`, we need to retrieve the backup saved on S3 to a new node, e.g. `node3`. As of v0.2.0, you can directly retrieve the snapshot from S3 when running the restore command, so this step is for users who stored the snapshot externally without using the integrated S3 options.
```
# Make a Directory
root@node3:~# mkdir -p /opt/rke/etcdbackup
# Get the Backup from S3
root@node3:~# s3cmd get s3://rke-etcd-backup/snapshot.db /opt/rke/etcd-snapshots/snapshot.db
# Get the pki bundle from S3, only needed prior to v0.2.0
root@node3:~# s3cmd get s3://rke-etcd-backup/pki.bundle.tar.gz /opt/rke/etcd-snapshots/pki.bundle.tar.gz
```
### Restore `etcd` on the new node from the backup
Before updating and restoring etcd, you will need to add the new node into the Kubernetes cluster with the `etcd` role. In the `cluster.yml`, comment out the old node and add in the new node. `
```yaml
nodes:
- address: 10.0.0.1
hostname_override: node1
user: ubuntu
role:
- controlplane
- worker
# - address: 10.0.0.2
# hostname_override: node2
# user: ubuntu
# role:
# - etcd
- address: 10.0.0.3
hostname_override: node3
user: ubuntu
role:
- etcd
```
After the new node is added to the `cluster.yml`, run `rke etcd snapshot-restore` to launch `etcd` from the backup. The snapshot and `pki.bundle.tar.gz` file are expected to be saved at `/opt/rke/etcd-snapshots`.
As of v0.2.0, if you want to directly retrieve the snapshot from S3, add in the [S3 options](#options-for-rke-etcd-snapshot-restore).
> **Note:** As of v0.2.0, the file **pki.bundle.tar.gz** is no longer required for the restore process as the certificates required to restore are preserved within the `cluster.rkestate`
```
$ rke etcd snapshot-restore --name snapshot.db --config cluster.yml
```
Finally, we need to restore the operations on the cluster by making the Kubernetes API point to the new `etcd` by running `rke up` again using the new `cluster.yml`.
```
$ rke up --config cluster.yml
```
Confirm that your Kubernetes cluster is functional by checking the pods on your cluster.
```
> kubectl get pods
NAME READY STATUS RESTARTS AGE
nginx-65899c769f-kcdpr 1/1 Running 0 17s
nginx-65899c769f-pc45c 1/1 Running 0 17s
nginx-65899c769f-qkhml 1/1 Running 0 17s
```
>>>>>>> Stashed changes
## Troubleshooting