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

Merge branch 'master' into rke-macports

Browse Source
This commit is contained in:
Catherine Luse
2020-04-14 14:45:39 -07:00
committed by GitHub
parent ffde51352c ec05cadd97
commit d0eaac89df
370 changed files with 7439 additions and 3997 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/_index.html
+1 -1
View File
@@ -215,7 +215,7 @@
<hr/> <hr/>
<p class="description-label">Lightweight Kubernetes. Easy to install, half the memory, all in a binary less than 40mb.</p> <p class="description-label">Lightweight Kubernetes. Easy to install, half the memory, all in a binary less than 50mb.</p>
<div class="buttons-container"> <div class="buttons-container">
<a href="{{<baseurl>}}/k3s/latest/en/"> <a href="{{<baseurl>}}/k3s/latest/en/">
content/k3s/latest/en/_index.md
+2 -2
View File
@@ -4,7 +4,7 @@ shortTitle: K3s
name: "menu" name: "menu"
--- ---
Lightweight Kubernetes. Easy to install, half the memory, all in a binary less than 50mb. Lightweight Kubernetes. Easy to install, half the memory, all in a binary of less than 50mb.
Great for: Great for:
@@ -12,7 +12,7 @@ Great for:
* IoT * IoT
* CI * CI
* ARM * ARM
* Situations where a PhD in k8s clusterology is infeasible * Situations where a PhD in K8s clusterology is infeasible
# What is K3s? # What is K3s?
content/k3s/latest/en/advanced/_index.md
+66
View File
@@ -10,11 +10,14 @@ This section contains advanced information describing the different ways you can
- [Auto-deploying manifests](#auto-deploying-manifests) - [Auto-deploying manifests](#auto-deploying-manifests)
- [Using Docker as the container runtime](#using-docker-as-the-container-runtime) - [Using Docker as the container runtime](#using-docker-as-the-container-runtime)
- [Secrets Encryption Config (Experimental)](#secrets-encryption-config-experimental)
- [Running K3s with RootlessKit (Experimental)](#running-k3s-with-rootlesskit-experimental) - [Running K3s with RootlessKit (Experimental)](#running-k3s-with-rootlesskit-experimental)
- [Node labels and taints](#node-labels-and-taints) - [Node labels and taints](#node-labels-and-taints)
- [Starting the server with the installation script](#starting-the-server-with-the-installation-script) - [Starting the server with the installation script](#starting-the-server-with-the-installation-script)
- [Additional preparation for Alpine Linux setup](#additional-preparation-for-alpine-linux-setup) - [Additional preparation for Alpine Linux setup](#additional-preparation-for-alpine-linux-setup)
- [Running K3d (K3s in Docker) and docker-compose](#running-k3d-k3s-in-docker-and-docker-compose) - [Running K3d (K3s in Docker) and docker-compose](#running-k3d-k3s-in-docker-and-docker-compose)
- [Enabling legacy iptables on Raspbian Buster](#enabling-legacy-iptables-on-raspbian-buster)
- [Experimental SELinux Support](#experimental-selinux-support)
# Auto-Deploying Manifests # Auto-Deploying Manifests
@@ -30,6 +33,45 @@ K3s will generate config.toml for containerd in `/var/lib/rancher/k3s/agent/etc/
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 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
# Secrets Encryption Config (Experimental)
As of v1.17.4+k3s1, K3s added the experimental feature of enabling secrets encryption at rest by passing the flag `--secrets-encryption` on a server, this flag will do the following automatically:
- Generate an AES-CBC key
- Generate an encryption config file with the generated key
```
{
"kind": "EncryptionConfiguration",
"apiVersion": "apiserver.config.k8s.io/v1",
"resources": [
{
"resources": [
"secrets"
],
"providers": [
{
"aescbc": {
"keys": [
{
"name": "aescbckey",
"secret": "xxxxxxxxxxxxxxxxxxx"
}
]
}
},
{
"identity": {}
}
]
}
]
}
```
- Pass the config to the KubeAPI as encryption-provider-config
Once enabled any created secret will be encrypted with this key. Note that if you disable encryption then any encrypted secrets will not be readable until you enable encryption again.
# Running K3s with RootlessKit (Experimental) # Running K3s with RootlessKit (Experimental)
> **Warning:** This feature is experimental. > **Warning:** This feature is experimental.
@@ -162,3 +204,27 @@ Alternatively the `docker run` command can also be used:
-e K3S_TOKEN=${NODE_TOKEN} \ -e K3S_TOKEN=${NODE_TOKEN} \
--privileged rancher/k3s:vX.Y.Z --privileged rancher/k3s:vX.Y.Z
# Enabling legacy iptables on Raspbian Buster
Raspbian Buster defaults to using `nftables` instead of `iptables`. **K3S** networking features require `iptables` and do not work with `nftables`. Follow the steps below to switch configure **Buster** to use `legacy iptables`:
```
sudo iptables -F
sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
sudo reboot
```
# Experimental SELinux Support
As of release v1.17.4+k3s1, experimental support for SELinux has been added to K3s's embedded containerd. If you are installing K3s on a system where SELinux is enabled by default (such as CentOS), you must ensure the proper SELinux policies have been installed. The [install script]({{<baseurl>}}/k3s/latest/en/installation/install-options/#installation-script-options) will fail if they are not. The necessary policies can be installed with the following commands:
```
yum install -y container-selinux selinux-policy-base
rpm -i https://rpm.rancher.io/k3s-selinux-0.1.1-rc1.el7.noarch.rpm
```
To force the install script to log a warning rather than fail, you can set the following environment variable: `INSTALL_K3S_SELINUX_WARN=true`.
You can turn off SELinux enforcement in the embedded containerd by launching K3s with the `--disable-selinux` flag.
Note that support for SELinux in containerd is still under development. Progress can be tracked in [this pull request](https://github.com/containerd/cri/pull/1246).
content/k3s/latest/en/installation/_index.md
+1 -2
View File
@@ -3,11 +3,10 @@ title: "Installation"
weight: 20 weight: 20
--- ---
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. This section contains instructions for installing K3s in various environments. Please ensure you have met the [Installation Requirements]({{< baseurl >}}/k3s/latest/en/installation/installation-requirements/) before you begin installing K3s.
[Installation and Configuration Options]({{<baseurl>}}/k3s/latest/en/installation/install-options/) provides guidance on the options available to you when installing K3s. [Installation and Configuration Options]({{<baseurl>}}/k3s/latest/en/installation/install-options/) provides guidance on the options available to you when installing K3s.
[High Availability with an External DB]({{<baseurl>}}/k3s/latest/en/installation/ha/) details how to set up an HA K3s cluster backed by an external datastore such as MySQL, PostgreSQL, or etcd. [High Availability with an External DB]({{<baseurl>}}/k3s/latest/en/installation/ha/) details how to set up an HA K3s cluster backed by an external datastore such as MySQL, PostgreSQL, or etcd.
[High Availability with Embedded DB (Experimental)]({{<baseurl>}}/k3s/latest/en/installation/ha-embedded/) details how to set up an HA K3s cluster that leverages a built-in distributed database. [High Availability with Embedded DB (Experimental)]({{<baseurl>}}/k3s/latest/en/installation/ha-embedded/) details how to set up an HA K3s cluster that leverages a built-in distributed database.
content/k3s/latest/en/installation/airgap/_index.md
+76 -38
View File
@@ -3,77 +3,115 @@ title: "Air-Gap Install"
weight: 60 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. You can install K3s in an air-gapped environment using two different methods. You can either deploy a private registry and mirror docker.io or you can manually deploy images such as for small clusters.
# Installation Outline # Private Registry Method
1. [Prepare Images Directory](#prepare-images-directory) This document assumes you have already created your nodes in your air-gap environment and have a secure Docker private registry on your bastion host.
2. [Create Registry YAML](#create-registry-YAML) If you have not yet set up a private Docker registry, refer to the official documentation [here](https://docs.docker.com/registry/deploying/#run-an-externally-accessible-registry).
3. [Install K3s](#install-k3s)
### Prepare Images Directory ### Create the Registry YAML
Follow the [Private Registry Configuration]({{< baseurl >}}/k3s/latest/en/installation/private-registry) guide to create and configure the registry.yaml file.
Once you have completed this, you may now go to the [Install K3s](#install-k3s) section below.
# Manually Deploy Images Method
We are assuming you have created your nodes in your air-gap environment.
This method requires you to manually deploy the necessary images to each node and is appropriate for edge deployments where running a private registry is not practical.
### Prepare the Images Directory and K3s Binary
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. 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: Place the tar file in the `images` directory, for example:
```sh ```sh
sudo mkdir -p /var/lib/rancher/k3s/agent/images/ sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/ sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/
``` ```
### Create Registry YAML Place the k3s binary at /usr/local/bin/k3s and ensure it is executable.
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:
``` Follow the steps in the next section to install K3s.
---
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
### Install K3s Only after you have completed either the [Private Registry Method](#private-registry-method) or the [Manually Deploy Images Method](#manually-deploy-images-method) above should you 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. Obtain the K3s binary from the [releases](https://github.com/rancher/k3s/releases) page, matching the same version used to get the airgap images.
Also obtain the K3s install script at https://get.k3s.io Obtain the K3s install script at https://get.k3s.io
Place the binary in `/usr/local/bin` on each node. Place the binary in `/usr/local/bin` on each node and ensure it is executable.
Place the install script anywhere on each node, name it `install.sh`. Place the install script anywhere on each node, and name it `install.sh`.
Install K3s on each server:
### Install Options
You can install K3s on one or more servers as described below.
{{% tabs %}}
{{% tab "Single Server Configuration" %}}
To install K3s on a single server simply do the following on the server node.
``` ```
INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh
``` ```
Install K3s on each agent: Then, to optionally add additional agents do the following on each agent node. 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 typically at `/var/lib/rancher/k3s/server/node-token`
``` ```
INSTALL_K3S_SKIP_DOWNLOAD=true K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken ./install.sh 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. {{% /tab %}}
The node-token is on the server at `/var/lib/rancher/k3s/server/node-token` {{% tab "High Availability Configuration" %}}
Reference the [High Availability with an External DB]({{< baseurl >}}/k3s/latest/en/installation/ha) or [High Availability with Embedded DB (Experimental)]({{< baseurl >}}/k3s/latest/en/installation/ha-embedded) guides. You will be tweaking install commands so you specify `INSTALL_K3S_SKIP_DOWNLOAD=true` and run your install script locally instead of via curl. You will also utilize `INSTALL_K3S_EXEC='args'` to supply any arguments to k3s.
For example, step two of the High Availability with an External DB guide mentions the following:
```
curl -sfL https://get.k3s.io | sh -s - server \
--datastore-endpoint="mysql://username:password@tcp(hostname:3306)/database-name"
```
Instead, you would modify such examples like below:
```
INSTALL_K3S_SKIP_DOWNLOAD=true INSTALL_K3S_EXEC='server --datastore-endpoint="mysql://username:password@tcp(hostname:3306)/database-name"' ./install.sh
```
{{% /tab %}}
{{% /tabs %}}
>**Note:** K3s additionally provides a `--resolv-conf` flag for kubelets, which may help with configuring DNS in air-gap networks. >**Note:** K3s additionally provides a `--resolv-conf` flag for kubelets, which may help with configuring DNS in air-gap networks.
# Upgrading # Upgrading
### Install Script Method
Upgrading an air-gap environment can be accomplished in the following manner: 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. 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
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. 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). 3. Restart the K3s service (if not restarted automatically by installer).
### Automated Upgrades Method
As of v1.17.4+k3s1 K3s supports [automated upgrades]({{< baseurl >}}/k3s/latest/en/upgrades/automated/). To enable this in air-gapped environments, you must ensure the required images are available in your private registry.
You will need the version of rancher/k3s-upgrade that corresponds to the version of K3s you intend to upgrade to. Note, the image tag replaces the `+` in the K3s release with a `-` because Docker images do not support `+`.
You will also need the versions of system-upgrade-controller and kubectl that are specified in the system-upgrade-controller manifest YAML that you will deploy. Check for the latest release of the system-upgrade-controller [here](https://github.com/rancher/system-upgrade-controller/releases/latest) and download the system-upgrade-controller.yaml to determine the versions you need to push to your private registry. For example, in release v0.4.0 of the system-upgrade-controller, these images are specified in the manifest YAML:
```
rancher/system-upgrade-controller:v0.4.0
rancher/kubectl:v0.17.0
```
Once you have added the necessary rancher/k3s-upgrade, rancher/system-upgrade-controller, and rancher/kubectl images to your private registry, follow the [automated upgrades]({{< baseurl >}}/k3s/latest/en/upgrades/automated/) guide.
content/k3s/latest/en/installation/datastore/_index.md
+3 -2
View File
@@ -14,6 +14,7 @@ K3s supports the following datastore options:
* Embedded [SQLite](https://www.sqlite.org/index.html) * Embedded [SQLite](https://www.sqlite.org/index.html)
* [PostgreSQL](https://www.postgresql.org/) (certified against versions 10.7 and 11.5) * [PostgreSQL](https://www.postgresql.org/) (certified against versions 10.7 and 11.5)
* [MySQL](https://www.mysql.com/) (certified against version 5.7) * [MySQL](https://www.mysql.com/) (certified against version 5.7)
* [MariaDB](https://mariadb.org/) (certified against version 10.3.20)
* [etcd](https://etcd.io/) (certified against version 3.3.15) * [etcd](https://etcd.io/) (certified against version 3.3.15)
* Embedded [DQLite](https://dqlite.io/) for High Availability (experimental) * Embedded [DQLite](https://dqlite.io/) for High Availability (experimental)
@@ -50,9 +51,9 @@ If you only supply `postgres://` as the endpoint, K3s will attempt to do the fo
{{% /tab %}} {{% /tab %}}
{{% tab "MySQL" %}} {{% tab "MySQL / MariaDB" %}}
In its most common form, the `datastore-endpoint` parameter for MySQL has the following format: In its most common form, the `datastore-endpoint` parameter for MySQL and MariaDB has the following format:
`mysql://username:password@tcp(hostname:3306)/database-name` `mysql://username:password@tcp(hostname:3306)/database-name`
content/k3s/latest/en/installation/ha/_index.md
+4 -2
View File
@@ -31,7 +31,7 @@ Setting up an HA cluster requires the following steps:
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. 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.
### 2. Launch Server Nodes ### 2. 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. K3s requires two or more server nodes for this HA configuration. See the [Installation Requirements]({{<baseurl>}}/k3s/latest/en/installation/installation-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. 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.
@@ -53,19 +53,21 @@ By default, server nodes will be schedulable and thus your workloads can get lau
Once you've launched the `k3s server` process on all server nodes, ensure that the cluster has come up properly with `k3s kubectl get nodes`. You should see your server nodes in the Ready state. Once you've launched the `k3s server` process on all server nodes, ensure that the cluster has come up properly with `k3s kubectl get nodes`. You should see your server nodes in the Ready state.
### 3. Configure the Fixed Registration Address ### 3. Configure the Fixed Registration Address
Agent nodes need a URL to register against. This can be the IP or hostname of any of the server nodes, but in many cases those may change over time. 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 set up using any number approaches, such as: Agent nodes need a URL to register against. This can be the IP or hostname of any of the server nodes, but in many cases those may change over time. 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 set up using any number approaches, such as:
* A layer-4 (TCP) load balancer * A layer-4 (TCP) load balancer
* Round-robin DNS * Round-robin DNS
* Virtual or elastic IP addresses * Virtual or elastic IP addresses
This endpoint can also be used for accessing the Kubernetes API. So you can, for example, modify your [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) file to point to it instead of a specific node. This endpoint can also be used for accessing the Kubernetes API. So you can, for example, modify your [kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) file to point to it instead of a specific node. To avoid certificate errors in such a configuration, you should install the server with the `--tls-san YOUR_IP_OR_HOSTNAME_HERE` option. This option adds an additional hostname or IP as a Subject Alternative Name in the TLS cert, and it can be specified multiple times if you would like to access via both the IP and the hostname.
### 4. Optional: Join Agent Nodes ### 4. Optional: Join Agent Nodes
Because K3s server nodes are schedulable by default, the minimum number of nodes for an HA K3s server cluster is two server nodes and zero agent nodes. To add nodes designated to run your apps and services, join agent nodes to your cluster. Because K3s server nodes are schedulable by default, the minimum number of nodes for an HA K3s server cluster is two server nodes and zero agent nodes. To add nodes designated to run your apps and services, join agent nodes to your cluster.
Joining agent nodes in an HA cluster is the same as joining agent nodes in a single server cluster. You just need to specify the URL the agent should register to and the token it should use. Joining agent nodes in an HA cluster is the same as joining agent 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 K3S_TOKEN=SECRET k3s agent --server https://fixed-registration-address:6443
``` ```
content/k3s/latest/en/installation/install-options/_index.md
+26 -164
View File
@@ -5,14 +5,16 @@ weight: 20
This page focuses on the options that can be used when you set up K3s for the first time: This page focuses on the options that can be used when you set up K3s for the first time:
- [Installation script options](#installation-script-options) - [Options for installation with script](#options-for-installation-with-script)
- [Installing K3s from the binary](#installing-k3s-from-the-binary) - [Options for installation from binary](#options-for-installation-from-binary)
- [Registration options for the K3s server](#registration-options-for-the-k3s-server) - [Registration options for the K3s server](#registration-options-for-the-k3s-server)
- [Registration options for the K3s agent](#registration-options-for-the-k3s-agent) - [Registration options for the K3s agent](#registration-options-for-the-k3s-agent)
For more advanced options, refer to [this page.]({{<baseurl>}}/k3s/latest/en/advanced) For more advanced options, refer to [this page.]({{<baseurl>}}/k3s/latest/en/advanced)
# Installation Script Options > Throughout the K3s documentation, you will see some options that can be passed in as both command flags and environment variables. For help with passing in options, refer to [How to Use Flags and Environment Variables.]({{<baseurl>}}/k3s/latest/en/installation/install-options/how-to-flags)
### Options for Installation with Script
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. 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.
@@ -23,58 +25,25 @@ 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: When using this method to install K3s, the following environment variables can be used to configure the installation:
- `INSTALL_K3S_SKIP_DOWNLOAD` | Environment Variable | Description |
|-----------------------------|---------------------------------------------|
If set to true will not download K3s hash or binary. | `INSTALL_K3S_SKIP_DOWNLOAD` | If set to true will not download K3s hash or binary. |
| `INSTALL_K3S_SYMLINK` | By default will create symlinks for the kubectl, crictl, and ctr binaries if the commands do not already exist in path. If set to 'skip' will not create symlinks and 'force' will overwrite. |
- `INSTALL_K3S_SYMLINK` | `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. |
If set to 'skip' will not create symlinks, 'force' will overwrite, default will symlink if command does not exist in path. | `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_SKIP_START` | `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, and the `K3S_URL` is set, it will default to "agent." If `K3S_URL` not set, it will default to "server." For help, refer to [this example.]({{<baseurl>}}/k3s/latest/en/installation/install-options/how-to-flags/#example-b-install-k3s-exec) |
If set to true will not start K3s service. | `INSTALL_K3S_NAME` | Name of systemd service to create, will default to 'k3s' if running k3s as a server and 'k3s-agent' if running k3s as an agent. 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.
- `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 of registering a server without flannel:
```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. 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.
# Installing K3s from the Binary # Installing K3s from the Binary
@@ -89,120 +58,13 @@ Command | Description
<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 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 <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: 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>.
# Registration Options for the K3s Server ### Registration Options for the K3s Server
```
NAME:
k3s server - Run management server
USAGE: For details on configuring the K3s server, refer to the [server configuration reference.]({{<baseurl>}}/k3s/latest/en/installation/install-options/server-config)
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]
```
# Registration Options for the K3s Agent ### Registration Options for the K3s Agent
```
NAME:
k3s agent - Run node agent
USAGE: For details on configuring the K3s agent, refer to the [agent configuration reference.]({{<baseurl>}}/k3s/latest/en/installation/install-options/agent-config)
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]
```
### Node Labels and Taints for Agents
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 commands.
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
```
If you want to change node labels and taints after node registration you should use `kubectl`. Refer to the official Kubernetes documentation for details on how to add [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) and [node labels.](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes/#add-a-label-to-a-node)
content/k3s/latest/en/installation/install-options/agent-config/_index.md
+136
View File
@@ -0,0 +1,136 @@
---
title: K3s Agent Configuration Reference
weight: 2
---
In this section, you'll learn how to configure the K3s agent.
> Throughout the K3s documentation, you will see some options that can be passed in as both command flags and environment variables. For help with passing in options, refer to [How to Use Flags and Environment Variables.]({{<baseurl>}}/k3s/latest/en/installation/install-options/how-to-flags)
- [Logging](#logging)
- [Cluster Options](#cluster-options)
- [Data](#data)
- [Node](#node)
- [Runtime](#runtime)
- [Networking](#networking)
- [Customized Flags](#customized-flags)
- [Experimental](#experimental)
- [Deprecated](#deprecated)
- [Node Labels and Taints for Agents](#node-labels-and-taints-for-agents)
- [K3s Agent CLI Help](#k3s-agent-cli-help)
### Logging
| Flag | Default | Description |
|------|---------|-------------|
| `-v` value | 0 | Number for the log level verbosity |
| `--vmodule` value | N/A | Comma-separated list of pattern=N settings for file-filtered logging |
| `--log value, -l` value | N/A | Log to file |
| `--alsologtostderr` | N/A | Log to standard error as well as file (if set) |
### Cluster Options
| Flag | Environment Variable | Description |
|------|----------------------|-------------|
| `--token value, -t` value | `K3S_TOKEN` | Token to use for authentication |
| `--token-file` value | `K3S_TOKEN_FILE` | Token file to use for authentication |
| `--server value, -s` value | `K3S_URL` | Server to connect to |
### Data
| Flag | Default | Description |
|------|---------|-------------|
| `--data-dir value, -d` value | "/var/lib/rancher/k3s" | Folder to hold state |
### Node
| Flag | Environment Variable | Description |
|------|----------------------|-------------|
| `--node-name` value | `K3S_NODE_NAME` | Node name |
| `--with-node-id` | N/A | Append id to node name |
| `--node-label` value | N/A | Registering and starting kubelet with set of labels |
| `--node-taint` value | N/A | Registering kubelet with set of taints |
### Runtime
| Flag | Default | Description |
|------|---------|-------------|
| `--docker` | N/A | Use docker instead of containerd |
| `--container-runtime-endpoint` value | N/A | Disable embedded containerd and use alternative CRI implementation |
| `--pause-image` value | "docker.io/rancher/pause:3.1" | Customized pause image for containerd or docker sandbox | (agent/runtime) (default: )
| `--private-registry` value | "/etc/rancher/k3s/registries.yaml" | Private registry configuration file |
### Networking
| Flag | Environment Variable | Description |
|------|----------------------|-------------|
| `--node-ip value, -i` value | N/A | IP address to advertise for node |
| `--node-external-ip` value | N/A | External IP address to advertise for node |
| `--resolv-conf` value | `K3S_RESOLV_CONF` | Kubelet resolv.conf file |
| `--flannel-iface` value | N/A | Override default flannel interface |
| `--flannel-conf` value | N/A | Override default flannel config file |
### Customized Flags
| Flag | Description |
|------|--------------|
| `--kubelet-arg` value | Customized flag for kubelet process |
| `--kube-proxy-arg` value | Customized flag for kube-proxy process |
### Experimental
| Flag | Description |
|------|--------------|
| `--rootless` | Run rootless |
### Deprecated
| Flag | Environment Variable | Description |
|------|----------------------|-------------|
| `--no-flannel` | N/A | Use `--flannel-backend=none` |
| `--cluster-secret` value | `K3S_CLUSTER_SECRET` | Use `--token` |
### Node Labels and Taints for Agents
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 commands.
Below is an example showing how to add labels and a taint:
```bash
--node-label foo=bar \
--node-label hello=world \
--node-taint key1=value1:NoExecute
```
If you want to change node labels and taints after node registration you should use `kubectl`. Refer to the official Kubernetes documentation for details on how to add [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) and [node labels.](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes/#add-a-label-to-a-node)
### K3s Agent CLI Help
> If an option appears in brackets below, for example `[$K3S_URL]`, it means that the option can be passed in as an environment variable of that name.
```bash
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 and starting 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 or docker sandbox (default: "docker.io/rancher/pause:3.1")
--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/install-options/how-to-flags/_index.md
+35
View File
@@ -0,0 +1,35 @@
---
title: How to Use Flags and Environment Variables
weight: 3
---
Throughout the K3s documentation, you will see some options that can be passed in as both command flags and environment variables. The below examples show how these options can be passed in both ways.
### Example A: K3S_KUBECONFIG_MODE
The option to allow writing to the kubeconfig file is useful for allowing a K3s cluster to be imported into Rancher. Below are two ways to pass in the option.
Using the flag `--write-kubeconfig-mode 644`:
```bash
$ curl -sfL https://get.k3s.io | sh -s - --write-kubeconfig-mode 644
```
Using the environment variable `K3S_KUBECONFIG_MODE`:
```bash
$ curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE="644" sh -s -
```
### Example B: INSTALL_K3S_EXEC
If this command is not specified as a server or agent command, 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 of registering a server without flannel:
```bash
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--no-flannel" sh -s -
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server --no-flannel" sh -s -
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server" sh -s - --no-flannel
curl -sfL https://get.k3s.io | sh -s - server --no-flannel
curl -sfL https://get.k3s.io | sh -s - --no-flannel
```
content/k3s/latest/en/installation/install-options/server-config/_index.md
+250
View File
@@ -0,0 +1,250 @@
---
title: K3s Server Configuration Reference
weight: 1
---
In this section, you'll learn how to configure the K3s server.
> Throughout the K3s documentation, you will see some options that can be passed in as both command flags and environment variables. For help with passing in options, refer to [How to Use Flags and Environment Variables.]({{<baseurl>}}/k3s/latest/en/installation/install-options/how-to-flags)
- [Commonly Used Options](#commonly-used-options)
- [Database](#database)
- [Cluster Options](#cluster-options)
- [Client Options](#client-options)
- [Agent Options](#agent-options)
- [Agent Nodes](#agent-nodes)
- [Agent Runtime](#agent-runtime)
- [Agent Networking](#agent-networking)
- [Advanced Options](#advanced-options)
- [Logging](#logging)
- [Listeners](#listeners)
- [Data](#data)
- [Networking](#networking)
- [Customized Options](#customized-options)
- [Storage Class](#storage-class)
- [Kubernetes Components](#kubernetes-components)
- [Customized Flags for Kubernetes Processes](#customized-flags-for-kubernetes-processes)
- [Experimental Options](#experimental-options)
- [Deprecated Options](#deprecated-options)
- [K3s Server Cli Help](#k3s-server-cli-help)
# Commonly Used Options
### Database
| Flag | Environment Variable | Description |
|------|----------------------|-------------|
| `--datastore-endpoint` value | `K3S_DATASTORE_ENDPOINT` | Specify etcd, Mysql, Postgres, or Sqlite (default) data source name |
| `--datastore-cafile` value | `K3S_DATASTORE_CAFILE` | TLS Certificate Authority file used to secure datastore backend communication |
| `--datastore-certfile` value | `K3S_DATASTORE_CERTFILE` | TLS certification file used to secure datastore backend communication |
| `--datastore-keyfile` value | `K3S_DATASTORE_KEYFILE` | TLS key file used to secure datastore backend communication |
### Cluster Options
| Flag | Environment Variable | Description |
|------|----------------------|-------------|
| `--token value, -t` value | `K3S_TOKEN` | Shared secret used to join a server or agent to a cluster |
| `--token-file` value | `K3S_TOKEN_FILE` | File containing the cluster-secret/token |
### Client Options
| Flag | Environment Variable | Description |
|------|----------------------|-------------|
| `--write-kubeconfig value, -o` value | `K3S_KUBECONFIG_OUTPUT` | Write kubeconfig for admin client to this file |
| `--write-kubeconfig-mode` value | `K3S_KUBECONFIG_MODE` | Write kubeconfig with this [mode.](https://en.wikipedia.org/wiki/Chmod) The option to allow writing to the kubeconfig file is useful for allowing a K3s cluster to be imported into Rancher. An example value is 644. |
# Agent Options
K3s agent options are available as server options because the server has the agent process embedded within.
### Agent Nodes
| Flag | Environment Variable | Description |
|------|----------------------|-------------|
| `--node-name` value | `K3S_NODE_NAME` | Node name |
| `--with-node-id` | N/A | Append id to node name | (agent/node)
| `--node-label` value | N/A | Registering and starting kubelet with set of labels |
| `--node-taint` value | N/A | Registering kubelet with set of taints |
### Agent Runtime
| Flag | Default | Description |
|------|---------|-------------|
| `--docker` | N/A | Use docker instead of containerd | (agent/runtime)
| `--container-runtime-endpoint` value | N/A | Disable embedded containerd and use alternative CRI implementation |
| `--pause-image` value | "docker.io/rancher/pause:3.1" | Customized pause image for containerd or Docker sandbox |
| `--private-registry` value | "/etc/rancher/k3s/registries.yaml" | Private registry configuration file |
### Agent Networking
the agent options are there because the server has the agent process embedded within
| Flag | Environment Variable | Description |
|------|----------------------|-------------|
| `--node-ip value, -i` value | N/A | IP address to advertise for node |
| `--node-external-ip` value | N/A | External IP address to advertise for node |
| `--resolv-conf` value | `K3S_RESOLV_CONF` | Kubelet resolv.conf file |
| `--flannel-iface` value | N/A | Override default flannel interface |
| `--flannel-conf` value | N/A | Override default flannel config file |
# Advanced Options
### Logging
| Flag | Default | Description |
|------|---------|-------------|
| `-v` value | 0 | Number for the log level verbosity |
| `--vmodule` value | N/A | Comma-separated list of pattern=N settings for file-filtered logging |
| `--log value, -l` value | N/A | Log to file |
| `--alsologtostderr` | N/A | Log to standard error as well as file (if set) |
### Listeners
| Flag | Default | Description |
|------|---------|-------------|
| `--bind-address` value | 0.0.0.0 | k3s bind address |
| `--https-listen-port` value | 6443 | HTTPS listen port |
| `--advertise-address` value | node-external-ip/node-ip | IP address that apiserver uses to advertise to members of the cluster |
| `--advertise-port` value | 0 | Port that apiserver uses to advertise to members of the cluster (default: listen-port) |
| `--tls-san` value | N/A | Add additional hostname or IP as a Subject Alternative Name in the TLS cert
### Data
| Flag | Default | Description |
|------|---------|-------------|
| `--data-dir value, -d` value | `/var/lib/rancher/k3s` or `${HOME}/.rancher/k3s` if not root | Folder to hold state |
### Networking
| Flag | Default | Description |
|------|---------|-------------|
| `--cluster-cidr` value | "10.42.0.0/16" | Network CIDR to use for pod IPs |
| `--service-cidr` value | "10.43.0.0/16" | Network CIDR to use for services IPs |
| `--cluster-dns` value | "10.43.0.10" | Cluster IP for coredns service. Should be in your service-cidr range |
| `--cluster-domain` value | "cluster.local" | Cluster Domain |
| `--flannel-backend` value | "vxlan" | One of 'none', 'vxlan', 'ipsec', 'host-gw', or 'wireguard' |
### Customized Flags
| Flag | Description |
|------|--------------|
| `--kube-apiserver-arg` value | Customized flag for kube-apiserver process |
| `--kube-scheduler-arg` value | Customized flag for kube-scheduler process |
| `--kube-controller-manager-arg` value | Customized flag for kube-controller-manager process |
| `--kube-cloud-controller-manager-arg` value | Customized flag for kube-cloud-controller-manager process |
### Storage Class
| Flag | Description |
|------|--------------|
| `--default-local-storage-path` value | Default local storage path for local provisioner storage class |
### Kubernetes Components
| Flag | Description |
|------|--------------|
| `--disable` value | Do not deploy packaged components and delete any deployed components (valid items: coredns, servicelb, traefik,local-storage, metrics-server) |
| `--disable-scheduler` | Disable Kubernetes default scheduler |
| `--disable-cloud-controller` | Disable k3s default cloud controller manager |
| `--disable-network-policy` | Disable k3s default network policy controller |
### Customized Flags for Kubernetes Processes
| Flag | Description |
|------|--------------|
| `--kubelet-arg` value | Customized flag for kubelet process |
| `--kube-proxy-arg` value | Customized flag for kube-proxy process |
### Experimental Options
| Flag | Environment Variable | Description |
|------|----------------------|-------------|
| `--rootless` | N/A | Run rootless | (experimental)
| `--agent-token` value | `K3S_AGENT_TOKEN` | Shared secret used to join agents to the cluster, but not servers |
| `--agent-token-file` value | `K3S_AGENT_TOKEN_FILE` | File containing the agent secret |
| `--server value, -s` value | `K3S_URL` | Server to connect to, used to join a cluster |
| `--cluster-init` | `K3S_CLUSTER_INIT` | Initialize new cluster master |
| `--cluster-reset` | `K3S_CLUSTER_RESET` | Forget all peers and become a single cluster new cluster master |
| `--secrets-encryption` | N/A | Enable Secret encryption at rest |
### Deprecated Options
| Flag | Environment Variable | Description |
|------|----------------------|-------------|
| `--no-flannel` | N/A | Use --flannel-backend=none |
| `--no-deploy` value | N/A | Do not deploy packaged components (valid items: coredns, servicelb, traefik, local-storage, metrics-server) |
| `--cluster-secret` value | `K3S_CLUSTER_SECRET` | Use --token |
# K3s Server CLI Help
> If an option appears in brackets below, for example `[$K3S_TOKEN]`, it means that the option can be passed in as an environment variable of that name.
```bash
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', 'host-gw', or 'wireguard' (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
--disable value (components) Do not deploy packaged components and delete any deployed 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 and starting 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 or docker sandbox (default: "docker.io/rancher/pause:3.1")
--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]
--secrets-encryption (experimental) Enable Secret encryption at rest
--no-flannel (deprecated) use --flannel-backend=none
--no-deploy value (deprecated) Do not deploy packaged components (valid items: coredns, servicelb, traefik, local-storage, metrics-server)
--cluster-secret value (deprecated) use --token [$K3S_CLUSTER_SECRET]
```
content/k3s/latest/en/installation/installation-requirements/_index.md
+32 -5
View File
@@ -1,6 +1,8 @@
--- ---
title: Installation Requirements title: Installation Requirements
weight: 1 weight: 1
aliases:
- /k3s/latest/en/installation/node-requirements/
--- ---
K3s is very lightweight, but has some minimum requirements as outlined below. K3s is very lightweight, but has some minimum requirements as outlined below.
@@ -9,7 +11,7 @@ Whether you're configuring a K3s cluster to run in a Docker or Kubernetes setup,
## Prerequisites ## 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. * Two nodes cannot have the same hostname. If all your nodes have the same hostname, use the `--with-node-id` option to append a random suffix for each node, or otherwise devise a unique name to pass with `--node-name` or `$K3S_NODE_NAME` for each node you add to the cluster.
## Operating Systems ## Operating Systems
@@ -17,9 +19,10 @@ K3s should run on just about any flavor of Linux. However, K3s is tested on the
* Ubuntu 16.04 (amd64) * Ubuntu 16.04 (amd64)
* Ubuntu 18.04 (amd64) * Ubuntu 18.04 (amd64)
* Raspbian Buster (armhf)
> If you are using Alpine Linux, follow [these steps]({{<baseurl>}}/k3s/latest/en/advanced/#additional-preparation-for-alpine-linux-setup) for additional setup. > * If you are using **Raspbian Buster**, follow [these steps]({{<baseurl>}}/k3s/latest/en/advanced/#enabling-legacy-iptables-on-raspbian-buster) to switch to legacy iptables.
> * If you are using **Alpine Linux**, follow [these steps]({{<baseurl>}}/k3s/latest/en/advanced/#additional-preparation-for-alpine-linux-setup) for additional setup.
## Hardware ## Hardware
@@ -34,15 +37,28 @@ K3s performance depends on the performance of the database. To ensure optimal sp
## Networking ## 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. The K3s server needs port 6443 to be accessible by the nodes.
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. The nodes need to be able to reach other nodes over UDP port 8472 when Flannel VXLAN is used. 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. However, if you do not use Flannel and provide your own custom CNI, then port 8472 is not needed by K3s.
If you wish to utilize the metrics server, you will need to open port 10250 on each node. If you wish to utilize the metrics server, you will need to open port 10250 on each node.
> **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 disables access to port 8472.
<figcaption>Inbound Rules for K3s Server Nodes</figcaption>
| Protocol | Port | Source | Description
|-----|-----|----------------|---|
| TCP | 6443 | K3s server nodes | Kubernetes API
| UDP | 8472 | K3s server and agent nodes | Required only for Flannel VXLAN
| TCP | 10250 | K3s server and agent nodes | kubelet
Typically all outbound traffic is allowed.
## Large Clusters ## Large Clusters
Hardware requirements are based on the size of your K3s cluster. For production and large clusters, we recommend using a high-availability setup with an external database. The following options are recommended for the external database in production: Hardware requirements are based on the size of your K3s cluster. For production and large clusters, we recommend using a high-availability setup with an external database. The following options are recommended for the external database in production:
- MySQL - MySQL
- PostgreSQL - PostgreSQL
- etcd - etcd
@@ -67,4 +83,15 @@ The cluster performance depends on database performance. To ensure optimal speed
You should consider increasing the subnet size for the cluster CIDR so that you don't run out of IPs for the pods. You can do that by passing the `--cluster-cidr` option to K3s server upon starting. You should consider increasing the subnet size for the cluster CIDR so that you don't run out of IPs for the pods. You can do that by passing the `--cluster-cidr` option to K3s server upon starting.
### Database
K3s supports different databases including MySQL, PostgreSQL, MariaDB, and etcd, the following is a sizing guide for the database resources you need to run large clusters:
| Deployment Size | Nodes | VCPUS | RAM |
|:---------------:|:---------:|:-----:|:-----:|
| Small | Up to 10 | 1 | 2 GB |
| Medium | Up to 100 | 2 | 8 GB |
| Large | Up to 250 | 4 | 16 GB |
| X-Large | Up to 500 | 8 | 32 GB |
| XX-Large | 500+ | 16 | 64 GB |
content/k3s/latest/en/installation/private-registry/_index.md
+20 -5
View File
@@ -25,7 +25,7 @@ Mirrors is a directive that defines the names and endpoints of the private regis
``` ```
mirrors: mirrors:
"mycustomreg.com:5000": docker.io:
endpoint: endpoint:
- "https://mycustomreg.com:5000" - "https://mycustomreg.com:5000"
``` ```
@@ -59,7 +59,7 @@ Below are examples showing how you may configure `/etc/rancher/k3s/registries.ya
``` ```
mirrors: mirrors:
"mycustomreg.com:5000": docker.io:
endpoint: endpoint:
- "https://mycustomreg.com:5000" - "https://mycustomreg.com:5000"
configs: configs:
@@ -78,7 +78,7 @@ configs:
``` ```
mirrors: mirrors:
"mycustomreg.com:5000": docker.io:
endpoint: endpoint:
- "https://mycustomreg.com:5000" - "https://mycustomreg.com:5000"
configs: configs:
@@ -101,7 +101,7 @@ Below are examples showing how you may configure `/etc/rancher/k3s/registries.ya
``` ```
mirrors: mirrors:
"mycustomreg.com:5000": docker.io:
endpoint: endpoint:
- "http://mycustomreg.com:5000" - "http://mycustomreg.com:5000"
configs: configs:
@@ -116,7 +116,7 @@ configs:
``` ```
mirrors: mirrors:
"mycustomreg.com:5000": docker.io:
endpoint: endpoint:
- "http://mycustomreg.com:5000" - "http://mycustomreg.com:5000"
``` ```
@@ -127,3 +127,18 @@ mirrors:
> In case of no TLS communication, you need to specify `http://` for the endpoints, otherwise it will default to https. > In case of no TLS communication, you need to specify `http://` for the endpoints, otherwise it will default to https.
In order for the registry changes to take effect, you need to restart K3s on each node. In order for the registry changes to take effect, you need to restart K3s on each node.
# Adding Images to the Private Registry
First, obtain the k3s-images.txt file from GitHub for the release you are working with.
Pull the K3s images listed on the k3s-images.txt file from docker.io
Example: `docker pull docker.io/rancher/coredns-coredns:1.6.3`
Then, retag the images to the private registry.
Example: `docker tag coredns-coredns:1.6.3 mycustomreg:5000/coredns-coredns`
Last, push the images to the private registry.
Example: `docker push mycustomreg:5000/coredns-coredns`
content/k3s/latest/en/networking/_index.md
+1 -1
View File
@@ -7,7 +7,7 @@ weight: 35
Open Ports Open Ports
---------- ----------
Please reference the [Node Requirements]({{< baseurl >}}/k3s/latest/en/installation/node-requirements/#networking) page for port information. Please reference the [Installation Requirements]({{<baseurl>}}/k3s/latest/en/installation/installation-requirements/#networking) page for port information.
CoreDNS CoreDNS
------- -------
content/k3s/latest/en/upgrades/_index.md
+3 -37
View File
@@ -3,42 +3,8 @@ title: "Upgrades"
weight: 25 weight: 25
--- ---
You can upgrade K3s by using the installation script, or by manually installing the binary of the desired version. This section describes how to upgrade your K3s cluster.
>**Note:** When upgrading, upgrade server nodes first one at a time, then any worker nodes. [Upgrade basics]({{< baseurl >}}/k3s/latest/en/upgrades/basic/) describes several techniques for upgrading your cluster manually. It can also be used as a basis for upgrading through third-party Infrastructure-as-Code tools like [Terraform](https://www.terraform.io/).
### Upgrade K3s Using the Installation Script [Automated upgrades]({{< baseurl >}}/k3s/latest/en/upgrades/automated/) describes how to perform Kubernetes-native automated upgrades using Rancher's [system-upgrade-controller](https://github.com/rancher/system-upgrade-controller).
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 -
```
### Manually Upgrade K3s Using the Binary
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
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/k3s/latest/en/upgrades/automated/_index.md
+115
View File
@@ -0,0 +1,115 @@
---
title: "Automated Upgrades"
weight: 20
---
>**Note:** This feature is available as of [v1.17.4+k3s1](https://github.com/rancher/k3s/releases/tag/v1.17.4%2Bk3s1)
### Overview
You can manage K3s cluster upgrades using Rancher's system-upgrade-controller. This is a Kubernetes-native approach to cluster upgrades. It leverages a [custom resource definition (CRD)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#custom-resources), the `plan`, and a [controller](https://kubernetes.io/docs/concepts/architecture/controller/) that schedules upgrades based on the configured plans.
A plan defines upgrade policies and requirements. This documentation will provide plans with defaults appropriate for upgrading a K3s cluster. For more advanced plan configuration options, please review the [CRD](https://github.com/rancher/system-upgrade-controller/blob/master/pkg/apis/upgrade.cattle.io/v1/types.go).
The controller schedules upgrades by monitoring plans and selecting nodes to run upgrade [jobs](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) on. A plan defines which nodes should be upgraded through a [label selector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/). When a job has run to completion successfully, the controller will label the node on which it ran accordingly.
>**Note:** The upgrade job that is launched must be highly privileged. It is configured with the following:
>
- Host `IPC`, `NET`, and `PID` namespaces
- The `CAP_SYS_BOOT` capability
- Host root mounted at `/host` with read and write permissions
For more details on the design and architecture of the system-upgrade-controller or its integration with K3s, see the following Git repositories:
- [system-upgrade-controller](https://github.com/rancher/system-upgrade-controller)
- [k3s-upgrade](https://github.com/rancher/k3s-upgrade)
To automate upgrades in this manner you must:
1. Install the system-upgrade-controller into your cluster
1. Configure plans
### Install the system-upgrade-controller
The system-upgrade-controller can be installed as a deployment into your cluster. The deployment requires a service-account, clusterRoleBinding, and a configmap. To install these components, run the following command:
```
kubectl apply -f https://github.com/rancher/system-upgrade-controller/releases/download/v0.4.0/system-upgrade-controller.yaml
```
The controller can be configured and customized via the previously mentioned configmap, but the controller must be redeployed for the changes to be applied.
### Configure plans
It is recommended that you minimally create two plans: a plan for upgrading server (master) nodes and a plan for upgrading agent (worker) nodes. As needed, you can create additional plans to control the rollout of the upgrade across nodes. The following two example plans will upgrade your cluster to K3s v1.17.4+k3s1. Once the plans are created, the controller will pick them up and begin to upgrade your cluster.
```
# Server plan
apiVersion: upgrade.cattle.io/v1
kind: Plan
metadata:
name: server-plan
namespace: system-upgrade
spec:
concurrency: 1
cordon: true
nodeSelector:
matchExpressions:
- key: node-role.kubernetes.io/master
operator: In
values:
- "true"
serviceAccountName: system-upgrade
upgrade:
image: rancher/k3s-upgrade
version: v1.17.4+k3s1
---
# Agent plan
apiVersion: upgrade.cattle.io/v1
kind: Plan
metadata:
name: agent-plan
namespace: system-upgrade
spec:
concurrency: 1
cordon: true
nodeSelector:
matchExpressions:
- key: node-role.kubernetes.io/master
operator: DoesNotExist
prepare:
args:
- prepare
- server-plan
image: rancher/k3s-upgrade:v1.17.4-k3s1
serviceAccountName: system-upgrade
upgrade:
image: rancher/k3s-upgrade
version: v1.17.4+k3s1
```
There are a few important things to call out regarding these plans:
First, the plans must be created in the same namespace where the controller was deployed.
Second, the `concurrency` field indicates how many nodes can be upgraded at the same time.
Third, the server-plan targets server nodes by specifying a label selector that selects nodes with the `node-role.kubernetes.io/master` label. The agent-plan targets agent nodes by specifying a label selector that select nodes without that label.
Fourth, the `prepare` step in the agent-plan will cause upgrade jobs for that plan to wait for the server-plan to complete before they execute.
Fifth, both plans have the `version` field set to v1.17.4+k3s1. Alternatively, you can omit the `version` field and set the `channel` field to a URL that resolves to a release of K3s. This will cause the controller to monitor that URL and upgrade the cluster any time it resolves to a new release. This is designed specifically to work with the [latest release functionality of GitHub](https://help.github.com/en/github/administering-a-repository/linking-to-releases). Thus, you can configure your plans with the following channel to ensure your cluster is always automatically upgraded to the latest release of K3s:
```
apiVersion: upgrade.cattle.io/v1
kind: Plan
...
spec:
...
channel: https://github.com/rancher/k3s/releases/latest
```
As stated, the upgrade will begin as soon as the controller detects that a plan was created. Updating a plan will cause the controller to re-evaluate the plan and determine if another upgrade is needed.
You can monitor the progress of an upgrade by viewing the plan and jobs via kubectl:
```
kubectl -n system-upgrade get plans -o yaml
kubectl -n system-upgrade get jobs -o yaml
```
content/k3s/latest/en/upgrades/basic/_index.md
+59
View File
@@ -0,0 +1,59 @@
---
title: "Upgrade Basics"
weight: 10
---
You can upgrade K3s by using the installation script, or by manually installing the binary of the desired version.
>**Note:** When upgrading, upgrade server nodes first one at a time, then any worker nodes.
### Upgrade K3s Using the Installation Script
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 -
```
### Manually Upgrade K3s Using the Binary
Or to manually upgrade K3s:
1. Download the desired version of the K3s binary from [releases](https://github.com/rancher/k3s/releases)
2. Copy the downloaded binary to `/usr/local/bin/k3s` (or your desired location)
3. Stop the old k3s binary
4. Launch the new k3s binary
### Restarting K3s
Restarting K3s is supported by the installation script for systemd and OpenRC.
**systemd**
To restart servers manually:
```sh
sudo systemctl restart k3s
```
To restart agents manually:
```sh
sudo systemctl restart k3s-agent
```
**OpenRC**
To restart servers manually:
```sh
sudo service k3s restart
```
To restart agents mantually:
```sh
sudo service k3s-agent restart
```
content/os/v1.x/en/_index.md
+1 -1
View File
@@ -29,7 +29,7 @@ You can adjust memory requirements by custom building RancherOS, please refer to
### How RancherOS Works ### How RancherOS Works
Everything in RancherOS is a Docker container. We accomplish this by launching two instances of Docker. One is what we call **System Docker** and is the first process on the system. All other system services, like `ntpd`, `syslog`, and `console`, are running in Docker containers. System Docker replaces traditional init systems like `systemd` and is used to launch [additional system services](installation/system-services/adding-system-services/). Everything in RancherOS is a Docker container. We accomplish this by launching two instances of Docker. One is what we call **System Docker** and is the first process on the system. All other system services, like `ntpd`, `syslog`, and `console`, are running in Docker containers. System Docker replaces traditional init systems like `systemd` and is used to launch [additional system services](installation/system-services/).
System Docker runs a special container called **Docker**, which is another Docker daemon responsible for managing all of the user’s containers. Any containers that you launch as a user from the console will run inside this Docker. This creates isolation from the System Docker containers and ensures that normal user commands don’t impact system services. System Docker runs a special container called **Docker**, which is another Docker daemon responsible for managing all of the user’s containers. Any containers that you launch as a user from the console will run inside this Docker. This creates isolation from the System Docker containers and ensures that normal user commands don’t impact system services.
content/os/v1.x/en/about/_index.md
+3 -3
View File
@@ -1,6 +1,6 @@
--- ---
title: About title: Additional Resources
weight: 4 weight: 200
--- ---
## Developing ## Developing
@@ -59,7 +59,7 @@ All of repositories are located within our main GitHub [page](https://github.com
[RancherOS Repo](https://github.com/rancher/os): This repo contains the bulk of the RancherOS code. [RancherOS Repo](https://github.com/rancher/os): This repo contains the bulk of the RancherOS code.
[RancherOS Services Repo](https://github.com/rancher/os-services): This repo is where any [system-services]({{< baseurl >}}/os/v1.x/en//installation/system-services/adding-system-services/) can be contributed. [RancherOS Services Repo](https://github.com/rancher/os-services): This repo is where any [system-services]({{< baseurl >}}/os/v1.x/en//system-services/) can be contributed.
[RancherOS Images Repo](https://github.com/rancher/os-images): This repo is for the corresponding service images. [RancherOS Images Repo](https://github.com/rancher/os-images): This repo is for the corresponding service images.
content/os/v1.x/en/about/running-rancher-on-rancherOS/_index.md
+1 -1
View File
@@ -7,7 +7,7 @@ RancherOS can be used to launch [Rancher](/rancher/) and be used as the OS to ad
### Launching Agents using Cloud-Config ### Launching Agents using Cloud-Config
You can easily add hosts into Rancher by using [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) to launch the rancher/agent container. You can easily add hosts into Rancher by using [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config) to launch the rancher/agent container.
After Rancher is launched and host registration has been saved, you will be able to find use the custom option to add Rancher OS nodes. After Rancher is launched and host registration has been saved, you will be able to find use the custom option to add Rancher OS nodes.
content/os/v1.x/en/installation/configuration/_index.md → content/os/v1.x/en/configuration/_index.md
+3 -1
View File
@@ -1,6 +1,8 @@
--- ---
title: Configuration title: Configuration
weight: 120 weight: 120
aliases:
- /os/v1.x/en/installation/configuration
--- ---
There are two ways that RancherOS can be configured. There are two ways that RancherOS can be configured.
@@ -34,7 +36,7 @@ In our example above, we have our `#cloud-config` line to indicate it's a cloud-
### Manually Changing Configuration ### Manually Changing Configuration
To update RancherOS configuration after booting, the `ros config set <key> <value>` command can be used. To update RancherOS configuration after booting, the `ros config set <key> <value>` command can be used.
For more complicated settings, like the [sysctl settings]({{< baseurl >}}/os/v1.x/en/installation/configuration/sysctl/), you can also create a small YAML file and then run `sudo ros config merge -i <your yaml file>`. For more complicated settings, like the [sysctl settings]({{< baseurl >}}/os/v1.x/en/configuration/sysctl/), you can also create a small YAML file and then run `sudo ros config merge -i <your yaml file>`.
#### Getting Values #### Getting Values
content/os/v1.x/en/installation/configuration/adding-kernel-parameters/_index.md → content/os/v1.x/en/configuration/adding-kernel-parameters/_index.md
+3 -1
View File
@@ -1,6 +1,8 @@
--- ---
title: Kernel boot parameters title: Kernel boot parameters
weight: 133 weight: 133
aliases:
- /os/v1.x/en/installation/configuration/adding-kernel-parameters
--- ---
RancherOS parses the Linux kernel boot cmdline to add any keys it understands to its configuration. This allows you to modify what cloud-init sources it will use on boot, to enable `rancher.debug` logging, or to almost any other configuration setting. RancherOS parses the Linux kernel boot cmdline to add any keys it understands to its configuration. This allows you to modify what cloud-init sources it will use on boot, to enable `rancher.debug` logging, or to almost any other configuration setting.
@@ -27,7 +29,7 @@ $ sudo system-docker run --rm -it -v /:/host alpine vi /host/boot/global.cfg
### During installation ### During installation
If you want to set the extra kernel parameters when you are [Installing RancherOS to Disk]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/server/install-to-disk/) please use the `--append` parameter. If you want to set the extra kernel parameters when you are [Installing RancherOS to Disk]({{< baseurl >}}/os/v1.x/en/installation/server/install-to-disk/) please use the `--append` parameter.
```bash ```bash
$ sudo ros install -d /dev/sda --append "rancheros.autologin=tty1" $ sudo ros install -d /dev/sda --append "rancheros.autologin=tty1"
content/os/v1.x/en/installation/configuration/airgap-configuration/_index.md → content/os/v1.x/en/configuration/airgap-configuration/_index.md
+9 -3
View File
@@ -1,6 +1,8 @@
--- ---
title: Air Gap Configuration title: Air Gap Configuration
weight: 138 weight: 138
aliases:
- /os/v1.x/en/installation/configuration/airgap-configuration
--- ---
In the air gap environment, the Docker registry, RancherOS repositories URL, and the RancherOS upgrade URL should be configured to ensure the OS can pull images, update OS services, and upgrade the OS. In the air gap environment, the Docker registry, RancherOS repositories URL, and the RancherOS upgrade URL should be configured to ensure the OS can pull images, update OS services, and upgrade the OS.
@@ -10,10 +12,10 @@ In the air gap environment, the Docker registry, RancherOS repositories URL, and
You should use a private Docker registry so that `user-docker` and `system-docker` can pull images. You should use a private Docker registry so that `user-docker` and `system-docker` can pull images.
1. Add the private Docker registry domain to the [images prefix]({{< baseurl >}}/os/v1.x/en/installation/configuration/images-prefix/). 1. Add the private Docker registry domain to the [images prefix]({{< baseurl >}}/os/v1.x/en/configuration/images-prefix/).
2. Set the private registry certificates for `user-docker`. For details, refer to [Certificates for Private Registries]({{< baseurl >}}/os/v1.x/en/installation/configuration/private-registries/#certificates-for-private-registries) 2. Set the private registry certificates for `user-docker`. For details, refer to [Certificates for Private Registries]({{< baseurl >}}/os/v1.x/en/configuration/private-registries/#certificates-for-private-registries)
3. Set the private registry certificates for `system-docker`. There are two ways to set the certificates: 3. Set the private registry certificates for `system-docker`. There are two ways to set the certificates:
- To set the private registry certificates before RancherOS starts, you can run a script included with RancherOS. For details, refer to [Set Custom Certs in ISO]({{< baseurl >}}/os/v1.x/en/installation/configuration/airgap-configuration/#set-custom-certs-in-iso). - To set the private registry certificates before RancherOS starts, you can run a script included with RancherOS. For details, refer to [Set Custom Certs in ISO]({{< baseurl >}}/os/v1.x/en/configuration/airgap-configuration/#set-custom-certs-in-iso).
- To set the private registry certificates after RancherOS starts, append your private registry certs to the `/etc/ssl/certs/ca-certificates.crt.rancher` file. Then reboot to make the certs fully take effect. - To set the private registry certificates after RancherOS starts, append your private registry certs to the `/etc/ssl/certs/ca-certificates.crt.rancher` file. Then reboot to make the certs fully take effect.
4. The images used by RancherOS should be pushed to your private registry. 4. The images used by RancherOS should be pushed to your private registry.
@@ -84,7 +86,11 @@ $ sudo ros config set rancher.upgrade.url https://foo.bar.com/os/releases.yml
Here is a total cloud-config example for using RancherOS in an air gap environment. Here is a total cloud-config example for using RancherOS in an air gap environment.
<<<<<<< HEAD:content/os/v1.x/en/installation/configuration/airgap-configuration/_index.md
For `system-docker`, see [Configuring Private Docker Registry]({{<baseurl>}}/os/v1.x/en/installation/configuration/airgap-configuration/#configuring-private-docker-registry). For `system-docker`, see [Configuring Private Docker Registry]({{<baseurl>}}/os/v1.x/en/installation/configuration/airgap-configuration/#configuring-private-docker-registry).
=======
For `system-docker`, see [Configuring Private Docker Registry]({{< baseurl >}}/os/v1.x/en/configuration/airgap-configuration/#configuring-private-docker-registry).
>>>>>>> Reorganize RancherOS docs:content/os/v1.x/en/configuration/airgap-configuration/_index.md
```yaml ```yaml
#cloud-config #cloud-config
content/os/v1.x/en/installation/configuration/date-and-timezone/_index.md → content/os/v1.x/en/configuration/date-and-timezone/_index.md
+3 -1
View File
@@ -1,11 +1,13 @@
--- ---
title: Date and time zone title: Date and time zone
weight: 121 weight: 121
aliases:
- /os/v1.x/en/installation/configuration/date-and-timezone
--- ---
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. 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) 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/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: 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:
content/os/v1.x/en/installation/configuration/disable-access-to-system/_index.md → content/os/v1.x/en/configuration/disable-access-to-system/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Disabling Access to RancherOS title: Disabling Access to RancherOS
weight: 136 weight: 136
aliases:
- /os/v1.x/en/installation/configuration/disable-access-to-system
--- ---
_Available as of v1.5_ _Available as of v1.5_
content/os/v1.x/en/installation/configuration/docker/_index.md → content/os/v1.x/en/configuration/docker/_index.md
+4 -2
View File
@@ -1,9 +1,11 @@
--- ---
title: Configuring Docker or System Docker title: Configuring Docker or System Docker
weight: 126 weight: 126
aliases:
- /os/v1.x/en/installation/configuration/docker
--- ---
In RancherOS, you can configure System Docker and Docker daemons by using [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config). In RancherOS, you can configure System Docker and Docker daemons by using [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config).
### Configuring Docker ### Configuring Docker
@@ -61,7 +63,7 @@ Key | Value | Default | Description
---|---|---| --- ---|---|---| ---
`extra_args` | List of Strings | `[]` | Arbitrary daemon arguments, appended to the generated command `extra_args` | List of Strings | `[]` | Arbitrary daemon arguments, appended to the generated command
`environment` | List of Strings | `[]` | `environment` | List of Strings | `[]` |
`tls` | Boolean | `false` | When [setting up TLS]({{< baseurl >}}/os/v1.x/en/installation/configuration/setting-up-docker-tls/), this key needs to be set to true. `tls` | Boolean | `false` | When [setting up TLS]({{< baseurl >}}/os/v1.x/en/configuration/setting-up-docker-tls/), this key needs to be set to true.
`tls_args` | List of Strings (used only if `tls: true`) | `[]` | `tls_args` | List of Strings (used only if `tls: true`) | `[]` |
`server_key` | String (used only if `tls: true`)| `""` | PEM encoded server TLS key. `server_key` | String (used only if `tls: true`)| `""` | PEM encoded server TLS key.
`server_cert` | String (used only if `tls: true`) | `""` | PEM encoded server TLS certificate. `server_cert` | String (used only if `tls: true`) | `""` | PEM encoded server TLS certificate.
content/os/v1.x/en/installation/configuration/hostname/_index.md → content/os/v1.x/en/configuration/hostname/_index.md
+3 -1
View File
@@ -1,9 +1,11 @@
--- ---
title: Setting the Hostname title: Setting the Hostname
weight: 124 weight: 124
aliases:
- /os/v1.x/en/installation/configuration/hostname
--- ---
You can set the hostname of the host using [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config). The example below shows how to configure it. You can set the hostname of the host using [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config). The example below shows how to configure it.
```yaml ```yaml
#cloud-config #cloud-config
content/os/v1.x/en/installation/configuration/images-prefix/_index.md → content/os/v1.x/en/configuration/images-prefix/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Images prefix title: Images prefix
weight: 121 weight: 121
aliases:
- /os/v1.x/en/installation/configuration/images-prefix
--- ---
_Available as of v1.3_ _Available as of v1.3_
content/os/v1.x/en/installation/configuration/kernel-modules-kernel-headers/_index.md → content/os/v1.x/en/configuration/kernel-modules-kernel-headers/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Installing Kernel Modules that require Kernel Headers title: Installing Kernel Modules that require Kernel Headers
weight: 135 weight: 135
aliases:
- /os/v1.x/en/installation/configuration/kernel-modules-kernel-headers
--- ---
To compile any kernel modules, you will need to download the kernel headers. The kernel headers are available in the form of a system service. Since the kernel headers are a system service, they need to be enabled using the `ros service` command. To compile any kernel modules, you will need to download the kernel headers. The kernel headers are available in the form of a system service. Since the kernel headers are a system service, they need to be enabled using the `ros service` command.
content/os/v1.x/en/installation/configuration/loading-kernel-modules/_index.md → content/os/v1.x/en/configuration/loading-kernel-modules/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Loading Kernel Modules title: Loading Kernel Modules
weight: 134 weight: 134
aliases:
- /os/v1.x/en/installation/configuration/loading-kernel-modules
--- ---
Since RancherOS v0.8, we build our own kernels using an unmodified kernel.org LTS kernel. Since RancherOS v0.8, we build our own kernels using an unmodified kernel.org LTS kernel.
content/os/v1.x/en/installation/configuration/private-registries/_index.md → content/os/v1.x/en/configuration/private-registries/_index.md
+4 -2
View File
@@ -1,9 +1,11 @@
--- ---
title: Private Registries title: Private Registries
weight: 128 weight: 128
aliases:
- /os/v1.x/en/installation/configuration/private-registries
--- ---
When launching services through a [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config), it is sometimes necessary to pull a private image from DockerHub or from a private registry. Authentication for these can be embedded in your cloud-config. When launching services through a [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config), it is sometimes necessary to pull a private image from DockerHub or from a private registry. Authentication for these can be embedded in your cloud-config.
For example, to add authentication for DockerHub: For example, to add authentication for DockerHub:
@@ -61,7 +63,7 @@ write_files:
### Certificates for Private Registries ### Certificates for Private Registries
Certificates can be stored in the standard locations (i.e. `/etc/docker/certs.d`) following the [Docker documentation](https://docs.docker.com/registry/insecure). By using the `write_files` directive of the [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config), the certificates can be written directly into `/etc/docker/certs.d`. Certificates can be stored in the standard locations (i.e. `/etc/docker/certs.d`) following the [Docker documentation](https://docs.docker.com/registry/insecure). By using the `write_files` directive of the [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config), the certificates can be written directly into `/etc/docker/certs.d`.
```yaml ```yaml
#cloud-config #cloud-config
content/os/v1.x/en/installation/configuration/resizing-device-partition/_index.md → content/os/v1.x/en/configuration/resizing-device-partition/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Resizing a Device Partition title: Resizing a Device Partition
weight: 131 weight: 131
aliases:
- /os/v1.x/en/installation/configuration/resizing-device-partition
--- ---
The `resize_device` cloud config option can be used to automatically extend the first partition (assuming its `ext4`) to fill the size of it's device. The `resize_device` cloud config option can be used to automatically extend the first partition (assuming its `ext4`) to fill the size of it's device.
content/os/v1.x/en/installation/configuration/running-commands/_index.md → content/os/v1.x/en/configuration/running-commands/_index.md
+3 -1
View File
@@ -1,6 +1,8 @@
--- ---
title: Running Commands title: Running Commands
weight: 123 weight: 123
aliases:
- /os/v1.x/en/installation/configuration/running-commands
--- ---
You can automate running commands on boot using the `runcmd` cloud-config directive. Commands can be specified as either a list or a string. In the latter case, the command is executed with `sh`. You can automate running commands on boot using the `runcmd` cloud-config directive. Commands can be specified as either a list or a string. In the latter case, the command is executed with `sh`.
@@ -31,4 +33,4 @@ write_files:
docker run -d nginx docker run -d nginx
``` ```
Running Docker commands in this manner is useful when pieces of the `docker run` command are dynamically generated. For services whose configuration is static, [adding a system service]({{< baseurl >}}/os/v1.x/en/installation/system-services/adding-system-services/) is recommended. Running Docker commands in this manner is useful when pieces of the `docker run` command are dynamically generated. For services whose configuration is static, [adding a system service]({{< baseurl >}}/os/v1.x/en/system-services/) is recommended.
content/os/v1.x/en/installation/configuration/setting-up-docker-tls/_index.md → content/os/v1.x/en/configuration/setting-up-docker-tls/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Setting up Docker TLS title: Setting up Docker TLS
weight: 127 weight: 127
aliases:
- /os/v1.x/en/installation/configuration/setting-up-docker-tls
--- ---
`ros tls generate` is used to generate both the client and server TLS certificates for Docker. `ros tls generate` is used to generate both the client and server TLS certificates for Docker.
content/os/v1.x/en/installation/configuration/ssh-keys/_index.md → content/os/v1.x/en/configuration/ssh-keys/_index.md
+3 -1
View File
@@ -1,9 +1,11 @@
--- ---
title: SSH Settings title: SSH Settings
weight: 121 weight: 121
aliases:
- /os/v1.x/en/installation/configuration/ssh-keys
--- ---
RancherOS supports adding SSH keys through the [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) file. Within the cloud-config file, you simply add the ssh keys within the `ssh_authorized_keys` key. RancherOS supports adding SSH keys through the [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config) file. Within the cloud-config file, you simply add the ssh keys within the `ssh_authorized_keys` key.
```yaml ```yaml
#cloud-config #cloud-config
content/os/v1.x/en/installation/configuration/switching-consoles/_index.md → content/os/v1.x/en/configuration/switching-consoles/_index.md
+12
View File
@@ -1,8 +1,11 @@
--- ---
title: Switching Consoles title: Switching Consoles
weight: 125 weight: 125
aliases:
- /os/v1.x/en/installation/configuration/switching-consoles
--- ---
<<<<<<< HEAD:content/os/v1.x/en/installation/configuration/switching-consoles/_index.md
When [booting from the ISO]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso/), RancherOS starts with the default console, which is based on busybox. When [booting from the ISO]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso/), RancherOS starts with the default console, which is based on busybox.
You can select which console you want RancherOS to start with using the [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config). You can select which console you want RancherOS to start with using the [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config).
@@ -10,6 +13,15 @@ You can select which console you want RancherOS to start with using the [cloud-c
### Enabling Consoles using Cloud-Config ### Enabling Consoles using Cloud-Config
When launching RancherOS with a [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) file, you can select which console you want to use. When launching RancherOS with a [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) file, you can select which console you want to use.
=======
When [booting from the ISO]({{< baseurl >}}/os/v1.x/en/installation/workstation//boot-from-iso/), RancherOS starts with the default console, which is based on busybox.
You can select which console you want RancherOS to start with using the [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config).
### Enabling Consoles using Cloud-Config
When launching RancherOS with a [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config) file, you can select which console you want to use.
>>>>>>> Reorganize RancherOS docs:content/os/v1.x/en/configuration/switching-consoles/_index.md
Currently, the list of available consoles are: Currently, the list of available consoles are:
content/os/v1.x/en/installation/configuration/switching-docker-versions/_index.md → content/os/v1.x/en/configuration/switching-docker-versions/_index.md
+10
View File
@@ -1,9 +1,15 @@
--- ---
title: Switching Docker Versions title: Switching Docker Versions
weight: 129 weight: 129
aliases:
- /os/v1.x/en/installation/configuration/switching-docker-versions
--- ---
<<<<<<< HEAD:content/os/v1.x/en/installation/configuration/switching-docker-versions/_index.md
The version of User Docker used in RancherOS can be configured using a [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) file or by using the `ros engine` command. The version of User Docker used in RancherOS can be configured using a [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) file or by using the `ros engine` command.
=======
The version of User Docker used in RancherOS can be configured using a [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config) file or by using the `ros engine` command.
>>>>>>> Reorganize RancherOS docs:content/os/v1.x/en/configuration/switching-docker-versions/_index.md
> **Note:** There are known issues in Docker when switching between versions. For production systems, we recommend setting the Docker engine only once [using a cloud-config](#setting-the-docker-engine-using-cloud-config). > **Note:** There are known issues in Docker when switching between versions. For production systems, we recommend setting the Docker engine only once [using a cloud-config](#setting-the-docker-engine-using-cloud-config).
@@ -83,7 +89,11 @@ FROM scratch
COPY engine /engine COPY engine /engine
``` ```
<<<<<<< HEAD:content/os/v1.x/en/installation/configuration/switching-docker-versions/_index.md
Once the image is built a [system service]({{<baseurl>}}/os/v1.x/en/installation/system-services/adding-system-services/) configuration file must be created. An [example file](https://github.com/rancher/os-services/blob/master/d/docker-18.06.3-ce.yml) can be found in the rancher/os-services repo. Change the `image` field to point to the Docker engine image you've built. Once the image is built a [system service]({{<baseurl>}}/os/v1.x/en/installation/system-services/adding-system-services/) configuration file must be created. An [example file](https://github.com/rancher/os-services/blob/master/d/docker-18.06.3-ce.yml) can be found in the rancher/os-services repo. Change the `image` field to point to the Docker engine image you've built.
=======
Once the image is built a [system service]({{< baseurl >}}/os/v1.x/en/system-services/) configuration file must be created. An [example file](https://github.com/rancher/os-services/blob/master/d/docker-18.06.3-ce.yml) can be found in the rancher/os-services repo. Change the `image` field to point to the Docker engine image you've built.
>>>>>>> Reorganize RancherOS docs:content/os/v1.x/en/configuration/switching-docker-versions/_index.md
All of the previously mentioned methods of switching Docker engines are now available. For example, if your service file is located at `https://myservicefile` then the following cloud-config file could be used to use your custom Docker engine. All of the previously mentioned methods of switching Docker engines are now available. For example, if your service file is located at `https://myservicefile` then the following cloud-config file could be used to use your custom Docker engine.
content/os/v1.x/en/installation/configuration/sysctl/_index.md → content/os/v1.x/en/configuration/sysctl/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Sysctl Settings title: Sysctl Settings
weight: 132 weight: 132
aliases:
- /os/v1.x/en/installation/configuration/sysctl
--- ---
The `rancher.sysctl` cloud-config key can be used to control sysctl parameters. This works in a manner similar to `/etc/sysctl.conf` for other Linux distros. The `rancher.sysctl` cloud-config key can be used to control sysctl parameters. This works in a manner similar to `/etc/sysctl.conf` for other Linux distros.
content/os/v1.x/en/installation/configuration/users/_index.md → content/os/v1.x/en/configuration/users/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Users title: Users
weight: 130 weight: 130
aliases:
- /os/v1.x/en/installation/configuration/users
--- ---
Currently, we don't support adding other users besides `rancher`. Currently, we don't support adding other users besides `rancher`.
content/os/v1.x/en/installation/configuration/write-files/_index.md → content/os/v1.x/en/configuration/write-files/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Writing Files title: Writing Files
weight: 122 weight: 122
aliases:
- /os/v1.x/en/installation/configuration/write-files
--- ---
You can automate writing files to disk using the `write_files` cloud-config directive. You can automate writing files to disk using the `write_files` cloud-config directive.
content/os/v1.x/en/installation/_index.md
+32 -2
View File
@@ -1,4 +1,34 @@
--- ---
title: Installation title: Installing and Running RancherOS
weight: 2 weight: 100
aliases:
- /os/v1.x/en/installation/running-rancheros
--- ---
RancherOS runs on virtualization platforms, cloud providers and bare metal servers. We also support running a local VM on your laptop.
To start running RancherOS as quickly as possible, follow our [Quick Start Guide]({{< baseurl >}}/os/v1.x/en/quick-start-guide/).
# Platforms
Refer to the below resources for more information on installing Rancher on your platform.
### Workstation
- [Docker Machine]({{< baseurl >}}/os/v1.x/en/installation/workstation//docker-machine)
- [Boot from ISO]({{< baseurl >}}/os/v1.x/en/installation/workstation//boot-from-iso)
### Cloud
- [Amazon EC2]({{< baseurl >}}/os/v1.x/en/installation/cloud/aws)
- [Google Compute Engine]({{< baseurl >}}/os/v1.x/en/installation/cloud/gce)
- [DigitalOcean]({{< baseurl >}}/os/v1.x/en/installation/cloud/do)
- [Azure]({{< baseurl >}}/os/v1.x/en/installation/cloud/azure)
- [OpenStack]({{< baseurl >}}/os/v1.x/en/installation/cloud/openstack)
- [VMware ESXi]({{< baseurl >}}/os/v1.x/en/installation/cloud/vmware-esxi)
- [Aliyun]({{< baseurl >}}/os/v1.x/en/installation/cloud/aliyun)
### Bare Metal & Virtual Servers
- [PXE]({{< baseurl >}}/os/v1.x/en/installation/server/pxe)
- [Install to Hard Disk]({{< baseurl >}}/os/v1.x/en/installation/server/install-to-disk)
- [Raspberry Pi]({{< baseurl >}}/os/v1.x/en/installation/server/raspberry-pi)
content/os/v1.x/en/installation/amazon-ecs/_index.md
+3 -3
View File
@@ -11,13 +11,13 @@ Prior to launching RancherOS EC2 instances, the [ECS Container Instance IAM Role
### Launching an instance with ECS ### Launching an instance with ECS
RancherOS makes it easy to join your ECS cluster. The ECS agent is a [system service]({{< baseurl >}}/os/v1.x/en/installation/system-services/adding-system-services/) that is enabled in the ECS enabled AMI. There may be other RancherOS AMIs that don't have the ECS agent enabled by default, but it can easily be added in the user data on any RancherOS AMI. RancherOS makes it easy to join your ECS cluster. The ECS agent is a [system service]({{< baseurl >}}/os/v1.x/en/system-services/) that is enabled in the ECS enabled AMI. There may be other RancherOS AMIs that don't have the ECS agent enabled by default, but it can easily be added in the user data on any RancherOS AMI.
When launching the RancherOS AMI, you'll need to specify the **IAM Role** and **Advanced Details** -> **User Data** in the **Configure Instance Details** step. When launching the RancherOS AMI, you'll need to specify the **IAM Role** and **Advanced Details** -> **User Data** in the **Configure Instance Details** step.
For the **IAM Role**, you'll need to be sure to select the ECS Container Instance IAM role. For the **IAM Role**, you'll need to be sure to select the ECS Container Instance IAM role.
For the **User Data**, you'll need to pass in the [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) file. For the **User Data**, you'll need to pass in the [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config) file.
```yaml ```yaml
#cloud-config #cloud-config
@@ -37,7 +37,7 @@ rancher:
By default, the ECS agent will be using the `latest` tag for the `amazon-ecs-agent` image. In v0.5.0, we introduced the ability to select which version of the `amazon-ecs-agent`. By default, the ECS agent will be using the `latest` tag for the `amazon-ecs-agent` image. In v0.5.0, we introduced the ability to select which version of the `amazon-ecs-agent`.
To select the version, you can update your [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) file. To select the version, you can update your [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config) file.
```yaml ```yaml
#cloud-config #cloud-config
content/os/v1.x/en/installation/boot-process/built-in-system-services/_index.md
+8 -8
View File
@@ -3,7 +3,7 @@ title: Built-in System Services
weight: 150 weight: 150
--- ---
To launch RancherOS, we have built-in system services. They are defined in the [Docker Compose](https://docs.docker.com/compose/compose-file/) format, and can be found in the default system config file, `/usr/share/ros/os-config.yml`. You can [add your own system services]({{< baseurl >}}/os/v1.x/en/installation/system-services/adding-system-services/) or override services in the cloud-config. To launch RancherOS, we have built-in system services. They are defined in the [Docker Compose](https://docs.docker.com/compose/compose-file/) format, and can be found in the default system config file, `/usr/share/ros/os-config.yml`. You can [add your own system services]({{< baseurl >}}/os/v1.x/en/system-services/) or override services in the cloud-config.
### preload-user-images ### preload-user-images
@@ -13,7 +13,7 @@ Read more about [image preloading]({{< baseurl >}}/os/v1.x/en/installation/boot-
During this service, networking is set up, e.g. hostname, interfaces, and DNS. During this service, networking is set up, e.g. hostname, interfaces, and DNS.
It is configured by `hostname` and `rancher.network`settings in [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config). It is configured by `hostname` and `rancher.network`settings in [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config).
### ntp ### ntp
@@ -24,13 +24,13 @@ Runs `ntpd` in a System Docker container.
This service provides the RancherOS user interface by running `sshd` and `getty`. It completes the RancherOS configuration on start up: This service provides the RancherOS user interface by running `sshd` and `getty`. It completes the RancherOS configuration on start up:
1. If the `rancher.password=<password>` kernel parameter exists, it sets `<password>` as the password for the `rancher` user. 1. If the `rancher.password=<password>` kernel parameter exists, it sets `<password>` as the password for the `rancher` user.
2. If there are no host SSH keys, it generates host SSH keys and saves them under `rancher.ssh.keys` in [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config). 2. If there are no host SSH keys, it generates host SSH keys and saves them under `rancher.ssh.keys` in [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config).
3. Runs `cloud-init -execute`, which does the following: 3. Runs `cloud-init -execute`, which does the following:
* Updates `.ssh/authorized_keys` in `/home/rancher` and `/home/docker` from [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/ssh-keys/) and metadata. * Updates `.ssh/authorized_keys` in `/home/rancher` and `/home/docker` from [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/ssh-keys/) and metadata.
* Writes files specified by the `write_files` [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/write-files/) setting. * Writes files specified by the `write_files` [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/write-files/) setting.
* Resizes the device specified by the `rancher.resize_device` [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/resizing-device-partition/) setting. * Resizes the device specified by the `rancher.resize_device` [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/resizing-device-partition/) setting.
* Mount devices specified in the `mounts` [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/storage/additional-mounts/) setting. * Mount devices specified in the `mounts` [cloud-config]({{< baseurl >}}/os/v1.x/en/storage/additional-mounts/) setting.
* Set sysctl parameters specified in the`rancher.sysctl` [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/sysctl/) setting. * Set sysctl parameters specified in the`rancher.sysctl` [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/sysctl/) setting.
4. If user-data contained a file that started with `#!`, then a file would be saved at `/var/lib/rancher/conf/cloud-config-script` during cloud-init and then executed. Any errors are ignored. 4. If user-data contained a file that started with `#!`, then a file would be saved at `/var/lib/rancher/conf/cloud-config-script` during cloud-init and then executed. Any errors are ignored.
5. Runs `/opt/rancher/bin/start.sh` if it exists and is executable. Any errors are ignored. 5. Runs `/opt/rancher/bin/start.sh` if it exists and is executable. Any errors are ignored.
6. Runs `/etc/rc.local` if it exists and is executable. Any errors are ignored. 6. Runs `/etc/rc.local` if it exists and is executable. Any errors are ignored.
content/os/v1.x/en/installation/boot-process/cloud-init/_index.md
+2 -2
View File
@@ -7,7 +7,7 @@ Userdata and metadata can be fetched from a cloud provider, VM runtime, or manag
### Userdata ### Userdata
Userdata is a file given by users when launching RancherOS hosts. It is stored in different locations depending on its format. If the userdata is a [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) file, indicated by beginning with `#cloud-config` and being in YAML format, it is stored in `/var/lib/rancher/conf/cloud-config.d/boot.yml`. If the userdata is a script, indicated by beginning with `#!`, it is stored in `/var/lib/rancher/conf/cloud-config-script`. Userdata is a file given by users when launching RancherOS hosts. It is stored in different locations depending on its format. If the userdata is a [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config) file, indicated by beginning with `#cloud-config` and being in YAML format, it is stored in `/var/lib/rancher/conf/cloud-config.d/boot.yml`. If the userdata is a script, indicated by beginning with `#!`, it is stored in `/var/lib/rancher/conf/cloud-config-script`.
### Metadata ### Metadata
@@ -15,7 +15,7 @@ Although the specifics vary based on provider, a metadata file will typically co
## Configuration Load Order ## Configuration Load Order
[Cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config/) is read by system services when they need to get configuration. Each additional file overwrites and extends the previous configuration file. [Cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config/) is read by system services when they need to get configuration. Each additional file overwrites and extends the previous configuration file.
1. `/usr/share/ros/os-config.yml` - This is the system default configuration, which should **not** be modified by users. 1. `/usr/share/ros/os-config.yml` - This is the system default configuration, which should **not** be modified by users.
2. `/usr/share/ros/oem/oem-config.yml` - This will typically exist by OEM, which should **not** be modified by users. 2. `/usr/share/ros/oem/oem-config.yml` - This will typically exist by OEM, which should **not** be modified by users.
content/os/v1.x/en/installation/running-rancheros/cloud/aliyun/_index.md → content/os/v1.x/en/installation/cloud/aliyun/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Aliyun title: Aliyun
weight: 111 weight: 111
aliases:
- /os/v1.x/en/installation/running-rancheros/cloud/aliyun
--- ---
# Adding the RancherOS Image into Aliyun # Adding the RancherOS Image into Aliyun
content/os/v1.x/en/installation/running-rancheros/cloud/aws/_index.md → content/os/v1.x/en/installation/cloud/aws/_index.md
+6
View File
@@ -1,6 +1,8 @@
--- ---
title: Amazon EC2 title: Amazon EC2
weight: 105 weight: 105
aliases:
- /os/v1.x/en/installation/running-rancheros/cloud/aws
--- ---
RancherOS is available as an Amazon Web Services AMI, and can be easily run on EC2. You can launch RancherOS either using the AWS Command Line Interface (CLI) or using the AWS console. RancherOS is available as an Amazon Web Services AMI, and can be easily run on EC2. You can launch RancherOS either using the AWS Command Line Interface (CLI) or using the AWS console.
@@ -28,7 +30,11 @@ Let’s walk through how to import and create a RancherOS on EC2 machine using t
{{< img "/img/os/Rancher_aws1.png" "RancherOS on AWS 1">}} {{< 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**. 2. Select the **Community AMIs** on the sidebar and search for **RancherOS**. Pick the latest version and click **Select**.
{{< img "/img/os/Rancher_aws2.png" "RancherOS on AWS 2">}} {{< img "/img/os/Rancher_aws2.png" "RancherOS on AWS 2">}}
<<<<<<< HEAD:content/os/v1.x/en/installation/running-rancheros/cloud/aws/_index.md
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. 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.
=======
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/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.
>>>>>>> Reorganize RancherOS docs:content/os/v1.x/en/installation/cloud/aws/_index.md
{{< img "/img/os/Rancher_aws6.png" "RancherOS on AWS 6">}} {{< 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**. 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**.
{{< img "/img/os/Rancher_aws3.png" "RancherOS on AWS 3">}} {{< img "/img/os/Rancher_aws3.png" "RancherOS on AWS 3">}}
content/os/v1.x/en/installation/running-rancheros/cloud/azure/_index.md → content/os/v1.x/en/installation/cloud/azure/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Azure title: Azure
weight: 110 weight: 110
aliases:
- /os/v1.x/en/installation/running-rancheros/cloud/azure
--- ---
RancherOS has been published in Azure Marketplace, you can get it from [here](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/rancher.rancheros). RancherOS has been published in Azure Marketplace, you can get it from [here](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/rancher.rancheros).
content/os/v1.x/en/installation/running-rancheros/cloud/do/_index.md → content/os/v1.x/en/installation/cloud/do/_index.md
+3 -1
View File
@@ -1,6 +1,8 @@
--- ---
title: Digital Ocean title: Digital Ocean
weight: 107 weight: 107
aliases:
- /os/v1.x/en/installation/running-rancheros/cloud/do
--- ---
RancherOS is available in the Digital Ocean portal. RancherOS is a member of container distributions and you can find it easily. RancherOS is available in the Digital Ocean portal. RancherOS is a member of container distributions and you can find it easily.
@@ -15,7 +17,7 @@ To start a RancherOS Droplet on Digital Ocean:
1. Click **Create Droplet.** 1. Click **Create Droplet.**
1. Click the **Container distributions** tab. 1. Click the **Container distributions** tab.
1. Click **RancherOS.** 1. Click **RancherOS.**
1. Choose a plan. Make sure your Droplet has the [minimum hardware requirements for RancherOS]({{< baseurl >}}os/v1.x/en/overview/#hardware-requirements). 1. Choose a plan. Make sure your Droplet has the [minimum hardware requirements for RancherOS]({{<baseurl>}}/os/v1.x/en/overview/#hardware-requirements).
1. Choose any options for backups, block storage, and datacenter region. 1. Choose any options for backups, block storage, and datacenter region.
1. Optional: In the **Select additional options** section, you can check the **User data** box and enter a `cloud-config` file in the text box that appears. The `cloud-config` file is used to provide a script to be run on the first boot. An example is below. 1. Optional: In the **Select additional options** section, you can check the **User data** box and enter a `cloud-config` file in the text box that appears. The `cloud-config` file is used to provide a script to be run on the first boot. An example is below.
1. Choose an SSH key that you have access to, or generate a new SSH key. 1. Choose an SSH key that you have access to, or generate a new SSH key.
content/os/v1.x/en/installation/running-rancheros/cloud/gce/_index.md → content/os/v1.x/en/installation/cloud/gce/_index.md
+4 -2
View File
@@ -1,9 +1,11 @@
--- ---
title: Google Compute Engine (GCE) title: Google Compute Engine (GCE)
weight: 106 weight: 106
aliases:
- /os/v1.x/en/installation/running-rancheros/cloud/gce
--- ---
> **Note:** Due to the maximum transmission unit (MTU) of [1460 bytes on GCE](https://cloud.google.com/compute/docs/troubleshooting#packetfragmentation), you will need to configure your [network interfaces]({{< baseurl >}}/os/v1.x/en/installation/networking/interfaces/) and both the [Docker and System Docker]({{< baseurl >}}/os/v1.x/en/installation/configuration/docker/) to use a MTU of 1460 bytes or you will encounter weird networking related errors. > **Note:** Due to the maximum transmission unit (MTU) of [1460 bytes on GCE](https://cloud.google.com/compute/docs/troubleshooting#packetfragmentation), you will need to configure your [network interfaces]({{< baseurl >}}/os/v1.x/en/networking/interfaces/) and both the [Docker and System Docker]({{< baseurl >}}/os/v1.x/en/configuration/docker/) to use a MTU of 1460 bytes or you will encounter weird networking related errors.
### Adding the RancherOS Image into GCE ### Adding the RancherOS Image into GCE
@@ -26,7 +28,7 @@ $ gcloud compute instances create --project <PROJECT_ID> --zone <ZONE_TO_CREATE_
### Using a Cloud Config File with GCE ### Using a Cloud Config File with GCE
If you want to pass in your own cloud config file that will be processed by [cloud init]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config), you can pass it as metadata upon creation of the instance during the `gcloud compute` command. The file will need to be stored locally before running the command. The key of the metadata will be `user-data` and the value is the location of the file. If any SSH keys are added in the cloud config file, it will also be added to the **rancher** user. If you want to pass in your own cloud config file that will be processed by [cloud init]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config), you can pass it as metadata upon creation of the instance during the `gcloud compute` command. The file will need to be stored locally before running the command. The key of the metadata will be `user-data` and the value is the location of the file. If any SSH keys are added in the cloud config file, it will also be added to the **rancher** user.
``` ```
$ gcloud compute instances create --project <PROJECT_ID> --zone <ZONE_TO_CREATE_INSTANCE> <INSTANCE_NAME> --image <PRIVATE_IMAGE_NAME> --metadata-from-file user-data=/Directory/of/Cloud_Config.yml $ gcloud compute instances create --project <PROJECT_ID> --zone <ZONE_TO_CREATE_INSTANCE> <INSTANCE_NAME> --image <PRIVATE_IMAGE_NAME> --metadata-from-file user-data=/Directory/of/Cloud_Config.yml
content/os/v1.x/en/installation/running-rancheros/cloud/openstack/_index.md → content/os/v1.x/en/installation/cloud/openstack/_index.md
+3 -1
View File
@@ -1,8 +1,10 @@
--- ---
title: OpenStack title: OpenStack
weight: 109 weight: 109
aliases:
- /os/v1.x/en/installation/running-rancheros/cloud/openstack
--- ---
As of v0.5.0, RancherOS releases include an Openstack image that can be found on our [releases page](https://github.com/rancher/os/releases). The image format is [QCOW3](https://wiki.qemu.org/Features/Qcow3#Fully_QCOW2_backwards-compatible_feature_set) that is backward compatible with QCOW2. As of v0.5.0, RancherOS releases include an Openstack image that can be found on our [releases page](https://github.com/rancher/os/releases). The image format is [QCOW3](https://wiki.qemu.org/Features/Qcow3#Fully_QCOW2_backwards-compatible_feature_set) that is backward compatible with QCOW2.
When launching an instance using the image, you must enable **Advanced Options** -> **Configuration Drive** and in order to use a [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config) file. When launching an instance using the image, you must enable **Advanced Options** -> **Configuration Drive** and in order to use a [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config) file.
content/os/v1.x/en/installation/running-rancheros/cloud/vmware-esxi/_index.md → content/os/v1.x/en/installation/cloud/vmware-esxi/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: VMware ESXi title: VMware ESXi
weight: 108 weight: 108
aliases:
- /os/v1.x/en/installation/running-rancheros/cloud/vmware-esxi
--- ---
As of v1.1.0, RancherOS automatically detects that it is running on VMware ESXi, and automatically adds the `open-vm-tools` service to be downloaded and started, and uses `guestinfo` keys to set the cloud-init data. As of v1.1.0, RancherOS automatically detects that it is running on VMware ESXi, and automatically adds the `open-vm-tools` service to be downloaded and started, and uses `guestinfo` keys to set the cloud-init data.
content/os/v1.x/en/installation/custom-builds/custom-console/_index.md
+10
View File
@@ -3,6 +3,7 @@ title: Custom Console
weight: 180 weight: 180
--- ---
<<<<<<< HEAD
When [booting from the ISO]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso/), RancherOS starts with the default console, which is based on busybox. When [booting from the ISO]({{<baseurl>}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso/), RancherOS starts with the default console, which is based on busybox.
You can select which console you want RancherOS to start with using the [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config). You can select which console you want RancherOS to start with using the [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config).
@@ -10,6 +11,15 @@ You can select which console you want RancherOS to start with using the [cloud-c
### Enabling Consoles using Cloud-Config ### Enabling Consoles using Cloud-Config
When launching RancherOS with a [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) file, you can select which console you want to use. When launching RancherOS with a [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config) file, you can select which console you want to use.
=======
When [booting from the ISO]({{< baseurl >}}/os/v1.x/en/installation/workstation//boot-from-iso/), RancherOS starts with the default console, which is based on busybox.
You can select which console you want RancherOS to start with using the [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config).
### Enabling Consoles using Cloud-Config
When launching RancherOS with a [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config) file, you can select which console you want to use.
>>>>>>> Reorganize RancherOS docs
Currently, the list of available consoles are: Currently, the list of available consoles are:
content/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/_index.md
+1 -1
View File
@@ -29,7 +29,7 @@ If you need a compressed ISO, you can run this command:
$ make release $ make release
``` ```
The `rancheros.iso` is ready to be used to [boot RancherOS from ISO]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso/) or [launch RancherOS using Docker Machine]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/docker-machine). The `rancheros.iso` is ready to be used to [boot RancherOS from ISO]({{< baseurl >}}/os/v1.x/en/installation/workstation//boot-from-iso/) or [launch RancherOS using Docker Machine]({{< baseurl >}}/os/v1.x/en/installation/workstation//docker-machine).
## Creating a GCE Image Archive ## Creating a GCE Image Archive
content/os/v1.x/en/installation/running-rancheros/server/install-to-disk/_index.md → content/os/v1.x/en/installation/server/install-to-disk/_index.md
+5 -3
View File
@@ -1,9 +1,11 @@
--- ---
title: Installing to Disk title: Installing to Disk
weight: 111 weight: 111
aliases:
- /os/v1.x/en/installation/running-rancheros/server/install-to-disk
--- ---
RancherOS comes with a simple installer that will install RancherOS on a given target disk. To install RancherOS on a new disk, you can use the `ros install` command. Before installing, you'll need to have already [booted RancherOS from ISO]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso). Please be sure to pick the `rancheros.iso` from our release [page](https://github.com/rancher/os/releases). RancherOS comes with a simple installer that will install RancherOS on a given target disk. To install RancherOS on a new disk, you can use the `ros install` command. Before installing, you'll need to have already [booted RancherOS from ISO]({{< baseurl >}}/os/v1.x/en/installation/workstation//boot-from-iso). Please be sure to pick the `rancheros.iso` from our release [page](https://github.com/rancher/os/releases).
### Using `ros install` to Install RancherOS ### Using `ros install` to Install RancherOS
@@ -11,7 +13,7 @@ The `ros install` command orchestrates the installation from the `rancher/os` co
#### Cloud-Config #### Cloud-Config
The easiest way to log in is to pass a `cloud-config.yml` file containing your public SSH keys. To learn more about what's supported in our cloud-config, please read our [documentation]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config). The easiest way to log in is to pass a `cloud-config.yml` file containing your public SSH keys. To learn more about what's supported in our cloud-config, please read our [documentation]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config).
The `ros install` command will process your `cloud-config.yml` file specified with the `-c` flag. This file will also be placed onto the disk and installed to `/var/lib/rancher/conf/`. It will be evaluated on every boot. The `ros install` command will process your `cloud-config.yml` file specified with the `-c` flag. This file will also be placed onto the disk and installed to `/var/lib/rancher/conf/`. It will be evaluated on every boot.
@@ -61,7 +63,7 @@ Status: Downloaded newer image for rancher/os:v0.5.0
Continue with reboot [y/N]: Continue with reboot [y/N]:
``` ```
After installing RancherOS to disk, you will no longer be automatically logged in as the `rancher` user. You'll need to have added in SSH keys within your [cloud-config file]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config). After installing RancherOS to disk, you will no longer be automatically logged in as the `rancher` user. You'll need to have added in SSH keys within your [cloud-config file]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config).
#### Installing a Different Version #### Installing a Different Version
content/os/v1.x/en/installation/running-rancheros/server/pxe/_index.md → content/os/v1.x/en/installation/server/pxe/_index.md
+4 -2
View File
@@ -1,6 +1,8 @@
--- ---
title: iPXE title: iPXE
weight: 112 weight: 112
aliases:
- /os/v1.x/en/installation/running-rancheros/server/pxe
--- ---
``` ```
@@ -63,11 +65,11 @@ Valid cloud-init datasources for RancherOS.
| cmdline | Kernel command line: `cloud-config-url=http://link/user_data` | | cmdline | Kernel command line: `cloud-config-url=http://link/user_data` |
| configdrive | /media/config-2 | | configdrive | /media/config-2 |
| url | URL address | | url | URL address |
| vmware| Set `guestinfo` cloud-init or interface data as per [VMware ESXi]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/cloud/vmware-esxi) | | vmware| Set `guestinfo` cloud-init or interface data as per [VMware ESXi]({{< baseurl >}}/os/v1.x/en/installation/cloud/vmware-esxi) |
| * | This will add ["configdrive", "vmware", "ec2", "digitalocean", "packet", "gce"] into the list of datasources to try | | * | This will add ["configdrive", "vmware", "ec2", "digitalocean", "packet", "gce"] into the list of datasources to try |
The vmware datasource was added as of v1.1. The vmware datasource was added as of v1.1.
### Cloud-Config ### Cloud-Config
When booting via iPXE, RancherOS can be configured using a [cloud-config file]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config). When booting via iPXE, RancherOS can be configured using a [cloud-config file]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config).
content/os/v1.x/en/installation/running-rancheros/server/raspberry-pi/_index.md → content/os/v1.x/en/installation/server/raspberry-pi/_index.md
+3 -1
View File
@@ -1,11 +1,13 @@
--- ---
title: Raspberry Pi title: Raspberry Pi
weight: 113 weight: 113
aliases:
- /os/v1.x/en/installation/running-rancheros/server/raspberry-pi
--- ---
As of v0.5.0, RancherOS releases include a Raspberry Pi image that can be found on our [releases page](https://github.com/rancher/os/releases). The official Raspberry Pi documentation contains instructions on how to [install operating system images](https://www.raspberrypi.org/documentation/installation/installing-images/). As of v0.5.0, RancherOS releases include a Raspberry Pi image that can be found on our [releases page](https://github.com/rancher/os/releases). The official Raspberry Pi documentation contains instructions on how to [install operating system images](https://www.raspberrypi.org/documentation/installation/installing-images/).
When installing, there is no ability to pass in a [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config). You will need to boot up, change the configuration and then reboot to apply those changes. When installing, there is no ability to pass in a [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config). You will need to boot up, change the configuration and then reboot to apply those changes.
Currently, only Raspberry Pi 3 is tested and known to work. Currently, only Raspberry Pi 3 is tested and known to work.
content/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso/_index.md → content/os/v1.x/en/installation/workstation/boot-from-iso/_index.md
+3 -1
View File
@@ -1,6 +1,8 @@
--- ---
title: Booting from ISO title: Booting from ISO
weight: 102 weight: 102
aliases:
- /os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso
--- ---
The RancherOS ISO file can be used to create a fresh RancherOS install on KVM, VMware, VirtualBox, Hyper-V, Proxmox VE, or bare metal servers. You can download the `rancheros.iso` file from our [releases page](https://github.com/rancher/os/releases/). The RancherOS ISO file can be used to create a fresh RancherOS install on KVM, VMware, VirtualBox, Hyper-V, Proxmox VE, or bare metal servers. You can download the `rancheros.iso` file from our [releases page](https://github.com/rancher/os/releases/).
@@ -17,4 +19,4 @@ You must boot with enough memory which you can refer to [here]({{< baseurl >}}/o
### Install to Disk ### Install to Disk
After you boot RancherOS from ISO, you can follow the instructions [here]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/server/install-to-disk/) to install RancherOS to a hard disk. After you boot RancherOS from ISO, you can follow the instructions [here]({{< baseurl >}}/os/v1.x/en/installation/server/install-to-disk/) to install RancherOS to a hard disk.
content/os/v1.x/en/installation/running-rancheros/workstation/docker-machine/_index.md → content/os/v1.x/en/installation/workstation/docker-machine/_index.md
+3 -1
View File
@@ -1,6 +1,8 @@
--- ---
title: Using Docker Machine title: Using Docker Machine
weight: 101 weight: 101
aliases:
- /os/v1.x/en/installation/running-rancheros/workstation/docker-machine
--- ---
Before we get started, you'll need to make sure that you have docker machine installed. Download it directly from the docker machine [releases](https://github.com/docker/machine/releases). Before we get started, you'll need to make sure that you have docker machine installed. Download it directly from the docker machine [releases](https://github.com/docker/machine/releases).
@@ -116,7 +118,7 @@ Logging into RancherOS follows the standard Docker Machine commands. To login in
$ docker-machine ssh <MACHINE-NAME> $ docker-machine ssh <MACHINE-NAME>
``` ```
You'll be logged into RancherOS and can start exploring the OS, This will log you into the RancherOS VM. You'll then be able to explore the OS by [adding system services]({{< baseurl >}}/os/v1.x/en/installation/system-services/adding-system-services/), [customizing the configuration]({{< baseurl >}}/os/v1.x/en/installation/configuration/), and launching containers. You'll be logged into RancherOS and can start exploring the OS, This will log you into the RancherOS VM. You'll then be able to explore the OS by [adding system services]({{< baseurl >}}/os/v1.x/en/system-services/), [customizing the configuration]({{< baseurl >}}/os/v1.x/en/configuration/), and launching containers.
If you want to exit out of RancherOS, you can exit by pressing `Ctrl+D`. If you want to exit out of RancherOS, you can exit by pressing `Ctrl+D`.
content/os/v1.x/en/installation/networking/dns/_index.md → content/os/v1.x/en/networking/dns/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Configuring DNS title: Configuring DNS
weight: 171 weight: 171
aliases:
- /os/v1.x/en/installation/networking/dns
--- ---
If you wanted to configure the DNS through the cloud config file, you'll need to place DNS configurations within the `rancher` key. If you wanted to configure the DNS through the cloud config file, you'll need to place DNS configurations within the `rancher` key.
content/os/v1.x/en/installation/networking/interfaces/_index.md → content/os/v1.x/en/networking/interfaces/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Configuring Network Interfaces title: Configuring Network Interfaces
weight: 170 weight: 170
aliases:
- /os/v1.x/en/installation/networking/interfaces
--- ---
Using `ros config`, you can configure specific interfaces. Wildcard globbing is supported so `eth*` will match `eth1` and `eth2`. The available options you can configure are `address`, `gateway`, `mtu`, and `dhcp`. Using `ros config`, you can configure specific interfaces. Wildcard globbing is supported so `eth*` will match `eth1` and `eth2`. The available options you can configure are `address`, `gateway`, `mtu`, and `dhcp`.
content/os/v1.x/en/installation/networking/proxy-settings/_index.md → content/os/v1.x/en/networking/proxy-settings/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Configuring Proxy Settings title: Configuring Proxy Settings
weight: 172 weight: 172
aliases:
- /os/v1.x/en/installation/networking/proxy-settings
--- ---
HTTP proxy settings can be set directly under the `network` key. This will automatically configure proxy settings for both Docker and System Docker. HTTP proxy settings can be set directly under the `network` key. This will automatically configure proxy settings for both Docker and System Docker.
content/os/v1.x/en/overview/_index.md
+1 -1
View File
@@ -29,7 +29,7 @@ You can adjust memory requirements by custom building RancherOS, please refer to
### How RancherOS Works ### How RancherOS Works
Everything in RancherOS is a Docker container. We accomplish this by launching two instances of Docker. One is what we call **System Docker** and is the first process on the system. All other system services, like `ntpd`, `syslog`, and `console`, are running in Docker containers. System Docker replaces traditional init systems like `systemd` and is used to launch [additional system services]({{< baseurl >}}/os/v1.x/en/installation/system-services/adding-system-services/). Everything in RancherOS is a Docker container. We accomplish this by launching two instances of Docker. One is what we call **System Docker** and is the first process on the system. All other system services, like `ntpd`, `syslog`, and `console`, are running in Docker containers. System Docker replaces traditional init systems like `systemd` and is used to launch [additional system services]({{< baseurl >}}/os/v1.x/en/system-services/).
System Docker runs a special container called **Docker**, which is another Docker daemon responsible for managing all of the user’s containers. Any containers that you launch as a user from the console will run inside this Docker. This creates isolation from the System Docker containers and ensures that normal user commands don’t impact system services. System Docker runs a special container called **Docker**, which is another Docker daemon responsible for managing all of the user’s containers. Any containers that you launch as a user from the console will run inside this Docker. This creates isolation from the System Docker containers and ensures that normal user commands don’t impact system services.
content/os/v1.x/en/quick-start-guide/_index.md
+1 -1
View File
@@ -3,7 +3,7 @@ title: Quick Start
weight: 1 weight: 1
--- ---
If you have a specific RanchersOS machine requirements, please check out our [guides on running RancherOS]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/). With the rest of this guide, we'll start up a RancherOS using [Docker machine]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/docker-machine/) and show you some of what RancherOS can do. If you have a specific RanchersOS machine requirements, please check out our [guides on running RancherOS]({{< baseurl >}}/os/v1.x/en/installation/platform/). With the rest of this guide, we'll start up a RancherOS using [Docker machine]({{< baseurl >}}/os/v1.x/en/installation/workstation//docker-machine/) and show you some of what RancherOS can do.
### Launching RancherOS using Docker Machine ### Launching RancherOS using Docker Machine
content/os/v1.x/en/installation/storage/additional-mounts/_index.md → content/os/v1.x/en/storage/additional-mounts/_index.md
+6
View File
@@ -1,9 +1,15 @@
--- ---
title: Additional Mounts title: Additional Mounts
weight: 161 weight: 161
aliases:
- /os/v1.x/en/installation/storage/additional-mounts
--- ---
<<<<<<< HEAD:content/os/v1.x/en/installation/storage/additional-mounts/_index.md
Additional mounts can be specified as part of your [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config). These mounts are applied within the console container. Here's a simple example that mounts `/dev/vdb` to `/mnt/s`. Additional mounts can be specified as part of your [cloud-config]({{<baseurl>}}/os/v1.x/en/installation/configuration/#cloud-config). These mounts are applied within the console container. Here's a simple example that mounts `/dev/vdb` to `/mnt/s`.
=======
Additional mounts can be specified as part of your [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config). These mounts are applied within the console container. Here's a simple example that mounts `/dev/vdb` to `/mnt/s`.
>>>>>>> Reorganize RancherOS docs:content/os/v1.x/en/storage/additional-mounts/_index.md
```yaml ```yaml
#cloud-config #cloud-config
content/os/v1.x/en/installation/storage/state-partition/_index.md → content/os/v1.x/en/storage/state-partition/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Persistent State Partition title: Persistent State Partition
weight: 160 weight: 160
aliases:
- /os/v1.x/en/installation/storage/state-partition
--- ---
RancherOS will store its state in a single partition specified by the `dev` field. The field can be a device such as `/dev/sda1` or a logical name such `LABEL=state` or `UUID=123124`. The default value is `LABEL=RANCHER_STATE`. The file system type of that partition can be set to `auto` or a specific file system type such as `ext4`. RancherOS will store its state in a single partition specified by the `dev` field. The field can be a device such as `/dev/sda1` or a logical name such `LABEL=state` or `UUID=123124`. The default value is `LABEL=RANCHER_STATE`. The file system type of that partition can be set to `auto` or a specific file system type such as `ext4`.
content/os/v1.x/en/installation/storage/using-zfs/_index.md → content/os/v1.x/en/storage/using-zfs/_index.md
+3 -1
View File
@@ -1,6 +1,8 @@
--- ---
title: Using ZFS title: Using ZFS
weight: 162 weight: 162
aliases:
- /os/v1.x/en/installation/storage/using-zfs
--- ---
#### Installing the ZFS service #### Installing the ZFS service
@@ -19,7 +21,7 @@ $ sudo ros service logs --follow zfs
$ lsmod | grep zfs $ lsmod | grep zfs
``` ```
> *Note:* if you switch consoles, you may need to re-run `ros up zfs`. > *Note:* if you switch consoles, you may need to re-run `sudo ros service up zfs`.
#### Creating ZFS pools #### Creating ZFS pools
content/os/v1.x/en/installation/system-services/adding-system-services/_index.md → content/os/v1.x/en/system-services/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: System Services title: System Services
weight: 140 weight: 140
aliases:
- /os/v1.x/en/installation/system-services/adding-system-services
--- ---
A system service is a container that can be run in either System Docker or Docker. Rancher provides services that are already available in RancherOS by adding them to the [os-services repo](https://github.com/rancher/os-services). Anything in the `index.yml` file from the repository for the tagged release will be an available system service when using the `ros service list` command. A system service is a container that can be run in either System Docker or Docker. Rancher provides services that are already available in RancherOS by adding them to the [os-services repo](https://github.com/rancher/os-services). Anything in the `index.yml` file from the repository for the tagged release will be an available system service when using the `ros service list` command.
content/os/v1.x/en/installation/system-services/custom-system-services/_index.md → content/os/v1.x/en/system-services/custom-system-services/_index.md
+3 -1
View File
@@ -1,9 +1,11 @@
--- ---
title: Custom System Services title: Custom System Services
weight: 141 weight: 141
aliases:
- /os/v1.x/en/installation/system-services/custom-system-services
--- ---
You can also create your own system service in [Docker Compose](https://docs.docker.com/compose/) format. After creating your own custom service, you can launch it in RancherOS in a couple of methods. The service could be directly added to the [cloud-config]({{< baseurl >}}/os/v1.x/en/installation/configuration/#cloud-config), or a `docker-compose.yml` file could be saved at a http(s) url location or in a specific directory of RancherOS. You can also create your own system service in [Docker Compose](https://docs.docker.com/compose/) format. After creating your own custom service, you can launch it in RancherOS in a couple of methods. The service could be directly added to the [cloud-config]({{< baseurl >}}/os/v1.x/en/configuration/#cloud-config), or a `docker-compose.yml` file could be saved at a http(s) url location or in a specific directory of RancherOS.
### Launching Services through Cloud-Config ### Launching Services through Cloud-Config
content/os/v1.x/en/installation/system-services/environment/_index.md → content/os/v1.x/en/system-services/environment/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: Environment title: Environment
weight: 143 weight: 143
aliases:
- /os/v1.x/en/installation/system-services/environment
--- ---
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. 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.
content/os/v1.x/en/installation/system-services/system-docker-volumes/_index.md → content/os/v1.x/en/system-services/system-docker-volumes/_index.md
+2
View File
@@ -1,6 +1,8 @@
--- ---
title: System Docker Volumes title: System Docker Volumes
weight: 142 weight: 142
aliases:
- /os/v1.x/en/installation/system-services/system-docker-volumes
--- ---
A few services are containers in `created` state. Their purpose is to provide volumes for other services. A few services are containers in `created` state. Their purpose is to provide volumes for other services.
content/os/v1.x/en/upgrading/_index.md
+2 -2
View File
@@ -9,7 +9,7 @@ Since RancherOS is a kernel and initrd, the upgrade process is downloading a new
Before upgrading to any version, please review the release notes on our [releases page](https://github.com/rancher/os/releases) in GitHub to review any updates in the release. Before upgrading to any version, please review the release notes on our [releases page](https://github.com/rancher/os/releases) in GitHub to review any updates in the release.
> **Note:** If you are using [`docker-machine`]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/docker-machine/) then you will not be able to upgrade your RancherOS version. You need to delete and re-create the machine. > **Note:** If you are using [`docker-machine`]({{< baseurl >}}/os/v1.x/en/installation/workstation//docker-machine/) then you will not be able to upgrade your RancherOS version. You need to delete and re-create the machine.
### Version Control ### Version Control
@@ -64,7 +64,7 @@ $ sudo ros -v
ros version v0.5.0 ros version v0.5.0
``` ```
> **Note:** If you are booting from ISO and have not installed to disk, your upgrade will not be saved. You can view our guide to [installing to disk]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/server/install-to-disk/). > **Note:** If you are booting from ISO and have not installed to disk, your upgrade will not be saved. You can view our guide to [installing to disk]({{< baseurl >}}/os/v1.x/en/installation/server/install-to-disk/).
#### Upgrading to a Specific Version #### Upgrading to a Specific Version
content/rancher/v2.x/en/_index.md
+5 -4
View File
@@ -8,13 +8,14 @@ insertOneSix: true
weight: 1 weight: 1
ctaBanner: intro-k8s-rancher-online-training ctaBanner: intro-k8s-rancher-online-training
--- ---
Rancher was originally built to work with multiple orchestrators, and it included its own orchestrator called Cattle. With the rise of Kubernetes in the marketplace, Rancher 2.x exclusively deploys and manages Kubernetes clusters running anywhere, on any provider.
# What's New? Rancher can provision Kubernetes from a hosted provider, provision compute nodes and then install Kubernetes onto them, or import existing Kubernetes clusters running anywhere.
Rancher was originally built to work with multiple orchestrators, and it included its own orchestrator called Cattle. With the rise of Kubernetes in the marketplace, Rancher now exclusively deploys and manages multiple Kubernetes clusters running anywhere, on any provider. It can provision Kubernetes from a hosted provider, provision compute nodes and then install Kubernetes onto them, or inherit existing Kubernetes clusters running anywhere. One Rancher server installation can manage thousands of Kubernetes clusters and thousands of nodes from the same user interface.
One Rancher server installation can manage hundreds of Kubernetes clusters from the same interface. Rancher adds significant value on top of Kubernetes, first by centralizing authentication and role-based access control (RBAC) for all of the clusters, giving global admins the ability to control cluster access from one location.
Rancher adds significant value on top of Kubernetes, first by centralizing role-based access control (RBAC) for all of the clusters and giving global admins the ability to control cluster access from one location. It then enables detailed monitoring and alerting for clusters and their resources, ships logs to external providers, and integrates directly with Helm via the Application Catalog. If you have an external CI/CD system, you can plug it into Rancher, but if you don't, Rancher even includes a pipeline engine to help you automatically deploy and upgrade workloads. It then enables detailed monitoring and alerting for clusters and their resources, ships logs to external providers, and integrates directly with Helm via the Application Catalog. If you have an external CI/CD system, you can plug it into Rancher, but if you don't, Rancher even includes a pipeline engine to help you automatically deploy and upgrade workloads.
Rancher is a _complete_ container management platform for Kubernetes, giving you the tools to successfully run Kubernetes anywhere. Rancher is a _complete_ container management platform for Kubernetes, giving you the tools to successfully run Kubernetes anywhere.
content/rancher/v2.x/en/admin-settings/authentication/azure-ad/_index.md
+28 -24
View File
@@ -28,9 +28,8 @@ Configuring Rancher to allow your users to authenticate with their Azure AD acco
- [1. Register Rancher with Azure](#1-register-rancher-with-azure) - [1. Register Rancher with Azure](#1-register-rancher-with-azure)
- [2. Create an Azure API Key](#2-create-an-azure-api-key) - [2. Create an Azure API Key](#2-create-an-azure-api-key)
- [3. Set Required Permissions for Rancher](#3-set-required-permissions-for-rancher) - [3. Set Required Permissions for Rancher](#3-set-required-permissions-for-rancher)
- [4. Add a Reply URL](#4-add-a-reply-url) - [4. Copy Azure Application Data](#4-copy-azure-application-data)
- [5. Copy Azure Application Data](#5-copy-azure-application-data) - [5. Configure Azure AD in Rancher](#5-configure-azure-ad-in-rancher)
- [6. Configure Azure AD in Rancher](#6-configure-azure-ad-in-rancher)
<!-- /TOC --> <!-- /TOC -->
@@ -44,39 +43,41 @@ Before enabling Azure AD within Rancher, you must register Rancher with Azure.
![Open App Registrations]({{<baseurl>}}/img/rancher/search-app-registrations.png) ![Open App Registrations]({{<baseurl>}}/img/rancher/search-app-registrations.png)
1. Click **New application registration** and complete the **Create** form. 1. Click **New registrations** and complete the **Create** form.
![New App Registration]({{<baseurl>}}/img/rancher/new-app-registration.png) ![New App Registration]({{<baseurl>}}/img/rancher/new-app-registration.png)
1. Enter a **Name** (something like `Rancher`). 1. Enter a **Name** (something like `Rancher`).
1. From **Application type**, make sure that **Web app / API** is selected. 1. From **Supported account types**, select "Accounts in this organizational directory only (AzureADTest only - Single tenant)" This corresponds to the legacy app registration options.
1. In the **Sign-on URL** field, enter the URL of your Rancher Server. 1. In the **Redirect URI** section, make sure **Web** is selected from the dropdown and enter the URL of your Rancher Server in the text box next to the dropdown. This Rancher server URL should be appended with the verification path: `<MY_RANCHER_URL>/verify-auth-azure`.
1. Click **Create**. >**Tip:** You can find your personalized Azure reply URL in Rancher on the Azure AD Authentication page (Global View > Security Authentication > Azure AD).
### 2. Create an Azure API Key 1. Click **Register**.
From the Azure portal, create an API key. Rancher will use this key to authenticate with Azure AD. >**Note:** It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration.
### 2. Create a new client secret
From the Azure portal, create a client secret. Rancher will use this key to authenticate with Azure AD.
1. Use search to open **App registrations** services. Then open the entry for Rancher that you created in the last procedure. 1. Use search to open **App registrations** services. Then open the entry for Rancher that you created in the last procedure.
![Open Rancher Registration]({{<baseurl>}}/img/rancher/open-rancher-app.png) ![Open Rancher Registration]({{<baseurl>}}/img/rancher/open-rancher-app.png)
**Step Result:** A new blade opens for Rancher. 1. From the navigation pane on left, click **Certificates and Secrets**.
1. Click **Settings**. 1. Click **New client secret**.
1. From the **Settings** blade, select **Keys**. ![Create new client secret]({{< baseurl >}}/img/rancher/select-client-secret.png)
1. From **Passwords**, create an API key. 1. Enter a **Description** (something like `Rancher`).
1. Enter a **Key description** (something like `Rancher`). 1. Select duration for the key from the options under **Expires**. This drop-down sets the expiration date for the key. Shorter durations are more secure, but require you to create a new key after expiration.
1. Select a **Duration** for the key. This drop-down sets the expiration date for the key. Shorter durations are more secure, but require you to create a new key after expiration. 1. Click **Add** (you don't need to enter a value—it will automatically populate after you save).
1. Click **Save** (you don't need to enter a value—it will automatically populate after you save).
<a id="secret"></a> <a id="secret"></a>
1. Copy the key value and save it to an [empty text file](#tip). 1. Copy the key value and save it to an [empty text file](#tip).
@@ -89,13 +90,16 @@ From the Azure portal, create an API key. Rancher will use this key to authentic
Next, set API permissions for Rancher within Azure. Next, set API permissions for Rancher within Azure.
1. From the **Settings** blade, select **Required permissions**. 1. From the navigation pane on left, select **API permissions**.
![Open Required Permissions]({{<baseurl>}}/img/rancher/select-required-permissions.png) ![Open Required Permissions]({{<baseurl>}}/img/rancher/select-required-permissions.png)
1. Click **Windows Azure Active Directory**. 1. Click **Add a permission**.
1. From the **Azure Active Directory Graph**, select the following **Delegated Permissions**:
![Select API Permissions]({{< baseurl >}}/img/rancher/select-required-permissions-2.png)
1. From the **Enable Access** blade, select the following **Delegated Permissions**:
<br/> <br/>
<br/> <br/>
- **Access the directory as the signed-in user** - **Access the directory as the signed-in user**
@@ -105,9 +109,9 @@ Next, set API permissions for Rancher within Azure.
- **Read all users' basic profiles** - **Read all users' basic profiles**
- **Sign in and read user profile** - **Sign in and read user profile**
1. Click **Save**. 1. Click **Add permissions**.
1. From **Required permissions**, click **Grant permissions**. Then click **Yes**. 1. From **API permissions**, click **Grant admin consent**. Then click **Yes**.
>**Note:** You must be signed in as an Azure administrator to successfully save your permission settings. >**Note:** You must be signed in as an Azure administrator to successfully save your permission settings.
@@ -141,7 +145,7 @@ As your final step in Azure, copy the data that you'll use to configure Rancher
![Open Azure Active Directory]({{<baseurl>}}/img/rancher/search-azure-ad.png) ![Open Azure Active Directory]({{<baseurl>}}/img/rancher/search-azure-ad.png)
1. From the **Azure Active Directory** menu, open **Properties**. 1. From the left navigation pane, open **Overview**.
2. Copy the **Directory ID** and paste it into your [text file](#tip). 2. Copy the **Directory ID** and paste it into your [text file](#tip).
@@ -171,7 +175,7 @@ As your final step in Azure, copy the data that you'll use to configure Rancher
>**Note:** Copy the v1 version of the endpoints >**Note:** Copy the v1 version of the endpoints
### 6. Configure Azure AD in Rancher ### 5. Configure Azure AD in Rancher
From the Rancher UI, enter information about your AD instance hosted in Azure to complete configuration. From the Rancher UI, enter information about your AD instance hosted in Azure to complete configuration.
content/rancher/v2.x/en/admin-settings/authentication/keycloak/_index.md
+7 -1
View File
@@ -17,12 +17,13 @@ If your organization uses Keycloak Identity Provider (IdP) for user authenticati
`Sign Documents` | `ON` <sup>1</sup> `Sign Documents` | `ON` <sup>1</sup>
`Sign Assertions` | `ON` <sup>1</sup> `Sign Assertions` | `ON` <sup>1</sup>
All other `ON/OFF` Settings | `OFF` All other `ON/OFF` Settings | `OFF`
`Client ID` | `https://yourRancherHostURL/v1-saml/keycloak/saml/metadata` `Client ID` | `https://yourRancherHostURL/v1-saml/keycloak/saml/metadata`<sup>2</sup>
`Client Name` | <CLIENT_NAME> (e.g. `rancher`) `Client Name` | <CLIENT_NAME> (e.g. `rancher`)
`Client Protocol` | `SAML` `Client Protocol` | `SAML`
`Valid Redirect URI` | `https://yourRancherHostURL/v1-saml/keycloak/saml/acs` `Valid Redirect URI` | `https://yourRancherHostURL/v1-saml/keycloak/saml/acs`
><sup>1</sup>: Optionally, you can enable either one or both of these settings. ><sup>1</sup>: Optionally, you can enable either one or both of these settings.
><sup>2</sup>: Rancher SAML metadata won't be generated until a SAML provider is configured and saved.
- Export a `metadata.xml` file from your Keycloak client: - Export a `metadata.xml` file from your Keycloak client:
From the `Installation` tab, choose the `SAML Metadata IDPSSODescriptor` format option and download your file. From the `Installation` tab, choose the `SAML Metadata IDPSSODescriptor` format option and download your file.
@@ -81,6 +82,11 @@ You are correctly redirected to your IdP login page and you are able to enter yo
* Check the Rancher debug log. * Check the Rancher debug log.
* If the log displays `ERROR: either the Response or Assertion must be signed`, make sure either `Sign Documents` or `Sign assertions` is set to `ON` in your Keycloak client. * If the log displays `ERROR: either the Response or Assertion must be signed`, make sure either `Sign Documents` or `Sign assertions` is set to `ON` in your Keycloak client.
### HTTP 502 when trying to access /v1-saml/keycloak/saml/metadata
This is usually due to the metadata not being created until a SAML provider is configured.
Try configuring and saving keycloak as your SAML provider and then accessing the metadata.
### Keycloak Error: "We're sorry, failed to process response" ### Keycloak Error: "We're sorry, failed to process response"
* Check your Keycloak log. * Check your Keycloak log.
content/rancher/v2.x/en/admin-settings/authentication/openldap/_index.md
+5 -81
View File
@@ -9,17 +9,6 @@ _Available as of v2.0.5_
If your organization uses LDAP for user authentication, you can configure Rancher to communicate with an OpenLDAP server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the organisation's central user repository, while allowing end-users to authenticate with their LDAP credentials when logging in to the Rancher UI. If your organization uses LDAP for user authentication, you can configure Rancher to communicate with an OpenLDAP server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the organisation's central user repository, while allowing end-users to authenticate with their LDAP credentials when logging in to the Rancher UI.
## OpenLDAP Authentication Flow
1. When a user attempts to login with his LDAP credentials, Rancher creates an initial bind to the LDAP server using a service account with permissions to search the directory and read user/group attributes.
2. Rancher then searches the directory for the user by using a search filter based on the provided username and configured attribute mappings.
3. Once the user has been found, he is authenticated with another LDAP bind request using the user's DN and provided password.
4. Once authentication succeeded, Rancher then resolves the group memberships both from the membership attribute in the user's object and by performing a group search based on the configured user mapping attribute.
> **Note:**
>
> Before you proceed with the configuration, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
## Prerequisites ## Prerequisites
Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below). Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below).
@@ -28,81 +17,16 @@ Rancher must be configured with a LDAP bind account (aka service account) to sea
> >
> If the certificate used by the OpenLDAP server is self-signed or not from a recognised certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain. > If the certificate used by the OpenLDAP server is self-signed or not from a recognised certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
## Configuration Steps ## Configure OpenLDAP in Rancher
### Open OpenLDAP Configuration
Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the [configuration reference.](../openldap-config)
> Before you proceed with the configuration, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
1. Log into the Rancher UI using the initial local `admin` account. 1. Log into the Rancher UI using the initial local `admin` account.
2. From the **Global** view, navigate to **Security** > **Authentication** 2. From the **Global** view, navigate to **Security** > **Authentication**
3. Select **OpenLDAP**. The **Configure an OpenLDAP server** form will be displayed. 3. Select **OpenLDAP**. The **Configure an OpenLDAP server** form will be displayed.
### Configure OpenLDAP Server Settings
In the section titled `1. Configure an OpenLDAP server`, complete the fields with the information specific to your server. Please refer to the following table for detailed information on the required values for each parameter.
> **Note:**
>
> If you are in doubt about the correct values to enter in the user/group Search Base configuration fields, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation.
**Table 1: OpenLDAP server parameters**
| Parameter | Description |
|:--|:--|
| Hostname | Specify the hostname or IP address of the OpenLDAP server |
| Port | Specify the port at which the OpenLDAP server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.|
| TLS | Check this box to enable LDAP over SSL/TLS (commonly known as LDAPS). You will also need to paste in the CA certificate if the server uses a self-signed/enterprise-signed certificate. |
| Server Connection Timeout | The duration in number of seconds that Rancher waits before considering the server unreachable. |
| Service Account Distinguished Name | Enter the Distinguished Name (DN) of the user that should be used to bind, search and retrieve LDAP entries. (see [Prerequisites](#prerequisites)). |
| Service Account Password | The password for the service account. |
| User Search Base | Enter the Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".|
| Group Search Base | If your groups live under a different node than the one configured under `User Search Base` you will need to provide the Distinguished Name here. Otherwise leave this field empty. For example: "ou=groups,dc=acme,dc=com".|
---
### Configure User/Group Schema
If your OpenLDAP directory deviates from the standard OpenLDAP schema, you must complete the **Customize Schema** section to match it.
Note that the attribute mappings configured in this section are used by Rancher to construct search filters and resolve group membership. It is therefore always recommended to verify that the configuration here matches the schema used in your OpenLDAP.
> **Note:**
>
> If you are unfamiliar with the user/group schema used in the OpenLDAP server, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation.
#### User Schema
The table below details the parameters for the user schema configuration.
**Table 2: User schema configuration parameters**
| Parameter | Description |
|:--|:--|
| 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`. |
| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the LDAP 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. |
| User Enabled Attribute | If the schema of your OpenLDAP server supports a user attribute whose value can be evaluated to determine if the account is disabled or locked, enter the name of that attribute. The default OpenLDAP schema does not support this and the field should usually be left empty. |
| Disabled Status Bitmask | This is the value for a disabled/locked user account. The parameter is ignored if `User Enabled Attribute` is empty. |
---
#### Group Schema
The table below details the parameters for the group schema configuration.
**Table 3: Group schema configuration parameters**
| Parameter | Description |
|:--|:--|
| 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. |
| Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects in the UI. See description of user schema `Search Attribute`. |
| Group DN Attribute | The name of the group attribute whose format matches the values in the user's group membership attribute. 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). |
---
### Test Authentication ### Test Authentication
Once you have completed the configuration, proceed by testing the connection to the OpenLDAP server. Authentication with OpenLDAP will be enabled implicitly if the test is successful. Once you have completed the configuration, proceed by testing the connection to the OpenLDAP server. Authentication with OpenLDAP will be enabled implicitly if the test is successful.
content/rancher/v2.x/en/admin-settings/authentication/openldap/openldap-config/_index.md
+86
View File
@@ -0,0 +1,86 @@
---
title: OpenLDAP Configuration Reference
weight: 2
---
This section is intended to be used as a reference when setting up an OpenLDAP authentication provider in Rancher.
For further details on configuring OpenLDAP, refer to the [official documentation.](https://www.openldap.org/doc/)
> Before you proceed with the configuration, please familiarize yourself with the concepts of [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
- [Background: OpenLDAP Authentication Flow](#background-openldap-authentication-flow)
- [OpenLDAP server configuration](#openldap-server-configuration)
- [User/group schema configuration](#user-group-schema-configuration)
- [User schema configuration](#user-schema-configuration)
- [Group schema configuration](#group-schema-configuration)
## Background: OpenLDAP Authentication Flow
1. When a user attempts to login with his LDAP credentials, Rancher creates an initial bind to the LDAP server using a service account with permissions to search the directory and read user/group attributes.
2. Rancher then searches the directory for the user by using a search filter based on the provided username and configured attribute mappings.
3. Once the user has been found, he is authenticated with another LDAP bind request using the user's DN and provided password.
4. Once authentication succeeded, Rancher then resolves the group memberships both from the membership attribute in the user's object and by performing a group search based on the configured user mapping attribute.
# OpenLDAP Server Configuration
You will need to enter the address, port, and protocol to connect to your OpenLDAP server. `389` is the standard port for insecure traffic, `636` for TLS traffic.
> **Using TLS?**
>
> If the certificate used by the OpenLDAP server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
If you are in doubt about the correct values to enter in the user/group Search Base configuration fields, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation.
<figcaption>OpenLDAP Server Parameters</figcaption>
| Parameter | Description |
|:--|:--|
| Hostname | Specify the hostname or IP address of the OpenLDAP server |
| Port | Specify the port at which the OpenLDAP server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.|
| TLS | Check this box to enable LDAP over SSL/TLS (commonly known as LDAPS). You will also need to paste in the CA certificate if the server uses a self-signed/enterprise-signed certificate. |
| Server Connection Timeout | The duration in number of seconds that Rancher waits before considering the server unreachable. |
| Service Account Distinguished Name | Enter the Distinguished Name (DN) of the user that should be used to bind, search and retrieve LDAP entries. (see [Prerequisites](#prerequisites)). |
| Service Account Password | The password for the service account. |
| User Search Base | Enter the Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".|
| Group Search Base | If your groups live under a different node than the one configured under `User Search Base` you will need to provide the Distinguished Name here. Otherwise leave this field empty. For example: "ou=groups,dc=acme,dc=com".|
# User/Group Schema Configuration
If your OpenLDAP directory deviates from the standard OpenLDAP schema, you must complete the **Customize Schema** section to match it.
Note that the attribute mappings configured in this section are used by Rancher to construct search filters and resolve group membership. It is therefore always recommended to verify that the configuration here matches the schema used in your OpenLDAP.
If you are unfamiliar with the user/group schema used in the OpenLDAP server, consult your LDAP administrator or refer to the section [Identify Search Base and Schema using ldapsearch]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/ad/#annex-identify-search-base-and-schema-using-ldapsearch) in the Active Directory authentication documentation.
### User Schema Configuration
The table below details the parameters for the user schema configuration.
<figcaption>User Schema Configuration Parameters</figcaption>
| Parameter | Description |
|:--|:--|
| 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`. |
| Search Attribute | When a user enters text to add users or groups in the UI, Rancher queries the LDAP 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. |
| User Enabled Attribute | If the schema of your OpenLDAP server supports a user attribute whose value can be evaluated to determine if the account is disabled or locked, enter the name of that attribute. The default OpenLDAP schema does not support this and the field should usually be left empty. |
| Disabled Status Bitmask | This is the value for a disabled/locked user account. The parameter is ignored if `User Enabled Attribute` is empty. |
### Group Schema Configuration
The table below details the parameters for the group schema configuration.
<figcaption>Group Schema Configuration Parameters<figcaption>
| Parameter | Description |
|:--|:--|
| 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. |
| Search Attribute | Attribute used to construct search filters when adding groups to clusters or projects in the UI. See description of user schema `Search Attribute`. |
| Group DN Attribute | The name of the group attribute whose format matches the values in the user's group membership attribute. See `User Member Attribute`. |
| Nested Group Membership | This settings defines whether Rancher should resolve nested group memberships. Use only if your organization makes use of these nested memberships (ie. you have groups that contain other groups as members). This option is disabled if you are using Shibboleth. |
content/rancher/v2.x/en/admin-settings/authentication/shibboleth/_index.md
+109
View File
@@ -0,0 +1,109 @@
---
title: Configuring Shibboleth (SAML)
weight: 1210
---
_Available as of v2.4.0_
If your organization uses Shibboleth Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in to Rancher using their Shibboleth credentials.
In this configuration, when Rancher users log in, they will be redirected to the Shibboleth IdP to enter their credentials. After authentication, they will be redirected back to the Rancher UI.
If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then the authenticated user will be able to access resources in Rancher that their groups have permissions for.
> The instructions in this section assume that you understand how Rancher, Shibboleth, and OpenLDAP work together. For a more detailed explanation of how it works, refer to [this page.](./about)
This section covers the following topics:
- [Setting up Shibboleth in Rancher](#setting-up-shibboleth-in-rancher)
- [Shibboleth Prerequisites](#shibboleth-prerequisites)
- [Configure Shibboleth in Rancher](#configure-shibboleth-in-rancher)
- [SAML Provider Caveats](#saml-provider-caveats)
- [Setting up OpenLDAP in Rancher](#setting-up-openldap-in-rancher)
- [OpenLDAP Prerequisites](#openldap-prerequisites)
- [Configure OpenLDAP in Rancher](#configure-openldap-in-rancher)
- [Troubleshooting](#troubleshooting)
# Setting up Shibboleth in Rancher
### Shibboleth Prerequisites
>
>- You must have a Shibboleth IdP Server configured.
>- Following are the Rancher Service Provider URLs needed for configuration:
Metadata URL: `https://<rancher-server>/v1-saml/shibboleth/saml/metadata`
Assertion Consumer Service (ACS) URL: `https://<rancher-server>/v1-saml/shibboleth/saml/acs`
>- Export a `metadata.xml` file from your IdP Server. For more information, see the [Shibboleth documentation.](https://wiki.shibboleth.net/confluence/display/SP3/Home)
### Configure Shibboleth in Rancher
If your organization uses Shibboleth for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
1. From the **Global** view, select **Security > Authentication** from the main menu.
1. Select **Shibboleth**.
1. Complete the **Configure Shibboleth Account** form. Shibboleth IdP lets you specify what data store you want to use. You can either add a database or use an existing ldap server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher.
1. **Display Name Field**: Enter the AD attribute that contains the display name of users (example: `displayName`).
1. **User Name Field**: Enter the AD attribute that contains the user name/given name (example: `givenName`).
1. **UID Field**: Enter an AD attribute that is unique to every user (example: `sAMAccountName`, `distinguishedName`).
1. **Groups Field**: Make entries for managing group memberships (example: `memberOf`).
1. **Rancher API Host**: Enter the URL for your Rancher Server.
1. **Private Key** and **Certificate**: This is a key-certificate pair to create a secure shell between Rancher and your IdP.
You can generate one using an openssl command. For example:
```
openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
```
1. **IDP-metadata**: The `metadata.xml` file that you exported from your IdP server.
1. After you complete the **Configure Shibboleth Account** form, click **Authenticate with Shibboleth**, which is at the bottom of the page.
Rancher redirects you to the IdP login page. Enter credentials that authenticate with Shibboleth IdP to validate your Rancher Shibboleth configuration.
>**Note:** You may have to disable your popup blocker to see the IdP login page.
**Result:** Rancher is configured to work with Shibboleth. Your users can now sign into Rancher using their Shibboleth logins.
### SAML Provider Caveats
If you configure Shibboleth without OpenLDAP, the following caveats apply due to the fact that SAML Protocol does not support search or lookup for users or groups.
- There is no validation on users or groups when assigning permissions to them in Rancher.
- When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
- When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
- The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.
To enable searching for groups when assigning permissions in Rancher, you will need to configure a back end for the SAML provider that supports groups, such as OpenLDAP.
# Setting up OpenLDAP in Rancher
If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then authenticated users will be able to access resources in Rancher that their groups have permissions for.
### OpenLDAP Prerequisites
Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below).
> **Using TLS?**
>
> If the certificate used by the OpenLDAP server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
### Configure OpenLDAP in Rancher
Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the [configuration reference.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/openldap/openldap-config) Note that nested group membership is not available for Shibboleth.
> Before you proceed with the configuration, please familiarise yourself with the concepts of [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.x/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
1. Log into the Rancher UI using the initial local `admin` account.
2. From the **Global** view, navigate to **Security** > **Authentication**
3. Select **OpenLDAP**. The **Configure an OpenLDAP server** form will be displayed.
# Troubleshooting
If you are experiencing issues while testing the connection to the OpenLDAP server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to [How can I enable debug logging]({{<baseurl>}}/rancher/v2.x/en/faq/technical/#how-can-i-enable-debug-logging) in this documentation.
content/rancher/v2.x/en/admin-settings/authentication/shibboleth/about/_index.md
+34
View File
@@ -0,0 +1,34 @@
---
title: Group Permissions with Shibboleth and OpenLDAP
weight: 1
---
_Available as of Rancher v2.4_
This page provides background information and context for Rancher users who intend to set up the Shibboleth authentication provider in Rancher.
Because Shibboleth is a SAML provider, it does not support searching for groups. While a Shibboleth integration can validate user credentials, it can't be used to assign permissions to groups in Rancher without additional configuration.
One solution to this problem is to configure an OpenLDAP identity provider. With an OpenLDAP back end for Shibboleth, you will be able to search for groups in Rancher and assign them to resources such as clusters, projects, or namespaces from the Rancher UI.
### Terminology
- **Shibboleth** is a single sign-on log-in system for computer networks and the Internet. It allows people to sign in using just one identity to various systems. It validates user credentials, but does not, on its own, handle group memberships.
- **SAML:** Security Assertion Markup Language, an open standard for exchanging authentication and authorization data between an identity provider and a service provider.
- **OpenLDAP:** a free, open-source implementation of the Lightweight Directory Access Protocol (LDAP). It is used to manage an organization’s computers and users. OpenLDAP is useful for Rancher users because it supports groups. In Rancher, it is possible to assign permissions to groups so that they can access resources such as clusters, projects, or namespaces, as long as the groups already exist in the identity provider.
- **IdP or IDP:** An identity provider. OpenLDAP is an example of an identity provider.
### Adding OpenLDAP Group Permissions to Rancher Resources
The diagram below illustrates how members of an OpenLDAP group can access resources in Rancher that the group has permissions for.
For example, a cluster owner could add an OpenLDAP group to a cluster so that they have permissions view most cluster level resources and create new projects. Then the OpenLDAP group members will have access to the cluster as soon as they log in to Rancher.
In this scenario, OpenLDAP allows the cluster owner to search for groups when assigning persmissions. Without OpenLDAP, the functionality to search for groups would not be supported.
When a member of the OpenLDAP group logs in to Rancher, she is redirected to Shibboleth and enters her username and password.
Shibboleth validates her credentials, and retrieves user attributes from OpenLDAP, including groups. Then Shibboleth sends a SAML assertion to Rancher including the user attributes. Rancher uses the group data so that she can access all of the resources and permissions that her groups have permissions for.
![Adding OpenLDAP Group Permissions to Rancher Resources]({{<baseurl>}}/img/rancher/shibboleth-with-openldap-groups.svg)
content/rancher/v2.x/en/admin-settings/k8s-metadata/_index.md
+22 -2
View File
@@ -39,10 +39,28 @@ To force Rancher to refresh the Kubernetes metadata, a manual refresh action is
The RKE metadata config controls how often Rancher syncs metadata and where it downloads data from. You can configure the metadata from the settings in the Rancher UI, or through the Rancher API at the endpoint `v3/settings/rke-metadata-config`. The RKE metadata config controls how often Rancher syncs metadata and where it downloads data from. You can configure the metadata from the settings in the Rancher UI, or through the Rancher API at the endpoint `v3/settings/rke-metadata-config`.
The way that the metadata is configured depends on the Rancher version.
{{% tabs %}}
{{% tab "Rancher v2.4+" %}}
To edit the metadata config in Rancher, To edit the metadata config in Rancher,
1. Go to the **Global** view and click the **Settings** tab. 1. Go to the **Global** view and click the **Settings** tab.
1. Go to the **rke-metadata-config** section. Click the **Ellipsis (...)** and click **Edit.** 1. Go to the **rke-metadata-config** section. Click the **&#8942;** and click **Edit.**
1. You can optionally fill in the following parameters:
- `refresh-interval-minutes`: This is the amount of time that Rancher waits to sync the metadata. To disable the periodic refresh, set `refresh-interval-minutes` to 0.
- `url`: This is the HTTP path that Rancher fetches data from. The path must be a direct path to a JSON file. For example, the default URL for Rancher v2.4 is `https://releases.rancher.com/kontainer-driver-metadata/release-v2.4/data.json`.
If you don't have an air gap setup, you don't need to specify the URL where Rancher gets the metadata, because the default setting is to pull from [Rancher's metadata Git repository.](https://github.com/rancher/kontainer-driver-metadata/blob/dev-v2.5/data/data.json)
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 to point to the new location of the JSON file.
{{% /tab %}}
{{% tab "Rancher v2.3" %}}
To edit the metadata config in Rancher,
1. Go to the **Global** view and click the **Settings** tab.
1. Go to the **rke-metadata-config** section. Click the **&#8942;** and click **Edit.**
1. You can optionally fill in the following parameters: 1. You can optionally fill in the following parameters:
- `refresh-interval-minutes`: This is the amount of time that Rancher waits to sync the metadata. To disable the periodic refresh, set `refresh-interval-minutes` to 0. - `refresh-interval-minutes`: This is the amount of time that Rancher waits to sync the metadata. To disable the periodic refresh, set `refresh-interval-minutes` to 0.
@@ -52,6 +70,8 @@ To edit the metadata config in Rancher,
If you don't have an air gap setup, you don't need to specify the URL or Git branch where Rancher gets the metadata, because the default setting is to pull from [Rancher's metadata Git repository.](https://github.com/rancher/kontainer-driver-metadata.git) If you don't have an air gap setup, you don't need to specify the URL or Git branch where Rancher gets the metadata, because the default setting is to pull from [Rancher's metadata Git repository.](https://github.com/rancher/kontainer-driver-metadata.git)
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. 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.
{{% /tab %}}
{{% /tabs %}}
### Air Gap Setups ### Air Gap Setups
@@ -59,7 +79,7 @@ Rancher relies on a periodic refresh of the `rke-metadata-config` to download ne
If you have an air gap setup, you might not be able to get the automatic periodic refresh of the Kubernetes metadata from Rancher's Git repository. In that case, you should disable the periodic refresh to prevent your logs from showing errors. Optionally, you can configure your metadata settings so that Rancher can sync with a local copy of the RKE metadata. If you have an air gap setup, you might not be able to get the automatic periodic refresh of the Kubernetes metadata from Rancher's Git repository. In that case, you should disable the periodic refresh to prevent your logs from showing errors. Optionally, you can configure your metadata settings so that Rancher can sync with a local copy of the RKE metadata.
To sync Rancher with a local mirror of the RKE metadata, an administrator would configure the `rke-metadata-config` settings by updating the `url` and `branch` to point to the mirror. To sync Rancher with a local mirror of the RKE metadata, an administrator would configure the `rke-metadata-config` settings to point to the mirror. For details, refer to [Configuring the Metadata Synchronization.](#configuring-the-metadata-synchronization)
After new Kubernetes versions are loaded into the Rancher setup, additional steps would be required in order to use them for launching clusters. Rancher needs access to updated system images. While the metadata settings can only be changed by administrators, any user can download the Rancher system images and prepare a private Docker registry for them. After new Kubernetes versions are loaded into the Rancher setup, additional steps would be required in order to use them for launching clusters. Rancher needs access to updated system images. While the metadata settings can only be changed by administrators, any user can download the Rancher system images and prepare a private Docker registry for them.
content/rancher/v2.x/en/admin-settings/pod-security-policies/_index.md
+2
View File
@@ -9,6 +9,8 @@ aliases:
_Pod Security Policies_ (or PSPs) are objects that control security-sensitive aspects of pod specification (like root privileges). If a pod does not meet the conditions specified in the PSP, Kubernetes will not allow it to start, and Rancher will display an error message of `Pod <NAME> is forbidden: unable to validate...`. _Pod Security Policies_ (or PSPs) are objects that control security-sensitive aspects of pod specification (like root privileges). If a pod does not meet the conditions specified in the PSP, Kubernetes will not allow it to start, and Rancher will display an error message of `Pod <NAME> is forbidden: unable to validate...`.
> **Note:** Assigning Pod Security Policies are only available for clusters that are [launched using RKE.]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/)
- You can assign PSPs at the cluster or project level. - You can assign PSPs at the cluster or project level.
- PSPs work through inheritance. - PSPs work through inheritance.
content/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/_index.md
+2 -2
View File
@@ -67,7 +67,7 @@ To assign the role to a new cluster member,
To assign any custom role to an existing cluster member, To assign any custom role to an existing cluster member,
1. Go to the member you want to give the role to. Click the **Ellipsis (...) > View in API.** 1. Go to the member you want to give the role to. Click the **&#8942; > View in API.**
1. In the **roleTemplateId** field, go to the drop-down menu and choose the role you want to assign to the member. Click **Show Request** and **Send Request.** 1. In the **roleTemplateId** field, go to the drop-down menu and choose the role you want to assign to the member. Click **Show Request** and **Send Request.**
**Result:** The member has the assigned role. **Result:** The member has the assigned role.
@@ -157,7 +157,7 @@ You can change the cluster or project role(s) that are automatically assigned to
1. From the **Global** view, select **Security > Roles** from the main menu. Select either the **Cluster** or **Project** tab. 1. From the **Global** view, select **Security > Roles** from the main menu. Select either the **Cluster** or **Project** tab.
1. Find the custom or individual role that you want to use as default. Then edit the role by selecting **Ellipsis > Edit**. 1. Find the custom or individual role that you want to use as default. Then edit the role by selecting **&#8942; > Edit**.
1. Enable the role as default. 1. Enable the role as default.
{{% accordion id="cluster" label="For Clusters" %}} {{% accordion id="cluster" label="For Clusters" %}}
content/rancher/v2.x/en/admin-settings/rbac/default-custom-roles/_index.md
+10 -11
View File
@@ -13,8 +13,7 @@ This section covers the following topics:
- [Prerequisites](#prerequisites) - [Prerequisites](#prerequisites)
- [Creating a custom role for a cluster or project](#creating-a-custom-role-for-a-cluster-or-project) - [Creating a custom role for a cluster or project](#creating-a-custom-role-for-a-cluster-or-project)
- [Creating a custom global role that copies rules from an existing role](#creating-a-custom-global-role-that-copies-rules-from-an-existing-role) - [Creating a custom global role](#creating-a-custom-global-role)
- [Creating a custom global role that does not copy rules from another role](#creating-a-custom-global-role-that-does-not-copy-rules-from-another-role)
- [Deleting a custom global role](#deleting-a-custom-global-role) - [Deleting a custom global role](#deleting-a-custom-global-role)
- [Assigning a custom global role to a group](#assigning-a-custom-global-role-to-a-group) - [Assigning a custom global role to a group](#assigning-a-custom-global-role-to-a-group)
@@ -93,9 +92,11 @@ The steps to add custom roles differ depending on the version of Rancher.
{{% /tab %}} {{% /tab %}}
{{% /tabs %}} {{% /tabs %}}
## Creating a Custom Global Role that Copies Rules from an Existing Role ## Creating a Custom Global Role
_Available as of v2.4.0-alpha1_ _Available as of v2.4.0_
### Creating a Custom Global Role that Copies Rules from an Existing Role
If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role in which all of the rules from another role, such as the administrator role, are copied into a new role. This allows you to only configure the variations between the existing role and the new role. If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role in which all of the rules from another role, such as the administrator role, are copied into a new role. This allows you to only configure the variations between the existing role and the new role.
@@ -104,15 +105,13 @@ The custom global role can then be assigned to a user or group so that the custo
To create a custom global role based on an existing role, To create a custom global role based on an existing role,
1. Go to the **Global** view and click **Security > Roles.** 1. Go to the **Global** view and click **Security > Roles.**
1. On the **Global** tab, go to the role that the custom global role will be based on. Click **Ellipsis (…) > Clone.** 1. On the **Global** tab, go to the role that the custom global role will be based on. Click **&#8942; (…) > Clone.**
1. Enter a name for the role. 1. Enter a name for the role.
1. Optional: To assign the custom role default for new users, go to the **New User Default** section and click **Yes: Default role for new users.** 1. Optional: To assign the custom role default for new users, go to the **New User Default** section and click **Yes: Default role for new users.**
1. In the **Grant Resources** section, select the Kubernetes resource operations that will be enabled for users with the custom role. 1. In the **Grant Resources** section, select the Kubernetes resource operations that will be enabled for users with the custom role.
1. Click **Save.** 1. Click **Save.**
## Creating a Custom Global Role that Does Not Copy Rules from Another Role ### Creating a Custom Global Role that Does Not Copy Rules from Another Role
_Available as of v2.4.0-alpha1_
Custom global roles don't have to be based on existing roles. To create a custom global role by choosing the specific Kubernetes resource operations that should be allowed for the role, follow these steps: Custom global roles don't have to be based on existing roles. To create a custom global role by choosing the specific Kubernetes resource operations that should be allowed for the role, follow these steps:
@@ -125,7 +124,7 @@ Custom global roles don't have to be based on existing roles. To create a custom
## Deleting a Custom Global Role ## Deleting a Custom Global Role
_Available as of v2.4.0-alpha1_ _Available as of v2.4.0_
When deleting a custom global role, all global role bindings with this custom role are deleted. When deleting a custom global role, all global role bindings with this custom role are deleted.
@@ -136,12 +135,12 @@ Custom global roles can be deleted, but built-in roles cannot be deleted.
To delete a custom global role, To delete a custom global role,
1. Go to the **Global** view and click **Security > Roles.** 1. Go to the **Global** view and click **Security > Roles.**
2. On the **Global** tab, go to the custom global role that should be deleted and click **Ellipsis (…) > Delete.** 2. On the **Global** tab, go to the custom global role that should be deleted and click **&#8942; (…) > Delete.**
3. Click **Delete.** 3. Click **Delete.**
## Assigning a Custom Global Role to a Group ## Assigning a Custom Global Role to a Group
_Available as of v2.4.0-alpha1_ _Available as of v2.4.0_
If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role. When the role is assigned to a group, the users in the group have the appropriate level of access the first time they sign into Rancher. If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role. When the role is assigned to a group, the users in the group have the appropriate level of access the first time they sign into Rancher.
content/rancher/v2.x/en/admin-settings/rbac/global-permissions/_index.md
+4 -4
View File
@@ -43,7 +43,7 @@ To see the default permissions for new users, go to the **Global** view and clic
Permissions can be assigned to an individual user with [these steps.](#configuring-global-permissions-for-existing-individual-users) Permissions can be assigned to an individual user with [these steps.](#configuring-global-permissions-for-existing-individual-users)
As of Rancher v2.4.0-alpha1, you can [assign a role to everyone in the group at the same time](#configuring-global-permissions-for-groups) if the external authentication provider supports groups. As of Rancher v2.4.0, you can [assign a role to everyone in the group at the same time](#configuring-global-permissions-for-groups) if the external authentication provider supports groups.
# Custom Global Permissions # Custom Global Permissions
@@ -102,7 +102,7 @@ To change the default global permissions that are assigned to external users upo
1. From the **Global** view, select **Security > Roles** from the main menu. Make sure the **Global** tab is selected. 1. From the **Global** view, select **Security > Roles** from the main menu. Make sure the **Global** tab is selected.
1. Find the permissions set that you want to add or remove as a default. Then edit the permission by selecting **Ellipsis > Edit**. 1. Find the permissions set that you want to add or remove as a default. Then edit the permission by selecting **&#8942; > Edit**.
1. If you want to add the permission as a default, Select **Yes: Default role for new users** and then click **Save**. 1. If you want to add the permission as a default, Select **Yes: Default role for new users** and then click **Save**.
@@ -116,7 +116,7 @@ To configure permission for a user,
1. Go to the **Users** tab. 1. Go to the **Users** tab.
1. On this page, go to the user whose access level you want to change and click **Ellipsis (...) > Edit.** 1. On this page, go to the user whose access level you want to change and click **&#8942; > Edit.**
1. In the **Global Permissions** section, click **Custom.** 1. In the **Global Permissions** section, click **Custom.**
@@ -128,7 +128,7 @@ To configure permission for a user,
### Configuring Global Permissions for Groups ### Configuring Global Permissions for Groups
_Available as of v2.4.0-alpha1_ _Available as of v2.4.0_
If you have a group of individuals that need the same level of access in Rancher, it can save time to assign permissions to the entire group at once, so that the users in the group have the appropriate level of access the first time they sign into Rancher. If you have a group of individuals that need the same level of access in Rancher, it can save time to assign permissions to the entire group at once, so that the users in the group have the appropriate level of access the first time they sign into Rancher.
content/rancher/v2.x/en/admin-settings/rbac/locked-roles/_index.md
+1 -1
View File
@@ -32,6 +32,6 @@ You can lock roles in two contexts:
1. From the **Global** view, select **Security** > **Roles**. 1. From the **Global** view, select **Security** > **Roles**.
2. From the role that you want to lock (or unlock), select **Vertical Ellipsis (...)** > **Edit**. 2. From the role that you want to lock (or unlock), select **&#8942;** > **Edit**.
3. From the **Locked** option, choose the **Yes** or **No** radio button. Then click **Save**. 3. From the **Locked** option, choose the **Yes** or **No** radio button. Then click **Save**.
content/rancher/v2.x/en/admin-settings/rke-templates/applying-templates/_index.md
+1 -1
View File
@@ -53,7 +53,7 @@ RKE templates cannot be applied to existing clusters, except if you save an exis
To convert an existing cluster to use an RKE template, To convert an existing cluster to use an RKE template,
1. From the **Global** view in Rancher, click the **Clusters** tab. 1. From the **Global** view in Rancher, click the **Clusters** tab.
1. Go to the cluster that will be converted to use an RKE template. Click **Ellipsis (...)** > **Save as RKE Template.** 1. Go to the cluster that will be converted to use an RKE template. Click **&#8942;** > **Save as RKE Template.**
1. Enter a name for the template in the form that appears, and click **Create.** 1. Enter a name for the template in the form that appears, and click **Create.**
**Results:** **Results:**
content/rancher/v2.x/en/admin-settings/rke-templates/creating-and-revising/_index.md
+11 -11
View File
@@ -40,7 +40,7 @@ You can revise, share, and delete a template if you are an owner of the template
1. Optional: Share the template with other users or groups by [adding them as members.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-templates-with-specific-users) You can also make the template public to share with everyone in the Rancher setup. 1. Optional: Share the template with other users or groups by [adding them as members.]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rke-templates/template-access-and-sharing/#sharing-templates-with-specific-users) You can also make the template public to share with everyone in the Rancher setup.
1. Then follow the form on screen to save the cluster configuration parameters as part of the template's revision. The revision can be marked as default for this template. 1. Then follow the form on screen to save the cluster configuration parameters as part of the template's revision. The revision can be marked as default for this template.
**Result:** An RKE template with one revision is configured. You can use this RKE template revision later when you [provision a Rancher-launched cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters). **Result:** An RKE template with one revision is configured. You can use this RKE template revision later when you [provision a Rancher-launched cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters). After a cluster is managed by an RKE template, it cannot be disconnected and the option to uncheck **Use an existing RKE Template and Revision** will be unavailable.
### Updating a Template ### Updating a Template
@@ -51,7 +51,7 @@ You can't edit individual revisions. Since you can't edit individual revisions o
When new template revisions are created, clusters using an older revision of the template are unaffected. When new template revisions are created, clusters using an older revision of the template are unaffected.
1. From the **Global** view, click **Tools > RKE Templates.** 1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the template that you want to edit and click the **Vertical Ellipsis (...) > Edit.** 1. Go to the template that you want to edit and click the **&#8942; > Edit.**
1. Edit the required information and click **Save.** 1. Edit the required information and click **Save.**
1. Optional: You can change the default revision of this template and also change who it is shared with. 1. Optional: You can change the default revision of this template and also change who it is shared with.
@@ -62,7 +62,7 @@ When new template revisions are created, clusters using an older revision of the
When you no longer use an RKE template for any of your clusters, you can delete it. When you no longer use an RKE template for any of your clusters, you can delete it.
1. From the **Global** view, click **Tools > RKE Templates.** 1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the RKE template that you want to delete and click the **Vertical Ellipsis (...) > Delete.** 1. Go to the RKE template that you want to delete and click the **&#8942; > Delete.**
1. Confirm the deletion when prompted. 1. Confirm the deletion when prompted.
**Result:** The template is deleted. **Result:** The template is deleted.
@@ -72,7 +72,7 @@ When you no longer use an RKE template for any of your clusters, you can delete
You can clone the default template revision and quickly update its settings rather than creating a new revision from scratch. Cloning templates saves you the hassle of re-entering the access keys and other parameters needed for cluster creation. You can clone the default template revision and quickly update its settings rather than creating a new revision from scratch. Cloning templates saves you the hassle of re-entering the access keys and other parameters needed for cluster creation.
1. From the **Global** view, click **Tools > RKE Templates.** 1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the RKE template that you want to clone and click the **Vertical Ellipsis (...) > New Revision From Default.** 1. Go to the RKE template that you want to clone and click the **&#8942; > New Revision From Default.**
1. Complete the rest of the form to create a new revision. 1. Complete the rest of the form to create a new revision.
**Result:** The RKE template revision is cloned and configured. **Result:** The RKE template revision is cloned and configured.
@@ -82,7 +82,7 @@ You can clone the default template revision and quickly update its settings rath
When creating new RKE template revisions from your user settings, you can clone an existing revision and quickly update its settings rather than creating a new one from scratch. Cloning template revisions saves you the hassle of re-entering the cluster parameters. When creating new RKE template revisions from your user settings, you can clone an existing revision and quickly update its settings rather than creating a new one from scratch. Cloning template revisions saves you the hassle of re-entering the cluster parameters.
1. From the **Global** view, click **Tools > RKE Templates.** 1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the template revision you want to clone. Then select **Ellipsis > Clone Revision.** 1. Go to the template revision you want to clone. Then select **&#8942; > Clone Revision.**
1. Complete the rest of the form. 1. Complete the rest of the form.
**Result:** The RKE template revision is cloned and configured. You can use the RKE template revision later when you provision a cluster. Any existing cluster using this RKE template can be upgraded to this new revision. **Result:** The RKE template revision is cloned and configured. You can use the RKE template revision later when you provision a cluster. Any existing cluster using this RKE template can be upgraded to this new revision.
@@ -94,7 +94,7 @@ When you no longer want an RKE template revision to be used for creating new clu
You can disable the revision if it is not being used by any cluster. You can disable the revision if it is not being used by any cluster.
1. From the **Global** view, click **Tools > RKE Templates.** 1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the template revision you want to disable. Then select **Ellipsis > Disable.** 1. Go to the template revision you want to disable. Then select **&#8942; > Disable.**
**Result:** The RKE template revision cannot be used to create a new cluster. **Result:** The RKE template revision cannot be used to create a new cluster.
@@ -103,7 +103,7 @@ You can disable the revision if it is not being used by any cluster.
If you decide that a disabled RKE template revision should be used to create new clusters, you can re-enable it. If you decide that a disabled RKE template revision should be used to create new clusters, you can re-enable it.
1. From the **Global** view, click **Tools > RKE Templates.** 1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the template revision you want to re-enable. Then select **Ellipsis > Enable.** 1. Go to the template revision you want to re-enable. Then select **&#8942; > Enable.**
**Result:** The RKE template revision can be used to create a new cluster. **Result:** The RKE template revision can be used to create a new cluster.
@@ -114,7 +114,7 @@ When end users create a cluster using an RKE template, they can choose which rev
To set an RKE template revision as default, To set an RKE template revision as default,
1. From the **Global** view, click **Tools > RKE Templates.** 1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the RKE template revision that should be default and click the **Ellipsis (...) > Set as Default.** 1. Go to the RKE template revision that should be default and click the **&#8942; > Set as Default.**
**Result:** The RKE template revision will be used as the default option when clusters are created with the template. **Result:** The RKE template revision will be used as the default option when clusters are created with the template.
@@ -125,7 +125,7 @@ You can delete all revisions of a template except for the default revision.
To permanently delete a revision, To permanently delete a revision,
1. From the **Global** view, click **Tools > RKE Templates.** 1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the RKE template revision that should be deleted and click the **Ellipsis (...) > Delete.** 1. Go to the RKE template revision that should be deleted and click the **&#8942; > Delete.**
**Result:** The RKE template revision is deleted. **Result:** The RKE template revision is deleted.
@@ -137,7 +137,7 @@ To permanently delete a revision,
To upgrade a cluster to use a new template revision, To upgrade a cluster to use a new template revision,
1. From the **Global** view in Rancher, click the **Clusters** tab. 1. From the **Global** view in Rancher, click the **Clusters** tab.
1. Go to the cluster that you want to upgrade and click **Ellipsis (...) > Edit.** 1. Go to the cluster that you want to upgrade and click **&#8942; > Edit.**
1. In the **Cluster Options** section, click the dropdown menu for the template revision, then select the new template revision. 1. In the **Cluster Options** section, click the dropdown menu for the template revision, then select the new template revision.
1. Click **Save.** 1. Click **Save.**
@@ -152,7 +152,7 @@ This exports the cluster's settings as a new RKE template, and also binds the cl
To convert an existing cluster to use an RKE template, To convert an existing cluster to use an RKE template,
1. From the **Global** view in Rancher, click the **Clusters** tab. 1. From the **Global** view in Rancher, click the **Clusters** tab.
1. Go to the cluster that will be converted to use an RKE template. Click **Ellipsis (...)** > **Save as RKE Template.** 1. Go to the cluster that will be converted to use an RKE template. Click **&#8942;** > **Save as RKE Template.**
1. Enter a name for the template in the form that appears, and click **Create.** 1. Enter a name for the template in the form that appears, and click **Create.**
**Results:** **Results:**
content/rancher/v2.x/en/admin-settings/rke-templates/creator-permissions/_index.md
+3 -3
View File
@@ -24,7 +24,7 @@ Administrators can give users permission to create RKE templates in two ways:
An administrator can individually grant the role **Create RKE Templates** to any existing user by following these steps: An administrator can individually grant the role **Create RKE Templates** to any existing user by following these steps:
1. From the global view, click the **Users** tab. Choose the user you want to edit and click the **Vertical Ellipsis (...) > Edit.** 1. From the global view, click the **Users** tab. Choose the user you want to edit and click the **&#8942; > Edit.**
1. In the **Global Permissions** section, choose **Custom** and select the **Create RKE Templates** role along with any other roles the user should have. Click **Save.** 1. In the **Global Permissions** section, choose **Custom** and select the **Create RKE Templates** role along with any other roles the user should have. Click **Save.**
**Result:** The user has permission to create RKE templates. **Result:** The user has permission to create RKE templates.
@@ -34,7 +34,7 @@ An administrator can individually grant the role **Create RKE Templates** to any
Alternatively, the administrator can give all new users the default permission to create RKE templates by following the following steps. This will not affect the permissions of existing users. Alternatively, the administrator can give all new users the default permission to create RKE templates by following the following steps. This will not affect the permissions of existing users.
1. From the **Global** view, click **Security > Roles.** 1. From the **Global** view, click **Security > Roles.**
1. Under the **Global** roles tab, go to the role **Create RKE Templates** and click the **Vertical Ellipsis (...) > Edit**. 1. Under the **Global** roles tab, go to the role **Create RKE Templates** and click the **&#8942; > Edit**.
1. Select the option **Yes: Default role for new users** and click **Save.** 1. Select the option **Yes: Default role for new users** and click **Save.**
**Result:** Any new user created in this Rancher installation will be able to create RKE templates. Existing users will not get this permission. **Result:** Any new user created in this Rancher installation will be able to create RKE templates. Existing users will not get this permission.
@@ -43,7 +43,7 @@ Alternatively, the administrator can give all new users the default permission t
Administrators can remove a user's permission to create templates with the following steps: Administrators can remove a user's permission to create templates with the following steps:
1. From the global view, click the **Users** tab. Choose the user you want to edit and click the **Vertical Ellipsis (...) > Edit.** 1. From the global view, click the **Users** tab. Choose the user you want to edit and click the **&#8942; > Edit.**
1. In the **Global Permissions** section, un-check the box for **Create RKE Templates**. In this section, you can change the user back to a standard user, or give the user a different set of custom permissions. 1. In the **Global Permissions** section, un-check the box for **Create RKE Templates**. In this section, you can change the user back to a standard user, or give the user a different set of custom permissions.
1. Click **Save.** 1. Click **Save.**
content/rancher/v2.x/en/admin-settings/rke-templates/enforcement/_index.md
+2 -2
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: 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. From the **Global** view, click the **Settings** tab.
1. Go to the `cluster-template-enforcement` setting. Click the vertical **Ellipsis (...)** and click **Edit.** 1. Go to the `cluster-template-enforcement` setting. Click the vertical **&#8942;** and click **Edit.**
1. Set the value to **True** and click **Save.** 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. **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: 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. From the **Global** view, click the **Settings** tab.
1. Go to the `cluster-template-enforcement` setting. Click the vertical **Ellipsis (...)** and click **Edit.** 1. Go to the `cluster-template-enforcement` setting. Click the vertical **&#8942;** and click **Edit.**
1. Set the value to **False** and click **Save.** 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/template-access-and-sharing/_index.md
+3 -3
View File
@@ -28,7 +28,7 @@ There are several ways to share templates:
To allow users or groups to create clusters using your template, you can give them the basic **User** access level for the template. To allow users or groups to create clusters using your template, you can give them the basic **User** access level for the template.
1. From the **Global** view, click **Tools > RKE Templates.** 1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the template that you want to share and click the **Vertical Ellipsis (...) > Edit.** 1. Go to the template that you want to share and click the **&#8942; > Edit.**
1. In the **Share Template** section, click on **Add Member**. 1. In the **Share Template** section, click on **Add Member**.
1. Search in the **Name** field for the user or group you want to share the template with. 1. Search in the **Name** field for the user or group you want to share the template with.
1. Choose the **User** access type. 1. Choose the **User** access type.
@@ -39,7 +39,7 @@ To allow users or groups to create clusters using your template, you can give th
### Sharing Templates with All Users ### Sharing Templates with All Users
1. From the **Global** view, click **Tools > RKE Templates.** 1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the template that you want to share and click the **Vertical Ellipsis (...) > Edit.** 1. Go to the template that you want to share and click the **&#8942; > Edit.**
1. Under **Share Template,** click **Make Public (read-only).** Then click **Save.** 1. Under **Share Template,** click **Make Public (read-only).** Then click **Save.**
**Result:** All users in the Rancher setup can create clusters using the template. **Result:** All users in the Rancher setup can create clusters using the template.
@@ -53,7 +53,7 @@ In that case, you can give users the Owner access type, which allows another use
To give Owner access to a user or group, To give Owner access to a user or group,
1. From the **Global** view, click **Tools > RKE Templates.** 1. From the **Global** view, click **Tools > RKE Templates.**
1. Go to the RKE template that you want to share and click the **Vertical Ellipsis (...) > Edit.** 1. Go to the RKE template that you want to share and click the **&#8942; > Edit.**
1. Under **Share Template**, click on **Add Member** and search in the **Name** field for the user or group you want to share the template with. 1. Under **Share Template**, click on **Add Member** and search in the **Name** field for the user or group you want to share the template with.
1. In the **Access Type** field, click **Owner.** 1. In the **Access Type** field, click **Owner.**
1. Click **Save.** 1. Click **Save.**
content/rancher/v2.x/en/backups/_index.md
+4 -3
View File
@@ -5,13 +5,14 @@ weight: 1000
This section is devoted to protecting your data in a disaster scenario. This section is devoted to protecting your data in a disaster scenario.
To protect yourself from a disaster scenario, you should create backups on a regular basis. To protect yourself from a disaster scenario, you should create backups on a regular basis.
- [Rancher Server Backups]({{< baseurl >}}/rancher/v2.x/en/backups/backups) - Rancher server backups:
- [Rancher installed on a K3s Kubernetes cluster](./backups/k3s-backups)
- [Rancher installed on an RKE Kubernetes cluster](./backups/ha-backups)
- [Rancher installed with Docker](./backups/single-node-backups/)
- [Backing up Rancher Launched Kubernetes Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/) - [Backing up Rancher Launched Kubernetes Clusters]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/)
In a disaster scenario, you can restore your `etcd` database by restoring a backup. In a disaster scenario, you can restore your `etcd` database by restoring a backup.
- [Rancher Server Restorations]({{<baseurl>}}/rancher/v2.x/en/backups/restorations) - [Rancher Server Restorations]({{<baseurl>}}/rancher/v2.x/en/backups/restorations)
content/rancher/v2.x/en/backups/backups/_index.md
+3 -2
View File
@@ -7,7 +7,8 @@ aliases:
--- ---
This section contains information about how to create backups of your Rancher data and how to restore them in a disaster scenario. This section contains information about how to create backups of your Rancher data and how to restore them in a disaster scenario.
- [Docker Install Backups](./single-node-backups/) - [Backing up Rancher installed on a K3s Kubernetes cluster](./k3s-backups)
- [Kubernetes Install Backups](./ha-backups/) - [Backing up Rancher installed on an RKE Kubernetes cluster](./ha-backups/)
- [Backing up Rancher installed with Docker](./single-node-backups/)
If you are looking to back up your [Rancher launched Kubernetes cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), please refer [here]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/). If you are looking to back up your [Rancher launched Kubernetes cluster]({{<baseurl>}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/), please refer [here]({{<baseurl>}}/rancher/v2.x/en/cluster-admin/backing-up-etcd/).
content/rancher/v2.x/en/backups/backups/ha-backups/_index.md
+9 -2
View File
@@ -1,6 +1,6 @@
--- ---
title: Creating Backups for Rancher Installed on Kubernetes title: Backing up Rancher Installed on an RKE Kubernetes Cluster
weight: 50 weight: 2
aliases: aliases:
- /rancher/v2.x/en/installation/after-installation/k8s-install-backup-and-restoration/ - /rancher/v2.x/en/installation/after-installation/k8s-install-backup-and-restoration/
- /rancher/v2.x/en/installation/backups-and-restoration/ha-backup-and-restoration/ - /rancher/v2.x/en/installation/backups-and-restoration/ha-backup-and-restoration/
@@ -9,6 +9,13 @@ This section describes how to create backups of your high-availability Rancher i
>**Prerequisites:** {{< requirements_rollback >}} >**Prerequisites:** {{< requirements_rollback >}}
## RKE Kubernetes Cluster Data
In an RKE installation, the cluster data is replicated on each of three etcd nodes in the cluster, providing redundancy and data duplication in case one of the nodes fails.
<figcaption>Architecture of an RKE Kubernetes Cluster Running the Rancher Management Server</figcaption>
![Architecture of an RKE Kubernetes cluster running the Rancher management server]({{<baseurl>}}/img/rancher/rke-server-storage.svg)
## Backup Outline ## Backup Outline
Backing up your high-availability Rancher cluster is process that involves completing multiple tasks. Backing up your high-availability Rancher cluster is process that involves completing multiple tasks.
content/rancher/v2.x/en/backups/backups/k3s-backups/_index.md
+25
View File
@@ -0,0 +1,25 @@
---
title: Backing up Rancher Installed on a K3s Kubernetes Cluster
weight: 1
---
When Rancher is installed on a high-availability Kubernetes cluster, we recommend using an external database to store the cluster data.
The database administrator will need to back up the external database, or restore it from a snapshot or dump.
We recommend configuring the database to take recurring snapshots.
### K3s Kubernetes Cluster Data
One main advantage of this K3s architecture is that it allows an external datastore to hold the cluster data, allowing the K3s server nodes to be treated as ephemeral.
<figcaption>Architecture of a K3s Kubernetes Cluster Running the Rancher Management Server</figcaption>
![Architecture of an RKE Kubernetes Cluster Running the Rancher Management Server]({{<baseurl>}}/img/rancher/k3s-server-storage.svg)
### Creating Snapshots and Restoring Databases from Snapshots
For details on taking database snapshots and restoring your database from them, refer to the official database documentation:
- [Official MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/replication-snapshot-method.html)
- [Official PostgreSQL documentation](https://www.postgresql.org/docs/8.3/backup-dump.html)
- [Official etcd documentation](https://github.com/etcd-io/etcd/blob/master/Documentation/op-guide/recovery.md)
content/rancher/v2.x/en/backups/backups/single-node-backups/_index.md
+2 -2
View File
@@ -1,6 +1,6 @@
--- ---
title: Creating Backups for Rancher Installed with Docker title: Backing up Rancher Installed with Docker
weight: 25 weight: 3
aliases: aliases:
- /rancher/v2.x/en/installation/after-installation/single-node-backup-and-restoration/ - /rancher/v2.x/en/installation/after-installation/single-node-backup-and-restoration/
--- ---
content/rancher/v2.x/en/backups/restorations/k3s-restoration/_index.md
+18
View File
@@ -0,0 +1,18 @@
---
title: Restoring Rancher Installed on a K3s Kubernetes Cluster
weight: 1
---
When Rancher is installed on a high-availability Kubernetes cluster, we recommend using an external database to store the cluster data.
The database administrator will need to back up the external database, or restore it from a snapshot or dump.
We recommend configuring the database to take recurring snapshots.
### Creating Snapshots and Restoring Databases from Snapshots
For details on taking database snapshots and restoring your database from them, refer to the official database documentation:
- [Official MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/replication-snapshot-method.html)
- [Official PostgreSQL documentation](https://www.postgresql.org/docs/8.3/backup-dump.html)
- [Official etcd documentation](https://github.com/etcd-io/etcd/blob/master/Documentation/op-guide/recovery.md)
content/rancher/v2.x/en/catalog/_index.md
+29 -114
View File
@@ -17,31 +17,17 @@ Rancher improves on Helm catalogs and charts. All native Helm charts can work wi
This section covers the following topics: This section covers the following topics:
- [Prerequisites](#prerequisites)
- [Catalog scopes](#catalog-scopes) - [Catalog scopes](#catalog-scopes)
- [Enabling built-in global catalogs](#enabling-built-in-global-catalogs) - [Catalog Helm Deployment Versions](#catalog-helm-deployment-versions)
- [Adding custom global catalogs](#adding-custom-global-catalogs) - [Built-in global catalogs](#built-in-global-catalogs)
- [Add custom Git repositories](#add-custom-git-repositories) - [Custom catalogs](#custom-catalogs)
- [Add custom Helm chart repositories](#add-custom-helm-chart-repositories) - [Creating and launching applications](#creating-and-launching-applications)
- [Add private Git/Helm chart repositories](#add-private-git-helm-chart-repositories)
- [Launching catalog applications](#launching-catalog-applications)
- [Working with catalogs](#working-with-catalogs)
- [Apps](#apps)
- [Global DNS](#global-dns)
- [Chart compatibility with Rancher](#chart-compatibility-with-rancher) - [Chart compatibility with Rancher](#chart-compatibility-with-rancher)
- [Global DNS](#global-dns)
# Prerequisites
When Rancher deploys a catalog app, it launches an ephemeral instance of a Helm service account that has the permissions of the user deploying the catalog app. Therefore, a user cannot gain more access to the cluster through Helm or a catalog application than they otherwise would have.
To launch a catalog app or a multi-cluster app, you should have at least one of the following permissions:
- A [project-member role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) in the target cluster, which gives you the ability to create, read, update, and delete the workloads
- A [cluster owner role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) for the cluster that include the target project
# Catalog Scopes # Catalog Scopes
Within Rancher, you can manage catalogs at three different scopes. Global catalogs are shared across all clusters and project. There are some use cases where you might not want to share catalogs across between different clusters or even projects in the same cluster. By leveraging cluster and project scoped catalogs, you will be able to provide applications for specific teams without needing to share them with all clusters and/or projects. Within Rancher, you can manage catalogs at three different scopes. Global catalogs are shared across all clusters and project. There are some use cases where you might not want to share catalogs between different clusters or even projects in the same cluster. By leveraging cluster and project scoped catalogs, you will be able to provide applications for specific teams without needing to share them with all clusters and/or projects.
Scope | Description | Available As of | Scope | Description | Available As of |
--- | --- | --- | --- | --- | --- |
@@ -49,119 +35,48 @@ Global | All clusters and all projects can access the Helm charts in this catalo
Cluster | All projects in the specific cluster can access the Helm charts in this catalog | v2.2.0 | Cluster | All projects in the specific cluster can access the Helm charts in this catalog | v2.2.0 |
Project | This specific cluster can access the Helm charts in this catalog | v2.2.0 | Project | This specific cluster can access the Helm charts in this catalog | v2.2.0 |
# Enabling Built-in Global Catalogs # Catalog Helm Deployment Versions
Within Rancher, there are default catalogs packaged as part of Rancher. These can be enabled or disabled by an administrator. _Applicable as of v2.4.0_
1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions prior to v2.2.0, you can select **Catalogs** directly in the navigation bar. In November 2019, Helm 3 was released, and some features were deprecated or refactored. It is not fully backwards compatible with Helm 2. Therefore, catalogs in Rancher need to be separated, with each catalog only using one Helm version.
2. Toggle the default catalogs that you want use to a setting of **Enabled**. When you create a custom catalog, you will have to configure the catalog to use either Helm 2 or Helm 3. This version cannot be changed later. If the catalog is added with the wrong Helm version, it will need to be deleted and re-added.
- **Library** When you launch a new app from a catalog, the app will be managed by the catalog's Helm version. A Helm 2 catalog will use Helm 2 to manage all of the apps, and a Helm 3 catalog will use Helm 3 to manage all apps.
The Library Catalog includes charts curated by Rancher. Rancher stores charts in a Git repository to expedite the fetch and update of charts. In Rancher 2.x, only global catalogs are supported. Support for cluster-level and project-level charts will be added in the future. By default, catalogs are assumed to be deployed using Helm 2. If you run an app in Rancher prior to v2.4.0, then upgrade to Rancher v2.4.0+, the app will still be managed by Helm 2. If the app was already using a Helm 3 Chart (API version 2) it will no longer work in v2.4.0+. You must either downgrade the chart's API version or recreate the catalog to use Helm 3.
This catalog features Rancher Charts, which include some [notable advantages]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/#chart-types) over native Helm charts. Charts that are specific to Helm 2 should only be added to a Helm 2 catalog, and Helm 3 specific charts should only be added to a Helm 3 catalog.
- **Helm Stable** # Built-in Global Catalogs
This catalog, , which is maintained by the Kubernetes community, includes native [Helm charts](https://github.com/kubernetes/helm/blob/master/docs/chart_template_guide/getting_started.md). This catalog features the largest pool of apps. Within Rancher, there are default catalogs packaged as part of Rancher. These can be enabled or disabled by an administrator. For details, refer to the section on managing [built-in global catalogs.]({{<baseurl>}}/rancher/v2.x/en/catalog/built-in)
- **Helm Incubator** # Custom Catalogs
Similar in user experience to Helm Stable, but this catalog is filled with applications in **beta**. There are two types of catalogs in Rancher: [Built-in global catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/built-in/) and [custom catalogs.]({{<baseurl>}}/rancher/v2.x/en/catalog/adding-catalogs/)
**Result**: The chosen catalogs are enabled. Wait a few minutes for Rancher to replicate the catalog charts. When replication completes, you'll be able to see them in any of your projects by selecting **Apps** from the main navigation bar. In versions prior to v2.2.0, you can select **Catalog Apps** from the main navigation bar. Any user can create custom catalogs to add into Rancher. Custom catalogs can be added into Rancher at the global level, cluster level, or project level. For details, refer to the [section on adding custom catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/adding-catalogs) and the [catalog configuration reference.]({{<baseurl>}}/rancher/v2.x/en/catalog/catalog-config)
# Adding Custom Global Catalogs # Creating and Launching Applications
Adding a catalog is as simple as adding a catalog name, a URL and a branch name. In Rancher, applications are deployed from the templates in a catalog. This section covers the following topics:
### Add Custom Git Repositories
The Git URL needs to be one that `git clone` [can handle](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) and must end in `.git`. The branch name must be a branch that is in your catalog URL. If no branch name is provided, it will use the `master` branch by default. Whenever you add a catalog to Rancher, it will be available immediately.
### Add Custom Helm Chart Repositories
A Helm chart repository is an HTTP server that houses one or more packaged charts. Any HTTP server that can serve YAML files and tar files and can answer GET requests can be used as a repository server.
Helm comes with built-in package server for developer testing (helm serve). The Helm team has tested other servers, including Google Cloud Storage with website mode enabled, S3 with website mode enabled or hosting custom chart repository server using open-source projects like [ChartMuseum](https://github.com/helm/chartmuseum).
In Rancher, you can add the custom Helm chart repository with only a catalog name and the URL address of the chart repository.
### Add Private Git/Helm Chart Repositories
_Available as of v2.2.0_
In Rancher v2.2.0, you can add private catalog repositories using credentials like Username and Password. You may also want to use the
OAuth token if your Git or Helm repository server support that.
[Read More About Adding Private Git/Helm Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/#private-repositories)
<!--There are two types of catalogs that can be added into Rancher. There are global catalogs and project catalogs. In a global catalog, the catalog templates are available in *all* projects. In a project catalog, the catalog charts are only available in the project that the catalog is added to.
An [admin]({{< baseurl >}}/rancher/v2.x/en/admin-settings/#global-Permissions) of Rancher has the ability to add or remove catalogs globally in Rancher.
NEEDS TO BE FIXED FOR 2.0: Any [users]({{site.baseurl}}/rancher/{{page.version}}/{{page.lang}}/configuration/accounts/#account-types) of a Rancher environment has the ability to add or remove environment catalogs in their respective Rancher environment in **Catalog** -> **Manage**.
-->
1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions prior to v2.2.0, you can select **Catalogs** directly in the navigation bar.
2. Click **Add Catalog**.
3. Complete the form and click **Create**.
**Result**: Your catalog is added to Rancher.
# Launching Catalog Applications
After you've either enabled the built-in catalogs or added your own custom catalog, you can start launching any catalog application.>
1. From the **Global** view, open the project that you want to deploy to.
2. From the main navigation bar, choose **Apps**. In versions prior to v2.2.0, choose **Catalog Apps** on the main navigation bar. Click **Launch**.
3. Find the app that you want to launch, and then click **View Now**.
4. Under **Configuration Options** enter a **Name**. By default, this name is also used to create a Kubernetes namespace for the application.
* If you would like to change the **Namespace**, click **Customize** and enter a new name.
* If you want to use a different namespace that already exists, click **Customize**, and then click **Use an existing namespace**. Choose a namespace from the list.
5. Select a **Template Version**.
6. Complete the rest of the **Configuration Options**.
* For native Helm charts (i.e., charts from the **Helm Stable** or **Helm Incubator** catalogs), answers are provided as key value pairs in the **Answers** section.
* Keys and values are available within **Detailed Descriptions**.
* When entering answers, you must format them using the syntax rules found in [Using Helm: The format and limitations of --set](https://helm.sh/docs/intro/using_helm/#the-format-and-limitations-of-set), as Rancher passes them as `--set` flags to Helm.
For example, when entering an answer that includes two values separated by a comma (i.e., `abc, bcd`), wrap the values with double quotes (i.e., `"abc, bcd"`).
7. Review the files in **Preview**. When you're satisfied, click **Launch**.
**Result**: Your application is deployed to your chosen namespace. You can view the application status from the project's:
By creating a customized repository with added files, Rancher improves on Helm repositories and charts. All native Helm charts can work within Rancher, but Rancher adds several enhancements to improve their user experience.
# Working with Catalogs
There are two types of catalogs in Rancher. Learn more about each type:
* [Built-in Global Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/built-in/)
* [Custom Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/)
### Apps
In Rancher, applications are deployed from the templates in a catalog. Rancher supports two types of applications:
* [Multi-cluster applications]({{<baseurl>}}/rancher/v2.x/en/catalog/multi-cluster-apps/) * [Multi-cluster applications]({{<baseurl>}}/rancher/v2.x/en/catalog/multi-cluster-apps/)
* [Applications deployed in a specific Project]({{< baseurl >}}/rancher/v2.x/en/catalog/apps) * [Creating catalog apps]({{<baseurl>}}/rancher/v2.x/en/catalog/creating-apps)
* [Launching catalog apps within a project]({{<baseurl>}}/rancher/v2.x/en/catalog/launching-apps)
* [Managing catalog apps]({{<baseurl>}}/rancher/v2.x/en/catalog/managing-apps)
* [Tutorial: Example custom chart creation]({{<baseurl>}}/rancher/v2.x/en/catalog/tutorial)
### Global DNS # Chart Compatibility with Rancher
Charts now support the fields `rancher_min_version` and `rancher_max_version` in the [`questions.yml` file](https://github.com/rancher/integration-test-charts/blob/master/charts/chartmuseum/v1.6.0/questions.yml) to specify the versions of Rancher that the chart is compatible with. When using the UI, only app versions that are valid for the version of Rancher running will be shown. API validation is done to ensure apps that don't meet the Rancher requirements cannot be launched. An app that is already running will not be affected on a Rancher upgrade if the newer Rancher version does not meet the app's requirements.
# Global DNS
_Available as v2.2.0_ _Available as v2.2.0_
When creating applications that span multiple Kubernetes clusters, a Global DNS entry can be created to route traffic to the endpoints in all of the different clusters. An external DNS server will need be programmed to assign a fully qualified domain name (a.k.a FQDN) to your application. Rancher will use the FQDN you provide and the IP addresses where your application is running to program the DNS. Rancher will gather endpoints from all the Kubernetes clusters running your application and program the DNS. When creating applications that span multiple Kubernetes clusters, a Global DNS entry can be created to route traffic to the endpoints in all of the different clusters. An external DNS server will need be programmed to assign a fully qualified domain name (a.k.a FQDN) to your application. Rancher will use the FQDN you provide and the IP addresses where your application is running to program the DNS. Rancher will gather endpoints from all the Kubernetes clusters running your application and program the DNS.
For more information on how to use this feature, see [Global DNS]({{<baseurl>}}/rancher/v2.x/en/catalog/globaldns/). For more information on how to use this feature, see [Global DNS]({{<baseurl>}}/rancher/v2.x/en/catalog/globaldns/).
### Chart Compatibility with Rancher
Charts now support the fields `rancher_min_version` and `rancher_max_version` in the [`questions.yml` file](https://github.com/rancher/integration-test-charts/blob/master/charts/chartmuseum/v1.6.0/questions.yml) to specify the versions of Rancher that the chart is compatible with. When using the UI, only app versions that are valid for the version of Rancher running will be shown. API validation is done to ensure apps that don't meet the Rancher requirements cannot be launched. An app that is already running will not be affected on a Rancher upgrade if the newer Rancher version does not meet the app's requirements.
content/rancher/v2.x/en/catalog/adding-catalogs/_index.md
+106
View File
@@ -0,0 +1,106 @@
---
title: Creating Custom Catalogs
weight: 200
aliases:
- /rancher/v2.x/en/tasks/global-configuration/catalog/adding-custom-catalogs/
- /rancher/v2.x/en/catalog/custom/adding
---
Custom catalogs can be added into Rancher at a global scope, cluster scope, or project scope.
- [Adding catalog repositories](#adding-catalog-repositories)
- [Add custom Git repositories](#add-custom-git-repositories)
- [Add custom Helm chart repositories](#add-custom-helm-chart-repositories)
- [Add private Git/Helm chart repositories](#add-private-git-helm-chart-repositories)
- [Adding global catalogs](#adding-global-catalogs)
- [Adding cluster level catalogs](#adding-cluster-level-catalogs)
- [Adding project level catalogs](#adding-project-level-catalogs)
- [Custom catalog configuration reference](#custom-catalog-configuration-reference)
# Adding Catalog Repositories
Adding a catalog is as simple as adding a catalog name, a URL and a branch name.
**Prerequisite:** An [admin]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) of Rancher has the ability to add or remove catalogs globally in Rancher.
### Add Custom Git Repositories
The Git URL needs to be one that `git clone` [can handle](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) and must end in `.git`. The branch name must be a branch that is in your catalog URL. If no branch name is provided, it will use the `master` branch by default. Whenever you add a catalog to Rancher, it will be available immediately.
### Add Custom Helm Chart Repositories
A Helm chart repository is an HTTP server that houses one or more packaged charts. Any HTTP server that can serve YAML files and tar files and can answer GET requests can be used as a repository server.
Helm comes with built-in package server for developer testing (helm serve). The Helm team has tested other servers, including Google Cloud Storage with website mode enabled, S3 with website mode enabled or hosting custom chart repository server using open-source projects like [ChartMuseum](https://github.com/helm/chartmuseum).
In Rancher, you can add the custom Helm chart repository with only a catalog name and the URL address of the chart repository.
### Add Private Git/Helm Chart Repositories
_Available as of v2.2.0_
Private catalog repositories can be added using credentials like Username and Password. You may also want to use the OAuth token if your Git or Helm repository server supports that.
For more information on private Git/Helm catalogs, refer to the [custom catalog configuration reference.]({{<baseurl>}}/rancher/v2.x/en/catalog/catalog-config)
1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions prior to v2.2.0, you can select **Catalogs** directly in the navigation bar.
2. Click **Add Catalog**.
3. Complete the form and click **Create**.
**Result:** Your catalog is added to Rancher.
# Adding Global Catalogs
>**Prerequisites:** In order to manage the [built-in catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/built-in/) or manage global catalogs, you need _one_ of the following permissions:
>
>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
>- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Catalogs]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.
1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions prior to v2.2.0, you can select **Catalogs** directly in the navigation bar.
2. Click **Add Catalog**.
3. Complete the form. Select the Helm version that will be used to launch all of the apps in the catalog. For more information about the Helm version, refer to [this section.](
{{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-helm-deployment-versions)
4. Click **Create**.
**Result**: Your custom global catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying [multi-cluster apps]({{<baseurl>}}/rancher/v2.x/en/catalog/multi-cluster-apps/) or [applications in any project]({{<baseurl>}}/rancher/v2.x/en/catalog/launching-apps/) from this catalog.
# Adding Cluster Level Catalogs
_Available as of v2.2.0_
>**Prerequisites:** In order to manage cluster scoped catalogs, you need _one_ of the following permissions:
>
>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
>- [Cluster Owner Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles)
>- [Custom Cluster Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) with the [Manage Cluster Catalogs]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-role-reference) role assigned.
1. From the **Global** view, navigate to your cluster that you want to start adding custom catalogs.
2. Choose the **Tools > Catalogs** in the navigation bar.
2. Click **Add Catalog**.
3. Complete the form. By default, the form will provide the ability to select `Scope` of the catalog. When you have added a catalog from the **Cluster** scope, it is defaulted to `Cluster`. Select the Helm version that will be used to launch all of the apps in the catalog. For more information about the Helm version, refer to [this section.](
{{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-helm-deployment-versions)
5. Click **Create**.
**Result**: Your custom cluster catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying [applications in any project in that cluster]({{<baseurl>}}/rancher/v2.x/en/catalog/apps/) from this catalog.
# Adding Project Level Catalogs
_Available as of v2.2.0_
>**Prerequisites:** In order to manage project scoped catalogs, you need _one_ of the following permissions:
>
>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
>- [Cluster Owner Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles)
>- [Project Owner Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles)
>- [Custom Project Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) with the [Manage Project Catalogs]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-role-reference) role assigned.
1. From the **Global** view, navigate to your project that you want to start adding custom catalogs.
2. Choose the **Tools > Catalogs** in the navigation bar.
2. Click **Add Catalog**.
3. Complete the form. By default, the form will provide the ability to select `Scope` of the catalog. When you have added a catalog from the **Project** scope, it is defaulted to `Cluster`. Select the Helm version that will be used to launch all of the apps in the catalog. For more information about the Helm version, refer to [this section.](
{{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-helm-deployment-versions)
5. Click **Create**.
**Result**: Your custom project catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying [applications in that project]({{<baseurl>}}/rancher/v2.x/en/catalog/apps/) from this catalog.
# Custom Catalog Configuration Reference
Refer to [this page]({{<baseurl>}}/rancher/v2.x/en/catalog/catalog-config) more information on configuring custom catalogs.
content/rancher/v2.x/en/catalog/apps/_index.md
-170
View File
@@ -1,170 +0,0 @@
---
title: Apps in a Project
weight: 5005
---
Within a project, when you want to deploy applications from catalogs, the applications available in your project will be based on the [scope of the catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/#catalog-scope).
If your application is using ingresses, you can program the ingress hostname to an external DNS by setting up a [Global DNS entry]({{< baseurl >}}/rancher/v2.x/en/catalog/globaldns/).
## Prerequisites
To create a multi-cluster app in Rancher, you must have at least one of the following permissions:
- A [project-member role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) in the target cluster, which gives you the ability to create, read, update, and delete the workloads
- A [cluster owner role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) for the cluster that include the target project
## Launching Catalog Applications
After you've either enabled the [built-in global catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/built-in/) or [added your own custom catalog]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/adding), you can start launching catalog applications.
1. From the **Global** view, navigate to your project that you want to start deploying applications.
2. From the main navigation bar, choose **Apps**. In versions prior to v2.2.0, choose **Catalog Apps** on the main navigation bar. Click **Launch**.
3. Find the application that you want to launch, and then click **View Details**.
4. (Optional) Review the detailed descriptions, which comes from the Helm chart's `README`.
5. Under **Configuration Options** enter a **Name**. By default, this name is also used to create a Kubernetes namespace for the application.
* If you would like to change the **Namespace**, click **Customize** and change the name of the namespace.
* If you want to use a different namespace that already exists, click **Customize**, and then click **Use an existing namespace**. Choose a namespace from the list.
6. Select a **Template Version**.
7. Complete the rest of the **Configuration Options**. Rancher handles how to [customize your configuration options](#configuration-options) depending on whether or not the custom catalog includes the `questions.yml` file.
8. Review the files in the **Preview** section. When you're satisfied, click **Launch**.
**Result**: Your application is deployed to your chosen namespace. You can view the application status from the project's:
- **Workloads** view
- **Apps** view. In versions prior to v2.2.0, this is the **Catalog Apps** view.
### Configuration Options
For each Helm chart, there are a list of desired answers that must be entered in order to successfully deploy the chart. When entering answers, you must format them using the syntax rules found in [Using Helm: The format and limitations of –set](https://github.com/helm/helm/blob/master/docs/using_helm.md#the-format-and-limitations-of---set), as Rancher passes them as `--set` flags to Helm.
> For example, when entering an answer that includes two values separated by a comma (i.e. `abc, bcd`), it is required to wrap the values with double quotes (i.e., ``"abc, bcd"``).
{{% tabs %}}
{{% tab "UI" %}}
#### Using a `questions.yml` file
If the Helm chart that you are deploying contains a `questions.yml` file, Rancher's UI will translate this file to display an easy to use UI to collect the answers for the questions.
#### Key Value Pairs for Native Helm Charts
For native Helm charts (i.e., charts from the **Helm Stable** or **Helm Incubator** catalogs or a [custom Helm chart repository]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/#custom-helm-chart-repository)), answers are provided as key value pairs in the **Answers** section. These answers are used to override the default values.
{{% /tab %}}
{{% tab "Editing YAML Files" %}}
_Available as of v2.1.0_
If you do not want to input answers using the UI, you can choose the **Edit as YAML** option.
With this example YAML:
```YAML
outer:
inner: value
servers:
- port: 80
host: example
```
#### Kev Value Pairs
You can have a YAML file that translates these fields to match how to [format custom values so that it can be used with `--set`](https://github.com/helm/helm/blob/master/docs/using_helm.md#the-format-and-limitations-of---set).
These values would be translated to:
```
outer.inner=value
servers[0].port=80
servers[0].host=example
```
#### YAML files
_Available as of v2.2.0_
You can directly paste that YAML formatted structure into the YAML editor. By allowing custom values to be set using a YAML formatted structure, Rancher has the ability to easily customize for more complicated input values (e.g. multi-lines, array and JSON objects).
{{% /tab %}}
{{% /tabs %}}
## Application Management
After deploying an application, one of the benefits of using an application versus individual workloads/resources is the ease of being able to manage many workloads/resources applications. Apps can be cloned, upgraded or rolled back.
### Cloning Catalog Applications
After an application is deployed, you can easily clone it to use create another application with almost the same configuration. It saves you the work of manually filling in duplicate information.
### Upgrading Catalog Applications
After an application is deployed, you can easily upgrade to a different template version.
1. From the **Global** view, navigate to the project that contains the catalog application that you want to upgrade.
1. From the main navigation bar, choose **Apps**. In versions prior to v2.2.0, choose **Catalog Apps** on the main navigation bar. Click **Launch**.
3. Find the application that you want to upgrade, and then click the Ellipsis to find **Upgrade**.
4. Select the **Template Version** that you want to deploy.
5. (Optional) Update your **Configuration Options**.
6. (Optional) Select whether or not you want to force the catalog application to be upgraded by checking the box for **Delete and recreate resources if needed during the upgrade**.
> In Kubernetes, some fields are designed to be immutable or cannot be updated directly. As of v2.2.0, you can now force your catalog application to be updated regardless of these fields. This will cause the catalog apps to be deleted and resources to be re-created if needed during the upgrade.
7. Review the files in the **Preview** section. When you're satisfied, click **Launch**.
**Result**: Your application is updated. You can view the application status from the project's:
- **Workloads** view
- **Apps** view. In versions prior to v2.2.0, this is the **Catalog Apps** view.
### Rolling Back Catalog Applications
After an application has been upgraded, you can easily rollback to a different template version.
1. From the **Global** view, navigate to the project that contains the catalog application that you want to upgrade.
1. From the main navigation bar, choose **Apps**. In versions prior to v2.2.0, choose **Catalog Apps** on the main navigation bar. Click **Launch**.
3. Find the application that you want to rollback, and then click the Ellipsis to find **Rollback**.
4. Select the **Revision** that you want to roll back to. By default, Rancher saves up to the last 10 revisions.
5. (Optional) Select whether or not you want to force the catalog application to be upgraded by checking the box for **Delete and recreate resources if needed during the upgrade**.
> In Kubernetes, some fields are designed to be immutable or cannot be updated directly. As of v2.2.0, you can now force your catalog application to be updated regardless of these fields. This will cause the catalog apps to be deleted and resources to be re-created if needed during the rollback.
7. Click **Rollback**.
**Result**: Your application is updated. You can view the application status from the project's:
- **Workloads** view
- **Apps** view. In versions prior to v2.2.0, this is the **Catalog Apps** view.
### Deleting Catalog Application Deployments
As a safeguard to prevent you from unintentionally deleting other catalog applications that share a namespace, deleting catalog applications themselves does not delete the namespace they're assigned to.
Therefore, if you want to delete both an app and the namespace that contains the app, you should remove the app and the namespace separately:
1. Uninstall the app using the app's `uninstall` function.
1. From the **Global** view, navigate to the project that contains the catalog application that you want to delete.
1. From the main menu, choose **Namespaces**.
1. Find the namespace running your catalog app. Select it and click **Delete**.
**Result:** The catalog application deployment and its namespace are deleted.
content/rancher/v2.x/en/catalog/built-in/_index.md
+10 -20
View File
@@ -1,35 +1,25 @@
--- ---
title: Built-in Global Catalogs title: Enabling and Disabling Built-in Global Catalogs
weight: 4000 weight: 100
aliases: aliases:
- /rancher/v2.x/en/tasks/global-configuration/catalog/enabling-default-catalogs/ - /rancher/v2.x/en/tasks/global-configuration/catalog/enabling-default-catalogs/
--- ---
There are default [global catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/#global-catalogs) packaged as part of Rancher. There are default global catalogs packaged as part of Rancher.
## Managing Built-in Global Catalogs Within Rancher, there are default catalogs packaged as part of Rancher. These can be enabled or disabled by an administrator.
>**Prerequisites:** In order to manage the built-in catalogs or [manage global catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/adding/#adding-global-catalogs), you need _one_ of the following permissions: >**Prerequisites:** In order to manage the built-in catalogs or manage global catalogs, you need _one_ of the following permissions:
> >
>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) >- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
>- [Custom Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Catalogs]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned. >- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Catalogs]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions-reference) role assigned.
1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions prior to v2.2.0, you can select **Catalogs** directly in the navigation bar. 1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions prior to v2.2.0, you can select **Catalogs** directly in the navigation bar.
2. Toggle the default catalogs that you want use to a setting of **Enabled**. 2. Toggle the default catalogs that you want to be enabled or disabled:
- **Library** - **Library:** The Library Catalog includes charts curated by Rancher. Rancher stores charts in a Git repository to expedite the fetch and update of charts. This catalog features Rancher Charts, which include some [notable advantages]({{<baseurl>}}/rancher/v2.x/en/catalog/creating-apps/#rancher-charts) over native Helm charts.
- **Helm Stable:** This catalog, which is maintained by the Kubernetes community, includes native [Helm charts](https://helm.sh/docs/chart_template_guide/). This catalog features the largest pool of apps.
The Library Catalog includes charts curated by Rancher. Rancher stores charts in a Git repository to expedite the fetch and update of charts. In Rancher 2.x, only global catalogs are supported. Support for cluster-level and project-level charts will be added in the future. - **Helm Incubator:** Similar in user experience to Helm Stable, but this catalog is filled with applications in **beta**.
This catalog features Rancher Charts, which include some [notable advantages]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/#chart-types) over native Helm charts.
- **Helm Stable**
This catalog, , which is maintained by the Kubernetes community, includes native [Helm charts](https://github.com/kubernetes/helm/blob/master/docs/chart_template_guide/getting_started.md). This catalog features the largest pool of apps.
- **Helm Incubator**
Similar in user experience to Helm Stable, but this catalog is filled with applications in **beta**.
**Result**: The chosen catalogs are enabled. Wait a few minutes for Rancher to replicate the catalog charts. When replication completes, you'll be able to see them in any of your projects by selecting **Apps** from the main navigation bar. In versions prior to v2.2.0, within a project, you can select **Catalog Apps** from the main navigation bar. **Result**: The chosen catalogs are enabled. Wait a few minutes for Rancher to replicate the catalog charts. When replication completes, you'll be able to see them in any of your projects by selecting **Apps** from the main navigation bar. In versions prior to v2.2.0, within a project, you can select **Catalog Apps** from the main navigation bar.
content/rancher/v2.x/en/catalog/custom/_index.md → content/rancher/v2.x/en/catalog/catalog-config/_index.md
+20 -11
View File
@@ -1,24 +1,32 @@
--- ---
title: Custom Catalogs title: Custom Catalog Configuration Reference
weight: 4020 weight: 300
aliases: aliases:
- /rancher/v2.x/en/catalog/catalog-config
--- ---
Any user can [create custom catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/creating/) to add into Rancher. Besides the content of the catalog, users must ensure their catalogs are able to be added into Rancher. Any user can create custom catalogs to add into Rancher. Besides the content of the catalog, users must ensure their catalogs are able to be added into Rancher.
## Types of Repositories - [Types of Repositories](#types-of-repositories)
- [Custom Git Repository](#custom-git-repository)
- [Custom Helm Chart Repository](#custom-helm-chart-repository)
- [Catalog Fields](#catalog-fields)
- [Private Repositories](#private-repositories)
- [Using Username and Password](#using-username-and-password)
- [Using an OAuth token](#using-an-oauth-token)
# Types of Repositories
Rancher supports adding in different types of repositories as a catalog: Rancher supports adding in different types of repositories as a catalog:
* Custom Git Repository * Custom Git Repository
* Custom Helm Chart Repository * Custom Helm Chart Repository
### Custom Git Repository # Custom Git Repository
The Git URL needs to be one that `git clone` [can handle](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) and must end in `.git`. The branch name must be a branch that is in your catalog URL. If no branch name is provided, it will default to use the `master` branch. Whenever you add a catalog to Rancher, it will be available almost immediately. The Git URL needs to be one that `git clone` [can handle](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) and must end in `.git`. The branch name must be a branch that is in your catalog URL. If no branch name is provided, it will default to use the `master` branch. Whenever you add a catalog to Rancher, it will be available almost immediately.
### Custom Helm Chart Repository # Custom Helm Chart Repository
A Helm chart repository is an HTTP server that contains one or more packaged charts. Any HTTP server that can serve YAML files and tar files and can answer GET requests can be used as a repository server. A Helm chart repository is an HTTP server that contains one or more packaged charts. Any HTTP server that can serve YAML files and tar files and can answer GET requests can be used as a repository server.
@@ -26,7 +34,7 @@ Helm comes with a built-in package server for developer testing (`helm serve`).
In Rancher, you can add the custom Helm chart repository with only a catalog name and the URL address of the chart repository. In Rancher, you can add the custom Helm chart repository with only a catalog name and the URL address of the chart repository.
## Catalog Fields # Catalog Fields
When [adding your catalog]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/adding/) to Rancher, you'll provide the following information: When [adding your catalog]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/adding/) to Rancher, you'll provide the following information:
@@ -36,11 +44,12 @@ When [adding your catalog]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/adding
| Name | Name for your custom catalog to distinguish the repositories in Rancher | | Name | Name for your custom catalog to distinguish the repositories in Rancher |
| Catalog URL | URL of your custom chart repository| | Catalog URL | URL of your custom chart repository|
| Use Private Catalog | Selected if you are using a private repository that requires authentication | | Use Private Catalog | Selected if you are using a private repository that requires authentication |
| Username (Optional) | [Username](#using-username-and-password) or [OAuth Token](#using-an-oauth-token) | | Username (Optional) | Username or OAuth Token |
| Password (Optional) | If you are authenticating using [username](#using-username-and-password), the associated password. If you are using an [OAuth Token](#using-an-oauth-token), use `x-oauth-basic`. | | Password (Optional) | If you are authenticating using a username, enter the associated password. If you are using an OAuth token, use `x-oauth-basic`. |
| Branch | For a Git repository, the branch name. Default: `master`. For a Helm Chart repository, this field is ignored. | | Branch | For a Git repository, the branch name. Default: `master`. For a Helm Chart repository, this field is ignored. |
| Helm version | The Helm version that will be used to deploy all of the charts in the catalog. This field cannot be changed later. For more information, refer to the [section on Helm versions.]({{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-helm-deployment-versions) |
## Private Repositories # Private Repositories
_Available as of v2.2.0_ _Available as of v2.2.0_

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