public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-05-24 21:58:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into staging

Browse Source
This commit is contained in:
Denise
2019-11-27 12:08:47 -07:00
committed by GitHub
parent 08b6cceabc da8e35e306
commit 7cc8e07ce6
273 changed files with 7718 additions and 2077 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/k3s/latest/en/_index.md
+8 -12
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"
---
@@ -18,18 +18,14 @@ Great for:
What is this?
---
k3s is intended to be a fully compliant Kubernetes distribution with the following changes:
K3s is a fully compliant Kubernetes distribution with the following enhancements:
1. Legacy, alpha, non-default features are removed. Hopefully, you shouldn't notice the
stuff that has been removed.
2. Removed most in-tree plugins (cloud providers and storage plugins) which can be replaced
with out of tree addons.
3. Add sqlite3 as the default storage mechanism. etcd3 is still available, but not the default.
4. Wrapped in simple launcher that handles a lot of the complexity of TLS and options.
5. Minimal to no OS dependencies (just a sane kernel and cgroup mounts needed). k3s packages required
dependencies
* An embedded SQLite database has replaced etcd as the default datastore. External datastores such as PostgreSQL, MySQL, and etcd are also supported.
* Simple but powerful "batteries-included" features have been added, such as: a local storage provider, a service load balancer, a helm controller, and the Traefik ingress controller.
* Operation of all Kubernetes control plane components is encapsulated in a single binary and process. This allows K3s to automate and manage complex cluster operations like distributing certificates.
* In-tree cloud providers and storage plugins have been removed.
* External dependencies have been minimized (just a modern kernel and cgroup mounts needed). K3s packages required dependencies, including:
* containerd
* Flannel
* CoreDNS
* CNI
* Host utilities (iptables, socat, etc)
content/k3s/latest/en/advanced/_index.md
+106
View File
@@ -0,0 +1,106 @@
---
title: "Advanced Options"
weight: 40
aliases:
- /k3s/latest/en/running/
---
This section contains advanced information describing the different ways you can run and manage K3s.
Starting the Server
------------------
The installation script will auto-detect if your OS is using systemd or openrc and start the service.
When running with openrc logs will be created at `/var/log/k3s.log`, or with systemd in `/var/log/syslog` and viewed using `journalctl -u k3s`. An example of installing and auto-starting with the install script:
```bash
curl -sfL https://get.k3s.io | sh -
```
When running the server manually you should get an output similar to:
```
$ k3s server
INFO[2019-01-22T15:16:19.908493986-07:00] Starting k3s dev
INFO[2019-01-22T15:16:19.908934479-07:00] Running kube-apiserver --allow-privileged=true --authorization-mode Node,RBAC --service-account-signing-key-file /var/lib/rancher/k3s/server/tls/service.key --service-cluster-ip-range 10.43.0.0/16 --advertise-port 6445 --advertise-address 127.0.0.1 --insecure-port 0 --secure-port 6444 --bind-address 127.0.0.1 --tls-cert-file /var/lib/rancher/k3s/server/tls/localhost.crt --tls-private-key-file /var/lib/rancher/k3s/server/tls/localhost.key --service-account-key-file /var/lib/rancher/k3s/server/tls/service.key --service-account-issuer k3s --api-audiences unknown --basic-auth-file /var/lib/rancher/k3s/server/cred/passwd --kubelet-client-certificate /var/lib/rancher/k3s/server/tls/token-node.crt --kubelet-client-key /var/lib/rancher/k3s/server/tls/token-node.key
Flag --insecure-port has been deprecated, This flag will be removed in a future version.
INFO[2019-01-22T15:16:20.196766005-07:00] Running kube-scheduler --kubeconfig /var/lib/rancher/k3s/server/cred/kubeconfig-system.yaml --port 0 --secure-port 0 --leader-elect=false
INFO[2019-01-22T15:16:20.196880841-07:00] Running kube-controller-manager --kubeconfig /var/lib/rancher/k3s/server/cred/kubeconfig-system.yaml --service-account-private-key-file /var/lib/rancher/k3s/server/tls/service.key --allocate-node-cidrs --cluster-cidr 10.42.0.0/16 --root-ca-file /var/lib/rancher/k3s/server/tls/token-ca.crt --port 0 --secure-port 0 --leader-elect=false
Flag --port has been deprecated, see --secure-port instead.
INFO[2019-01-22T15:16:20.273441984-07:00] Listening on :6443
INFO[2019-01-22T15:16:20.278383446-07:00] Writing manifest: /var/lib/rancher/k3s/server/manifests/coredns.yaml
INFO[2019-01-22T15:16:20.474454524-07:00] Node token is available at /var/lib/rancher/k3s/server/node-token
INFO[2019-01-22T15:16:20.474471391-07:00] To join node to cluster: k3s agent -s https://10.20.0.3:6443 -t ${NODE_TOKEN}
INFO[2019-01-22T15:16:20.541027133-07:00] Wrote kubeconfig /etc/rancher/k3s/k3s.yaml
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).
Alpine Linux
------------
In order to pre-setup Alpine Linux you have to go through the following steps:
```bash
echo "cgroup /sys/fs/cgroup cgroup defaults 0 0" >> /etc/fstab
cat >> /etc/cgconfig.conf <<EOF
mount {
cpuacct = /cgroup/cpuacct;
memory = /cgroup/memory;
devices = /cgroup/devices;
freezer = /cgroup/freezer;
net_cls = /cgroup/net_cls;
blkio = /cgroup/blkio;
cpuset = /cgroup/cpuset;
cpu = /cgroup/cpu;
}
EOF
```
Then update **/etc/update-extlinux.conf** by adding:
```
default_kernel_opts="... cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory"
```
Then update the config and reboot:
```bash
update-extlinux
reboot
```
After rebooting:
- download **k3s** to **/usr/local/bin/k3s**
- create an openrc file in **/etc/init.d**
Running in Docker (and docker-compose)
-----------------
[k3d](https://github.com/rancher/k3d) is a utility designed to easily run K3s in Docker. It can be installed via the [brew](https://brew.sh/) utility for MacOS.
`rancher/k3s` images are also available to run K3s server and agent from Docker. A `docker-compose.yml` is in the root of the K3s repo that
serves as an example of how to run K3s from Docker. To run from `docker-compose` from this repo run:
docker-compose up --scale node=3
# kubeconfig is written to current dir
kubectl --kubeconfig kubeconfig.yaml get node
NAME STATUS ROLES AGE VERSION
497278a2d6a2 Ready <none> 11s v1.13.2-k3s2
d54c8b17c055 Ready <none> 11s v1.13.2-k3s2
db7a5a5a5bdd Ready <none> 12s v1.13.2-k3s2
To run the agent only in Docker, use `docker-compose up node`. Alternatively the Docker run command can also be used;
sudo docker run \
-d --tmpfs /run \
--tmpfs /var/run \
-e K3S_URL=${SERVER_URL} \
-e K3S_TOKEN=${NODE_TOKEN} \
--privileged rancher/k3s:vX.Y.Z
content/k3s/latest/en/building/_index.md
-47
View File
@@ -1,47 +0,0 @@
---
title: "Building from Source"
weight: 10
---
This section provides information on building k3s from source.
See the [release](https://github.com/rancher/k3s/releases/latest) page for pre-built releases.
The clone will be much faster on this repo if you do
git clone --depth 1 https://github.com/rancher/k3s.git
This repo includes all of Kubernetes history so `--depth 1` will avoid most of that.
To build the full release binary run `make` and that will create `./dist/artifacts/k3s`.
Optionally to build the binaries without running linting or building docker images:
```sh
./scripts/download && ./scripts/build && ./scripts/package-cli
```
For development, you just need go 1.12 and a sane GOPATH. To compile the binaries run:
```bash
go build -o k3s
go build -o kubectl ./cmd/kubectl
go build -o hyperkube ./vendor/k8s.io/kubernetes/cmd/hyperkube
```
This will create the main executable, but it does not include the dependencies like containerd, CNI,
etc. To run a server and agent with all the dependencies for development run the following
helper scripts:
```bash
# Server
./scripts/dev-server.sh
# Agent
./scripts/dev-agent.sh
```
Kubernetes Source
-----------------
The source code for Kubernetes is in `vendor/` and the location from which that is copied
is in `./vendor.conf`. Go to the referenced repo/tag and you'll find all the patches applied
to upstream Kubernetes.
content/k3s/latest/en/configuration/_index.md
+51 -173
View File
@@ -1,9 +1,9 @@
---
title: "Configuration Info"
weight: 4
weight: 50
---
This section contains information on using k3s with various configurations.
This section contains information on using K3s with various configurations.
Auto-Deploying Manifests
@@ -12,7 +12,7 @@ Auto-Deploying Manifests
Any file found in `/var/lib/rancher/k3s/server/manifests` will automatically be deployed to
Kubernetes in a manner similar to `kubectl apply`.
It is also possible to deploy Helm charts. k3s supports a CRD controller for installing charts. A YAML file specification can look as following (example taken from `/var/lib/rancher/k3s/server/manifests/traefik.yaml`):
It is also possible to deploy Helm charts. K3s supports a CRD controller for installing charts. A YAML file specification can look as following (example taken from `/var/lib/rancher/k3s/server/manifests/traefik.yaml`):
```yaml
apiVersion: helm.cattle.io/v1
@@ -27,7 +27,7 @@ spec:
ssl.enabled: "true"
```
Keep in mind that `namespace` in your HelmChart resource metadata section should always be `kube-system`, because k3s deploy controller is configured to watch this namespace for new HelmChart resources. If you want to specify the namespace for the actual helm release, you can do that using `targetNamespace` key in the spec section:
Keep in mind that `namespace` in your HelmChart resource metadata section should always be `kube-system`, because the K3s deploy controller is configured to watch this namespace for new HelmChart resources. If you want to specify the namespace for the actual helm release, you can do that using `targetNamespace` key in the spec section:
```
apiVersion: helm.cattle.io/v1
@@ -53,51 +53,68 @@ spec:
Also note that besides `set` you can use `valuesContent` in the spec section. And it's okay to use both of them.
k3s versions <= v0.5.0 used `k3s.cattle.io` for the api group of helmcharts, this has been changed to `helm.cattle.io` for later versions.
K3s versions `<= v0.5.0` used `k3s.cattle.io` for the api group of helmcharts, this has been changed to `helm.cattle.io` for later versions.
Using the helm CRD
---------------------
You can deploy a 3rd party helm chart using an example like this:
```yaml
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
name: nginx
namespace: kube-system
spec:
chart: nginx
repo: https://charts.bitnami.com/bitnami
targetNamespace: default
```
You can install a specific version of a helm chart using an example like this:
```yaml
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
name: stable/nginx-ingress
namespace: kube-system
spec:
chart: nginx-ingress
version: 1.24.4
targetNamespace: default
```
Accessing Cluster from Outside
-----------------------------
Copy `/etc/rancher/k3s/k3s.yaml` on your machine located outside the cluster as `~/.kube/config`. Then replace
"localhost" with the IP or name of your k3s server. `kubectl` can now manage your k3s cluster.
Open Ports / Network Security
---------------------------
The server needs port 6443 to be accessible by the nodes. The nodes need to be able to reach
other nodes over UDP port 8472. The nodes also need to be able to reach the server on UDP port 8472. This is used for flannel VXLAN. If you don't use flannel
and provide your own custom CNI, then 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, it opens up your
cluster network to accessed by anyone. Run your nodes behind a firewall/security group that
disables access to port 8472.
"localhost" with the IP or name of your K3s server. `kubectl` can now manage your K3s cluster.
Node Registration
-----------------
Agents will register with the server using the node cluster secret along with a randomly generated
password for the node, stored at `/var/lib/rancher/k3s/agent/node-password.txt`. The server will
password for the node, stored at `/etc/rancher/node/password`. The server will
store the passwords for individual nodes at `/var/lib/rancher/k3s/server/cred/node-passwd`, and any
subsequent attempts must use the same password. If the data directory of an agent is removed the
password file should be recreated for the agent, or the entry removed from the server.
subsequent attempts must use the same password. If the `/etc/rancher/node` directory of an agent is removed the
password file should be recreated for the agent, or the entry removed from the server. A unique node
id can be appended to the hostname by launching k3s servers or agents using the `--with-node-id` flag.
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.
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
@@ -110,9 +127,9 @@ In short, latest Ubuntu is your best bet for this to work.
* **Ports**
When running rootless a new network namespace is created. This means that k3s instance is running with networking
fairly detached from the host. The only way to access services run in k3s from the host is to setup port forwards
to the k3s network namespace. We have a controller that will automatically bind 6443 and service port below 1024 to the host with an offset of 10000.
When running rootless a new network namespace is created. This means that K3s instance is running with networking
fairly detached from the host. The only way to access services run in K3s from the host is to setup port forwards
to the K3s network namespace. We have a controller that will automatically bind 6443 and service port below 1024 to the host with an offset of 10000.
That means service port 80 will become 10080 on the host, but 8080 will become 8080 without any offset.
@@ -120,7 +137,7 @@ In short, latest Ubuntu is your best bet for this to work.
* **Daemon lifecycle**
Once you kill k3s and then start a new instance of k3s it will create a new network namespace, but it doesn't kill the old pods. So you are left
Once you kill K3s and then start a new instance of K3s it will create a new network namespace, but it doesn't kill the old pods. So you are left
with a fairly broken setup. This is the main issue at the moment, how to deal with the network namespace.
The issue is tracked in https://github.com/rootless-containers/rootlesskit/issues/65
@@ -133,155 +150,16 @@ In short, latest Ubuntu is your best bet for this to work.
Just add `--rootless` flag to either server or agent. So run `k3s server --rootless` and then look for the message
`Wrote kubeconfig [SOME PATH]` for where your kubeconfig to access you cluster is. Be careful, if you use `-o` to write
the kubeconfig to a different directory it will probably not work. This is because the k3s instance in running in a different
the kubeconfig to a different directory it will probably not work. This is because the K3s instance in running in a different
mount namespace.
Node Labels and Taints
----------------------
k3s agents can be configured with options `--node-label` and `--node-taint` which adds set of Labels and Taints to kubelet, the two options only adds labels/taints at registration time, so they can only be added once and not changed after that, an example of options to add new label is:
K3s agents can be configured with the options `--node-label` and `--node-taint` which adds a label and taint to the kubelet. The two options only add labels and/or taints at registration time, so they can only be added once and not changed after that again by running K3s. If you want to change node labels and taints after node registration you should use `kubectl`. Below is an example showing how to add labels and a taint:
```
--node-label foo=bar \
--node-label hello=world \
--node-taint key1=value1:NoExecute
```
Flannel
-------
Flannel is included by default, if you don't want flannel then run the agent with `--no-flannel` option.
In this setup you will still be required to install your own CNI driver. More info [here](https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#pod-network)
CoreDNS
-------
CoreDNS is deployed on start of the agent, to disable run the server with the `--no-deploy coredns` option.
If you don't install CoreDNS you will need to install a cluster DNS provider yourself.
Traefik
-------
Traefik is deployed by default when starting the server; to disable it, start the server with the `--no-deploy traefik` option.
Service Load Balancer
---------------------
k3s includes a basic service load balancer that uses available host ports. If you try to create
a load balancer that listens on port 80, for example, it will try to find a free host in the cluster
for port 80. If no port is available the load balancer will stay in Pending.
To disable the embedded load balancer run the server with the `--no-deploy servicelb` option. This is necessary if you wish to run a different load balancer, such as MetalLB.
Metrics Server
--------------
To add functionality for commands such as `k3s kubectl top nodes` metrics-server must be installed,
to install see the instructions located at https://github.com/kubernetes-incubator/metrics-server/.
**NOTE** : By default the image used in `metrics-server-deployment.yaml` is valid only for **amd64** devices,
this should be edited as appropriate for your architecture. As of this writing metrics-server provides
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
----------------
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`]
* `--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`]
### MySQL
To use k3s with MySQL storage backend, you can specify the following for insecure connection:
```
--storage-endpoint="mysql://"
```
By default the server will attempt to connect to mysql using the mysql socket at `/var/run/mysqld/mysqld.sock` using the root user and with no password, k3s will also create a database with the name `kubernetes` if the database is not specified in the DSN.
To override the method of connection, user/pass, and database name, you can provide a custom DSN, for example:
```
--storage-endpoint="mysql://k3suser:k3spass@tcp(192.168.1.100:3306)/k3stest"
```
This command will attempt to connect to MySQL on host `192.168.1.100` on port `3306` with username `k3suser` and password `k3spass` and k3s will automatically create a new database with the name `k3stest` if it doesn't exist, for more information about the MySQL driver data source name, please refer to https://github.com/go-sql-driver/mysql#dsn-data-source-name
To connect to MySQL securely, you can use the following example:
```
--storage-endpoint="mysql://k3suser:k3spass@tcp(192.168.1.100:3306)/k3stest" \
--storage-cafile ca.crt \
--storage-certfile mysql.crt \
--storage-keyfile mysql.key
```
The above command will use these certificates to generate the tls config to communicate with mysql securely.
### Postgres
Connection to postgres can be established using the following command:
```
--storage-endpoint="postgres://"
```
By default the server will attempt to connect to postgres on localhost with using the `postgres` user and with `postgres` password, k3s will also create a database with the name `kubernetes` if the database is not specified in the DSN.
To override the method of connection, user/pass, and database name, you can provide a custom DSN, for example:
```
--storage-endpoint="postgres://k3suser:k3spass@192.168.1.100:5432/k3stest"
```
This command will attempt to connect to Postgres on host `192.168.1.100` on port `5432` with username `k3suser` and password `k3spass` and k3s will automatically create a new database with the name `k3stest` if it doesn't exist, for more information about the Postgres driver data source name, please refer to https://godoc.org/github.com/lib/pq
To connect to Postgres securely, you can use the following example:
```
--storage-endpoint="postgres://k3suser:k3spass@192.168.1.100:5432/k3stest" \
--storage-certfile postgres.crt \
--storage-keyfile postgres.key \
--storage-cafile ca.crt
```
The above command will use these certificates to generate the tls config to communicate with postgres securely.
### etcd
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 \
--storage-keyfile etcd.key
```
The above command will use these certificates to generate the tls config to communicate with etcd securely.
content/k3s/latest/en/faq/_index.md
+22
View File
@@ -0,0 +1,22 @@
---
title: FAQ
weight: 60
---
The FAQ is updated periodically and designed to answer the questions our users most frequently ask about K3s.
**Is K3s a suitable replacement for k8s?**
K3s is capable of nearly everything k8s can do. It is just a more lightweight version. See the [main]({{<baseurl>}}/k3s/latest/en/) docs page for more details.
**How can I use my own Ingress instead of Traefik?**
Simply start K3s server with `--no-deploy=traefik` and deploy your ingress.
**Does K3s support Windows?**
At this time K3s does not natively support Windows, however we are open to the idea in the future.
**How can I build from source?**
Please reference the K3s [BUILDING.md](https://github.com/rancher/k3s/blob/master/BUILDING.md) with instructions.
content/k3s/latest/en/installation/_index.md
+9 -339
View File
@@ -1,349 +1,19 @@
---
title: "Installation Options"
weight: 2
title: "Installation"
weight: 20
---
This section contains information on flags and environment variables used for starting a k3s cluster.
This section contains instructions for installing K3s in various environments. Please ensure you have met the [Node Requirements]({{< baseurl >}}/k3s/latest/en/installation/node-requirements/) before you begin installing K3s.
Install Script
--------------
[Installation and Configuration Options]({{< baseurl >}}/k3s/latest/en/installation/install-options/) provides guidance on the options available to you when installing K3s.
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 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 -
```
[High Availability with an External DB]({{< baseurl >}}/k3s/latest/en/installation/ha/) details how to setup an HA K3s cluster backed by an external datastore such as MySQL, PostgreSQL, or etcd.
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 with Embedded DB (Experimental)]({{< baseurl >}}/k3s/latest/en/installation/ha-embedded/) details how to setup an HA K3s cluster that leverages a built-in distributed database.
curl -sfL https://get.k3s.io -o install-k3s.sh
chmod 0755 install-k3s.sh
[Air-Gap Installation]({{< baseurl >}}/k3s/latest/en/installation/airgap/) details how to setup K3s in environments that do not have direct access to the Internet.
export INSTALL_K3S_SKIP_DOWNLOAD=true
./install-k3s.sh
```
### Uninstalling
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
```
If you installed K3s with the help of the `install.sh` script, an uninstall script is generated during installation, which will be created on your node at `/usr/local/bin/k3s-uninstall.sh` (or as `k3s-agent-uninstall.sh`).
content/k3s/latest/en/installation/airgap/_index.md
+77
View File
@@ -0,0 +1,77 @@
---
title: "Air-Gap Install"
weight: 60
---
In this guide, we are assuming you have created your nodes in your air-gap environment and have a secure Docker private registry on your bastion server.
Installation Outline
--------------------
1. Prepare Images Directory
2. Create Registry YAML
3. Install K3s
### Prepare Images Directory
Obtain the images tar file for your architecture from the [releases](https://github.com/rancher/k3s/releases) page for the version of K3s you will be running.
Place the tar file in the `images` directory before starting K3s on each node, for example:
```sh
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/
```
### Create Registry YAML
Create the registries.yaml file at `/etc/rancher/k3s/registries.yaml`. This will tell K3s the necessary details to connect to your private registry.
The registries.yaml file should look like this before plugging in the necessary information:
```
---
mirrors:
customreg:
endpoint:
- "https://ip-to-server:5000"
configs:
customreg:
auth:
username: xxxxxx # this is the registry username
password: xxxxxx # this is the registry password
tls:
cert_file: <path to the cert file used in the registry>
key_file: <path to the key file used in the registry>
ca_file: <path to the ca file used in the registry>
```
Note, at this time only secure registries are supported with K3s (SSL with custom CA)
### Install K3s
Obtain the K3s binary from the [releases](https://github.com/rancher/k3s/releases) page, matching the same version used to get the airgap images tar.
Also obtain the K3s install script at https://get.k3s.io
Place the binary in `/usr/local/bin` on each node.
Place the install script anywhere on each node, name it `install.sh`.
Install K3s on each node. The example below shows how to do this for a server or an agent (worker):
```
# K3s Server
INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh
# K3s Agent
INSTALL_K3S_SKIP_DOWNLOAD=true K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken ./install.sh
```
Note, take care to ensure you replace `myserver` with the IP or valid DNS of the server and replace `mynodetoken` with the node-token from the server.
The node-token is on the server at `/var/lib/rancher/k3s/server/node-token`
>**Note:** K3s additionally provides a `--resolv-conf` flag for kubelets, which may help with configuring DNS in air-gap networks.
# Upgrading
Upgrading an air-gap environment can be accomplished in the following manner:
1. Download the new air-gap images (tar file) from the [releases](https://github.com/rancher/k3s/releases) page for the version of K3s you will be upgrading to. Place the tar in the `/var/lib/rancher/k3s/agent/images/` directory on each node. Delete the old tar file.
2. Copy and replace the old K3s binary in `/usr/local/bin` on each node. Copy over the install script at https://get.k3s.io (as it is possible it has changed since the last release). Run the script again just as you had done in the past with the same environment variables.
3. Restart the K3s service (if not restarted automatically by installer).
content/k3s/latest/en/installation/datastore/_index.md
+97
View File
@@ -0,0 +1,97 @@
---
title: "Cluster Datastore Options"
weight: 50
---
The ability to run Kubernetes using a datastore other than etcd sets K3s apart from other Kubernetes distributions. This feature provides flexibility to Kubernetes operators. The available datastore options allow you to select a datastore that best fits your use case. For example:
* If your team doesn't have expertise in operating etcd, you can choose an enterprise-grade SQL database like MySQL or PostgreSQL
* If you need to run a simple, short-lived cluster in your CI/CD environment, you can use the embedded SQLite database
* If you wish to deploy Kubernetes on the edge and require a highly available solution but can't afford the operational overhead of managing a database at the edge, you can use K3s's embedded HA datastore built on top of DQLite (currently experimental)
K3s supports the following datastore options:
* Embedded [SQLite](https://www.sqlite.org/index.html)
* [PostgreSQL](https://www.postgresql.org/) (certified against versions 10.7 and 11.5)
* [MySQL](https://www.mysql.com/) (certified against version 5.7)
* [etcd](https://etcd.io/) (certified against version 3.3.15)
* Embedded [DQLite](https://dqlite.io/) for High Availability (experimental)
### External Datastore Configuration Parameters
If you wish to use an external datastore such as PostgreSQL, MySQL, or etcd you must set the `datastore-endpoint` parameter so that K3s knows how to connect to it. You may also specify parameters to configure the authentication and encryption of the connection. The below table summarizes these parameters, which can be passed as either CLI flags or environment variables.
CLI Flag | Environment Variable | Description
------------|-------------|------------------
<span style="white-space: nowrap">`--datastore-endpoint`</span> | `K3S_DATASTORE_ENDPOINT` | Specify a PostgresSQL, MySQL, or etcd connection string. This is a string used to describe the connection to the datastore. The structure of this string is specific to each backend and is detailed below.
<span style="white-space: nowrap">`--datastore-cafile`</span> | `K3S_DATASTORE_CAFILE` | TLS Certificate Authority (CA) file used to help secure communication with the datastore. If your datastore serves requests over TLS using a certificate signed by a custom certificate authority, you can specify that CA using this parameter so that the K3s client can properly verify the certificate. |
| <span style="white-space: nowrap">`--datastore-certfile`</span> | `K3S_DATASTORE_CERTFILE` | TLS certificate file used for client certificate based authentication to your datastore. To use this feature, your datastore must be configured to support client certificate based authentication. If you specify this parameter, you must also specify the `datastore-keyfile` parameter. |
| <span style="white-space: nowrap">`--datastore-keyfile`</span> | `K3S_DATASTORE_KEYFILE` | TLS key file used for client certificate based authentication to your datastore. See the previous `datastore-certfile` parameter for more details. |
As a best practice we recommend setting these parameters as environment variables rather than command line arguments so that your database credentials or other sensitive information aren't exposed as part of the process info.
### Datastore Endpoint Format and Functionality
As mentioned, the format of the value passed to the `datastore-endpoint` parameter is dependent upon the datastore backend. The following details this format and functionality for each supported external datastore.
{{% tabs %}}
{{% tab "PostgreSQL" %}}
In its most common form, the datastore-endpoint parameter for PostgreSQL has the following format:
`postgres://username:password@hostname:port/database-name`
More advanced configuration parameters are available. For more information on these, please see https://godoc.org/github.com/lib/pq.
If you specify a database name and it does not exist, the server will attempt to create it.
If you only supply `postgres://` as the endpoint, K3s will attempt to do the following:
* Connect to localhost using `postgres` as the username and password
* Create a database named `kubernetes`
{{% /tab %}}
{{% tab "MySQL" %}}
In its most common form, the `datastore-endpoint` parameter for MySQL has the following format:
`mysql://username:password@tcp(hostname:3306)/database-name`
More advanced configuration parameters are available. For more information on these, please see https://github.com/go-sql-driver/mysql#dsn-data-source-name
Note that due to a [known issue](https://github.com/rancher/k3s/issues/1093) in K3s, you cannot set the `tls` parameter. TLS communication is supported, but you cannot, for example, set this parameter to "skip-verify" to cause K3s to skip certificate verification.
If you specify a database name and it does not exist, the server will attempt to create it.
If you only supply `mysql://` as the endpoint, K3s will attempt to do the following:
* Connect to the MySQL socket at `/var/run/mysqld/mysqld.sock` using the `root` user and no password
* Create a database with the name `kubernetes`
{{% /tab %}}
{{% tab "etcd" %}}
In its most common form, the `datastore-endpoint` parameter for etcd has the following format:
`https://etcd-host-1:2379,https://etcd-host-2:2379,https://etcd-host-3:2379`
The above assumes a typical three node etcd cluster. The parameter can accept one more comma separated etcd URLs.
{{% /tab %}}
{{% /tabs %}}
<br/>Based on the above, the following example command could be used to launch a server instance that connects to a PostgresSQL database named k3s-db:
```
K3S_DATASTORE_ENDPOINT='postgres://username:password@hostname:5432/k3s-db' k3s server
```
And the following example could be used to connect to a MySQL database using client certificate authentication:
```
K3S_DATASTORE_ENDPOINT='mysql://username:password@tcp(hostname:3306)/k3s-db' \
K3S_DATASTORE_CERTFILE='/path/to/client.crt' \
K3S_DATASTORE_KEYFILE='/path/to/client.key' \
k3s server
```
### Embedded DQLite for HA (Experimental)
K3s's use of DQLite is similar to its use of SQLite. It is simple to setup and manage. As such, there is no external configuration or additional steps to take in order to use this option. Please see [High Availability with Embedded DB (Experimental)]({{< baseurl >}}/k3s/latest/en/installation/ha-embedded/) for instructions on how to run with this option.
content/k3s/latest/en/installation/ha-embedded/_index.md
+22
View File
@@ -0,0 +1,22 @@
---
title: "High Availability with Embedded DB (Experimental)"
weight: 40
---
As of v1.0.0, K3s is previewing support for running a highly available control plane without the need for an external database. This means there is no need to manage an external etcd or SQL datastore in order to run a reliable production-grade setup. While this feature is currently experimental, we expect it to be the primary architecture for running HA K3s clusters in the future.
This architecture is achieved by embedding a dqlite database within the K3s server process. DQLite is short for "distributed SQLite." According to https://dqlite.io, it is "*a fast, embedded, persistent SQL database with Raft consensus that is perfect for fault-tolerant IoT and Edge devices.*" This makes it a natural fit for K3s.
To run K3s in this mode, you must have an odd number of server nodes. We recommend starting with three nodes.
To get started, first launch a server node with the `cluster-init` flag to enable clustering and a token that will be used as a shared secret to join additional servers to the cluster.
```
K3S_TOKEN=SECRET k3s server --cluster-init
```
After launching the first server, join the second and third servers to the cluster using the shared secret:
```
K3S_TOKEN=SECRET k3s server --server https://<ip or hostname of server1>:6443
```
Now you have a highly available control plane. Joining additional worker nodes to the cluster follows the same procedure as a single server cluster.
content/k3s/latest/en/installation/ha/_index.md
+57
View File
@@ -0,0 +1,57 @@
---
title: "High Availability with an External DB"
weight: 30
---
>**Note:** Official support for High-Availability (HA) was introduced in our v1.0.0 release.
Single server clusters can meet a variety of use cases, but for environments where uptime of the Kubernetes control plane is critical, you can run K3s in an HA configuration. An HA K3s cluster is comprised of:
* Two or more **server nodes** that will serve the Kubernetes API and run other control plane services
* An **external datastore** (as opposed to the embedded SQLite datastore used in single server setups)
* A **fixed registration address** placed in front of the server nodes to allow worker nodes to register with the cluster
The following diagram illustrates the above configuration:
![k3s HA]({{< baseurl >}}/img/k3s/k3s-production-setup.svg)
In this architecture a server node is defined as a machine (bare-metal or virtual) running the `k3s server` command. A worker node is defined as a machine running the `k3s agent` command.
Workers register through the fixed registration address, but after registration they establish a connection directly to one of the sever nodes. This is a websocket connection initiated by the `k3s agent` process and it is maintained by a client-side load balancer running as part of the agent process.
Installation Outline
--------------------
Setting up an HA cluster requires the following steps:
1. Create an external datastore
2. Launch server nodes
3. Configure fixed registration address
4. Join worker nodes
### Create an External Datastore
You will first need to create an external datastore for the cluster. See the [Cluster Datastore Options]({{< baseurl >}}/k3s/latest/en/installation/datastore/) documentation for more details.
### Launch Server Nodes
K3s requires two or more server nodes for this HA configuration. See the [Node Requirements]({{< baseurl >}}/k3s/latest/en/installation/node-requirements/) guide for minimum machine requirements.
When running the `k3s server` command on these nodes, you must set the `datastore-endpoint` parameter so that K3s knows how to connect to the external datastore. Please see the [datastore configuration guide]({{< baseurl >}}/k3s/latest/en/installation/datastore/#external-datastore-configuration-parameters) for information on configuring this parameter.
> **Note:** The same installation options available to single-server installs are also available for HA installs. For more details, see the [Installation and Configuration Options]({{< baseurl >}}/k3s/latest/en/installation/install-options/) documentation.
By default, server nodes will be schedulable and thus your workloads can get launched on them. If you wish to have a dedicated control plane where no user workloads will run, you can use taints. The <span style='white-space: nowrap'>`node-taint`</span> parameter will allow you to configure nodes with taints, for example <span style='white-space: nowrap'>`--node-taint k3s-controlplane=true:NoExecute`</span>.
Once you've launched the `k3s server` process on all server nodes, you can ensure that the cluster has come up properly by checking that the nodes are in the Ready state with `k3s kubectl get nodes`.
### Configure the Fixed Registration Address
Worker nodes need a URL to register against. This can be the IP or hostname of any of the server nodes, but in many cases those may change over time. For example, if you are running your cluster in a cloud that supports scaling groups, you may scale the server node group up and down over time, causing nodes to be created and destroyed and thus having different IPs from the initial set of server nodes. Therefore, you should have a stable endpoint in front of the server nodes that will not change over time. This endpoint can be setup using any number approaches, such as:
* A layer-4 (TCP) load balancer
* Round-robin DNS
* A virtual or elastic IP addresses
This endpoint can also be used for accessing the Kubernetes API. So you can, for example, modify your kubeconfig file to point to it instead of a specific node.
### Join Worker Nodes
Joining worker nodes in an HA cluster is the same as joining worker nodes in a single server cluster. You just need to specify the URL the agent should register to and the token it should use.
```
K3S_TOKEN=SECRET k3s agent --server https://fixed-registration-address:6443
```
content/k3s/latest/en/installation/install-options/_index.md
+183
View File
@@ -0,0 +1,183 @@
---
title: "Installation and Configuration Options"
weight: 20
---
### Installation script options
As mentioned in the [Quick-Start Guide]({{< baseurl >}}/k3s/latest/en/quick-start/), you can use the installation script available at https://get.k3s.io to install K3s as a service on systemd and openrc based systems.
The simplest form of this command is as follows:
```sh
curl -sfL https://get.k3s.io | sh -
```
When using this method to install K3s, the following environment variables can be used to configure the installation:
- `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_SKIP_START`
If set to true will not start K3s service.
- `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_BIN_DIR_READ_ONLY`
If set to true will not write files to `INSTALL_K3S_BIN_DIR`, forces setting INSTALL_K3S_SKIP_DOWNLOAD=true.
- `INSTALL_K3S_SYSTEMD_DIR`
Directory to install systemd service and environment files to, or use `/etc/systemd/system` as the default.
- `INSTALL_K3S_EXEC`
Command with flags to use for launching K3s in the service. If the command is not specified, it will default to "agent" if `K3S_URL` is set or "server" if it is not set. The final systemd command resolves to a combination of this environment variable and script args. To illustrate this, 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.
Environment variables which begin with `K3S_` will be preserved for the systemd and openrc services to use. Setting `K3S_URL` without explicitly setting an exec command will default the command to "agent". When running the agent `K3S_TOKEN` must also be set.
### Beyond the Installation Script
As stated, the installation script is primarily concerned with configuring K3s to run as a service. If you choose to not use the script, you can run K3s simply by downloading the binary from our [release page](https://github.com/rancher/k3s/releases/latest), placing it on your path, and executing it. The K3s binary supports the following commands:
Command | Description
--------|------------------
<span class='nowrap'>`k3s server`</span> | Run the K3s management server, which will also launch Kubernetes control plane components such as the API server, controller-manager, and scheduler.
<span class='nowrap'>`k3s agent`</span> | Run the K3s node agent. This will cause K3s to run as a worker node, launching the Kubernetes node services `kubelet` and `kube-proxy`.
<span class='nowrap'>`k3s kubectl`</span> | Run an embedded [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/) CLI. If the `KUBECONFIG` environment variable is not set, this will automatically attempt to use the config file that is created at `/etc/rancher/k3s/k3s.yaml` when launching a K3s server node.
<span class='nowrap'>`k3s crictl`</span> | Run an embedded [crictl](https://github.com/kubernetes-sigs/cri-tools/blob/master/docs/crictl.md). This is a CLI for interacting with Kubernetes's container runtime interface (CRI). Useful for debugging.
<span class='nowrap'>`k3s ctr`</span> | Run an embedded [ctr](https://github.com/projectatomic/containerd/blob/master/docs/cli.md). This is a CLI for containerd, the container daemon used by K3s. Useful for debugging.
<span class='nowrap'>`k3s help`</span> | Shows a list of commands or help for one command
The `k3s server` and `k3s agent` commands have additional configuration options that can be viewed with <span class='nowrap'>`k3s server --help`</span> or <span class='nowrap'>`k3s agent --help`</span>. For convenience, that help text is presented here:
### `k3s server`
```
NAME:
k3s server - Run management server
USAGE:
k3s server [OPTIONS]
OPTIONS:
-v value (logging) Number for the log level verbosity (default: 0)
--vmodule value (logging) Comma-separated list of pattern=N settings for file-filtered logging
--log value, -l value (logging) Log to file
--alsologtostderr (logging) Log to standard error as well as file (if set)
--bind-address value (listener) k3s bind address (default: 0.0.0.0)
--https-listen-port value (listener) HTTPS listen port (default: 6443)
--advertise-address value (listener) IP address that apiserver uses to advertise to members of the cluster (default: node-external-ip/node-ip)
--advertise-port value (listener) Port that apiserver uses to advertise to members of the cluster (default: listen-port) (default: 0)
--tls-san value (listener) Add additional hostname or IP as a Subject Alternative Name in the TLS cert
--data-dir value, -d value (data) Folder to hold state default /var/lib/rancher/k3s or ${HOME}/.rancher/k3s if not root
--cluster-cidr value (networking) Network CIDR to use for pod IPs (default: "10.42.0.0/16")
--service-cidr value (networking) Network CIDR to use for services IPs (default: "10.43.0.0/16")
--cluster-dns value (networking) Cluster IP for coredns service. Should be in your service-cidr range (default: 10.43.0.10)
--cluster-domain value (networking) Cluster Domain (default: "cluster.local")
--flannel-backend value (networking) One of 'none', 'vxlan', 'ipsec', or 'flannel' (default: "vxlan")
--token value, -t value (cluster) Shared secret used to join a server or agent to a cluster [$K3S_TOKEN]
--token-file value (cluster) File containing the cluster-secret/token [$K3S_TOKEN_FILE]
--write-kubeconfig value, -o value (client) Write kubeconfig for admin client to this file [$K3S_KUBECONFIG_OUTPUT]
--write-kubeconfig-mode value (client) Write kubeconfig with this mode [$K3S_KUBECONFIG_MODE]
--kube-apiserver-arg value (flags) Customized flag for kube-apiserver process
--kube-scheduler-arg value (flags) Customized flag for kube-scheduler process
--kube-controller-manager-arg value (flags) Customized flag for kube-controller-manager process
--kube-cloud-controller-manager-arg value (flags) Customized flag for kube-cloud-controller-manager process
--datastore-endpoint value (db) Specify etcd, Mysql, Postgres, or Sqlite (default) data source name [$K3S_DATASTORE_ENDPOINT]
--datastore-cafile value (db) TLS Certificate Authority file used to secure datastore backend communication [$K3S_DATASTORE_CAFILE]
--datastore-certfile value (db) TLS certification file used to secure datastore backend communication [$K3S_DATASTORE_CERTFILE]
--datastore-keyfile value (db) TLS key file used to secure datastore backend communication [$K3S_DATASTORE_KEYFILE]
--default-local-storage-path value (storage) Default local storage path for local provisioner storage class
--no-deploy value (components) Do not deploy packaged components (valid items: coredns, servicelb, traefik, local-storage, metrics-server)
--disable-scheduler (components) Disable Kubernetes default scheduler
--disable-cloud-controller (components) Disable k3s default cloud controller manager
--disable-network-policy (components) Disable k3s default network policy controller
--node-name value (agent/node) Node name [$K3S_NODE_NAME]
--with-node-id (agent/node) Append id to node name
--node-label value (agent/node) Registering kubelet with set of labels
--node-taint value (agent/node) Registering kubelet with set of taints
--docker (agent/runtime) Use docker instead of containerd
--container-runtime-endpoint value (agent/runtime) Disable embedded containerd and use alternative CRI implementation
--pause-image value (agent/runtime) Customized pause image for containerd sandbox
--private-registry value (agent/runtime) Private registry configuration file (default: "/etc/rancher/k3s/registries.yaml")
--node-ip value, -i value (agent/networking) IP address to advertise for node
--node-external-ip value (agent/networking) External IP address to advertise for node
--resolv-conf value (agent/networking) Kubelet resolv.conf file [$K3S_RESOLV_CONF]
--flannel-iface value (agent/networking) Override default flannel interface
--flannel-conf value (agent/networking) Override default flannel config file
--kubelet-arg value (agent/flags) Customized flag for kubelet process
--kube-proxy-arg value (agent/flags) Customized flag for kube-proxy process
--rootless (experimental) Run rootless
--agent-token value (experimental/cluster) Shared secret used to join agents to the cluster, but not servers [$K3S_AGENT_TOKEN]
--agent-token-file value (experimental/cluster) File containing the agent secret [$K3S_AGENT_TOKEN_FILE]
--server value, -s value (experimental/cluster) Server to connect to, used to join a cluster [$K3S_URL]
--cluster-init (experimental/cluster) Initialize new cluster master [$K3S_CLUSTER_INIT]
--cluster-reset (experimental/cluster) Forget all peers and become a single cluster new cluster master [$K3S_CLUSTER_RESET]
--no-flannel (deprecated) use --flannel-backend=none
--cluster-secret value (deprecated) use --token [$K3S_CLUSTER_SECRET]
```
### `k3s agent`
```
NAME:
k3s agent - Run node agent
USAGE:
k3s agent [OPTIONS]
OPTIONS:
-v value (logging) Number for the log level verbosity (default: 0)
--vmodule value (logging) Comma-separated list of pattern=N settings for file-filtered logging
--log value, -l value (logging) Log to file
--alsologtostderr (logging) Log to standard error as well as file (if set)
--token value, -t value (cluster) Token to use for authentication [$K3S_TOKEN]
--token-file value (cluster) Token file to use for authentication [$K3S_TOKEN_FILE]
--server value, -s value (cluster) Server to connect to [$K3S_URL]
--data-dir value, -d value (agent/data) Folder to hold state (default: "/var/lib/rancher/k3s")
--node-name value (agent/node) Node name [$K3S_NODE_NAME]
--with-node-id (agent/node) Append id to node name
--node-label value (agent/node) Registering kubelet with set of labels
--node-taint value (agent/node) Registering kubelet with set of taints
--docker (agent/runtime) Use docker instead of containerd
--container-runtime-endpoint value (agent/runtime) Disable embedded containerd and use alternative CRI implementation
--pause-image value (agent/runtime) Customized pause image for containerd sandbox
--private-registry value (agent/runtime) Private registry configuration file (default: "/etc/rancher/k3s/registries.yaml")
--node-ip value, -i value (agent/networking) IP address to advertise for node
--node-external-ip value (agent/networking) External IP address to advertise for node
--resolv-conf value (agent/networking) Kubelet resolv.conf file [$K3S_RESOLV_CONF]
--flannel-iface value (agent/networking) Override default flannel interface
--flannel-conf value (agent/networking) Override default flannel config file
--kubelet-arg value (agent/flags) Customized flag for kubelet process
--kube-proxy-arg value (agent/flags) Customized flag for kube-proxy process
--rootless (experimental) Run rootless
--no-flannel (deprecated) use --flannel-backend=none
--cluster-secret value (deprecated) use --token [$K3S_CLUSTER_SECRET]
```
content/k3s/latest/en/installation/node-requirements/_index.md
+38
View File
@@ -0,0 +1,38 @@
---
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.
## Prerequisites
* Two nodes cannot have the same hostname. If all your nodes have the same hostname, pass `--node-name` or set `$K3S_NODE_NAME` with a unique name for each node you add to the cluster.
## 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)
* Raspbian 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.
If you wish to utilize the metrics server, you will need to open port 10250 on each node.
content/k3s/latest/en/known-issues/_index.md
+13
View File
@@ -0,0 +1,13 @@
---
title: Known Issues
weight: 70
---
The Known Issues are updated periodically and designed to inform you about any issues that may not be immediately addressed in the next upcoming release.
**Snap Docker**
If you plan to use K3s with docker, Docker installed via a snap package is not recommended as it has been known to cause issues running K3s.
**Iptables**
If you are running iptables in nftables mode instead of legacy you might encounter issues. We recommend utilizing newer iptables (such as 1.6.1+) to avoid issues.
content/k3s/latest/en/networking/_index.md
+43
View File
@@ -0,0 +1,43 @@
---
title: "Networking"
weight: 35
---
Open Ports
----------
Please reference the [Node Requirements]({{< baseurl >}}/k3s/latest/en/installation/node-requirements/#networking) page for port information.
Flannel
-------
Flannel is included by default, if you don't want flannel then run each agent with `--no-flannel` option.
In this setup you will still be required to install your own CNI driver. More info [here](https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#pod-network)
CoreDNS
-------
CoreDNS is deployed on start of the agent, to disable run each server with the `--no-deploy coredns` option.
If you don't install CoreDNS you will need to install a cluster DNS provider yourself.
Traefik Ingress Controller
--------------------------
Traefik is deployed by default when starting the server. For more information see [Auto Deploying Manifests]({{< baseurl >}}/k3s/latest/en/configuration/#auto-deploying-manifests). The default config file is found in `/var/lib/rancher/k3s/server/manifests/traefik.yaml` and any changes made to this file will automatically be deployed to Kubernetes in a manner similar to `kubectl apply`.
The Traefik ingress controller will use ports 80, 443, and 8080 on the host (i.e. these will not be usable for HostPort or NodePort).
You can tweak traefik to meet your needs by setting options in the traefik.yaml file.
Reference the official [Traefik for Helm Configuration Parameters](https://github.com/helm/charts/tree/master/stable/traefik#configuration) readme for more information.
To disable it, start each server with the `--no-deploy traefik` option.
Service Load Balancer
---------------------
K3s includes a basic service load balancer that uses available host ports. If you try to create
a load balancer that listens on port 80, for example, it will try to find a free host in the cluster
for port 80. If no port is available the load balancer will stay in Pending.
To disable the embedded load balancer run the server with the `--no-deploy servicelb` option. This is necessary if you wish to run a different load balancer, such as MetalLB.
content/k3s/latest/en/quick-start/_index.md
+16 -30
View File
@@ -1,44 +1,30 @@
---
title: "Quick-Start"
weight: 1
title: "Quick-Start Guide"
weight: 10
---
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:** This guide will help you quickly launch a cluster with default options. The [installation section](../installation) covers in greater detail how K3s can be set up.
> New to Kubernetes? The official Kubernetes docs already have some great tutorials outlining the basics [here](https://kubernetes.io/docs/tutorials/kubernetes-basics/).
Install Script
--------------
The k3s `install.sh` script provides a convenient way for installing to systemd or openrc,
to install k3s as a service just run:
K3s provides an installation script that is a convenient way to install it as a service on systemd or openrc based systems. This script is available at https://get.k3s.io. To install K3s using this method, just run:
```bash
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:
After running this installation:
* The K3s service will be configured to automatically restart after node reboots or if the process crashes or is killed
* Additional utilities will be installed, including `kubectl`, `crictl`, `ctr`, `k3s-killall.sh`, and `k3s-uninstall.sh`
* A kubeconfig file will be written to `/etc/rancher/k3s/k3s.yaml` and the kubectl installed by K3s will automatically use it
To install on worker nodes and add them to the cluster, run the installation script with the `K3S_URL` and `K3S_TOKEN` environment variables. Here is an example showing how to join a worker node:
```bash
sudo kubectl get nodes
curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken sh -
```
Setting the `K3S_URL` parameter causes K3s to run in worker mode. The K3s agent will register with the K3s server listening at the supplied URL. The value to use for `K3S_TOKEN` is stored at `/var/lib/rancher/k3s/server/node-token` on your server 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/k3s/latest/en/running/_index.md
-253
View File
@@ -1,253 +0,0 @@
---
title: "Running K3S"
weight: 3
---
This section contains information for running k3s in various environments.
Starting the Server
------------------
The installation script will auto-detect if your OS is using systemd or openrc and start the service.
When running with openrc logs will be created at `/var/log/k3s.log`, or with systemd in `/var/log/syslog` and viewed using `journalctl -u k3s`. An example of installing and auto-starting with the install script:
```bash
curl -sfL https://get.k3s.io | sh -
```
When running the server manually you should get an output similar to:
```
$ k3s server
INFO[2019-01-22T15:16:19.908493986-07:00] Starting k3s dev
INFO[2019-01-22T15:16:19.908934479-07:00] Running kube-apiserver --allow-privileged=true --authorization-mode Node,RBAC --service-account-signing-key-file /var/lib/rancher/k3s/server/tls/service.key --service-cluster-ip-range 10.43.0.0/16 --advertise-port 6445 --advertise-address 127.0.0.1 --insecure-port 0 --secure-port 6444 --bind-address 127.0.0.1 --tls-cert-file /var/lib/rancher/k3s/server/tls/localhost.crt --tls-private-key-file /var/lib/rancher/k3s/server/tls/localhost.key --service-account-key-file /var/lib/rancher/k3s/server/tls/service.key --service-account-issuer k3s --api-audiences unknown --basic-auth-file /var/lib/rancher/k3s/server/cred/passwd --kubelet-client-certificate /var/lib/rancher/k3s/server/tls/token-node.crt --kubelet-client-key /var/lib/rancher/k3s/server/tls/token-node.key
Flag --insecure-port has been deprecated, This flag will be removed in a future version.
INFO[2019-01-22T15:16:20.196766005-07:00] Running kube-scheduler --kubeconfig /var/lib/rancher/k3s/server/cred/kubeconfig-system.yaml --port 0 --secure-port 0 --leader-elect=false
INFO[2019-01-22T15:16:20.196880841-07:00] Running kube-controller-manager --kubeconfig /var/lib/rancher/k3s/server/cred/kubeconfig-system.yaml --service-account-private-key-file /var/lib/rancher/k3s/server/tls/service.key --allocate-node-cidrs --cluster-cidr 10.42.0.0/16 --root-ca-file /var/lib/rancher/k3s/server/tls/token-ca.crt --port 0 --secure-port 0 --leader-elect=false
Flag --port has been deprecated, see --secure-port instead.
INFO[2019-01-22T15:16:20.273441984-07:00] Listening on :6443
INFO[2019-01-22T15:16:20.278383446-07:00] Writing manifest: /var/lib/rancher/k3s/server/manifests/coredns.yaml
INFO[2019-01-22T15:16:20.474454524-07:00] Node token is available at /var/lib/rancher/k3s/server/node-token
INFO[2019-01-22T15:16:20.474471391-07:00] To join node to cluster: k3s agent -s https://10.20.0.3:6443 -t ${NODE_TOKEN}
INFO[2019-01-22T15:16:20.541027133-07:00] Wrote kubeconfig /etc/rancher/k3s/k3s.yaml
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
------------
In order to pre-setup Alpine Linux you have to go through the following steps:
```bash
echo "cgroup /sys/fs/cgroup cgroup defaults 0 0" >> /etc/fstab
cat >> /etc/cgconfig.conf <<EOF
mount {
cpuacct = /cgroup/cpuacct;
memory = /cgroup/memory;
devices = /cgroup/devices;
freezer = /cgroup/freezer;
net_cls = /cgroup/net_cls;
blkio = /cgroup/blkio;
cpuset = /cgroup/cpuset;
cpu = /cgroup/cpu;
}
EOF
```
Then update **/etc/update-extlinux.conf** by adding:
```
default_kernel_opts="... cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory"
```
Then update the config and reboot:
```bash
update-extlinux
reboot
```
After rebooting:
- download **k3s** to **/usr/local/bin/k3s**
- create an openrc file in **/etc/init.d**
Running in Docker (and docker-compose)
-----------------
[k3d](https://github.com/rancher/k3d) is a utility designed to easily run k3s in Docker. It can be installed via the [brew](https://brew.sh/) utility for MacOS.
`rancher/k3s` images are also available to run k3s server and agent from Docker. A `docker-compose.yml` is in the root of the k3s repo that
serves as an example of how to run k3s from Docker. To run from `docker-compose` from this repo run:
docker-compose up --scale node=3
# kubeconfig is written to current dir
kubectl --kubeconfig kubeconfig.yaml get node
NAME STATUS ROLES AGE VERSION
497278a2d6a2 Ready <none> 11s v1.13.2-k3s2
d54c8b17c055 Ready <none> 11s v1.13.2-k3s2
db7a5a5a5bdd Ready <none> 12s v1.13.2-k3s2
To run the agent only in Docker, use `docker-compose up node`. Alternatively the Docker run command can also be used;
sudo docker run \
-d --tmpfs /run \
--tmpfs /var/run \
-e K3S_URL=${SERVER_URL} \
-e K3S_TOKEN=${NODE_TOKEN} \
--privileged rancher/k3s:vX.Y.Z
Air-Gap Support
---------------
k3s supports pre-loading of containerd images by placing them in the `images` directory for the agent before starting, for example:
```sh
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/
```
Images needed for a base install are provided through the releases page, additional images can be created with the `docker save` command.
Offline Helm charts are served from the `/var/lib/rancher/k3s/server/static` directory, and Helm chart manifests may reference the static files with a `%{KUBERNETES_API}%` templated variable. For example, the default traefik manifest chart installs from `https://%{KUBERNETES_API}%/static/charts/traefik-X.Y.Z.tgz`.
If networking is completely disabled k3s may not be able to start (ie ethernet unplugged or wifi disconnected), in which case it may be necessary to add a default route. For example:
```sh
sudo ip -c address add 192.168.123.123/24 dev eno1
sudo ip route add default via 192.168.123.1
```
k3s additionally provides a `--resolv-conf` flag for kubelets, which may help with configuring DNS in air-gap networks.
Upgrades
--------
To upgrade k3s from an older version you can re-run the installation script using the same flags, for example:
```sh
curl -sfL https://get.k3s.io | sh -
```
If you want to upgrade to specific version you can run the following command:
```sh
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=vX.Y.Z-rc1 sh -
```
Or to manually upgrade k3s:
1. Download the desired version of k3s from [releases](https://github.com/rancher/k3s/releases/latest)
2. Install to an appropriate location (normally `/usr/local/bin/k3s`)
3. Stop the old version
4. Start the new version
Restarting k3s is supported by the installation script for systemd and openrc.
To restart manually for systemd use:
```sh
sudo systemctl restart k3s
```
To restart manually for openrc use:
```sh
sudo service k3s restart
```
Upgrading an air-gap environment can be accomplished in the following manner:
1. Download air-gap images and install if changed
2. Install new k3s binary (from installer or manual download)
3. Restart k3s (if not restarted automatically by installer)
Uninstalling
------------
If you installed k3s with the help of `install.sh` script an uninstall script is generated during installation, which will be created on your server node at `/usr/local/bin/k3s-uninstall.sh` (or as `k3s-agent-uninstall.sh`).
Hyperkube
---------
k3s is bundled in a nice wrapper to remove the majority of the headache of running k8s. If
you don't want that wrapper and just want a smaller k8s distro, the releases includes
the `hyperkube` binary you can use. It's then up to you to know how to use `hyperkube`. If
you want individual binaries you will need to compile them yourself from source.
content/k3s/latest/en/storage/_index.md
+122
View File
@@ -0,0 +1,122 @@
---
title: "Volumes and Storage"
weight: 30
---
When deploying an application that needs to retain data, you’ll need to create persistent storage. Persistent storage allows you to store application data external from the pod running your application. This storage practice allows you to maintain application data, even if the application’s pod fails.
# Local Storage Provider
K3s comes with Rancher's Local Path Provisioner and this enables the ability to create persistent volume claims out of the box using local storage on the respective node. Below we cover a simple example. For more information please reference the official documentation [here](https://github.com/rancher/local-path-provisioner/blob/master/README.md#usage).
Create a hostPath backed persistent volume claim and a pod to utilize it:
### pvc.yaml
```
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: local-path-pvc
namespace: default
spec:
accessModes:
- ReadWriteOnce
storageClassName: local-path
resources:
requests:
storage: 2Gi
```
### pod.yaml
```
apiVersion: v1
kind: Pod
metadata:
name: volume-test
namespace: default
spec:
containers:
- name: volume-test
image: nginx:stable-alpine
imagePullPolicy: IfNotPresent
volumeMounts:
- name: volv
mountPath: /data
ports:
- containerPort: 80
volumes:
- name: volv
persistentVolumeClaim:
claimName: local-path-pvc
```
Apply the yaml `kubectl create -f pvc.yaml` and `kubectl create -f pod.yaml`
Confirm the PV and PVC are created. `kubectl get pv` and `kubectl get pvc` The status should be Bound for each.
# Longhorn
[comment]: <> (pending change - longhorn may support arm64 and armhf in the future.)
> **Note:** At this time Longhorn only supports amd64.
K3s supports [Longhorn](https://github.com/longhorn/longhorn). Below we cover a simple example. For more information please reference the official documentation [here](https://github.com/longhorn/longhorn/blob/master/README.md).
Apply the longhorn.yaml to install Longhorn.
```
kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/master/deploy/longhorn.yaml
```
Longhorn will be installed in the namespace `longhorn-system`.
Before we create a PVC, we will create a storage class for longhorn with this yaml.
```
kubectl create -f https://raw.githubusercontent.com/longhorn/longhorn/master/examples/storageclass.yaml
```
Now, apply the following yaml to create the PVC and pod with `kubectl create -f pvc.yaml` and `kubectl create -f pod.yaml`
### pvc.yaml
```
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: longhorn-volv-pvc
spec:
accessModes:
- ReadWriteOnce
storageClassName: longhorn
resources:
requests:
storage: 2Gi
```
### pod.yaml
```
apiVersion: v1
kind: Pod
metadata:
name: volume-test
namespace: default
spec:
containers:
- name: volume-test
image: nginx:stable-alpine
imagePullPolicy: IfNotPresent
volumeMounts:
- name: volv
mountPath: /data
ports:
- containerPort: 80
volumes:
- name: volv
persistentVolumeClaim:
claimName: longhorn-volv-pvc
```
Confirm the PV and PVC are created. `kubectl get pv` and `kubectl get pvc` The status should be Bound for each.
content/k3s/latest/en/upgrades/_index.md
+36
View File
@@ -0,0 +1,36 @@
---
title: "Upgrades"
weight: 25
---
>**Note:** When upgrading, upgrade server nodes first one at a time then any worker nodes.
To upgrade K3s from an older version you can re-run the installation script using the same flags, for example:
```sh
curl -sfL https://get.k3s.io | sh -
```
If you want to upgrade to specific version you can run the following command:
```sh
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=vX.Y.Z-rc1 sh -
```
Or to manually upgrade K3s:
1. Download the desired version of K3s from [releases](https://github.com/rancher/k3s/releases/latest)
2. Install to an appropriate location (normally `/usr/local/bin/k3s`)
3. Stop the old version
4. Start the new version
Restarting K3s is supported by the installation script for systemd and openrc.
To restart manually for systemd use:
```sh
sudo systemctl restart k3s
```
To restart manually for openrc use:
```sh
sudo service k3s restart
```
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/configuration/date-and-timezone/_index.md
+22
View File
@@ -0,0 +1,22 @@
---
title: Date and time zone
weight: 121
---
The default console keeps time in the Coordinated Universal Time (UTC) zone and synchronizes clocks with the Network Time Protocol (NTP). The Network Time Protocol daemon (ntpd) is an operating system program that maintains the system time in synchronization with time servers using the NTP.
RancherOS can run ntpd in the System Docker container. You can update its configurations by updating `/etc/ntp.conf`. For an example of how to update a file such as `/etc/ntp.conf` within a container, refer to [this page.]({{< baseurl >}}/os/v1.x/en/installation/configuration/write-files/#writing-files-in-specific-system-services)
The default console cannot support changing the time zone because including `tzdata` (time zone data) will increase the ISO size. However, you can change the time zone in the container by passing a flag to specify the time zone when you run the container:
```
$ docker run -e TZ=Europe/Amsterdam debian:jessie date
Tue Aug 20 09:28:19 CEST 2019
```
You may need to install the `tzdata` in some images:
```
$ docker run -e TZ=Asia/Shanghai -e DEBIAN_FRONTEND=noninteractive -it --rm ubuntu /bin/bash -c "apt-get update && apt-get install -yq tzdata && date”
Thu Aug 29 08:13:02 CST 2019
```
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/_index.md
+1 -1
View File
@@ -42,7 +42,7 @@ Drivers in Rancher allow you to manage which providers can be used to provision
For more information, see [Provisioning Drivers]({{< baseurl >}}/rancher/v2.x/en/admin-settings/drivers/).
## Adding Kubernetes Versions into RANCHER
## Adding Kubernetes Versions into Rancher
_Available as of v2.3.0_
content/rancher/v2.x/en/admin-settings/authentication/ad/_index.md
+6 -4
View File
@@ -74,11 +74,12 @@ The table below details the parameters for the user schema section configuration
| Parameter | Description |
|:--|:--|
| Object Class | The name of the object class used for user objects in your domain. |
| Object Class | The name of the object class used for user objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
| Username Attribute | The user attribute whose value is suitable as a display name. |
| Login Attribute | The attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. If your users authenticate with their UPN (e.g. "jdoe@acme.com") as username then this field must normally be set to `userPrincipalName`. Otherwise for the old, NetBIOS-style logon names (e.g. "jdoe") it's usually `sAMAccountName`. |
| User Member Attribute | The attribute containing the groups that a user is a member of. |
| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the AD server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("\|") symbol. To match UPN usernames (e.g. jdoe@acme.com) you should usually set the value of this field to `userPrincipalName`. |
| Search Filter | This filter gets applied to the list of users that is searched when Rancher attempts to add users to a site access list or tries to add members to clusters or projects. For example, a user search filter could be <code>(&#124;(memberOf=CN=group1,CN=Users,DC=testad,DC=rancher,DC=io)(memberOf=CN=group2,CN=Users,DC=testad,DC=rancher,DC=io))</code>. Note: If the search filter does not use [valid AD search syntax,](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax) the list of users will be empty. |
| User Enabled Attribute | The attribute containing an integer value representing a bitwise enumeration of user account flags. Rancher uses this to determine if a user account is disabled. You should normally leave this set to the AD standard `userAccountControl`. |
| Disabled Status Bitmask | This is the value of the `User Enabled Attribute` designating a disabled user account. You should normally leave this set to the default value of "2" as specified in the Microsoft Active Directory schema (see [here](https://docs.microsoft.com/en-us/windows/desktop/adschema/a-useraccountcontrol#remarks)). |
@@ -92,11 +93,12 @@ The table below details the parameters for the group schema configuration.
| Parameter | Description |
|:--|:--|
| Object Class | The name of the object class used for group objects in your domain. |
| Object Class | The name of the object class used for group objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
| Name Attribute | The group attribute whose value is suitable for a display name. |
| Group Member User Attribute | The name of the **user attribute** whose format matches the group members in the `Group Member Mapping Attribute`. |
| Group Member Mapping Attribute | The name of the group attribute containing the members of a group. |
| Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects. See description of user schema `Search Attribute`. |
| Search Filter | This filter gets applied to the list of groups that is searched when Rancher attempts to add groups to a site access list or tries to add groups to clusters or projects. For example, a group search filter could be <code>(&#124;(cn=group1)(cn=group2))</code>. Note: If the search filter does not use [valid AD search syntax,](https://docs.microsoft.com/en-us/windows/win32/adsi/search-filter-syntax) the list of groups will be empty. |
| Group DN Attribute | The name of the group attribute whose format matches the values in the user attribute describing a the user's memberships. See `User Member Attribute`. |
| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organisation makes use of these nested memberships (ie. you have groups that contain other groups as members). |
@@ -146,7 +148,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 +181,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/azure-ad/_index.md
+2
View File
@@ -9,6 +9,8 @@ _Available as of v2.0.3_
If you have an instance of Active Directory (AD) hosted in Azure, you can configure Rancher to allow your users to log in using their AD accounts. Configuration of Azure AD external authentication requires you to make configurations in both Azure and Rancher.
>**Note:** Azure AD integration only supports Service Provider initiated logins.
>**Prerequisite:** Have an instance of Azure AD configured.
>**Note:** Most of this procedure takes place from the [Microsoft Azure Portal](https://portal.azure.com/).
content/rancher/v2.x/en/admin-settings/authentication/google/_index.md
+3
View File
@@ -94,6 +94,9 @@ Using the Unique ID of the service account key, register it as an Oauth Client u
1. Sign into Rancher using a local user assigned the [administrator]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions) role. This user is also called the local principal.
1. From the **Global** view, click **Security > Authentication** from the main menu.
1. Click **Google.** The instructions in the UI cover the steps to set up authentication with Google OAuth.
1. Admin Email: Provide the email of an administrator account from your GSuite setup. In order to perform user and group lookups, google apis require an administrator's email in conjunction with the service account key.
1. Domain: Provide the domain on which you have configured GSuite. Provide the exact domain and not any aliases.
1. Nested Group Membership: Check this box to enable nested group memberships. Rancher admins can disable this at any time after configuring auth.
- **Step One** is about adding Rancher as an authorized domain, which we already covered in [this section.](#1-adding-rancher-as-an-authorized-domain)
- For **Step Two,** provide the OAuth credentials JSON that you downloaded after completing [this section.](#2-creating-oauth2-credentials-for-the-rancher-server) You can upload the file or paste the contents into the **OAuth Credentials** field.
- For **Step Three,** provide the service account credentials JSON that downloaded at the end of [this section.](#3-creating-service-account-credentials) The credentials will only work if you successfully [registered the service account key](#4-register-the-service-account-key-as-an-oauth-client) as an OAuth client in your G Suite account.
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/authentication/okta/_index.md
+2
View File
@@ -7,6 +7,8 @@ _Available as of v2.2.0_
If your organization uses Okta Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
>**Note:** Okta integration only supports Service Provider initiated logins.
## Prerequisites
In Okta, create a SAML Application with the settings below. See the [Okta documentation](https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta) for help.
content/rancher/v2.x/en/admin-settings/authentication/openldap/_index.md
+2 -2
View File
@@ -75,7 +75,7 @@ The table below details the parameters for the user schema configuration.
| Parameter | Description |
|:--|:--|
| Object Class | The name of the object class used for user objects in your domain. |
| Object Class | The name of the object class used for user objects in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
| Username Attribute | The user attribute whose value is suitable as a display name. |
| Login Attribute | The attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. This is typically `uid`. |
| User Member Attribute | The user attribute containing the Distinguished Name of groups a user is member of. Usually this is one of `memberOf` or `isMemberOf`. |
@@ -93,7 +93,7 @@ The table below details the parameters for the group schema configuration.
| Parameter | Description |
|:--|:--|
| Object Class | The name of the object class used for group entries in your domain. |
| Object Class | The name of the object class used for group entries in your domain. If defined, only specify the name of the object class - *don't* include it in an LDAP wrapper such as &(objectClass=xxxx) |
| Name Attribute | The group attribute whose value is suitable for a display name. |
| Group Member User Attribute | The name of the **user attribute** whose format matches the group members in the `Group Member Mapping Attribute`. |
| Group Member Mapping Attribute | The name of the group attribute containing the members of a group. |
content/rancher/v2.x/en/admin-settings/feature-flags/_index.md
+16 -10
View File
@@ -25,10 +25,16 @@ For example, if you install Rancher, then set a feature flag to true with the Ra
The following is a list of the feature flags available in Rancher:
Feature | Environment Variable Key | Default Value | Description | Available as of |
---|---|---|---|---
[Allow unsupported storage drivers]({{<baseurl>}}/rancher/v2.x/en/admin-settings/feature-flags/enable-not-default-storage-drivers) | `unsupported-storage-drivers` | `false` | This feature enables types for storage providers and provisioners that are not enabled by default. | v2.3.0
[UI for Istio virtual services and destination rules]({{<baseurl>}}/rancher/v2.x/en/admin-settings/feature-flags/istio-virtual-service-ui) | `istio-virtual-service-ui`| `false` | Enables a UI that lets you create, read, update and delete virtual services and destination rules, which are traffic management features of Istio | v2.3.0
- `unsupported-storage-drivers`: This feature [allows unsupported storage drivers.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/feature-flags/enable-not-default-storage-drivers) In other words, it enables types for storage providers and provisioners that are not enabled by default.
- `istio-virtual-service-ui`: This feature enables a [UI to create, read, update, and delete Istio virtual services and destination rules]({{<baseurl>}}/rancher/v2.x/en/admin-settings/feature-flags/istio-virtual-service-ui), which are traffic management features of Istio.
The below table shows the availability and default value for feature flags in Rancher:
Feature Flag Name | Default Value | Status | Available as of |
---|---|---|---
`unsupported-storage-drivers` | `false` | Experimental | v2.3.0
`istio-virtual-service-ui` | `false` | Experimental | v2.3.0
`istio-virtual-service-ui` | `true` | GA | v2.3.2
# Enabling Features when Starting Rancher
@@ -38,21 +44,21 @@ When you install Rancher, enable the feature you want with a feature flag. The c
{{% tabs %}}
{{% tab "HA Install" %}}
When installing Rancher with a Helm chart, use the `--features` option:
When installing Rancher with a Helm chart, use the `--features` option. In the below example, two features are enabled by passing the feature flag names names in a comma separated list:
```
helm install rancher-latest/rancher \
--name rancher \
--namespace cattle-system \
--set hostname=rancher.my.org \
--set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
--set 'extraEnv[0].value=<FEATURE-NAME1>=true,<FEATURE-NAME2>=true' # Available as of v2.3.0
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0
```
### Rendering the Helm Chart for Air Gap Installations
For an air gap installation of Rancher, you need to add a Helm chart repository and render a Helm template before installing Rancher with Helm. For details, refer to the [air gap installation documentation.]({{<baseurl>}}/rancher/v2.x/en/installation/air-gap/install-rancher)
Here is an example of a command for passing in the feature flag options when rendering the Helm template:
Here is an example of a command for passing in the feature flag names when rendering the Helm template. In the below example, two features are enabled by passing the feature flag names in a comma separated list:
```
helm template ./rancher-<VERSION>.tgz --output-dir . \
--name rancher \
@@ -63,16 +69,16 @@ helm template ./rancher-<VERSION>.tgz --output-dir . \
--set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
--set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
--set 'extraEnv[0].value=<FEATURE-NAME1>=true,<FEATURE-NAME2>=true' # Available as of v2.3.0
--set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0
```
{{% /tab %}}
{{% tab "Single Node Install" %}}
When installing Rancher with Docker, use the `--features` option:
When installing Rancher with Docker, use the `--features` option. In the below example, two features are enabled by passing the feature flag names in a comma separated list:
```
docker run -d -p 80:80 -p 443:443 \
--restart=unless-stopped \
rancher/rancher:rancher-latest \
--features=<FEATURE-NAME1>=true,<FEATURE-NAME2>=true # Available as of v2.3.0
--features=<FEATURE-FLAG-NAME-1>=true,<FEATURE-NAME-2>=true # Available as of v2.3.0
```
{{% /tab %}}
{{% /tabs %}}
content/rancher/v2.x/en/admin-settings/feature-flags/istio-virtual-service-ui/_index.md
+6 -3
View File
@@ -4,13 +4,16 @@ weight: 2
---
_Available as of v2.3.0_
This feature enables a UI that lets you create, read, update and delete virtual services and destination rules, which are traffic management features of Istio.
> **Prerequisite:** Turning on this feature does not enable Istio. A cluster administrator needs to [enable Istio for the cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup) in order to use the feature.
To enable or disable this feature, refer to the instructions on [the main page about enabling experimental features.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/feature-flags)
Environment Variable Key | Default Value | Description
---|---|---
`istio-virtual-service-ui`| `false` | Enables a UI that lets you create, read, update and delete virtual services and destination rules, which are traffic management features of Istio
Environment Variable Key | Default Value | Status | Available as of
---|---|---|---
`istio-virtual-service-ui` |`false` | Experimental | v2.3.0
`istio-virtual-service-ui` | `true` | GA | v2.3.2
# About this Feature
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/admin-settings/rke-templates/example-yaml/_index.md
+14 -1
View File
@@ -12,8 +12,21 @@ The YAML in the RKE template uses the same customization that is used when you c
# Cluster Config
#
docker_root_dir: /var/lib/docker
enable_cluster_alerting: false
enable_cluster_monitoring: false
# This setting is not enforced. Clusters
# created with this sample template
# would have alerting turned off by default,
# but end users could still turn alerting
# on or off.
enable_cluster_monitoring: true
# This setting is not enforced. Clusters
# created with this sample template
# would have monitoring turned on
# by default, but end users could still
# turn monitoring on or off.
enable_network_policy: false
local_cluster_auth_endpoint:
enabled: true
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/cloning-clusters/_index.md
+2
View File
@@ -53,6 +53,8 @@ Begin by using Rancher CLI to export the configuration for the cluster that you
Use your favorite text editor to modify the cluster configuration in `cluster-template.yml` for your cloned cluster.
> **Note:** As of Rancher v2.3.0, cluster configuration directives must be nested under the `rancher_kubernetes_engine_config` directive in `cluster.yml`. For more information, refer to the section on [the config file structure in Rancher v2.3.0+.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#config-file-structure-in-rancher-v2-3-0)
1. Open `cluster-template.yml` (or whatever you named your config) in your favorite text editor.
>**Warning:** Only edit the cluster config values explicitly called out below. Many of the values listed in this file are used to provision your cloned cluster, and editing their values may break the provisioning process.
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/alerts/default-alerts/_index.md
+1 -6
View File
@@ -54,9 +54,4 @@ Alerts can be triggered based on node metrics. Each computing resource in a Kube
| Node disk is running full within 24 hours | A critical alert is triggered if the disk space on the node is expected to run out in the next 24 hours based on the disk growth over the last 6 hours. |
# Project-level Alerts
When you enable monitoring for the project, some project-level alerts are provided.
| Alert | Explanation |
|-------|-------------|
| Less than half workload available | A critical alert is triggered if less than half of a workload is available, based on workloads where the key is `app` and the value is `workload`. |
| Memory usage close to the quota | A warning alert is triggered if the workload's memory usage exceeds the memory resource quota that is set for the workload. You can see the memory limit in the Rancher UI if you go to the workload under the **Security & Host Config** tab. |
When you enable monitoring for the project, some project-level alerts are provided. For details, refer to the [section on project-level alerts.]({{<baseurl>}}/rancher/v2.x/en/project-admin/tools/alerts/#default-project-level-alerts)
content/rancher/v2.x/en/cluster-admin/tools/istio/setup/_index.md
+3 -3
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)
@@ -23,6 +23,6 @@ If you use Istio for traffic management, you will need to allow external traffic
This guide assumes you have already [installed Rancher,]({{<baseurl>}}/rancher/v2.x/en/installation) and you have already [provisioned a separate Kubernetes cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning) on which you will install Istio.
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 nodes in your cluster must meet the [CPU and memory requirements.]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/resources/)
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/deploy-workloads/_index.md
+4 -3
View File
@@ -15,9 +15,10 @@ Wait a few minutes for the workload to upgrade to have the istio sidecar. Click
Next we add the Kubernetes resources for the sample deployments and services for the BookInfo app in Istio's documentation.
1. Go to the cluster view and click **Import YAML.**
1. Go to the project inside the cluster you want to deploy the workload on.
1. In Workloads, click **Import YAML.**
1. Copy the below resources into the form.
1. Click **Import.**
1. Click **Import.**
This will set up the following sample resources from Istio's example BookInfo app:
@@ -318,4 +319,4 @@ spec:
---
```
### [Next: Set up the Istio Gateway]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/gateway)
### [Next: Set up the Istio Gateway]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/gateway)
content/rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-cluster/_index.md
+2 -2
View File
@@ -7,7 +7,7 @@ This cluster uses the default Nginx controller to allow traffic into the cluster
A Rancher [administrator]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) or [cluster owner]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) can configure Rancher to deploy Istio in a Kubernetes cluster.
1. From the **Global** view, navigate to the cluster where you want to enable Istio.
1. From the **Global** view, navigate to the **cluster** where you want to enable Istio.
1. Click **Tools > Istio.**
1. Optional: Configure member access and [resource limits]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/config/) for the Istio components. Ensure you have enough resources on your worker nodes to enable Istio.
1. Click **Enable**.
@@ -19,4 +19,4 @@ The Istio application, `cluster-istio`, is added as an [application]({{<baseurl>
When Istio is enabled in the cluster, the label for Istio sidecar auto injection,`istio-injection=enabled`, will be automatically added to each new namespace in this cluster. This automatically enables Istio sidecar injection in all new workloads that are deployed in those namespaces. You will need to manually enable Istio in preexisting namespaces and workloads.
### [Next: Enable Istio in a Namespace]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-namespace)
### [Next: Enable Istio in a Namespace]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-namespace)
content/rancher/v2.x/en/cluster-admin/tools/istio/setup/enable-istio-in-namespace/_index.md
+21
View File
@@ -21,4 +21,25 @@ This namespace setting will only affect new workloads in the namespace. Any pree
To verify that Istio is enabled, deploy a hello-world workload in the namespace. Go to the workload and click the pod name. In the **Containers** section, you should see the `istio-proxy` container.
### Excluding Workloads from Being Injected with the Istio Sidecar
If you need to exclude a workload from getting injected with the Istio sidecar, use the following annotation on the workload:
```
sidecar.istio.io/inject: “false”
```
To add the annotation to a workload,
1. From the **Global** view, open the project that has the workload that should not have the sidecar.
1. Click **Resources > Workloads.**
1. Go to the workload that should not have the sidecar and click **Ellipsis (...) > Edit.**
1. Click **Show Advanced Options.** Then expand the **Labels & Annotations** section.
1. Click **Add Annotation.**
1. In the **Key** field, enter `sidecar.istio.io/inject`.
1. In the **Value** field, enter `false`.
1. Click **Save.**
**Result:** The Istio sidecar will not be injected into the workload.
### [Next: Set up Taints and Tolerations]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/tools/istio/setup/node-selectors)
content/rancher/v2.x/en/cluster-admin/tools/istio/setup/gateway/_index.md
+29 -2
View File
@@ -53,13 +53,40 @@ 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.
Confirm that the resource exists by running:
```
kubectl get gateway
kubectl get gateway -A
```
The result should be something like this:
@@ -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/logging/syslog/_index.md
+2
View File
@@ -21,6 +21,8 @@ If you are using rsyslog, please make sure your rsyslog authentication mode is `
1. Select a **Log Severity** for events that are logged to the Syslog server. For more information on each severity level, see the [Syslog protocol documentation](https://tools.ietf.org/html/rfc5424#page-11).
- By specifying a **Log Severity** does not mean that will act as a filtering mechanism for logs. To do that you should use a parser on the Syslog server.
## Encryption Configuration
If your Syslog server is using **TCP** protocol and uses TLS, you need to select **Use TLS** and complete the **Encryption Configuration** form.
content/rancher/v2.x/en/cluster-admin/tools/monitoring/cluster-metrics/_index.md
+1 -1
View File
@@ -101,7 +101,7 @@ Workload metrics display the hardware utilization for a Kubernetes workload. You
1. From the **Global** view, navigate to the project that you want to view workload metrics.
1. Select **Workloads > Workloads** in the navigation bar.
1. From the main navigation bar, choose **Resources > Workloads.** In versions prior to v2.3.0, choose **Workloads** on the main navigation bar.
1. Select a specific workload and click on its name.
content/rancher/v2.x/en/cluster-admin/tools/monitoring/viewing-metrics/_index.md
+2 -2
View File
@@ -15,9 +15,9 @@ Rancher's dashboards are available at multiple locations:
- **Cluster Dashboard**: From the **Global** view, navigate to the cluster.
- **Node Metrics**: From the **Global** view, navigate to the cluster. Select **Nodes**. Find the individual node and click on its name. Click **Node Metrics.**
- **Workload Metrics**: From the **Global** view, navigate to the project. Select **Workloads > Workloads**. Find the individual workload and click on its name. Click **Workload Metrics.**
- **Workload Metrics**: From the **Global** view, navigate to the project. From the main navigation bar, choose **Resources > Workloads.** (In versions prior to v2.3.0, choose **Workloads** on the main navigation bar.) Find the individual workload and click on its name. Click **Workload Metrics.**
- **Pod Metrics**: From the **Global** view, navigate to the project. Select **Workloads > Workloads**. Find the individual workload and click on its name. Find the individual pod and click on its name. Click **Pod Metrics.**
- **Container Metrics**: From the **Global** view, navigate to the project. Select **Workloads > Workloads**. Find the individual workload and click on its name. Find the individual pod and click on its name. Find the individual container and click on its name. Click **Container Metrics.**
- **Container Metrics**: From the **Global** view, navigate to the project. From the main navigation bar, choose **Resources > Workloads.** (In versions prior to v2.3.0, choose **Workloads** on the main navigation bar.) Find the individual workload and click on its name. Find the individual pod and click on its name. Find the individual container and click on its name. Click **Container Metrics.**
Prometheus metrics are displayed and are denoted with the Grafana icon. If you click on the icon, the metrics will open a new tab in Grafana.
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/_index.md
+27
View File
@@ -189,6 +189,33 @@ services:
- "/sbin/iscsiadm:/sbin/iscsiadm"
```
## GlusterFS Volumes With Rancher Launched Kubernetes Clusters
In [Rancher Launched Kubernetes clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) that store data on GlusterFS volumes, you may experience an issue where pods fail to mount volumes after restarting the `kubelet`. The logging of the `kubelet` will show: `transport endpoint is not connected`. To prevent this from happening, you can configure your cluster to mount the `systemd-run` binary in the `kubelet` container. There are two requirements before you can change the cluster configuration:
- The node needs to have the `systemd-run` binary installed (this can be checked by using the command `which systemd-run` on each cluster node)
- The `systemd-run` binary needs to be compatible with Debian OS on which the hyperkube image is based (this can be checked using the following command on each cluster node, replacing the image tag with the Kubernetes version you want to use)
```
docker run -v /usr/bin/systemd-run:/usr/bin/systemd-run --entrypoint /usr/bin/systemd-run rancher/hyperkube:v1.16.2-rancher1 --version
```
>**Note:**
>
>Before updating your Kubernetes YAML to mount the `systemd-run` binary, make sure the `systemd` package is installed on your cluster nodes. If this package isn't installed _before_ the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.
```
services:
kubelet:
extra_binds:
- "/usr/bin/systemd-run:/usr/bin/systemd-run"
```
After the cluster has finished provisioning, you can check the `kubelet` container logging to see if the functionality is activated by looking for the following logline:
```
Detected OS with systemd
```
## What's Next?
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-admin/volumes-and-storage/persistent-volume-claims/_index.md
+2 -2
View File
@@ -10,14 +10,14 @@ _Persistent Volume Claims_ (or PVCs) are objects that request storage resources
- Rancher lets you create as many PVCs within a project as you'd like.
- You can mount PVCs to a deployment as you create it, or later after its running.
- Each Rancher project contains a list of PVCs that you've created, available from the **Volumes** tab. You can reuse these PVCs when creating deployments in the future.
- Each Rancher project contains a list of PVCs that you've created, available from **Resources > Workloads > Volumes.** (In versions prior to v2.3.0, the PVCs are in the **Volumes** tab.) You can reuse these PVCs when creating deployments in the future.
>**Prerequisite:**
> You must have a pre-provisioned [persistent volume]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/#adding-a-persistent-volume) available for use, or you must have a [storage class created]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/#adding-storage-classes) that dynamically creates a volume upon request from the workload.
1. From the **Global** view, open the project containing a workload that you want to add a PVC to.
1. From the main menu, make sure that **Workloads** is selected. Then select the **Volumes** tab. Click **Add Volume**.
1. From the main navigation bar, choose **Resources > Workloads.** (In versions prior to v2.3.0, choose **Workloads** on the main navigation bar.) Then select the **Volumes** tab. Click **Add Volume**.
1. Enter a **Name** for the volume claim.
content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/cce/_index.md
+2
View File
@@ -50,6 +50,8 @@ Huawei CCE service doesn't support the ability to create clusters with public ac
| Cluster Label | The labels for the cluster. |
| Highway Subnet | This option is only supported in `BareMetal` type. It requires you to select a VPC with high network speed for the bare metal machines. |
> **Note:** If you are editing the cluster in the `cluster.yml` instead of the Rancher UI, note that as of Rancher v2.3.0, cluster configuration directives must be nested under the `rancher_kubernetes_engine_config` directive in `cluster.yml`. For more information, refer to the section on [the config file structure in Rancher v2.3.0+.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#config-file-structure-in-rancher-v2-3-0)
7. Fill the following node configuration of the cluster:
|Settings|Description|
content/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/tke/_index.md
+2
View File
@@ -48,6 +48,8 @@ You can use Rancher to create a cluster hosted in Tencent Kubernetes Engine (TKE
| VPC | Select the VPC name that you have created in the Tencent Cloud Console. |
| Container Network CIDR | Enter the CIDR range of your Kubernetes cluster, you may check the available range of the CIDR in the VPC service of the Tencent Cloud Console. Default to 172.16.0.0/16. |
> Note: If you are editing the cluster in the `cluster.yml` instead of the Rancher UI, note that as of Rancher v2.3.0, cluster configuration directives must be nested under the `rancher_kubernetes_engine_config` directive in `cluster.yml`. For more information, refer to the section on [the config file structure in Rancher v2.3.0+.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/#config-file-structure-in-rancher-v2-3-0)
7. Click `Next: Select Instance Type` to choose the instance type that will use for your TKE cluster.
| Option | Description |
content/rancher/v2.x/en/cluster-provisioning/node-requirements/_index.md
+160
View File
@@ -0,0 +1,160 @@
---
title: Node Requirements for User Clusters
weight: 1
---
This page describes the requirements for the nodes where your apps and services will be installed.
In this section, "user cluster" refers to a cluster running your apps, which should be separate from the cluster (or single node) running Rancher.
> It is important to note that if Rancher is installed on a high-availability Kubernetes cluster, the Rancher server cluster and user clusters have the same requirements for OS and Docker, but other requirements are different. For Rancher installation requirements, refer to the node requirements in the [installation section.]({{<baseurl>}}/rancher/v2.x/en/installation/requirements/)
Make sure the nodes for the Rancher server fulfill the following requirements:
- Operating systems and Docker requirements - same as the [requirements for Rancher installation]({{<baseurl>}}/rancher/v2.x/en/installation/requirements/#operating-systems-and-docker-requirements)
- [Hardware Requirements](#hardware-requirements)
- [Networking Requirements](#networking-requirements)
# Operating Systems and Docker Requirements
For the nodes in user clusters, the requirements for the operating system and Docker version are the same as the [OS and Docker requirements for the Rancher server cluster.]({{<baseurl>}}/rancher/v2.x/en/installation/requirements/#operating-systems-and-docker-requirements)
# Hardware Requirements
The hardware requirements for nodes with the `worker` role mostly depend on your workloads. The minimum to run the Kubernetes node components is 1 CPU (core) and 1GB of memory.
Regarding CPU and memory, it is recommended that the different planes of Kubernetes clusters (etcd, controplane, and workers) should be hosted on different nodes so that they can scale separately from each other.
For hardware recommendations for large Kubernetes clusters, refer to the official Kubernetes documentation on [building large clusters.](https://kubernetes.io/docs/setup/best-practices/cluster-large/)
For hardware recommendations for etcd clusters in production, refer to the official [etcd documentation.](https://etcd.io/docs/v3.4.0/op-guide/hardware/)
# Networking Requirements
For a production cluster, we recommend that you restrict traffic by opening only the ports defined in the port requirements below.
The ports required to be open are different depending on how the user cluster is launched. Each of the sections below list the ports that need to be opened for different [cluster creation options]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/#cluster-creation-options).
For a breakdown of the port requirements for etcd nodes, controlplane nodes, and worker nodes in a Kubernetes cluster, refer to the [port requirements for the Rancher Kubernetes Engine.]({{<baseurl>}}/rke/latest/en/os/#ports)
Details on which ports are used in each situation are found in the following sections:
- [Commonly used ports](#commonly-used-ports)
- [Port requirements for custom clusters](#port-requirements-for-custom-clusters)
- [Port requirements for clusters hosted by an infrastructure provider](#port-requirements-for-clusters-hosted-by-an-infrastructure-provider)
- [Security group for nodes on AWS EC2](#security-group-for-nodes-on-aws-ec2)
- [Port requirements for clusters hosted by a Kubernetes provider](#port-requirements-for-clusters-hosted-by-a-kubernetes-provider)
- [Port requirements for imported clusters](#port-requirements-for-imported-clusters)
- [Port requirements for local traffic](#port-requirements-for-local-traffic)
### Commonly Used Ports
If security isn't a large concern and you're okay with opening a few additional ports, you can use this table as your port reference instead of the comprehensive tables in the following sections.
These ports are typically opened on your Kubernetes nodes, regardless of what type of cluster it is.
{{% accordion id="common-ports" label="Click to Expand" %}}
<figcaption>Commonly Used Ports Reference</figcaption>
| Protocol | Port | Description |
|:--------: |:----------------: |------------------------------------------------- |
| TCP | 22 | Node driver SSH provisioning |
| TCP | 2376 | Node driver Docker daemon TLS port |
| TCP | 2379 | etcd client requests |
| TCP | 2380 | etcd peer communication |
| UDP | 8472 | Canal/Flannel VXLAN overlay networking |
| UDP | 4789 | Flannel VXLAN overlay networking on Windows cluster |
| TCP | 9099 | Canal/Flannel livenessProbe/readinessProbe |
| TCP | 6783 | Weave Port |
| UDP | 6783-6784 | Weave UDP Ports |
| TCP | 10250 | kubelet API |
| TCP | 10254 | Ingress controller livenessProbe/readinessProbe |
| TCP/UDP | 30000-</br>32767 | NodePort port range |
{{% /accordion %}}
### Port Requirements for Custom Clusters
If you are launching a Kubernetes cluster on your existing infrastructure, refer to these port requirements.
{{% accordion id="port-reqs-for-custom-clusters" label="Click to Expand" %}}
The following table depicts the port requirements for [Rancher Launched Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) with [custom nodes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/custom-nodes/).
{{< ports-custom-nodes >}}
{{% /accordion %}}
### Port Requirements for Clusters Hosted by an Infrastructure Provider
If you are launching a Kubernetes cluster on nodes that are in an infastructure provider such as Amazon EC2, Google Container Engine, DigitalOcean, Azure, or vSphere, [these port requirements]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements/port-reqs-for-infrastructure-provider) apply.
These required ports are automatically opened by Rancher during creation of clusters using cloud providers.
{{% accordion id="port-reqs-for-infrastructure-providers" label="Click to Expand" %}}
The following table depicts the port requirements for [Rancher Launched Kubernetes]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/) with nodes created in an [Infrastructure Provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/).
>**Note:**
>The required ports are automatically opened by Rancher during creation of clusters in cloud providers like Amazon EC2 or DigitalOcean.
{{< ports-iaas-nodes >}}
{{% /accordion %}}
#### Security Group for Nodes on AWS EC2
When using the [AWS EC2 node driver]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/) to provision cluster nodes in Rancher, you can choose to let Rancher create a security group called `rancher-nodes`. The following rules are automatically added to this security group.
| Type | Protocol | Port Range | Source/Destination | Rule Type |
|-----------------|:--------:|:-----------:|------------------------|:---------:|
| SSH | TCP | 22 | 0.0.0.0/0 | Inbound |
| HTTP | TCP | 80 | 0.0.0.0/0 | Inbound |
| Custom TCP Rule | TCP | 443 | 0.0.0.0/0 | Inbound |
| Custom TCP Rule | TCP | 2376 | 0.0.0.0/0 | Inbound |
| Custom TCP Rule | TCP | 2379-2380 | sg-xxx (rancher-nodes) | Inbound |
| Custom UDP Rule | UDP | 4789 | sg-xxx (rancher-nodes) | Inbound |
| Custom TCP Rule | TCP | 6443 | 0.0.0.0/0 | Inbound |
| Custom UDP Rule | UDP | 8472 | sg-xxx (rancher-nodes) | Inbound |
| Custom TCP Rule | TCP | 10250-10252 | sg-xxx (rancher-nodes) | Inbound |
| Custom TCP Rule | TCP | 10256 | sg-xxx (rancher-nodes) | Inbound |
| Custom TCP Rule | TCP | 30000-32767 | 0.0.0.0/0 | Inbound |
| Custom UDP Rule | UDP | 30000-32767 | 0.0.0.0/0 | Inbound |
| All traffic | All | All | 0.0.0.0/0 | Outbound |
### Port Requirements for Clusters Hosted by a Kubernetes Provider
If you are launching a cluster with a hosted Kubernetes provider such as Google Kubernetes Engine, Amazon EKS, or Azure Kubernetes Service, refer to these port requirements.
{{% accordion id="port-reqs-for-hosted-kubernetes" label="Click to Expand" %}}
The following table depicts the port requirements for nodes in [hosted Kubernetes clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters).
{{< ports-imported-hosted >}}
{{% /accordion %}}
### Port Requirements for Imported Clusters
If you are importing an existing cluster, refer to these port requirements.
{{% accordion id="port-reqs-for-imported-clusters" label="Click to Expand" %}}
The following table depicts the port requirements for [imported clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/imported-clusters/).
{{< ports-imported-hosted >}}
{{% /accordion %}}
### Port Requirements for Local Traffic
Ports marked as `local traffic` (i.e., `9099 TCP`) in the port requirements are used for Kubernetes healthchecks (`livenessProbe` and`readinessProbe`).
These healthchecks are executed on the node itself. In most cloud environments, this local traffic is allowed by default.
However, this traffic may be blocked when:
- You have applied strict host firewall policies on the node.
- You are using nodes that have multiple interfaces (multihomed).
In these cases, you have to explicitly allow this traffic in your host firewall, or in case of public/private cloud hosted machines (i.e. AWS or OpenStack), in your security group configuration. Keep in mind that when using a security group as source or destination in your security group, explicitly opening ports only applies to the private interface of the nodes/instances.
content/rancher/v2.x/en/cluster-provisioning/production/_index.md
+23 -111
View File
@@ -1,137 +1,49 @@
---
title: Production Ready Cluster
title: Checklist for Production-Ready Clusters
weight: 2005
---
While Rancher makes it easy to create Kubernetes clusters, a production ready cluster takes more consideration and planning. There are three roles that can be assigned to nodes: `etcd`, `controlplane` and `worker`. In the next sections each of the roles will be described in more detail.
In this section, we recommend best practices for creating the production-ready Kubernetes clusters that will run your apps and services.
When designing your cluster(s), you have two options:
For a list of requirements for your cluster, including the requirements for OS/Docker, hardware, and networking, refer to the section on [node requirements.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements)
* Use dedicated nodes for each role. This ensures resource availability for the components needed for the specified role. It also strictly isolates network traffic between each of the roles according to the [Port Requirements]({{< baseurl >}}/rancher/v2.x/en/installation/references/).
* Assign the `etcd` and `controlplane` roles to the same nodes. These nodes must meet the hardware requirements for both roles.
This is a shortlist of best practices that we strongly recommend for all production clusters.
>**Note:** Do not add the `worker` role to any node configured with either the `etcd` or `controlplane` role. This will make the nodes schedulable for regular workloads, which could interfere with critical cluster components running on the nodes with the `etcd` or `controlplane` role.
For a full list of all the best practices that we recommend, refer to the [best practices section.]({{<baseurl>}}/rancher/v2.x/en/best-practices)
## etcd
### Node Requirements
Nodes with the `etcd` role run etcd, which is a consistent and highly available key value store used as Kubernetes’ backing store for all cluster data. etcd replicates the data to each node.
* Make sure your nodes fulfill all of the [node requirements,]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements/) including the port requirements.
>**Note:** Nodes with the `etcd` role are shown as `Unschedulable` in the UI, meaning no pods will be scheduled to these nodes by default.
### Back up etcd
### Hardware Requirements
* Enable etcd snapshots. Verify that snapshots are being created, and run a disaster recovery scenario to verify the snapshots are valid. etcd is the location where the state of your cluster is stored, and losing etcd data means losing your cluster. Make sure you configure [etcd Recurring Snapshots]({{<baseurl>}}/rancher/v2.x/en/backups/backups/ha-backups/#option-a-recurring-snapshots) for your cluster(s), and make sure the snapshots are stored externally (off the node) as well.
Please see [Kubernetes: Building Large Clusters](https://kubernetes.io/docs/setup/cluster-large/) and [etcd: Hardware Recommendations](https://coreos.com/etcd/docs/latest/op-guide/hardware.html) for the hardware requirements.
### Count of etcd Nodes
The number of nodes that you can lose at once while maintaining cluster availability is determined by the number of nodes assigned the `etcd` role. For a cluster with n members, the minimum is (n/2)+1. Therefore, we recommend creating an `etcd` node in 3 different availability zones to survive the loss of one availability zone within a region. If you use only two zones, you can only survive the loss of the zone where you don't lose the majority of nodes.
| Nodes with `etcd` role | Majority | Failure Tolerance |
|--------------|------------|-------------------|
| 1 | 1 | 0 |
| 2 | 2 | 0 |
| 3 | 2 | **1** |
| 4 | 3 | 1 |
| 5 | 3 | **2** |
| 6 | 4 | 2 |
| 7 | 4 | **3** |
| 8 | 5 | 3 |
| 9 | 5 | **4** |
References:
* [etcd cluster size](https://coreos.com/etcd/docs/latest/v2/admin_guide.html#optimal-cluster-size)
* [Operating etcd clusters for Kubernetes](https://kubernetes.io/docs/tasks/administer-cluster/configure-upgrade-etcd/)
### Network Latency
Rancher recommends minimizing latency between the etcd nodes. The default setting for `heartbeat-interval` is `500`, and the default setting for `election-timeout` is `5000`. These settings allow etcd to run in most networks (except really high latency networks).
References:
* [etcd Tuning](https://coreos.com/etcd/docs/latest/tuning.html)
### Backups
etcd is the location where the state of your cluster is stored. Losing etcd data means losing your cluster. Make sure you configure [etcd Recurring Snapshots]({{< baseurl >}}/rancher/v2.x/en/backups/backups/ha-backups/#option-a-recurring-snapshots) for your cluster(s), and make sure the snapshots are stored externally (off the node) as well.
## controlplane
Nodes with the `controlplane` role run the Kubernetes master components (excluding `etcd`, as it's a separate role). See [Kubernetes: Master Components](https://kubernetes.io/docs/concepts/overview/components/#master-components) for a detailed list of components.
>**Note:** Nodes with the `controlplane` role are shown as `Unschedulable` in the UI, meaning no pods will be scheduled to these nodes by default.
References:
* [Kubernetes: Master Components](https://kubernetes.io/docs/concepts/overview/components/#master-components)
### Hardware Requirements
Please see [Kubernetes: Building Large Clusters](https://kubernetes.io/docs/setup/cluster-large/) for the hardware requirements.
### Count of controlplane Nodes
Adding more than one node with the `controlplane` role makes every master component highly available. See below for a breakdown of how high availability is achieved per component.
#### kube-apiserver
The Kubernetes API server (`kube-apiserver`) scales horizontally. Each node with the role `controlplane` will be added to the NGINX proxy on the nodes with components that need to access the Kubernetes API server. This means that if a node becomes unreachable, the local NGINX proxy on the node will forward the request to another Kubernetes API server in the list.
#### kube-controller-manager
The Kubernetes controller manager uses leader election using an endpoint in Kubernetes. One instance of the `kube-controller-manager` will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive).
#### kube-scheduler
The Kubernetes scheduler uses leader election using an endpoint in Kubernetes. One instance of the `kube-scheduler` will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive).
## worker
Nodes with the `worker` role run the Kubernetes node components. See [Kubernetes: Node Components](https://kubernetes.io/docs/concepts/overview/components/#node-components) for a detailed list of components.
References:
* [Kubernetes: Node Components](https://kubernetes.io/docs/concepts/overview/components/#node-components)
### Hardware Requirements
The hardware requirements for nodes with the `worker` role mostly depend on your workloads. The minimum to run the Kubernetes node components is 1 CPU (core) and 1GB of memory.
### Count of worker Nodes
Adding more than one node with the `worker` role will make sure your workloads can be rescheduled if a node fails.
## Networking
Cluster nodes should be located within a single region. Most cloud providers provide multiple availability zones within a region, which can be used to create higher availability for your cluster. Using multiple availability zones is fine for nodes with any role. If you are using [Kubernetes Cloud Provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) resources, consult the documentation for any restrictions (i.e. zone storage restrictions).
## Cluster Diagram
This diagram is applicable to Kubernetes clusters built using RKE or [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/).
![Cluster diagram]({{< baseurl >}}/img/rancher/clusterdiagram.svg)<br/>
<sup>Lines show the traffic flow between components. Colors are used purely for visual aid</sup>
## Production checklist
### Cluster Architecture
* Nodes should have one of the following role configurations:
* `etcd`
* `controlplane`
* `etcd` and `controlplane`
* `worker` (the `worker` role should not be used or added on nodes with the `etcd` or `controlplane` role)
* Network traffic is only strictly allowed according to [Port Requirements]({{< baseurl >}}/rancher/v2.x/en/installation/references/).
* Have at least three nodes with the role `etcd` to survive losing one node. Increase this count for higher node fault toleration, and spread them across (availability) zones to provide even better fault tolerance.
* Assign two or more nodes the `controlplane` role for master component high availability.
* Assign two or more nodes the `worker` role for workload rescheduling upon node failure.
* Enable etcd snapshots. Verify that snapshots are being created, and run a disaster recovery scenario to verify the snapshots are valid.
* Perform load tests on your cluster to verify that its hardware can support your workloads.
For more information on what each role is used for, refer to the [section on roles for nodes in Kubernetes.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/production/nodes-and-roles)
For more information about the recommended number of nodes for each Kubernetes role, refer to the [section on recommended architecture.]({{<baseurl>}}/rancher/v2.x/en/cluster/provisioning/recommended-architecture)
### Logging and Monitoring
* Configure alerts/notifiers for Kubernetes components (System Service).
* Configure logging for cluster analysis and post-mortems.
## RKE cluster running Rancher HA
### Reliability
You may have noticed that our [High Availability (HA) Install]({{< baseurl >}}/rancher/v2.x/en/installation/ha/) instructions do not meet our definition of a production-ready cluster, as there are no dedicated nodes for the `worker` role. However, for your Rancher installation, this three node cluster is valid, as:
* Perform load tests on your cluster to verify that its hardware can support your workloads.
* It allows one `etcd` node failure.
* It maintains multiple instances of the master components by having multiple `controlplane` nodes.
* No other workloads than Rancher itself should be created on this cluster.
### Networking
* Minimize network latency. Rancher recommends minimizing latency between the etcd nodes. The default setting for `heartbeat-interval` is `500`, and the default setting for `election-timeout` is `5000`. These [settings for etcd tuning](https://coreos.com/etcd/docs/latest/tuning.html) allow etcd to run in most networks (except really high latency networks).
* Cluster nodes should be located within a single region. Most cloud providers provide multiple availability zones within a region, which can be used to create higher availability for your cluster. Using multiple availability zones is fine for nodes with any role. If you are using [Kubernetes Cloud Provider]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers/) resources, consult the documentation for any restrictions (i.e. zone storage restrictions).
content/rancher/v2.x/en/cluster-provisioning/production/nodes-and-roles/_index.md
+43
View File
@@ -0,0 +1,43 @@
---
title: Roles for Nodes in Kubernetes
weight: 1
---
This section describes the roles for etcd nodes, controlplane nodes, and worker nodes in Kubernetes, and how the roles work together in a cluster.
This diagram is applicable to Kubernetes clusters built using RKE or [Rancher Launched Kubernetes]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/).
![Cluster diagram]({{< baseurl >}}/img/rancher/clusterdiagram.svg)<br/>
<sup>Lines show the traffic flow between components. Colors are used purely for visual aid</sup>
# etcd
Nodes with the `etcd` role run etcd, which is a consistent and highly available key value store used as Kubernetes’ backing store for all cluster data. etcd replicates the data to each node.
>**Note:** Nodes with the `etcd` role are shown as `Unschedulable` in the UI, meaning no pods will be scheduled to these nodes by default.
# controlplane
Nodes with the `controlplane` role run the Kubernetes master components (excluding `etcd`, as it's a separate role). See [Kubernetes: Master Components](https://kubernetes.io/docs/concepts/overview/components/#master-components) for a detailed list of components.
>**Note:** Nodes with the `controlplane` role are shown as `Unschedulable` in the UI, meaning no pods will be scheduled to these nodes by default.
### kube-apiserver
The Kubernetes API server (`kube-apiserver`) scales horizontally. Each node with the role `controlplane` will be added to the NGINX proxy on the nodes with components that need to access the Kubernetes API server. This means that if a node becomes unreachable, the local NGINX proxy on the node will forward the request to another Kubernetes API server in the list.
### kube-controller-manager
The Kubernetes controller manager uses leader election using an endpoint in Kubernetes. One instance of the `kube-controller-manager` will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive).
### kube-scheduler
The Kubernetes scheduler uses leader election using an endpoint in Kubernetes. One instance of the `kube-scheduler` will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive).
# worker
Nodes with the `worker` role run the Kubernetes node components. See [Kubernetes: Node Components](https://kubernetes.io/docs/concepts/overview/components/#node-components) for a detailed list of components.
# References
* [Kubernetes: Node Components](https://kubernetes.io/docs/concepts/overview/components/#node-components)
content/rancher/v2.x/en/cluster-provisioning/production/recommended-architecture/_index.md
+74
View File
@@ -0,0 +1,74 @@
---
title: Recommended Cluster Architecture
weight: 1
---
There are three roles that can be assigned to nodes: `etcd`, `controlplane` and `worker`.
# Separating Worker Nodes from Nodes with Other Roles
When designing your cluster(s), you have two options:
* Use dedicated nodes for each role. This ensures resource availability for the components needed for the specified role. It also strictly isolates network traffic between each of the roles according to the [port requirements]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements/#networking-requirements/).
* Assign the `etcd` and `controlplane` roles to the same nodes. These nodes must meet the hardware requirements for both roles.
In either case, the `worker` role should not be used or added to nodes with the `etcd` or `controlplane` role.
Therefore, each node should have one of the following role configurations:
* `etcd`
* `controlplane`
* Both `etcd` and `controlplane`
* `worker`
# Recommended Number of Nodes with Each Role
The cluster should have:
- At least three nodes with the role `etcd` to survive losing one node. Increase this count for higher node fault toleration, and spread them across (availability) zones to provide even better fault tolerance.
- At least two nodes with the role `controlplane` for master component high availability.
- At least two nodes with the role `worker` for workload rescheduling upon node failure.
For more information on what each role is used for, refer to the [section on roles for nodes in Kubernetes.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/production/nodes-and-roles)
### Number of Controlplane Nodes
Adding more than one node with the `controlplane` role makes every master component highly available.
### Number of etcd Nodes
The number of nodes that you can lose at once while maintaining cluster availability is determined by the number of nodes assigned the `etcd` role. For a cluster with n members, the minimum is (n/2)+1. Therefore, we recommend creating an `etcd` node in 3 different availability zones within a region to survive the loss of one availability zone. If you use only two zones, you can only survive the loss of the zone where you don't lose the majority of nodes.
| Nodes with `etcd` role | Majority | Failure Tolerance |
|--------------|------------|-------------------|
| 1 | 1 | 0 |
| 2 | 2 | 0 |
| 3 | 2 | **1** |
| 4 | 3 | 1 |
| 5 | 3 | **2** |
| 6 | 4 | 2 |
| 7 | 4 | **3** |
| 8 | 5 | 3 |
| 9 | 5 | **4** |
References:
* [Official etcd documentation on optimal etcd cluster size](https://github.com/bmizerany/etcd-team/blob/master/Documentation/optimal-cluster-size.md)
* [Official Kubernetes documentation on operating etcd clusters for Kubernetes](https://kubernetes.io/docs/tasks/administer-cluster/configure-upgrade-etcd/)
### Number of Worker Nodes
Adding more than one node with the `worker` role will make sure your workloads can be rescheduled if a node fails.
### Why Production Requirements are Different for the Rancher Cluster and the Clusters Running Your Applications
You may have noticed that our [High Availability (HA) Install]({{<baseurl>}}/rancher/v2.x/en/installation/ha/) instructions do not meet our definition of a production-ready cluster, as there are no dedicated nodes for the `worker` role. However, for your Rancher installation, this three node cluster is valid, because:
* It allows one `etcd` node failure.
* It maintains multiple instances of the master components by having multiple `controlplane` nodes.
* No other workloads than Rancher itself should be created on this cluster.
# References
* [Kubernetes: Master Components](https://kubernetes.io/docs/concepts/overview/components/#master-components)
content/rancher/v2.x/en/cluster-provisioning/rancher-agents/_index.md
+2 -3
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.
@@ -27,8 +27,7 @@ _Applies to v2.3.0 and higher_
| `cattle-cluster-agent` | `beta.kubernetes.io/os:NotIn:windows` | none | `operator:Exists` |
| `cattle-node-agent` | `beta.kubernetes.io/os:NotIn:windows` | none | `operator:Exists` |
The `cattle-cluster-agent` Deployment has preferred scheduling rules using `requiredDuringSchedulingIgnoredDuringExecution`, favoring to be scheduled on nodes with the `controlplane` node. See [Kubernetes: Assigning Pods to Nodes](https://kubernetes.io/docs
concepts/configuration/assign-pod-node/) to find more information about scheduling rules.
The `cattle-cluster-agent` Deployment has preferred scheduling rules using `requiredDuringSchedulingIgnoredDuringExecution`, favoring to be scheduled on nodes with the `controlplane` node. See [Kubernetes: Assigning Pods to Nodes](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/) to find more information about scheduling rules.
The `requiredDuringSchedulingIgnoredDuringExecution` configuration is shown in the table below:
content/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/ec2/_index.md
+45 -2
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.
@@ -39,7 +40,7 @@ Use {{< product >}} to create a Kubernetes cluster in Amazon EC2.
{{< step_create-cloud-credential >}}
- **Zone and Network** configures the availability zone and network settings for your cluster.
- **Security Groups** creates or configures the Security Groups applied to your nodes. Please refer to [Amazon EC2 security group when using Node Driver]({{< baseurl >}}/rancher/v2.x/en/installation/references/#amazonec2-securitygroup-nodedriver) to see what rules are created in the `rancher-nodes` Security Group.
- **Security Groups** creates or configures the Security Groups applied to your nodes. Please refer to [Amazon EC2 security group when using Node Driver]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements/#amazonec2-securitygroup-nodedriver) to see what rules are created in the `rancher-nodes` Security Group.
- **Instance** configures the instances that will be created. Make sure you configure the correct **SSH User** for the configured AMI.
<br><br>
If you need to pass an **IAM Instance Profile Name** (not ARN), for example, when you want to use a [Kubernetes Cloud Provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/options/cloud-providers), you will need an additional permission in your policy. See [Example IAM policy with PassRole](#example-iam-policy-with-passrole) for an example policy.
@@ -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/options/_index.md
+206 -5
View File
@@ -1,14 +1,14 @@
---
title: Cluster Options
weight: 2250
---
---
As you configure a new cluster that's provisioned using [RKE]({{< baseurl >}}/rke/latest/en/), you can choose custom Kubernetes options.
You can configure Kubernetes options one of two ways:
- [Rancher UI](#rancher-ui): Use the Rancher UI to select options that are commonly customized when setting up a Kubernetes cluster.
- [Config File](#config-file): Alternatively, you can create a [RKE config file]({{< baseurl >}}/rke/latest/en/config-options/) to customize any option offered by Kubernetes.
- [Config File](#config-file): The cluster config file allows you to use any option offered by Kubernetes by specifying them in YAML. In Rancher v2.0.0-v2.2.x, the config file is identical to the [cluster config file for the Rancher Kubernetes Engine]({{<baseurl>}}/rke/latest/en/config-options/), which is the tool Rancher uses to provision clusters. In Rancher v2.3.0, the RKE information is still included in the config file, but it is separated from other options, so that the RKE cluster config options are nested under the `rancher_kubernetes_engine_config` directive.
## Rancher UI
@@ -58,13 +58,20 @@ If you want to see all the configuration options for a cluster, please click **S
_Available as of v2.2.0_
If you are using a private registry with authentication for your Docker images, please configure the registry in this section to allow the nodes to pull images from this registry. See [Private Registries]({{< baseurl >}}/rke/latest/en/config-options/private-registries/) for more information.
The registry configuration here is applied during the provisioning of the cluster. This option tells Rancher where to pull the [system images]({{<baseurl>}}/rke/latest/en/config-options/system-images/) or [addon images.]({{<baseurl>}}/rke/latest/en/config-options/add-ons/)
- **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.
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.
### Authorized Cluster Endpoint
_Available as of v2.2.0_
Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher. This is enabled by default, using the IP of the node with the `controlplane` role and the default Kubernetes self signed certificates. It is recommended to create an FQDN pointing to a load balancer which load balances across your nodes with the `controlplane` role. If you are using private CA signed certificates on the load balancer, you have to supply the CA certificate which will be included in the generated kubeconfig to validate the certificate chain. See the [Kubeconfig Files]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/kubeconfig/) and [API Keys]({{< baseurl >}}/v2.x/en/user-settings/api-keys/#creating-an-api-key) documentation for more information.
Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher. This is enabled by default, using the IP of the node with the `controlplane` role and the default Kubernetes self signed certificates. It is recommended to create an FQDN pointing to a load balancer which load balances across your nodes with the `controlplane` role. If you are using private CA signed certificates on the load balancer, you have to supply the CA certificate which will be included in the generated kubeconfig to validate the certificate chain. See the [Kubeconfig Files]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/kubeconfig/) and [API Keys]({{<baseurl>}}/rancher/v2.x/en/user-settings/api-keys/#creating-an-api-key) documentation for more information.
### Advanced Cluster Options
@@ -107,7 +114,188 @@ Instead of using the Rancher UI to choose Kubernetes options for the cluster, ad
![image]({{< baseurl >}}/img/rancher/cluster-options-yaml.png)
For an example of RKE config file syntax, see the [RKE documentation]({{< baseurl >}}/rke/latest/en/example-yamls/).
The structure of the config file is different depending on your version of Rancher. Below are example config files for Rancher v2.0.0-v2.2.x and for Rancher v2.3.0+.
### Config File Structure in Rancher v2.3.0+
RKE (Rancher Kubernetes Engine) is the tool that Rancher uses to provision Kubernetes clusters. Rancher's cluster config files used to have the same structure as [RKE config files,]({{<baseurl>}}/rke/latest/en/example-yamls/) but the structure changed so that in Rancher, RKE cluster config items are separated from non-RKE config items. Therefore, configuration for your cluster needs to be nested under the `rancher_kubernetes_engine_config` directive in the cluster config file. Cluster config files created with earlier versions of Rancher will need to be updated for this format. An example cluster config file is included below.
{{% accordion id="v2.3.0-cluster-config-file" label="Example Cluster Config File for Rancher v2.3.0+" %}}
```yaml
#
# Cluster Config
#
docker_root_dir: /var/lib/docker
enable_cluster_alerting: false
enable_cluster_monitoring: false
enable_network_policy: false
local_cluster_auth_endpoint:
enabled: true
#
# Rancher Config
#
rancher_kubernetes_engine_config: # Your RKE template config goes here.
addon_job_timeout: 30
authentication:
strategy: x509
ignore_docker_version: true
#
# # Currently only nginx ingress provider is supported.
# # To disable ingress controller, set `provider: none`
# # To enable ingress on specific nodes, use the node_selector, eg:
# provider: nginx
# node_selector:
# app: ingress
#
ingress:
provider: nginx
kubernetes_version: v1.15.3-rancher3-1
monitoring:
provider: metrics-server
#
# If you are using calico on AWS
#
# network:
# plugin: calico
# calico_network_provider:
# cloud_provider: aws
#
# # To specify flannel interface
#
# network:
# plugin: flannel
# flannel_network_provider:
# iface: eth1
#
# # To specify flannel interface for canal plugin
#
# network:
# plugin: canal
# canal_network_provider:
# iface: eth1
#
network:
options:
flannel_backend_type: vxlan
plugin: canal
#
# services:
# kube-api:
# service_cluster_ip_range: 10.43.0.0/16
# kube-controller:
# cluster_cidr: 10.42.0.0/16
# service_cluster_ip_range: 10.43.0.0/16
# kubelet:
# cluster_domain: cluster.local
# cluster_dns_server: 10.43.0.10
#
services:
etcd:
backup_config:
enabled: true
interval_hours: 12
retention: 6
safe_timestamp: false
creation: 12h
extra_args:
election-timeout: 5000
heartbeat-interval: 500
gid: 0
retention: 72h
snapshot: false
uid: 0
kube_api:
always_pull_images: false
pod_security_policy: false
service_node_port_range: 30000-32767
ssh_agent_auth: false
windows_prefered_cluster: false
```
{{% /accordion %}}
### Config File Structure in Rancher v2.0.0-v2.2.x
An example cluster config file is included below.
{{% accordion id="prior-to-v2.3.0-cluster-config-file" label="Example Cluster Config File for Rancher v2.0.0-v2.2.x" %}}
```yaml
addon_job_timeout: 30
authentication:
strategy: x509
ignore_docker_version: true
#
# # Currently only nginx ingress provider is supported.
# # To disable ingress controller, set `provider: none`
# # To enable ingress on specific nodes, use the node_selector, eg:
# provider: nginx
# node_selector:
# app: ingress
#
ingress:
provider: nginx
kubernetes_version: v1.15.3-rancher3-1
monitoring:
provider: metrics-server
#
# If you are using calico on AWS
#
# network:
# plugin: calico
# calico_network_provider:
# cloud_provider: aws
#
# # To specify flannel interface
#
# network:
# plugin: flannel
# flannel_network_provider:
# iface: eth1
#
# # To specify flannel interface for canal plugin
#
# network:
# plugin: canal
# canal_network_provider:
# iface: eth1
#
network:
options:
flannel_backend_type: vxlan
plugin: canal
#
# services:
# kube-api:
# service_cluster_ip_range: 10.43.0.0/16
# kube-controller:
# cluster_cidr: 10.42.0.0/16
# service_cluster_ip_range: 10.43.0.0/16
# kubelet:
# cluster_domain: cluster.local
# cluster_dns_server: 10.43.0.10
#
services:
etcd:
backup_config:
enabled: true
interval_hours: 12
retention: 6
safe_timestamp: false
creation: 12h
extra_args:
election-timeout: 5000
heartbeat-interval: 500
gid: 0
retention: 72h
snapshot: false
uid: 0
kube_api:
always_pull_images: false
pod_security_policy: false
service_node_port_range: 30000-32767
ssh_agent_auth: false
```
{{% /accordion %}}
### Default DNS provider
@@ -149,3 +337,16 @@ local_cluster_auth_endpoint:
fqdn: "FQDN"
ca_certs: "BASE64_CACERT"
```
### Custom Network Plug-in
_Available as of v2.2.4_
You can add a custom network plug-in by using the [user-defined add-on functionality]({{<baseurl>}}/rke/latest/en/config-options/add-ons/user-defined-add-ons/) of RKE. You define any add-on that you want deployed after the Kubernetes cluster is deployed.
There are two ways that you can specify an add-on:
- [In-line Add-ons]({{<baseurl>}}/rke/latest/en/config-options/add-ons/user-defined-add-ons/#in-line-add-ons)
- [Referencing YAML Files for Add-ons]({{<baseurl>}}/rke/latest/en/config-options/add-ons/user-defined-add-ons/#referencing-yaml-files-for-add-ons)
For an example of how to configure a custom network plug-in by editing the `cluster.yml`, refer to the [RKE documentation.]({{<baseurl>}}/rke/latest/en/config-options/add-ons/network-plugins/custom-network-plugin-example)
content/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/_index.md
+46 -41
View File
@@ -5,28 +5,30 @@ weight: 2240
_Available as of v2.3.0_
When provisioning a [custom cluster]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/custom-clusters/) using Rancher, Rancher uses RKE (the Rancher Kubernetes Engine) to provision the Kubernetes custom cluster on your existing infrastructure.
You can use a mix of Linux and Windows hosts as your cluster nodes. Windows nodes can only be used for deploying workloads, while Linux nodes are required for cluster management.
You can only add Windows nodes to a cluster if Windows support is enabled. Windows support can be enabled for new custom clusters that use Kubernetes 1.15+ and the Flannel network provider. Windows support cannot be enabled for existing clusters.
> Windows clusters have more requirements than Linux clusters. For example, Windows nodes must have 50 GB of disk space. Make sure your Windows cluster fulfills all of the [requirements.](#requirements-for-windows-clusters)
For a summary of Kubernetes features supported in Windows, see the Kubernetes documentation on [supported functionality and limitations for using Kubernetes with Windows](https://kubernetes.io/docs/setup/production-environment/windows/intro-windows-in-kubernetes/#supported-functionality-and-limitations) or the [guide for scheduling Windows containers in Kubernetes](https://kubernetes.io/docs/setup/production-environment/windows/user-guide-windows-containers/).
This guide covers the following topics:
<!-- TOC -->
- [Prerequisites](#prerequisites)
- [Requirements](#requirements-for-windows-clusters)
- [OS and Docker](#os-and-docker)
- [Hardware](#hardware)
- [Networking](#networking)
- [Architecture](#architecture)
- [Containers](#containers)
- [OS and Docker](#os-and-docker-requirements)
- [Nodes](#node-requirements)
- [Networking](#networking-requirements)
- [Architecture](#architecture-requirements)
- [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
@@ -38,26 +40,29 @@ Before provisioning a new cluster, be sure that you have already installed Ranch
For a custom cluster, the general node requirements for networking, operating systems, and Docker are the same as the node requirements for a [Rancher installation]({{< baseurl >}}/rancher/v2.x/en/installation/requirements/).
### OS and Docker
### 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 Engine - Enterprise Edition (EE):
>**Notes:**
- Nodes with Windows Server core version 1809 should use Docker EE-basic 18.09 or Docker EE-basic 19.03.
- Nodes with Windows Server core version 1903 should use Docker EE-basic 19.03.
> **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.
### Hardware
### Node Requirements
The hosts in the cluster need to have at least:
- 2 core CPUs
- 4.5 GiB memory (~4.83 GB)
- 30 GiB of disk space (~32.21 GB)
- 5 GB memory
- 50 GB disk space
Rancher will not provision the node if the node does not meet these requirements.
### Networking
### Networking Requirements
Rancher only supports Windows using Flannel as the network provider.
@@ -67,7 +72,7 @@ For **Host Gateway (L2bridge)** networking, it's best to use the same Layer 2 ne
For **VXLAN (Overlay)** networking, the [KB4489899](https://support.microsoft.com/en-us/help/4489899) hotfix must be installed. Most cloud-hosted VMs already have this hotfix.
### Architecture
### Architecture Requirements
The Kubernetes cluster management nodes (`etcd` and `controlplane`) must be run on Linux nodes.
@@ -77,15 +82,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 |
### 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
@@ -96,11 +101,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
@@ -118,11 +124,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)
@@ -148,7 +154,7 @@ Windows support only be enabled if the cluster uses Kubernetes v1.15+ and the Fl
1. Click **Next**.
> **Important:** For **Host Gateway (L2bridge)** networking, it's best to use the same Layer 2 network for all nodes. Otherwise, you need to configure the route rules for them. For details, refer to the [documentation on configuring cloud-hosted VM routes.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/host-gateway-requirements/#cloud-hosted-vm-routes-configuration) You will also need to [disable private IP address checks]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/host-gateway-requirements/#disabling-private-ip-address-checks) if you are using Amazon EC2, Google GCE, or Azure VM.
> **Important:** For <b>Host Gateway (L2bridge)</b> networking, it's best to use the same Layer 2 network for all nodes. Otherwise, you need to configure the route rules for them. For details, refer to the [documentation on configuring cloud-hosted VM routes.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/host-gateway-requirements/#cloud-hosted-vm-routes-configuration) You will also need to [disable private IP address checks]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/host-gateway-requirements/#disabling-private-ip-address-checks) if you are using Amazon EC2, Google GCE, or Azure VM.
# 3. Add Nodes to the Cluster
@@ -178,8 +184,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.**
@@ -199,11 +204,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
@@ -231,11 +236,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
@@ -260,7 +265,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/contributing/_index.md
+1 -3
View File
@@ -43,12 +43,10 @@ To see all libraries/projects used in Rancher, see the `vendor.conf` in the `ran
# Building
Every repository should have a Makefile and can be built using the `make` command. The `make` targets are based on the scripts in the `/scripts` directory in the repository (plus additional `trash` commands, please see below for more information about using `trash`), and each target will use [Dapper](https://github.com/rancher/dapper) to run the target in an isolated environment. The `Dockerfile.dapper` will be used for this process, and includes all the necessary build tooling needed.
Every repository should have a Makefile and can be built using the `make` command. The `make` targets are based on the scripts in the `/scripts` directory in the repository, and each target will use [Dapper](https://github.com/rancher/dapper) to run the target in an isolated environment. The `Dockerfile.dapper` will be used for this process, and includes all the necessary build tooling needed.
The default target is `ci`, and will run `./scripts/validate`, `./scripts/build`, `./scripts/test` and `./scripts/package`. The resulting binaries of the build will be in `./build/bin` and are usually also packaged in a Docker image.
Dependencies on other libraries/projects are managed using [Trash](https://github.com/rancher/trash). See the [Trash README](https://github.com/rancher/trash/blob/master/README.md) to discover how it can be used. In short, it uses a `vendor.conf` file to specify the source repository and revision to fetch, checkout and copy to the `./vendor` directory. After updating `vendor.conf`, you can run `make trash` to update dependencies for your change. When the dependencies are updated, you can build the project again using `make` so that it will be built using the updated dependencies.
# Bugs, Issues or Questions
If you find any bugs or are having any trouble, please search the [reported issue](https://github.com/rancher/rancher/issues) as someone may have experienced the same issue or we are actively working on a solution.
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
+6 -6
View File
@@ -53,11 +53,11 @@ Canal is a CNI network provider that gives you the best of Flannel and Calico. I
In Rancher, Canal is the default CNI network provider combined with Flannel and VXLAN encapsulation.
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.
Kubernetes workers should open UDP port `8472` (VXLAN) and TCP port `9099` (healthcheck). For details, refer to [the port requirements for user clusters.]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements/)
![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).
For more information, see the [Canal GitHub Page.](https://github.com/projectcalico/canal)
#### Flannel
@@ -67,7 +67,7 @@ Flannel is a simple and easy way to configure L3 network fabric designed for Kub
Encapsulated traffic is unencrypted by default. Therefore, flannel provides an experimental backend for encryption, [IPSec](https://github.com/coreos/flannel/blob/master/Documentation/backends.md#ipsec), which makes use of [strongSwan](https://www.strongswan.org/) to establish encrypted IPSec tunnels between Kubernetes workers.
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.
Kubernetes workers should open UDP port `8472` (VXLAN) and TCP port `9099` (healthcheck). See [the port requirements for user clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements/#networking-requirements/) for more details.
![Flannel Diagram]({{< baseurl >}}/img/rancher/flannel-diagram.png)
@@ -81,7 +81,7 @@ Calico enables networking and network policy in Kubernetes clusters across the c
Calico also provides a stateless IP-in-IP encapsulation mode that can be used, if necessary. Calico also offers policy isolation, allowing you to secure and govern your Kubernetes workloads using advanced ingress and egress policies.
Kubernetes workers should open TCP port `179` (BGP). See [Port Requirements]({{< baseurl >}}/rancher/v2.x/en/installation/references/) for more details.
Kubernetes workers should open TCP port `179` (BGP). See [the port requirements for user clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements/#networking-requirements/) for more details.
![Calico Diagram]({{< baseurl >}}/img/rancher/calico-diagram.svg)
@@ -99,7 +99,7 @@ _Available as of v2.2.0_
Weave enables networking and network policy in Kubernetes clusters across the cloud. Additionally, it support encrypting traffic between the peers.
Kubernetes workers should open TCP port `6783` (control port), UDP port `6783` and UDP port `6784` (data ports). See [Port Requirements]({{< baseurl >}}/rancher/v2.x/en/installation/references/) for more details.
Kubernetes workers should open TCP port `6783` (control port), UDP port `6783` and UDP port `6784` (data ports). See the [port requirements for user clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements/#networking-requirements/) for more details.
For more information, see the following pages:
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/_index.md
+2 -10
View File
@@ -4,6 +4,8 @@ weight: 50
---
This section contains instructions for installing Rancher in development and production environments.
Before installing Rancher, make sure that your nodes fulfill all of the [installation requirements.]({{<baseurl>}}/rancher/v2.x/en/installation/requirements/)
### Installation Options
- [Single Node Installation]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/)
@@ -13,13 +15,3 @@ This section contains instructions for installing Rancher in development and pro
- [High Availability Installation]({{< baseurl >}}/rancher/v2.x/en/installation/ha/)
This install scenario creates a new Kubernetes cluster dedicated to running Rancher Server in a high-availability (HA) configuration, which runs Rancher Server on multiple hosts so that it's always accessible provided that one of your cluster nodes is running. We recommend high-availability installs in production environments, where your user base requires 24/7 access to your applications.
### Reference
- [Requirements]({{< baseurl >}}/rancher/v2.x/en/installation/requirements/)
A reference of hardware and software requirements for the server(s) hosting Rancher.
- [Port Requirements]({{< baseurl >}}/rancher/v2.x/en/installation/references/)
List of required ports you must open to operate Rancher.
content/rancher/v2.x/en/installation/air-gap/_index.md
+1 -1
View File
@@ -24,7 +24,7 @@ The following CLI tools are required for the HA install. Make sure these tools a
* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) - Kubernetes command-line tool.
* [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.
* [helm](https://docs.helm.sh/using_helm/#installing-helm) - Package management for Kubernetes. Refer to the [Helm version requirements]({{<baseurl>}}/rancher/v2.x/en/installation/helm-version) to choose a version of Helm to install Rancher.
{{% /tab %}}
{{% /tabs %}}
content/rancher/v2.x/en/installation/air-gap/install-rancher/_index.md
+2 -2
View File
@@ -28,7 +28,7 @@ This section describes installing Rancher in five parts:
From a system that has access to the internet, fetch the latest Helm chart and copy the resulting manifests to a system that has access to the Rancher server cluster.
1. If you haven't already, initialize `helm` locally on a workstation that has internet access.
1. If you haven't already, initialize `helm` locally on a workstation that has internet access. Note: Refer to the [Helm version requirements]({{<baseurl>}}/rancher/v2.x/en/installation/helm-version) to choose a version of Helm to install Rancher.
```plain
helm init -c
@@ -213,7 +213,7 @@ If you are installing Rancher versions prior to v2.3.0, you will not be able to
These resources could be helpful when installing Rancher:
- [Rancher Helm chart options]({{<baseurl>}}rancher/v2.x/en/installation/ha/helm-rancher/chart-options/)
- [Rancher Helm chart options]({{<baseurl>}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/)
- [Adding TLS secrets]({{<baseurl>}}/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/)
- [Troubleshooting Rancher HA installations]({{<baseurl>}}/rancher/v2.x/en/installation/ha/helm-rancher/troubleshooting/)
content/rancher/v2.x/en/installation/air-gap/launch-kubernetes/_index.md
+1 -1
View File
@@ -11,7 +11,7 @@ Rancher recommends installing Rancher in a Highly Available (HA) configuration.
This section is about how to prepare to launch a Kubernetes cluster which is used to deploy Rancher server for your air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.
Since a HA installation requires a Kubernetes cluster, we will create a Kubernetes cluster using [Rancher Kubernetes Engine]({{< baseurl >}}/rke/latest/en/) (RKE). Before being able to start your Kubernetes cluster, you'll need to create a RKE config file.
Since a HA installation requires a Kubernetes cluster, we will create a Kubernetes cluster using [Rancher Kubernetes Engine]({{< baseurl >}}/rke/latest/en/) (RKE). Before being able to start your Kubernetes cluster, you'll need to [install RKE]({{< baseurl >}}/rke/latest/en/installation/) and create a RKE config file.
### A. Create an RKE Config File
content/rancher/v2.x/en/installation/air-gap/populate-private-registry/_index.md
+4 -2
View File
@@ -5,6 +5,8 @@ aliases:
- /rancher/v2.x/en/installation/air-gap-installation/prepare-private-reg/
- /rancher/v2.x/en/installation/air-gap-high-availability/prepare-private-registry/
- /rancher/v2.x/en/installation/air-gap-single-node/prepare-private-registry/
- /rancher/v2.x/en/installation/air-gap-single-node/config-rancher-for-private-reg/
- /rancher/v2.x/en/installation/air-gap-high-availability/config-rancher-for-private-reg/
---
>**Prerequisites:** You must have a [private registry](https://docs.docker.com/registry/deploying/) available to use.
@@ -123,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.
@@ -259,7 +261,7 @@ The workstation must have Docker 18.02+ in order to support manifests, which are
### D. Populate the private registry
Move the images in the `rancher-images.tar.gz` to your private registry using the scripts to load the images. The `rancher-images.txt`, `rancher-windows-images.txt` is expected to be on the workstation in the same directory that you are running the `rancher-load-images.sh` script.
Move the images in the `rancher-images.tar.gz` to your private registry using the `rancher-load-images.sh script` to load the images. The `rancher-images.txt` / `rancher-windows-images.txt` image list is expected to be on the workstation in the same directory that you are running the `rancher-load-images.sh` script.
1. Log into your private registry if required:
content/rancher/v2.x/en/installation/ha/_index.md
+1 -3
View File
@@ -28,9 +28,7 @@ The following CLI tools are required for this install. Please make sure these to
* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl) - Kubernetes command-line tool.
* [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.
* [helm](https://docs.helm.sh/using_helm/#installing-helm) - Package management for Kubernetes. Refer to the [Helm version requirements]({{<baseurl>}}/rancher/v2.x/en/installation/helm-version) to choose a version of Helm to install Rancher.
## 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/helm-init/_index.md
+5 -2
View File
@@ -3,10 +3,13 @@ title: "3. Initialize Helm (Install Tiller)"
weight: 195
---
Helm is the package management tool of choice for Kubernetes. Helm "charts" provide templating syntax for Kubernetes YAML manifest documents. With Helm we can create configurable deployments instead of just using static files. For more information about creating your own catalog of deployments, check out the docs at [https://helm.sh/](https://helm.sh/). To be able to use Helm, the server-side component `tiller` needs to be installed on your cluster.
> **Note:** For systems without direct internet access see [Helm - Air Gap]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#helm) for install details.
For systems without direct internet access, see [Helm - Air Gap]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#helm) for install details.
Refer to the [Helm version requirements]({{<baseurl>}}/rancher/v2.x/en/installation/helm-version) to choose a version of Helm to install Rancher.
> **Note:** The installation instructions assume you are using Helm 2. The instructions will be updated for Helm 3 soon. In the meantime, if you want to use Helm 3, refer to [these instructions.](https://github.com/ibrokethecloud/rancher-helm3)
### Install Tiller on the Cluster
content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md
+5 -1
View File
@@ -5,7 +5,11 @@ weight: 200
Rancher installation is managed using the Helm package manager for Kubernetes. Use `helm` to install the prerequisite and charts to install Rancher.
> **Note:** For systems without direct internet access see [Air Gap: High Availability Install]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/).
For systems without direct internet access, see [Air Gap: High Availability Install]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/).
Refer to the [Helm version requirements]({{<baseurl>}}/rancher/v2.x/en/installation/helm-version) to choose a version of Helm to install Rancher.
> **Note:** The installation instructions assume you are using Helm 2. The instructions will be updated for Helm 3 soon. In the meantime, if you want to use Helm 3, refer to [these instructions.](https://github.com/ibrokethecloud/rancher-helm3)
### Add the Helm Chart Repository
content/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/_index.md
+11
View File
@@ -156,6 +156,17 @@ You may terminate the SSL/TLS on a L7 load balancer external to the Rancher clus
Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly.
#### Configuring Ingress for External TLS when Using NGINX v0.25
In NGINX v0.25, the behavior of NGINX has [changed](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0220) regarding forwarding headers and external TLS termination. Therefore, in the scenario that you are using external TLS termination configuration with NGINX v0.25, you must edit the `cluster.yml` to enable the `use-forwarded-headers` option for ingress:
```yaml
ingress:
provider: nginx
options:
use-forwarded-headers: "true"
```
#### Required Headers
* `Host`
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/ha/rke-add-on/troubleshooting/generic-troubleshooting/_index.md
+2 -2
View File
@@ -15,7 +15,7 @@ Below are steps that you can follow to determine what is wrong in your cluster.
### Double check if all the required ports are opened in your (host) firewall
Double check if all the [required ports]({{< baseurl >}}/rancher/v2.x/en/installation/references/) are opened in your (host) firewall.
Double check if all the [required ports]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements/#networking-requirements/) are opened in your (host) firewall.
### All nodes should be present and in **Ready** state
@@ -143,7 +143,7 @@ To test the overlay network, you can launch the following `DaemonSet` definition
=> End
```
If you see error in the output, that means that the [required ports]({{< baseurl >}}/rancher/v2.x/en/installation/references/) for overlay networking are not opened between the hosts indicated.
If you see error in the output, that means that the [required ports]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements/#networking-requirements/) for overlay networking are not opened between the hosts indicated.
Example error output of a situation where NODE1 had the UDP ports blocked.
content/rancher/v2.x/en/installation/helm-version/_index.md
+12
View File
@@ -0,0 +1,12 @@
---
title: Helm Version Requirements
weight: 400
---
This section contains the requirements for Helm, which is the tool used to install Rancher on a high-availability Kubernetes cluster.
> **Note:** The installation instructions assume you are using Helm 2. The instructions will be updated for Helm 3 soon. In the meantime, if you want to use Helm 3, refer to [these instructions.](https://github.com/ibrokethecloud/rancher-helm3)
- Helm v2.15.1 or higher is required for Kubernetes v1.16. For the default Kubernetes version, refer to the [release notes](https://github.com/rancher/rke/releases) for the version of RKE that you are using.
- Helm v2.15.0 should not be used, because of an issue with converting/comparing numbers.
- Helm v2.12.0 should not be used, because of an issue with `cert-manager`.
content/rancher/v2.x/en/installation/options/_index.md
+1 -1
View File
@@ -11,4 +11,4 @@ When installing Rancher, there are several advanced options that can be enabled
| [API Audit Log]({{<baseurl>}}/rancher/v2.x/en/installation/options/api-audit-log/) | v2.0.0 |
| [TLS Settings]({{<baseurl>}}/rancher/v2.x/en/installation/options/tls-settings/) | v2.1.7 |
| [etcd configuration]({{<baseurl>}}/rancher/v2.x/en/installation/options/etcd/) | v2.2.0 |
| [Local System Charts for Air Gap Installations]({{<baseurl>}})/rancher/v2.x/en/installation/options/local-system-charts | v2.3.0 |
| [Local System Charts for Air Gap Installations]({{<baseurl>}}/rancher/v2.x/en/installation/options/local-system-charts) | v2.3.0 |
content/rancher/v2.x/en/installation/options/api-audit-log/_index.md
+1 -1
View File
@@ -67,7 +67,7 @@ kubectl -n cattle-system logs -f rancher-84d886bdbb-s4s69 rancher-audit-log
![Local Cluster: System Project]({{< baseurl >}}/img/rancher/audit_logs_gui/context_local_system.png)
1. From the **Workloads** tab, find the `cattle-system` namespace. Open the `rancher` workload by clicking its link.
1. From the main navigation bar, choose **Resources > Workloads.** (In versions prior to v2.3.0, choose **Workloads** on the main navigation bar.) Find the `cattle-system` namespace. Open the `rancher` workload by clicking its link.
![Rancher Workload]({{< baseurl >}}/img/rancher/audit_logs_gui/rancher_workload.png)
content/rancher/v2.x/en/installation/options/firewall/_index.md
+106
View File
@@ -0,0 +1,106 @@
---
title: Opening Ports with firewalld
weight: 12000
---
Some distributions of Linux [derived from RHEL,](https://en.wikipedia.org/wiki/Red_Hat_Enterprise_Linux#Rebuilds) including Oracle Linux, may have default firewall rules that block communication with Helm.
For example, one Oracle Linux image in AWS has REJECT rules that stop Helm from communicating with Tiller:
```
Chain INPUT (policy ACCEPT)
target prot opt source destination
ACCEPT all -- anywhere anywhere state RELATED,ESTABLISHED
ACCEPT icmp -- anywhere anywhere
ACCEPT all -- anywhere anywhere
ACCEPT tcp -- anywhere anywhere state NEW tcp dpt:ssh
REJECT all -- anywhere anywhere reject-with icmp-host-prohibited
Chain FORWARD (policy ACCEPT)
target prot opt source destination
REJECT all -- anywhere anywhere reject-with icmp-host-prohibited
Chain OUTPUT (policy ACCEPT)
target prot opt source destination
```
You can check the default firewall rules with this command:
```
sudo iptables --list
```
This section describes how to use `firewalld` to apply the [firewall port rules]({{<baseurl>}}/rancher/v2.x/en/installation/references) for nodes in a high-availability Rancher server cluster.
# Prerequisite
Install v7.x or later ofv`firewalld`:
```
yum install firewalld
systemctl start firewalld
systemctl enable firewalld
```
# Applying Firewall Port Rules
In the Rancher high-availability installation instructions, the Rancher server is set up on three nodes that have all three Kubernetes roles: etcd, controlplane, and worker. If your Rancher server nodes have all three roles, run the following commands on each node:
```
firewall-cmd --permanent --add-port=22/tcp
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --permanent --add-port=2376/tcp
firewall-cmd --permanent --add-port=2379/tcp
firewall-cmd --permanent --add-port=2380/tcp
firewall-cmd --permanent --add-port=6443/tcp
firewall-cmd --permanent --add-port=8472/udp
firewall-cmd --permanent --add-port=9099/tcp
firewall-cmd --permanent --add-port=10250/tcp
firewall-cmd --permanent --add-port=10254/tcp
firewall-cmd --permanent --add-port=30000-32767/tcp
firewall-cmd --permanent --add-port=30000-32767/udp
```
If your Rancher server nodes have separate roles, use the following commands based on the role of the node:
```
# For etcd nodes, run the following commands:
firewall-cmd --permanent --add-port=2376/tcp
firewall-cmd --permanent --add-port=2379/tcp
firewall-cmd --permanent --add-port=2380/tcp
firewall-cmd --permanent --add-port=8472/udp
firewall-cmd --permanent --add-port=9099/tcp
firewall-cmd --permanent --add-port=10250/tcp
# For control plane nodes, run the following commands:
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --permanent --add-port=2376/tcp
firewall-cmd --permanent --add-port=6443/tcp
firewall-cmd --permanent --add-port=8472/udp
firewall-cmd --permanent --add-port=9099/tcp
firewall-cmd --permanent --add-port=10250/tcp
firewall-cmd --permanent --add-port=10254/tcp
firewall-cmd --permanent --add-port=30000-32767/tcp
firewall-cmd --permanent --add-port=30000-32767/udp
# For worker nodes, run the following commands:
firewall-cmd --permanent --add-port=22/tcp
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --permanent --add-port=2376/tcp
firewall-cmd --permanent --add-port=8472/udp
firewall-cmd --permanent --add-port=9099/tcp
firewall-cmd --permanent --add-port=10250/tcp
firewall-cmd --permanent --add-port=10254/tcp
firewall-cmd --permanent --add-port=30000-32767/tcp
firewall-cmd --permanent --add-port=30000-32767/udp
```
After the `firewall-cmd` commands have been run on a node, use the following command to enable the firewall rules:
```
firewall-cmd --reload
```
**Result:** The firewall is updated so that Helm can communicate with the Rancher server nodes.
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 -3
View File
@@ -1,8 +1,6 @@
---
title: Port Requirements
weight: 300
aliases:
- /rancher/v2.x/en/hosts/amazon/#required-ports-for-rancher-to-work/
---
To operate properly, Rancher requires a number of ports to be open on Rancher nodes and Kubernetes cluster nodes.
@@ -13,7 +11,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
+110 -64
View File
@@ -1,94 +1,140 @@
---
title: Node Requirements
title: Installation Requirements
weight: 1
aliases:
- /rancher/v2.x/en/hosts/amazon/#required-ports-for-rancher-to-work/
- /rancher/v2.x/en/installation/references
---
Whether you're configuring Rancher to run in a single-node or high-availability setup, each node running Rancher Server must meet the following requirements.
This page describes the software, hardware, and networking requirements for the nodes where the Rancher server will be installed. The Rancher server can be installed on a single node or a high-availability Kubernetes cluster.
> It is important to note that if you install Rancher on a Kubernetes cluster, the hardware and networking requirements for the Rancher cluster are different than the [node requirements for user clusters,]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/node-requirements/) which will run your apps and services.
Make sure the node(s) for the Rancher server fulfill the following requirements:
- [Operating Systems and Docker Requirements](#operating-systems-and-docker-requirements)
- [Hardware Requirements](#hardware-requirements)
- [CPU and Memory](#cpu-and-memory)
- [Disks](#disks)
- [Networking Requirements](#networking-requirements)
- [Node IP Addresses](#node-ip-addresses)
- [Port Requirements](#port-requirements)
For a list of best practices that we recommend for running the Rancher server in production, refer to the [best practices section.]({{<baseurl>}}/rancher/v2.x/en/best-practices/deployment-types/)
# Operating Systems and Docker Requirements
{{% tabs %}}
{{% tab "Operating Systems and Docker" %}}
<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)
* Docker 19.03
* Supported for worker nodes only. See [Configuring Custom Clusters for Windows]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/windows-clusters/)
For details on which OS and Docker versions were tested with each Rancher version, refer to the [support maintenance terms.](https://rancher.com/support-maintenance-terms/all-supported-versions/rancher-v2.3.0/)
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
Operating System | Tested Docker Versions
---------------------|--------------------------
Ubuntu 16.04 (64-bit x86) | Docker 17.03.x, 18.06.x, 18.09.x, 19.03.x
Ubuntu 18.04 (64-bit x86) | Docker 18.06.x, 18.09.x, 19.03.x
Red Hat Enterprise Linux (RHEL)/CentOS 7.7 (64-bit x86) | RHEL Docker 1.13
Oracle Linux 7 update 6* (64-bit x86) | Docker 17.03.x, 18.06.x, 18.09.x, 19.03.x
RancherOS 1.5.4 (64-bit x86) | Docker 17.03.x, 18.06.x, 18.09.x, 19.03.x
Windows Server 2019 (64-bit x86) | Requires Docker Engine - Enterprise Edition (EE).**
# 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>
[Docker Documentation: Installation Instructions](https://docs.docker.com/)
<br>
<br>
{{% /tab %}}
{{% tab "Hardware" %}}
<br>
Hardware requirements scale based on the size of your Rancher deployment. Provision each individual node according to the requirements.
\* Some distributions of Linux derived from RHEL, including Oracle Linux, may have default firewall rules that block communication with Helm. This [how-to guide]({{<baseurl>}}/rancher/v2.x/en/installation/options/firewall) shows how to check the default firewall rules and how to open the ports with `firewalld` if necessary.
\** Nodes with Windows Server core version 1809 should use Docker EE-basic 18.09 or Docker EE-basic 19.03. 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/)
**[HA Node]({{< baseurl >}}/rancher/v2.x/en/installation/ha/create-nodes-lb/) Requirements**
If you plan to run Rancher on ARM64, see [Running on ARM64 (Experimental)]({{<baseurl>}}/rancher/v2.x/en/installation/arm64-platform/)
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/) |
For information on how to install Docker, refer to the offical [Docker documentation.](https://docs.docker.com/)
<br>
# Hardware Requirements
**[Single Node]({{< baseurl >}}/rancher/v2.x/en/installation/single-node/) Requirements**
This section describes the CPU, memory, and disk requirements for the nodes where the Rancher server is installed.
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 |
### CPU and Memory
<br/>
Hardware requirements scale based on the size of your Rancher deployment. Provision each individual node according to the requirements. The requirements are different depending on if you are installing Rancher on a single node or on a high-availability (HA) cluster.
**Disks**
For production environments, the Rancher server should be installed on an HA cluster.
Rancher performance depends on etcd in the cluster performance. To ensure optimal speed, we recommend always using SSD disks to back your Rancher management Kubernetes cluster. On cloud providers, you will also want to use the minimum size that allows the maximum IOPs. In larger clusters consider using dedicated storage devices for etcd data and wal directories.
Rancher can also be installed on a single node in a development or testing environment.
<br/>
{{% tabs %}}
{{% tab "HA Node Requirements" %}}
These requirements apply to [HA installations]({{<baseurl>}}/rancher/v2.x/en/installation/ha/) of Rancher.
| 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/) |
{{% /tab %}}
{{% tab "Networking" %}}
<br>
{{% tab "Single Node Requirements" %}}
### Node IP Address
These requirements apply to [single node]({{<baseurl>}}/rancher/v2.x/en/installation/single-node/) installations of Rancher.
Each node used (either for the Single Node Install, High Availability (HA) Install or nodes that are used in clusters) should have a static IP configured. In case of DHCP, the nodes should have a DHCP reservation to make sure the node gets the same IP allocated.
| 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 |
{{% /tab %}}
{{% /tabs %}}
### Disks
Rancher performance depends on etcd in the cluster performance. To ensure optimal speed, we recommend always using SSD disks to back your Rancher management Kubernetes cluster. On cloud providers, you will also want to use the minimum size that allows the maximum IOPS. In larger clusters, consider using dedicated storage devices for etcd data and wal directories.
# Networking Requirements
This section describes the networking requirements for the node(s) where the Rancher server is installed.
### Node IP Addresses
Each node used should have a static IP configured, regardless of whether you are installing Rancher on a single node or on an HA cluster. In case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated.
### Port Requirements
When deploying Rancher in an HA cluster, certain ports on your nodes must be open to allow communication with Rancher. The ports that must be open change according to the type of machines hosting your cluster nodes. For example, if your are deploying Rancher on nodes hosted by an infrastructure, port `22` must be open for SSH. The following diagram depicts the ports that are opened for each [cluster type]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning).
This section describes the port requirements for nodes running the `rancher/rancher` container.
<figcaption>Cluster Type Port Requirements</figcaption>
The port requirements are different depending on whether you are installing Rancher on a single node or on a high-availability Kubernetes cluster. For a single node, you only need to open the [ports required to enable Rancher to communicate with user clusters.](#port-requirements-for-enabling-rancher-to-communicate-with-user-clusters) For a high-availability installation, the same ports need to be opened, as well as additional [ports required to set up the Kubernetes cluster](#additional-port-requirements-for-nodes-in-high-availability-rancher-installations) that Rancher is installed on.
![Basic Port Requirements]({{< baseurl >}}/img/rancher/port-communications.svg)
### Port Requirements for Enabling Rancher to Communicate with User Clusters
{{< requirements_ports_rancher >}}
{{< requirements_ports_rke >}}
{{< ports_aws_securitygroup_nodedriver >}}
{{% /tab %}}
{{% /tabs %}}
For a single-node installation, you only need to open the ports for the Rancher management plane. These ports are opened to allow the Rancher server to communicate with the Kubernetes clusters that will run your apps and services.
For a high-availability installation, these rules apply as well as the [port requirements to set up the Kubernetes cluster](#additional-port-requirements-for-nodes-in-high-availability-rancher-installations) that Rancher is installed on.
The port requirements are different based the infrastructure you are using. For example, if you are deploying Rancher on nodes hosted by an infrastructure provider, port `22` must be open for SSH. The following diagram depicts the ports that are opened for each [cluster type]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning).
<figcaption>Port Requirements for the Rancher Management Plane</figcaption>
![Basic Port Requirements]({{<baseurl>}}/img/rancher/port-communications.svg)
The following tables break down the port requirements for inbound and outbound traffic:
<figcaption>Inbound Rules for Rancher Nodes</figcaption>
| Protocol | Port | Source | Description |
|------------|-------|---------|----------------|
| TCP | 80 | Load balancer/proxy that does external SSL termination | Rancher UI/API when external SSL termination is used |
| TCP | 443 | <ul><li>etcd nodes</li><li>controlplane nodes</li><li>worker nodes</li><li>hosted/imported Kubernetes</li><li>any source that needs to be able to use the Rancher UI or API</li></ul> | Rancher agent, Rancher UI/API, kubectl |
<figcaption>Outbound Rules for Rancher Nodes</figcaption>
| Protocol | Port | Source | Description |
|------------|-------|---------|----------------|
| TCP | 22 | Any node IP from a node created using Node Driver | SSH provisioning of nodes using Node Driver |
| TCP | 443 | `35.160.43.145/32`, `35.167.242.46/32`, `52.33.59.17/32` | git.rancher.io (catalogs) |
| TCP | 2376 | Any node IP from a node created using Node driver | Docker daemon TLS port used by Docker Machine |
| TCP | 6443 | Hosted/Imported Kubernetes API | Kubernetes API server |
**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).
### Additional Port Requirements for Nodes in High-Availability Rancher Installations
You will need to open additional ports to the launch the Kubernetes cluster that is required for a high-availability installation of Rancher.
The ports that need to be opened for each node depend on the node's Kubernetes role: etcd, controlplane, or worker. For a breakdown of the port requirements for each role, refer to the [port requirements for the Rancher Kubernetes Engine.]({{<baseurl>}}/rke/latest/en/os/#ports)
content/rancher/v2.x/en/installation/server-tags/_index.md
+11 -7
View File
@@ -1,9 +1,15 @@
---
title: Choosing a Version
title: Choosing a Rancher Version
weight: 230
---
## Single Node Installs
This section describes how to choose a Rancher version.
For a high-availability installation of Rancher, which is recommended for production, the Rancher server is installed using a Helm chart on a Kubernetes cluster. Refer to the [Helm version requirements]({{<baseurl>}}/rancher/v2.x/en/installation/helm-version) to choose a version of Helm to install Rancher.
For single node installations of Rancher, which is used for development and testing, you will install Rancher as a Docker image.
# Single Node Installs
When performing [single-node installs]({{< baseurl >}}/rancher/v2.x/en/installation/single-node), upgrades, or rollbacks, you can use _tags_ to install a specific version of Rancher.
@@ -17,9 +23,6 @@ Tag | Description
`rancher/rancher:stable` | Our newest stable release. This tag is recommended for production.
`rancher/rancher:<v2.X.X>` | You can install specific versions of Rancher by using the tag from a previous release. See what's available at DockerHub.
>**Notes:**
>
>- The `master` tag or any tag with `-rc` or another suffix is meant for the Rancher testing team to validate. You should not use these tags, as these builds are not officially supported.
@@ -27,11 +30,12 @@ Tag | Description
>
> _Caveat:_ Alpha releases cannot be upgraded to or from any other release.
## High Availability Installs
# High Availability Installs
When installing, upgrading, or rolling back Rancher Server in a [high availability configuration]({{< baseurl >}}/rancher/v2.x/en/installation/ha/), Rancher server is installed using a Helm chart on a Kubernetes cluster. Therefore, as you prepare to install or upgrade a high availability Rancher configuration, you must add a Helm chart repository that contains the charts for installing Rancher.
Refer to the [Helm version requirements]({{<baseurl>}}/rancher/v2.x/en/installation/helm-version) to choose a version of Helm to install Rancher.
### Helm Chart Repositories
Rancher provides several different Helm chart repositories to choose from. We align our latest and stable Helm chart repositories with the Docker tags that are used for a single node installation. Therefore, the `rancher-latest` repository will contain charts for all the Rancher versions that have been tagged as `rancher/rancher:latest`. When a Rancher version has been promoted to the `rancher/rancher:stable`, it will get added to the `rancher-stable` repository.
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/horitzontal-pod-autoscaler/_index.md
+3 -3
View File
@@ -18,8 +18,8 @@ The way that you manage HPAs is different based on your version of the Kubernete
HPAs are also managed differently based on your version of Rancher:
- **For Rancher Prior to v2.3.0-alpha5:** To manage and configure HPAs, you need to use `kubectl`. For instructions on how to create, manage, and scale HPAs, refer to [Managing HPAs with kubectl]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/horitzontal-pod-autoscaler/manage-hpa-with-kubectl).
- **For Rancher v2.3.0-alpha5+**: You can create, manage, and delete HPAs using the Rancher UI. From the Rancher UI you can configure the HPA to scale based on CPU and memory utilization. For more information, refer to [Managing HPAs with the Rancher UI]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/horitzontal-pod-autoscaler/manage-hpa-with-rancher-ui). To scale the HPA based on custom metrics, you still need to use `kubectl`. For more information, refer to [Configuring HPA to Scale Using Custom Metrics with Prometheus]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/horitzontal-pod-autoscaler/manage-hpa-with-kubectl/#configuring-hpa-to-scale-using-custom-metrics-with-prometheus).
- **For Rancher v2.3.0+**: You can create, manage, and delete HPAs using the Rancher UI. From the Rancher UI you can configure the HPA to scale based on CPU and memory utilization. For more information, refer to [Managing HPAs with the Rancher UI]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/horitzontal-pod-autoscaler/manage-hpa-with-rancher-ui). To scale the HPA based on custom metrics, you still need to use `kubectl`. For more information, refer to [Configuring HPA to Scale Using Custom Metrics with Prometheus]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/horitzontal-pod-autoscaler/manage-hpa-with-kubectl/#configuring-hpa-to-scale-using-custom-metrics-with-prometheus).
- **For Rancher Prior to v2.3.0:** To manage and configure HPAs, you need to use `kubectl`. For instructions on how to create, manage, and scale HPAs, refer to [Managing HPAs with kubectl]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/horitzontal-pod-autoscaler/manage-hpa-with-kubectl).
You might have additional HPA installation steps if you are using an older version of Rancher:
@@ -28,7 +28,7 @@ You might have additional HPA installation steps if you are using an older versi
## Testing HPAs with a Service Deployment
In Rancher v2.3.x+, you can see your HPA's current number of replicas by going to your project's **HPA** tab. For more information, refer to [Get HPA Metrics and Status]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/horitzontal-pod-autoscaler/manage-hpa-with-rancher-ui/).
In Rancher v2.3.x+, you can see your HPA's current number of replicas by going to your project and clicking **Resources > HPA.** For more information, refer to [Get HPA Metrics and Status]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/horitzontal-pod-autoscaler/manage-hpa-with-rancher-ui/).
You can also use `kubectl` to get the status of HPAs that you test with your load testing tool. For more information, refer to [Testing HPAs with kubectl]
({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/horitzontal-pod-autoscaler/testing-hpa/).
content/rancher/v2.x/en/k8s-in-rancher/horitzontal-pod-autoscaler/manage-hpa-with-rancher-ui/_index.md
+5 -5
View File
@@ -3,7 +3,7 @@ title: Managing HPAs with the Rancher UI
weight: 3028
---
_Available as of v2.3.0-alpha5_
_Available as of v2.3.0_
The Rancher UI supports creating, managing, and deleting HPAs. You can configure CPU or memory usage as the metric that the HPA uses to scale.
@@ -13,7 +13,7 @@ If you want to create HPAs that scale based on other metrics than CPU and memory
1. From the **Global** view, open the project that you want to deploy a HPA to.
1. Select **Workloads** in the navigation bar and then select the **HPA** tab.
1. Click **Resources > HPA.**
1. Click **Add HPA.**
@@ -29,13 +29,13 @@ If you want to create HPAs that scale based on other metrics than CPU and memory
1. Click **Create** to create the HPA.
> **Result:** The HPA is deployed to the chosen namespace. You can view the HPA's status from the project's Workloads > HPA view.
> **Result:** The HPA is deployed to the chosen namespace. You can view the HPA's status from the project's Resources > HPA view.
## Get HPA Metrics and Status
1. From the **Global** view, open the project with the HPAs you want to look at.
1. Select **Workloads** in the navigation bar and then select the **HPA** tab. The **HPA** tab shows the number of current replicas.
1. Click **Resources > HPA.** The **HPA** tab shows the number of current replicas.
1. For more detailed metrics and status of a specific HPA, click the name of the HPA. This leads to the HPA detail page.
@@ -44,7 +44,7 @@ If you want to create HPAs that scale based on other metrics than CPU and memory
1. From the **Global** view, open the project that you want to delete an HPA from.
1. Select **Workloads** in the navigation bar and then select the **HPA** tab.
1. Click **Resources > HPA.**
1. Find the HPA which you would like to delete.
content/rancher/v2.x/en/k8s-in-rancher/load-balancers-and-ingress/_index.md
+17 -7
View File
@@ -3,13 +3,13 @@ title: Load Balancing and Ingresses
weight: 3040
---
Within Rancher, you can setup load balancers and ingress controllers to redirect service requests.
Within Rancher, you can set up load balancers and ingress controllers to redirect service requests.
## Load Balancers
After you launch an application, the app is only available within the cluster. It can't be reached from outside the cluster.
If you want your applications to be externally accessible, you must add a load balancer to your cluster. Load balancers create a gateway for external connections to access your cluster, provided that the user knows the load balancer's IP address and the application's port number.
If you want your applications to be externally accessible, you must add a load balancer or ingress to your cluster. Load balancers create a gateway for external connections to access your cluster, provided that the user knows the load balancer's IP address and the application's port number.
Rancher supports two types of load balancers:
@@ -33,18 +33,28 @@ Load Balancers have a couple of limitations you should be aware of:
## Ingress
As mentioned in the limitations above, using a load balancer per service can be expensive. You can get around this issue using an ingress.
As mentioned in the limitations above, the disadvantages of using a load balancer are:
Ingress is a set or rules that act as a load balancer. Ingress works in conjunction with one or more ingress controllers to dynamically route service requests. When the ingress receives a request, the ingress controller(s) in your cluster program the load balancer to direct the request to the correct service based on service subdomains or path rules that you've configured.
- Load Balancers can only handle one IP address per service.
- If you run multiple services in your cluster, you must have a load balancer for each service.
- It can be expensive to have a load balancer for every service.
Your load balancer can either reside within your cluster or externally. Ingress and ingress controllers residing in RKE-launcher clusters are powered by [Nginx](https://www.nginx.com/).
In contrast, when an ingress is used as the entrypoint into a cluster, the ingress can route traffic to multiple services with greater flexibility. It can map multiple HTTP requests to services without individual IP addresses for each service.
Therefore, it is useful to have an ingress if you want multiple services to be exposed with the same IP address, the same Layer 7 protocol, or the same privileged node-ports: 80 and 443.
Ingress works in conjunction with one or more ingress controllers to dynamically route service requests. When the ingress receives a request, the ingress controller(s) in your cluster direct the request to the correct service based on service subdomains or path rules that you've configured.
Each Kubernetes Ingress resource corresponds roughly to a file in `/etc/nginx/sites-available/` containing a `server{}` configuration block, where requests for specific files and folders are configured.
Your ingress, which creates a port of entry to your cluster similar to a load balancer, can reside within your cluster or externally. Ingress and ingress controllers residing in RKE-launcher clusters are powered by [Nginx](https://www.nginx.com/).
Ingress can provide other functionality as well, such as SSL termination, name-based virtual hosting, and more.
>**Using Rancher in a High Availability Configuration?**
>
>Refrain from adding an Ingress to the `local` cluster. The Nginx Ingress Controller that Rancher uses acts as a global load balancer for _all_ clusters managed by Rancher, including the `local` cluster. Therefore, when users try to access an application, your Rancher connection may drop due to the Nginx configuration being reloaded. We recommend working around this issue by deploying applications only in clusters that you launch using Rancher.
>Refrain from adding an Ingress to the `local` cluster. The Nginx Ingress Controller that Rancher uses acts as a global entry point for _all_ clusters managed by Rancher, including the `local` cluster. Therefore, when users try to access an application, your Rancher connection may drop due to the Nginx configuration being reloaded. We recommend working around this issue by deploying applications only in clusters that you launch using Rancher.
- For more information on how to setup ingress in Rancher, see [Ingress]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/load-balancers-and-ingress/ingress).
- For more information on how to set up ingress in Rancher, see [Ingress]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/load-balancers-and-ingress/ingress).
- For complete information about ingress and ingress controllers, see the [Kubernetes Ingress Documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/)
- When using ingresses in a project, you can program the ingress hostname to an external DNS by setting up a Global DNS entry, see [Global DNS]({{< baseurl >}}/rancher/v2.x/en/catalog/globaldns/).
content/rancher/v2.x/en/k8s-in-rancher/load-balancers-and-ingress/ingress/_index.md
+1 -1
View File
@@ -9,7 +9,7 @@ Ingress can be added for workloads to provide load balancing, SSL termination an
1. From the **Global** view, open the project that you want to add ingress to.
1. Select the **Load Balancing** tab. Then click **Add Ingress**.
1. Click **Resources** in the main navigation bar. Click the **Load Balancing** tab. (In versions prior to v2.3.0, just click the **Load Balancing** tab.) Then click **Add Ingress**.
1. Enter a **Name** for the ingress.
content/rancher/v2.x/en/k8s-in-rancher/load-balancers-and-ingress/load-balancers/_index.md
+15 -8
View File
@@ -8,7 +8,11 @@ Kubernetes supports load balancing in two ways: Layer-4 Load Balancing and Layer
## Layer-4 Load Balancer
Layer-4 load balancer (or the external load balancer) forwards traffic to Nodeports. Layer-4 load balancer allows you to forward both HTTP and TCP traffic. Layer-4 load balancer is supported by the underlying cloud provider. As a result, when you deploy RKE clusters on bare metal servers and vSphere clusters, layer-4 load balancer is not supported.
Layer-4 load balancer (or the external load balancer) forwards traffic to Nodeports. Layer-4 load balancer allows you to forward both HTTP and TCP traffic.
Often, the Layer-4 load balancer is supported by the underlying cloud provider, so when you deploy RKE clusters on bare-metal servers and vSphere clusters, Layer-4 load balancer is not supported. However, a single [globally managed config-map](https://kubernetes.github.io/ingress-nginx/user-guide/exposing-tcp-udp-services/) can be used to expose services on NGINX or third-party ingress.
> **Note:** It is possible to deploy a cluster with a non-cloud load balancer, such as [MetalLB.](https://metallb.universe.tf/) However, that use case is more advanced than the Layer-4 load balancer supported by a cloud provider, and it is not configurable in Rancher or RKE.
### Support for Layer-4 Load Balancing
@@ -16,13 +20,16 @@ Support for layer-4 load balancer varies based on the underlying cloud provider.
Cluster Deployment | Layer-4 Load Balancer Support
----------------------------------------------|--------------------------------
Amazon EKS | Supported by AWS cloud provider
Google GKE | Supported by GCE cloud provider
Azure AKS | Supported by Azure cloud provider
RKE on EC2 | Supported by AWS cloud provider
RKE on DigitalOcean | Not Supported
RKE on vSphere | Not Supported
RKE on Custom Hosts<br/>(e.g. bare-metal servers) | Not Supported
Amazon EKS | Supported by AWS cloud provider
Google GKE | Supported by GCE cloud provider
Azure AKS | Supported by Azure cloud provider
RKE on EC2 | Supported by AWS cloud provider
RKE on DigitalOcean | Limited NGINX or third-party Ingress*
RKE on vSphere | Limited NGINX or third party-Ingress*
RKE on Custom Hosts<br/>(e.g. bare-metal servers) | Limited NGINX or third-party Ingress*
Third-party MetalLB | Limited NGINX or third-party Ingress*
\* Services can be exposed through a single [globally managed config-map.](https://kubernetes.github.io/ingress-nginx/user-guide/exposing-tcp-udp-services/)
## Layer-7 Load Balancer
content/rancher/v2.x/en/k8s-in-rancher/pipelines/_index.md
+9 -9
View File
@@ -41,7 +41,7 @@ After the version control provider is authorized, you are automatically re-direc
1. From the **Global** view, navigate to the project that you want to configure pipelines.
1. Select **Workloads** in the navigation bar and then select the **Pipelines** tab.
1. Click **Resources > Pipelines.** In versions prior to v2.3.0, click **Workloads > Pipelines.**
1. Click on **Configure Repositories**.
@@ -59,7 +59,7 @@ Now that repositories are added to your project, you can start configuring the p
1. From the **Global** view, navigate to the project that you want to configure pipelines.
1. Select **Workloads** in the navigation bar and then select the **Pipelines** tab.
1. Click **Resources > Pipelines.** In versions prior to v2.3.0, click **Workloads > Pipelines.**
1. Find the repository that you want to set up a pipeline for. Pipelines can be configured either through the UI or using a yaml file in the repository, i.e. `.rancher-pipeline.yml` or `.rancher-pipeline.yaml`. Throughout the next couple of steps, we'll provide the options of how to do pipeline configuration through the UI or the YAML file.
@@ -231,7 +231,7 @@ timeout: 30
## Running your Pipelines
Run your pipeline for the first time. From the **Pipeline** tab, find your pipeline and select the vertical **Ellipsis (...) > Run**.
Run your pipeline for the first time. From the project view in Rancher, go to **Resources > Pipelines.** (In versions prior to v2.3.0, go to the **Pipelines** tab.) Find your pipeline and select the vertical **Ellipsis (...) > Run**.
During this initial run, your pipeline is tested, and the following [pipeline components]({{< baseurl >}}/rancher/v2.x/en/project-admin/tools/pipelines/#how-pipelines-work) are deployed to your project as workloads in a new namespace dedicated to the pipeline:
@@ -257,7 +257,7 @@ Available Events:
1. From the **Global** view, navigate to the project that you want to modify the event trigger for the pipeline.
1. Select **Workloads** in the navigation bar and then select the **Pipelines** tab.
1. 1. Click **Resources > Pipelines.** In versions prior to v2.3.0, click **Workloads > Pipelines.**
1. Find the repository that you want to modify the event triggers. Select the vertical **Ellipsis (...) > Setting**.
@@ -553,7 +553,7 @@ Wildcard character (`*`) expansion is supported in `branch` conditions.
1. From the **Global** view, navigate to the project that you want to configure a pipeline trigger rule.
1. Select **Workloads** in the navigation bar and then select the **Pipelines** tab.
1. Click **Resources > Pipelines.** In versions prior to v2.3.0, click **Workloads > Pipelines.**
1. From the repository for which you want to manage trigger rules, select the vertical **Ellipsis (...) > Edit Config**.
@@ -571,7 +571,7 @@ Wildcard character (`*`) expansion is supported in `branch` conditions.
{{% tab "Stage Trigger" %}}
1. From the **Global** view, navigate to the project that you want to configure a stage trigger rule.
1. Select **Workloads** in the navigation bar and then select the **Pipelines** tab.
1. Click **Resources > Pipelines.** In versions prior to v2.3.0, click **Workloads > Pipelines.**
1. From the repository for which you want to manage trigger rules, select the vertical **Ellipsis (...) > Edit Config**.
@@ -596,7 +596,7 @@ Wildcard character (`*`) expansion is supported in `branch` conditions.
{{% tab "Step Trigger" %}}
1. From the **Global** view, navigate to the project that you want to configure a stage trigger rule.
1. Select **Workloads** in the navigation bar and then select the **Pipelines** tab.
1. Click **Resources > Pipelines.** In versions prior to v2.3.0, click **Workloads > Pipelines.**
1. From the repository for which you want to manage trigger rules, select the vertical **Ellipsis (...) > Edit Config**.
@@ -654,7 +654,7 @@ When configuring a pipeline, certain [step types](#step-types) allow you to use
{{% tab "By UI" %}}
1. From the **Global** view, navigate to the project that you want to configure pipelines.
1. Select **Workloads** in the navigation bar and then select the **Pipelines** tab.
1. Click **Resources > Pipelines.** In versions prior to v2.3.0, click **Workloads > Pipelines.**
1. From the pipeline for which you want to edit build triggers, select **Ellipsis (...) > Edit Config**.
@@ -703,7 +703,7 @@ Create a secret in the same project as your pipeline, or explicitly in the names
{{% tab "By UI" %}}
1. From the **Global** view, navigate to the project that you want to configure pipelines.
1. Select **Workloads** in the navigation bar and then select the **Pipelines** tab.
1. Click **Resources > Pipelines.** In versions prior to v2.3.0, click **Workloads > Pipelines.**
1. From the pipeline for which you want to edit build triggers, select **Ellipsis (...) > Edit Config**.
content/rancher/v2.x/en/k8s-in-rancher/pipelines/example-repos/_index.md
+4 -4
View File
@@ -11,7 +11,7 @@ Rancher ships with several example repositories that you can use to familiarize
- Maven
- php
> **Note**: The example repositories are only available if you have not [configured a version control provider]({{< baseurl >}}/rancher/v2.x/en/project-admin/tools/pipelines).
> **Note:** The example repositories are only available if you have not [configured a version control provider]({{< baseurl >}}/rancher/v2.x/en/project-admin/tools/pipelines).
## Configure Repositories
@@ -19,7 +19,7 @@ By default, the example pipeline repositories are disabled. Enable one (or more)
1. From the **Global** view, navigate to the project that you want to test out pipelines.
1. Select **Workloads** in the navigation bar and then select the **Pipelines** tab.
1. Click **Resources > Pipelines.** In versions prior to v2.3.0, click **Workloads > Pipelines.**
1. Click **Configure Repositories**.
@@ -45,7 +45,7 @@ After enabling an example repository, review the pipeline to see how it is set u
1. From the **Global** view, navigate to the project that you want to test out pipelines.
1. Select **Workloads** in the navigation bar and then select the **Pipelines** tab.
1. Click **Resources > Pipelines.** In versions prior to v2.3.0, click **Workloads > Pipelines.**
1. Find the example repository, select the vertical **Ellipsis (...)**. There are two ways to view the pipeline:
* **Rancher UI**: Click on **Edit Config** to view the stages and steps of the pipeline.
@@ -57,7 +57,7 @@ After enabling an example repository, run the pipeline to see how it works.
1. From the **Global** view, navigate to the project that you want to test out pipelines.
1. Select **Workloads** in the navigation bar and then select the **Pipelines** tab.
1. Click **Resources > Pipelines.** In versions prior to v2.3.0, click **Workloads > Pipelines.**
1. Find the example repository, select the vertical **Ellipsis (...) > Run**.

Some files were not shown because too many files have changed in this diff Show More