mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-05-21 20:35:27 +00:00
Initial HA added and tweaks
- Add children to "Installation Options" covering Node Requirements, Single Server Install, and HA install (Experimental) - Make some small tweaks as needed to hide "--disable-agent" as per https://github.com/rancher/k3s/issues/891 - Make some miscellaneous tweaks such as to hide "--storage-backend" as this is no longer used and other changes as recommended in a recent internal meeting
This commit is contained in:
David Nuzik
@@ -86,18 +86,16 @@ password file should be recreated for the agent, or the entry removed from the s
|
||||
Containerd and Docker
|
||||
----------
|
||||
|
||||
k3s includes and defaults to containerd. Why? Because it's just plain better. If you want to
|
||||
run with Docker first stop and think, "Really? Do I really want more headache?" If still
|
||||
yes then you just need to run the agent with the `--docker` flag.
|
||||
k3s includes and defaults to containerd. If you want to use Docker instead of containerd then you simply need to run the agent with the `--docker` flag.
|
||||
|
||||
k3s will generate config.toml for containerd in `/var/lib/rancher/k3s/agent/etc/containerd/config.toml`, for advanced customization for this file you can create another file called `config.toml.tmpl` in the same directory and it will be used instead.
|
||||
|
||||
The `config.toml.tmpl` will be treated as a Golang template file, and the `config.Node` structure is being passed to the template, the following is an example on how to use the structure to customize the configuration file https://github.com/rancher/k3s/blob/master/pkg/agent/templates/templates.go#L16-L32
|
||||
|
||||
Rootless
|
||||
Rootless (Experimental)
|
||||
--------
|
||||
|
||||
_**WARNING**:_ Some advanced magic, user beware
|
||||
_**WARNING**:_ Experimental feature
|
||||
|
||||
Initial rootless support has been added but there are a series of significant usability issues surrounding it.
|
||||
We are releasing the initial support for those interested in rootless and hopefully some people can help to
|
||||
@@ -185,15 +183,11 @@ this should be edited as appropriate for your architecture. As of this writing m
|
||||
the following images relevant to k3s: `amd64:v0.3.3`, `arm64:v0.3.2`, and `arm:v0.3.2`. Further information
|
||||
on the images provided through gcr.io can be found at https://console.cloud.google.com/gcr/images/google-containers/GLOBAL.
|
||||
|
||||
Storage Backends
|
||||
Storage Backends (Experimental)
|
||||
----------------
|
||||
|
||||
As of version 0.6.0, k3s can support various storage backends including: SQLite (default), MySQL, Postgres, and etcd, this enhancement depends on the following arguments that can be passed to k3s server:
|
||||
|
||||
* `--storage-backend` _value_
|
||||
|
||||
Specify storage type etcd3 or kvsql [$`K3S_STORAGE_BACKEND`]
|
||||
|
||||
* `--storage-endpoint` _value_
|
||||
|
||||
Specify etcd, Mysql, Postgres, or Sqlite (default) data source name [$`K3S_STORAGE_ENDPOINT`]
|
||||
@@ -271,13 +265,11 @@ The above command will use these certificates to generate the tls config to comm
|
||||
Connection to etcd3 can be established using the following command:
|
||||
|
||||
```
|
||||
--storage-backend=etcd3 \
|
||||
--storage-endpoint="https://127.0.0.1:2379"
|
||||
```
|
||||
The above command will attempt to connect insecurely to etcd on localhost with port `2379`, you can connect securely to etcd using the following command:
|
||||
|
||||
```
|
||||
--storage-backend=etcd3 \
|
||||
--storage-endpoint="https://127.0.0.1:2379" \
|
||||
--storage-cafile ca.crt \
|
||||
--storage-certfile etcd.crt \
|
||||
|
||||
@@ -3,347 +3,14 @@ title: "Installation Options"
|
||||
weight: 2
|
||||
---
|
||||
|
||||
This section contains information on flags and environment variables used for starting a k3s cluster.
|
||||
This section contains instructions for installing K3S in testing and production environments. Please ensure you have met the [Node Requirements]({{< baseurl >}}/k3s/latest/en/installation/node-requirements/) before you begin installing K3S.
|
||||
|
||||
Install Script
|
||||
--------------
|
||||
### Installation Options
|
||||
|
||||
The install script will attempt to download the latest release, to specify a specific
|
||||
version for download we can use the `INSTALL_K3S_VERSION` environment variable, for example:
|
||||
```sh
|
||||
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=vX.Y.Z-rc1 sh -
|
||||
```
|
||||
* [Single Server Installation]({{< baseurl >}}/k3s/latest/en/installation/single-server/)
|
||||
|
||||
To install just the server without an agent we can add a `INSTALL_K3S_EXEC`
|
||||
environment variable to the command:
|
||||
```sh
|
||||
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable-agent" sh -
|
||||
```
|
||||
Install K3S on a single Linux host. Single server installs are recommended for development and test environments, as setup is simple and the server doesn't have to be readily available for a user-base.
|
||||
|
||||
The installer can also be run without performing downloads by setting `INSTALL_K3S_SKIP_DOWNLOAD=true`, for example:
|
||||
```sh
|
||||
curl -sfL https://github.com/rancher/k3s/releases/download/vX.Y.Z/k3s -o /usr/local/bin/k3s
|
||||
chmod 0755 /usr/local/bin/k3s
|
||||
* [High Availability (HA) Installation]({{< baseurl >}}/k3s/latest/en/installation/ha/)
|
||||
|
||||
curl -sfL https://get.k3s.io -o install-k3s.sh
|
||||
chmod 0755 install-k3s.sh
|
||||
|
||||
export INSTALL_K3S_SKIP_DOWNLOAD=true
|
||||
./install-k3s.sh
|
||||
```
|
||||
|
||||
The full help text for the install script environment variables are as follows:
|
||||
- `K3S_*`
|
||||
|
||||
Environment variables which begin with `K3S_` will be preserved for the
|
||||
systemd service to use. Setting `K3S_URL` without explicitly setting
|
||||
a systemd exec command will default the command to "agent", and we
|
||||
enforce that `K3S_TOKEN` or `K3S_CLUSTER_SECRET` is also set.
|
||||
|
||||
- `INSTALL_K3S_SKIP_DOWNLOAD`
|
||||
|
||||
If set to true will not download k3s hash or binary.
|
||||
|
||||
- INSTALL_K3S_SYMLINK
|
||||
|
||||
If set to 'skip' will not create symlinks, 'force' will overwrite,
|
||||
default will symlink if command does not exist in path.
|
||||
|
||||
- `INSTALL_K3S_VERSION`
|
||||
|
||||
Version of k3s to download from github. Will attempt to download the
|
||||
latest version if not specified.
|
||||
|
||||
- `INSTALL_K3S_BIN_DIR`
|
||||
|
||||
Directory to install k3s binary, links, and uninstall script to, or use
|
||||
/usr/local/bin as the default
|
||||
|
||||
- `INSTALL_K3S_SYSTEMD_DIR`
|
||||
|
||||
Directory to install systemd service and environment files to, or use
|
||||
/etc/systemd/system as the default
|
||||
|
||||
- `INSTALL_K3S_EXEC` or script arguments
|
||||
|
||||
Command with flags to use for launching k3s in the systemd service, if
|
||||
the command is not specified will default to "agent" if `K3S_URL` is set
|
||||
or "server" if not. The final systemd command resolves to a combination
|
||||
of EXEC and script args ($@).
|
||||
|
||||
The following commands result in the same behavior:
|
||||
```sh
|
||||
curl ... | INSTALL_K3S_EXEC="--disable-agent" sh -s -
|
||||
curl ... | INSTALL_K3S_EXEC="server --disable-agent" sh -s -
|
||||
curl ... | INSTALL_K3S_EXEC="server" sh -s - --disable-agent
|
||||
curl ... | sh -s - server --disable-agent
|
||||
curl ... | sh -s - --disable-agent
|
||||
```
|
||||
|
||||
- `INSTALL_K3S_NAME`
|
||||
|
||||
Name of systemd service to create, will default from the k3s exec command
|
||||
if not specified. If specified the name will be prefixed with 'k3s-'.
|
||||
|
||||
- `INSTALL_K3S_TYPE`
|
||||
|
||||
Type of systemd service to create, will default from the k3s exec command
|
||||
if not specified.
|
||||
|
||||
Server Options
|
||||
--------------
|
||||
|
||||
The following information on server options is also available through `k3s server --help` :
|
||||
|
||||
* `--bind-address` _value_
|
||||
|
||||
k3s bind address (default: localhost)
|
||||
|
||||
* `--https-listen-port` _value_
|
||||
|
||||
HTTPS listen port (default: 6443)
|
||||
|
||||
* `--http-listen-port` _value_
|
||||
|
||||
HTTP listen port (for /healthz, HTTPS redirect, and port for TLS terminating LB) (default: 0)
|
||||
|
||||
* `--data-dir` _value_, `-d` _value_
|
||||
|
||||
Folder to hold state default /var/lib/rancher/k3s or ${HOME}/.rancher/k3s if not root
|
||||
|
||||
* `--disable-agent`
|
||||
|
||||
Do not run a local agent and register a local kubelet
|
||||
|
||||
* `--log` _value_, `-l` _value_
|
||||
|
||||
Log to file
|
||||
|
||||
* `--cluster-cidr` _value_
|
||||
|
||||
Network CIDR to use for pod IPs (default: "10.42.0.0/16")
|
||||
|
||||
* `--cluster-secret` _value_
|
||||
|
||||
Shared secret used to bootstrap a cluster [$`K3S_CLUSTER_SECRET`]
|
||||
|
||||
* `--service-cidr` _value_
|
||||
|
||||
Network CIDR to use for services IPs (default: "10.43.0.0/16")
|
||||
|
||||
* `--cluster-dns` _value_
|
||||
|
||||
Cluster IP for coredns service. Should be in your service-cidr range
|
||||
|
||||
* `--cluster-domain` _value_
|
||||
|
||||
Cluster Domain (default: "cluster.local")
|
||||
|
||||
* `--no-deploy` _value_
|
||||
|
||||
Do not deploy packaged components (valid items: coredns, servicelb, traefik)
|
||||
|
||||
* `--write-kubeconfig` _value_, `-o` _value_
|
||||
|
||||
Write kubeconfig for admin client to this file [$`K3S_KUBECONFIG_OUTPUT`]
|
||||
|
||||
* `--write-kubeconfig-mode` _value_
|
||||
|
||||
Write kubeconfig with this mode [$`K3S_KUBECONFIG_MODE`]
|
||||
|
||||
* `--tls-san` _value_
|
||||
|
||||
Add additional hostname or IP as a Subject Alternative Name in the TLS cert
|
||||
|
||||
* `--kube-apiserver-arg` _value_
|
||||
|
||||
Customized flag for kube-apiserver process
|
||||
|
||||
* `--kube-scheduler-arg` _value_
|
||||
|
||||
Customized flag for kube-scheduler process
|
||||
|
||||
* `--kube-controller-arg` _value_
|
||||
|
||||
Customized flag for kube-controller-manager process
|
||||
|
||||
* `--rootless`
|
||||
|
||||
(experimental) Run rootless
|
||||
|
||||
* `--storage-backend` _value_
|
||||
|
||||
Specify storage type etcd3 or kvsql [$`K3S_STORAGE_BACKEND`]
|
||||
|
||||
* `--storage-endpoint` _value_
|
||||
|
||||
Specify etcd, Mysql, Postgres, or Sqlite (default) data source name [$`K3S_STORAGE_ENDPOINT`]
|
||||
|
||||
* `--storage-cafile` _value_
|
||||
|
||||
SSL Certificate Authority file used to secure storage backend communication [$`K3S_STORAGE_CAFILE`]
|
||||
|
||||
* `--storage-certfile` _value_
|
||||
|
||||
SSL certification file used to secure storage backend communication [$`K3S_STORAGE_CERTFILE`]
|
||||
|
||||
* `--storage-keyfile` _value_
|
||||
|
||||
SSL key file used to secure storage backend communication [$`K3S_STORAGE_KEYFILE`]
|
||||
|
||||
* `--node-ip` _value_, `-i` _value_
|
||||
|
||||
(agent) IP address to advertise for node
|
||||
|
||||
* `--node-name` _value_
|
||||
|
||||
(agent) Node name [$`K3S_NODE_NAME`]
|
||||
|
||||
* `--docker`
|
||||
|
||||
(agent) Use docker instead of containerd
|
||||
|
||||
* `--no-flannel`
|
||||
|
||||
(agent) Disable embedded flannel
|
||||
|
||||
* `--flannel-iface` _value_
|
||||
|
||||
(agent) Override default flannel interface
|
||||
|
||||
* `--container-runtime-endpoint` _value_
|
||||
|
||||
(agent) Disable embedded containerd and use alternative CRI implementation
|
||||
|
||||
* `--pause-image` _value_
|
||||
|
||||
(agent) Customized pause image for containerd sandbox
|
||||
|
||||
* `--resolv-conf` _value_
|
||||
|
||||
(agent) Kubelet resolv.conf file [$`K3S_RESOLV_CONF`]
|
||||
|
||||
* `--kubelet-arg` _value_
|
||||
|
||||
(agent) Customized flag for kubelet process
|
||||
|
||||
* `--kube-proxy-arg` _value_
|
||||
|
||||
(agent) Customized flag for kube-proxy process
|
||||
|
||||
* `--node-label` _value_
|
||||
|
||||
(agent) Registering kubelet with set of labels
|
||||
|
||||
* `--node-taint` _value_
|
||||
|
||||
(agent) Registering kubelet with set of taints
|
||||
|
||||
Agent Options
|
||||
------------------
|
||||
|
||||
The following information on agent options is also available through `k3s agent --help` :
|
||||
|
||||
* `--token` _value_, `-t` _value_
|
||||
|
||||
Token to use for authentication [$`K3S_TOKEN`]
|
||||
|
||||
* `--token-file` _value_
|
||||
|
||||
Token file to use for authentication [$`K3S_TOKEN_FILE`]
|
||||
|
||||
* `--server` _value_, `-s` _value_
|
||||
|
||||
Server to connect to [$`K3S_URL`]
|
||||
|
||||
* `--data-dir` _value_, `-d` _value_
|
||||
|
||||
Folder to hold state (default: "/var/lib/rancher/k3s")
|
||||
|
||||
* `--cluster-secret` _value_
|
||||
|
||||
Shared secret used to bootstrap a cluster [$`K3S_CLUSTER_SECRET`]
|
||||
|
||||
* `--rootless`
|
||||
|
||||
(experimental) Run rootless
|
||||
|
||||
* `--docker`
|
||||
|
||||
(agent) Use docker instead of containerd
|
||||
|
||||
* `--no-flannel`
|
||||
|
||||
(agent) Disable embedded flannel
|
||||
|
||||
* `--flannel-iface` _value_
|
||||
|
||||
(agent) Override default flannel interface
|
||||
|
||||
* `--node-name` _value_
|
||||
|
||||
(agent) Node name [$`K3S_NODE_NAME`]
|
||||
|
||||
* `--node-ip` _value_, `-i` _value
|
||||
|
||||
(agent) IP address to advertise for node
|
||||
|
||||
* `--container-runtime-endpoint` _value_
|
||||
|
||||
(agent) Disable embedded containerd and use alternative CRI implementation
|
||||
|
||||
* `--pause-image` _value_
|
||||
|
||||
(agent) Customized pause image for containerd sandbox
|
||||
|
||||
* `--resolv-conf` _value_
|
||||
|
||||
(agent) Kubelet resolv.conf file [$`K3S_RESOLV_CONF`]
|
||||
|
||||
* `--kubelet-arg` _value_
|
||||
|
||||
(agent) Customized flag for kubelet process
|
||||
|
||||
* `--kube-proxy-arg` _value_
|
||||
|
||||
(agent) Customized flag for kube-proxy process
|
||||
|
||||
* `--node-label` _value_
|
||||
|
||||
(agent) Registering kubelet with set of labels
|
||||
|
||||
* `--node-taint` _value_
|
||||
|
||||
(agent) Registering kubelet with set of taints
|
||||
|
||||
Customizing components
|
||||
----------------------
|
||||
|
||||
As of v0.3.0 any of the following processes can be customized with extra flags:
|
||||
|
||||
* `--kube-apiserver-arg` _value_
|
||||
|
||||
(server) [kube-apiserver options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/)
|
||||
|
||||
* `--kube-controller-arg` _value_
|
||||
|
||||
(server) [kube-controller-manager options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/)
|
||||
|
||||
* `--kube-scheduler-arg` _value_
|
||||
|
||||
(server) [kube-scheduler options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-scheduler/)
|
||||
|
||||
* `--kubelet-arg` _value_
|
||||
|
||||
(agent) [kubelet options](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/)
|
||||
|
||||
* `--kube-proxy-arg` _value_
|
||||
|
||||
(agent) [kube-proxy options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-proxy/)
|
||||
|
||||
Adding extra arguments can be done by passing the following flags to server or agent.
|
||||
For example to add the following arguments `-v=9` and `log-file=/tmp/kubeapi.log` to the kube-apiserver, you should add the following options to k3s server:
|
||||
|
||||
```
|
||||
--kube-apiserver-arg v=9 --kube-apiserver-arg log-file=/tmp/kubeapi.log
|
||||
```
|
||||
Install K3S on two or more Linux hosts. High Availability installs are recommended for production environments.
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: "High Availability (HA) Install (Experimental)"
|
||||
weight: 30
|
||||
---
|
||||
|
||||
>**Important:** High-Availability (HA) was introduced in the v0.10.0 release of K3S and is _experimental_. Our next release plans to support HA in production environments. HA should currently only be used for testing purposes in non-production environments.
|
||||
>**Note:** K3S does not utilize etcd by default so only a 2-node cluster is needed for HA at a minimum. The following will guide you through setting up a 2-node cluster with PostgreSQL. You could optionally add one or more nodes for additional redundancy. In the future we plan to add support for additional database providers.
|
||||
|
||||
For production environments, we recommend installing K3S in a high-availability configuration so that you can always access your cluster. This procedure walks you through setting up a 2-node cluster with K3S with an external PostgreSQL database. As of v0.10.0 release (Experimental HA) we are supporting PostgreSQL 10.7-R1 thru 11.5-R1
|
||||
|
||||
Installation Outline
|
||||
--------------------
|
||||
1. Create backend database (PostgreSQL)
|
||||
2. Create master nodes
|
||||
3. Create a load balancer for the master nodes
|
||||
4. (Optionally) Join worker nodes
|
||||
|
||||
### Create Database
|
||||
The first step for setting up High Availability (HA) is to create the database for the backend. As of v0.10.0 release (Experimental HA) we are currently supporting PostgreSQL 10.7-R1 thru 11.5-R1
|
||||
|
||||
Provision a database via your provider of choice. K3S does not have any unique requirements.
|
||||
|
||||
A strong master password should be utilized and the database should only be privately accessible by the master nodes.
|
||||
|
||||
|
||||
### Create Master Nodes
|
||||
Following the [Node Requirements]({{< baseurl >}}/k3s/latest/en/installation/node-requirements/) page, provision at least two machines to fill the role of the master nodes. They will need to be able to access the database that was created.
|
||||
|
||||
On the first machine, run the following command to install K3S and connect it to the database. Do not run this command on the second machine.
|
||||
|
||||
>**Note:** You may wish to taint the master nodes. They will run the kubelet by default and be scheduleable. You can only add node labels and taints during the install process. If you wish to do this, use the `--node-taint` flag. For example `--node-taint key1=value1:NoExecute` the folllowing examples do not include this flag.
|
||||
|
||||
```
|
||||
curl -fL https://get.k3s.io | sh -s - server --storage-endpoint='postgres://username:password@hostname:5432/dbname' --bootstrap-save
|
||||
```
|
||||
Note: You may want to provide the password temporarily via a file or environment variable then destroy it or clear your bash history so the password is no longer exposed in plain text on the machine.
|
||||
|
||||
On the second machine, run the following command. Since we ran the first node with the `--bootstrap-save` flag the second and any additional machines will now automatically bootstrap HA.
|
||||
|
||||
```
|
||||
curl -fL https://get.k3s.io | sh -s - server --storage-endpoint='postgres://username:password@hostname:5432/dbname'
|
||||
```
|
||||
|
||||
Ensure that both of the nodes are up and ready such as with `k3s kubectl get nodes`
|
||||
|
||||
### Create the Load Balancer
|
||||
You should create a TCP Load Balancer for the master nodes. This will allow worker nodes to address any master node should one of them fail. The Load Balancer should point to each of the master nodes on port 6443 (Default port for the server).
|
||||
|
||||
### (Optionally) Join Worker Nodes
|
||||
Following the [Node Requirements]({{< baseurl >}}/k3s/latest/en/installation/node-requirements/) page, provision one or more machines to fill the role of the worker node(s).
|
||||
|
||||
Run the following command to join a worker node to the master nodes. You can get the node-token from any of the servers at /var/lib/rancher/k3s/server/node-token
|
||||
|
||||
```
|
||||
curl -sfL https://get.k3s.io | K3S_URL=https:/myserver:6443 K3S_TOKEN=XXX sh-
|
||||
```
|
||||
|
||||
Provide the FQDN of the Load Balancer for the master nodes in place of "myserver".
|
||||
|
||||
### Additional Options
|
||||
You may wish to taint the master nodes as they are schedulable by default. This is because the k3s agent is also running on the master nodes (this is required for the kubelet to be running on the master nodes such as so you can manage the master nodes via kubectl).
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Node Requirements
|
||||
weight: 1
|
||||
---
|
||||
|
||||
K3S is very lightweight, but has some minimum requirements as outlined below.
|
||||
|
||||
Whether you're configuring a K3S cluster to run in a single-node or high-availability (HA) setup, each node running k3s should meet the following minimum requirements. You may need more resources to fit your needs.
|
||||
|
||||
## Operating Systems
|
||||
|
||||
K3S should run on just about any flavor of Linux. However, k3s is tested on the following operating systems and their subsequent non-major releases.
|
||||
|
||||
* Ubuntu 18.04 (amd64)
|
||||
|
||||
## Hardware
|
||||
|
||||
Hardware requirements scale based on the size of your deployments. Minimum recommenedations are outlined here.
|
||||
|
||||
* RAM: 512MB Minimum
|
||||
* CPU: 1 Minimum
|
||||
|
||||
#### Disks
|
||||
|
||||
K3S performance depends on the performance of the database. To ensure optimal speed, we recommend using an SSD when possible. Disk performance will vary on ARM devices utilizing an SD card or eMMC.
|
||||
|
||||
## Networking
|
||||
|
||||
The K3S server needs port 6443 to be accessible by the nodes. The nodes need to be able to reach other nodes over UDP port 8472 (Flannel VXLAN). If you do not use flannel and provide your own custom CNI, then port 8472 is not needed by K3S. The node should not listen on any other port. K3S uses reverse tunneling such that the nodes make outbound connections to the server and all kubelet traffic runs through that tunnel.
|
||||
|
||||
IMPORTANT: The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disabled access to port 8472.
|
||||
@@ -0,0 +1,349 @@
|
||||
---
|
||||
title: "Single Server Install"
|
||||
weight: 20
|
||||
---
|
||||
|
||||
>**Note:** This section contains information on flags and environment variables used for starting a single-server
|
||||
(non-HA) K3S cluster. A High-Availability (HA) K3S cluster is required for production. A single server install is
|
||||
intended only for development and testing environments.
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
K3S is easy to install. To install the latest version, simply run the following:
|
||||
|
||||
```sh
|
||||
curl -sfL https://get.k3s.io
|
||||
```
|
||||
|
||||
The install script will attempt to download the latest release, to specify a specific
|
||||
version for download we can use the `INSTALL_K3S_VERSION` environment variable, for example:
|
||||
```sh
|
||||
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=vX.Y.Z-rc1 sh -
|
||||
```
|
||||
|
||||
To install with a specific flag we can use the `INSTALL_K3S_EXEC`
|
||||
environment variable like in this example shown below:
|
||||
```sh
|
||||
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--no-flannel" sh -
|
||||
```
|
||||
|
||||
The installer can also be run without performing downloads by setting `INSTALL_K3S_SKIP_DOWNLOAD=true`, for example:
|
||||
```sh
|
||||
curl -sfL https://github.com/rancher/k3s/releases/download/vX.Y.Z/k3s -o /usr/local/bin/k3s
|
||||
chmod 0755 /usr/local/bin/k3s
|
||||
|
||||
curl -sfL https://get.k3s.io -o install-k3s.sh
|
||||
chmod 0755 install-k3s.sh
|
||||
|
||||
export INSTALL_K3S_SKIP_DOWNLOAD=true
|
||||
./install-k3s.sh
|
||||
```
|
||||
|
||||
The full help text for the install script environment variables are as follows:
|
||||
- `K3S_*`
|
||||
|
||||
Environment variables which begin with `K3S_` will be preserved for the
|
||||
systemd service to use. Setting `K3S_URL` without explicitly setting
|
||||
a systemd exec command will default the command to "agent", and we
|
||||
enforce that `K3S_TOKEN` or `K3S_CLUSTER_SECRET` is also set.
|
||||
|
||||
- `INSTALL_K3S_SKIP_DOWNLOAD`
|
||||
|
||||
If set to true will not download k3s hash or binary.
|
||||
|
||||
- `INSTALL_K3S_SYMLINK`
|
||||
|
||||
If set to 'skip' will not create symlinks, 'force' will overwrite,
|
||||
default will symlink if command does not exist in path.
|
||||
|
||||
- `INSTALL_K3S_VERSION`
|
||||
|
||||
Version of k3s to download from github. Will attempt to download the
|
||||
latest version if not specified.
|
||||
|
||||
- `INSTALL_K3S_BIN_DIR`
|
||||
|
||||
Directory to install k3s binary, links, and uninstall script to, or use
|
||||
/usr/local/bin as the default
|
||||
|
||||
- `INSTALL_K3S_SYSTEMD_DIR`
|
||||
|
||||
Directory to install systemd service and environment files to, or use
|
||||
/etc/systemd/system as the default
|
||||
|
||||
- `INSTALL_K3S_EXEC` or script arguments
|
||||
|
||||
Command with flags to use for launching k3s in the systemd service, if
|
||||
the command is not specified will default to "agent" if `K3S_URL` is set
|
||||
or "server" if not. The final systemd command resolves to a combination
|
||||
of EXEC and script args ($@).
|
||||
|
||||
The following commands result in the same behavior:
|
||||
```sh
|
||||
curl ... | INSTALL_K3S_EXEC="--no-flannel" sh -s -
|
||||
curl ... | INSTALL_K3S_EXEC="server --no-flannel" sh -s -
|
||||
curl ... | INSTALL_K3S_EXEC="server" sh -s - --no-flannel
|
||||
curl ... | sh -s - server --no-flannel
|
||||
curl ... | sh -s - --no-flannel
|
||||
```
|
||||
|
||||
- `INSTALL_K3S_NAME`
|
||||
|
||||
Name of systemd service to create, will default from the k3s exec command
|
||||
if not specified. If specified the name will be prefixed with 'k3s-'.
|
||||
|
||||
- `INSTALL_K3S_TYPE`
|
||||
|
||||
Type of systemd service to create, will default from the k3s exec command
|
||||
if not specified.
|
||||
|
||||
Server Options
|
||||
--------------
|
||||
|
||||
The following information on server options is also available through `k3s server --help` :
|
||||
|
||||
* `--bind-address` _value_
|
||||
|
||||
k3s bind address (default: localhost)
|
||||
|
||||
* `--https-listen-port` _value_
|
||||
|
||||
HTTPS listen port (default: 6443)
|
||||
|
||||
* `--http-listen-port` _value_
|
||||
|
||||
HTTP listen port (for /healthz, HTTPS redirect, and port for TLS terminating LB) (default: 0)
|
||||
|
||||
* `--data-dir` _value_, `-d` _value_
|
||||
|
||||
Folder to hold state default /var/lib/rancher/k3s or ${HOME}/.rancher/k3s if not root
|
||||
|
||||
* `--log` _value_, `-l` _value_
|
||||
|
||||
Log to file
|
||||
|
||||
* `--cluster-cidr` _value_
|
||||
|
||||
Network CIDR to use for pod IPs (default: "10.42.0.0/16")
|
||||
|
||||
* `--cluster-secret` _value_
|
||||
|
||||
Shared secret used to bootstrap a cluster [$`K3S_CLUSTER_SECRET`]
|
||||
|
||||
* `--service-cidr` _value_
|
||||
|
||||
Network CIDR to use for services IPs (default: "10.43.0.0/16")
|
||||
|
||||
* `--cluster-dns` _value_
|
||||
|
||||
Cluster IP for coredns service. Should be in your service-cidr range
|
||||
|
||||
* `--cluster-domain` _value_
|
||||
|
||||
Cluster Domain (default: "cluster.local")
|
||||
|
||||
* `--no-deploy` _value_
|
||||
|
||||
Do not deploy packaged components (valid items: coredns, servicelb, traefik)
|
||||
|
||||
* `--write-kubeconfig` _value_, `-o` _value_
|
||||
|
||||
Write kubeconfig for admin client to this file [$`K3S_KUBECONFIG_OUTPUT`]
|
||||
|
||||
* `--write-kubeconfig-mode` _value_
|
||||
|
||||
Write kubeconfig with this mode [$`K3S_KUBECONFIG_MODE`]
|
||||
|
||||
* `--tls-san` _value_
|
||||
|
||||
Add additional hostname or IP as a Subject Alternative Name in the TLS cert
|
||||
|
||||
* `--kube-apiserver-arg` _value_
|
||||
|
||||
Customized flag for kube-apiserver process
|
||||
|
||||
* `--kube-scheduler-arg` _value_
|
||||
|
||||
Customized flag for kube-scheduler process
|
||||
|
||||
* `--kube-controller-arg` _value_
|
||||
|
||||
Customized flag for kube-controller-manager process
|
||||
|
||||
* `--rootless`
|
||||
|
||||
(experimental) Run rootless
|
||||
|
||||
* `--storage-endpoint` _value_
|
||||
|
||||
Specify etcd, Mysql, Postgres, or Sqlite (default) data source name [$`K3S_STORAGE_ENDPOINT`]
|
||||
|
||||
* `--storage-cafile` _value_
|
||||
|
||||
SSL Certificate Authority file used to secure storage backend communication [$`K3S_STORAGE_CAFILE`]
|
||||
|
||||
* `--storage-certfile` _value_
|
||||
|
||||
SSL certification file used to secure storage backend communication [$`K3S_STORAGE_CERTFILE`]
|
||||
|
||||
* `--storage-keyfile` _value_
|
||||
|
||||
SSL key file used to secure storage backend communication [$`K3S_STORAGE_KEYFILE`]
|
||||
|
||||
* `--node-ip` _value_, `-i` _value_
|
||||
|
||||
(agent) IP address to advertise for node
|
||||
|
||||
* `--node-name` _value_
|
||||
|
||||
(agent) Node name [$`K3S_NODE_NAME`]
|
||||
|
||||
* `--docker`
|
||||
|
||||
(agent) Use docker instead of containerd
|
||||
|
||||
* `--no-flannel`
|
||||
|
||||
(agent) Disable embedded flannel
|
||||
|
||||
* `--flannel-iface` _value_
|
||||
|
||||
(agent) Override default flannel interface
|
||||
|
||||
* `--container-runtime-endpoint` _value_
|
||||
|
||||
(agent) Disable embedded containerd and use alternative CRI implementation
|
||||
|
||||
* `--pause-image` _value_
|
||||
|
||||
(agent) Customized pause image for containerd sandbox
|
||||
|
||||
* `--resolv-conf` _value_
|
||||
|
||||
(agent) Kubelet resolv.conf file [$`K3S_RESOLV_CONF`]
|
||||
|
||||
* `--kubelet-arg` _value_
|
||||
|
||||
(agent) Customized flag for kubelet process
|
||||
|
||||
* `--kube-proxy-arg` _value_
|
||||
|
||||
(agent) Customized flag for kube-proxy process
|
||||
|
||||
* `--node-label` _value_
|
||||
|
||||
(agent) Registering kubelet with set of labels
|
||||
|
||||
* `--node-taint` _value_
|
||||
|
||||
(agent) Registering kubelet with set of taints
|
||||
|
||||
Agent Options
|
||||
------------------
|
||||
|
||||
The following information on agent options is also available through `k3s agent --help` :
|
||||
|
||||
* `--token` _value_, `-t` _value_
|
||||
|
||||
Token to use for authentication [$`K3S_TOKEN`]
|
||||
|
||||
* `--token-file` _value_
|
||||
|
||||
Token file to use for authentication [$`K3S_TOKEN_FILE`]
|
||||
|
||||
* `--server` _value_, `-s` _value_
|
||||
|
||||
Server to connect to [$`K3S_URL`]
|
||||
|
||||
* `--data-dir` _value_, `-d` _value_
|
||||
|
||||
Folder to hold state (default: "/var/lib/rancher/k3s")
|
||||
|
||||
* `--cluster-secret` _value_
|
||||
|
||||
Shared secret used to bootstrap a cluster [$`K3S_CLUSTER_SECRET`]
|
||||
|
||||
* `--rootless`
|
||||
|
||||
(experimental) Run rootless
|
||||
|
||||
* `--docker`
|
||||
|
||||
(agent) Use docker instead of containerd
|
||||
|
||||
* `--no-flannel`
|
||||
|
||||
(agent) Disable embedded flannel
|
||||
|
||||
* `--flannel-iface` _value_
|
||||
|
||||
(agent) Override default flannel interface
|
||||
|
||||
* `--node-name` _value_
|
||||
|
||||
(agent) Node name [$`K3S_NODE_NAME`]
|
||||
|
||||
* `--node-ip` _value_, `-i` _value
|
||||
|
||||
(agent) IP address to advertise for node
|
||||
|
||||
* `--container-runtime-endpoint` _value_
|
||||
|
||||
(agent) Disable embedded containerd and use alternative CRI implementation
|
||||
|
||||
* `--pause-image` _value_
|
||||
|
||||
(agent) Customized pause image for containerd sandbox
|
||||
|
||||
* `--resolv-conf` _value_
|
||||
|
||||
(agent) Kubelet resolv.conf file [$`K3S_RESOLV_CONF`]
|
||||
|
||||
* `--kubelet-arg` _value_
|
||||
|
||||
(agent) Customized flag for kubelet process
|
||||
|
||||
* `--kube-proxy-arg` _value_
|
||||
|
||||
(agent) Customized flag for kube-proxy process
|
||||
|
||||
* `--node-label` _value_
|
||||
|
||||
(agent) Registering kubelet with set of labels
|
||||
|
||||
* `--node-taint` _value_
|
||||
|
||||
(agent) Registering kubelet with set of taints
|
||||
|
||||
Customizing components
|
||||
----------------------
|
||||
|
||||
As of v0.3.0 any of the following processes can be customized with extra flags:
|
||||
|
||||
* `--kube-apiserver-arg` _value_
|
||||
|
||||
(server) [kube-apiserver options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/)
|
||||
|
||||
* `--kube-controller-arg` _value_
|
||||
|
||||
(server) [kube-controller-manager options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/)
|
||||
|
||||
* `--kube-scheduler-arg` _value_
|
||||
|
||||
(server) [kube-scheduler options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-scheduler/)
|
||||
|
||||
* `--kubelet-arg` _value_
|
||||
|
||||
(agent) [kubelet options](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/)
|
||||
|
||||
* `--kube-proxy-arg` _value_
|
||||
|
||||
(agent) [kube-proxy options](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-proxy/)
|
||||
|
||||
Adding extra arguments can be done by passing the following flags to server or agent.
|
||||
For example to add the following arguments `-v=9` and `log-file=/tmp/kubeapi.log` to the kube-apiserver, you should add the following options to k3s server:
|
||||
|
||||
```
|
||||
--kube-apiserver-arg v=9 --kube-apiserver-arg log-file=/tmp/kubeapi.log
|
||||
```
|
||||
@@ -1,10 +1,9 @@
|
||||
---
|
||||
title: "Quick-Start"
|
||||
title: "Quick-Start Guide"
|
||||
weight: 1
|
||||
---
|
||||
|
||||
There are many ways to run k3s, we cover a couple easy ways to get started in this section.
|
||||
The [installation options](../installation) section will cover in greater detail how k3s can be setup.
|
||||
>**Note:** The intent of this guide is to quickly launch a cluster that you can use to evaluate K3S. This guide is not intended for production environments. Production environments should utilize a High-Availability solutuion. The [installation options](../installation) section covers in greater detail how K3S can be setup.
|
||||
|
||||
Install Script
|
||||
--------------
|
||||
@@ -15,30 +14,12 @@ curl -sfL https://get.k3s.io | sh -
|
||||
```
|
||||
|
||||
A kubeconfig file is written to `/etc/rancher/k3s/k3s.yaml` and the service is automatically started or restarted.
|
||||
The install script will install k3s and additional utilities, such as `kubectl`, `crictl`, `k3s-killall.sh`, and `k3s-uninstall.sh`, for example:
|
||||
The install script will install k3s and additional utilities, such as `kubectl`, `crictl`, `ctr`, `k3s-killall.sh`, and `k3s-uninstall.sh`.
|
||||
|
||||
```bash
|
||||
sudo kubectl get nodes
|
||||
```
|
||||
To install on worker nodes and add them to the cluster, we should pass `K3S_URL` along with `K3S_TOKEN` or `K3S_CLUSTER_SECRET` environment variables. `K3S_TOKEN` is created at `/var/lib/rancher/k3s/server/node-token` on your server. Here is an example showing how to join a node:
|
||||
|
||||
`K3S_TOKEN` is created at `/var/lib/rancher/k3s/server/node-token` on your server.
|
||||
To install on worker nodes we should pass `K3S_URL` along with
|
||||
`K3S_TOKEN` or `K3S_CLUSTER_SECRET` environment variables, for example:
|
||||
```bash
|
||||
curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=XXX sh -
|
||||
```
|
||||
|
||||
Manual Download
|
||||
---------------
|
||||
1. Download `k3s` from latest [release](https://github.com/rancher/k3s/releases/latest), x86_64, armhf, and arm64 are supported.
|
||||
2. Run server.
|
||||
|
||||
```bash
|
||||
sudo k3s server &
|
||||
# Kubeconfig is written to /etc/rancher/k3s/k3s.yaml
|
||||
sudo k3s kubectl get nodes
|
||||
|
||||
# On a different node run the below. NODE_TOKEN comes from
|
||||
# /var/lib/rancher/k3s/server/node-token on your server
|
||||
sudo k3s agent --server https://myserver:6443 --token ${NODE_TOKEN}
|
||||
```
|
||||
Note: Each machine must have a unique hostname. If your machines do not have unique hostnames, pass the `K3S_NODE_NAME` environment variable and provide a value with a valid and unique hostname for each node.
|
||||
|
||||
@@ -39,81 +39,6 @@ will register itself as a node (run the agent).
|
||||
It is common and almost required these days that the control plane be part of the cluster.
|
||||
To disable the agent when running the server use the `--disable-agent` flag, the agent can then be run as a separate process.
|
||||
|
||||
Joining Nodes
|
||||
-------------
|
||||
|
||||
When the server starts it creates a file `/var/lib/rancher/k3s/server/node-token`.
|
||||
Using the contents of that file as `K3S_TOKEN` and setting `K3S_URL` allows the node
|
||||
to join as an agent using the install script:
|
||||
|
||||
curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=XXX sh -
|
||||
|
||||
When using the install script openrc logs will be created at `/var/log/k3s-agent.log`, or with systemd in `/var/log/syslog` and viewed using `journalctl -u k3s-agent`.
|
||||
|
||||
Or running k3s manually with the token as `NODE_TOKEN`:
|
||||
|
||||
k3s agent --server https://myserver:6443 --token ${NODE_TOKEN}
|
||||
|
||||
SystemD
|
||||
-------
|
||||
|
||||
If you are using systemd here is a sample unit `k3s.service`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Lightweight Kubernetes
|
||||
Documentation=https://k3s.io
|
||||
After=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=notify
|
||||
EnvironmentFile=/etc/systemd/system/k3s.service.env
|
||||
ExecStart=/usr/local/bin/k3s server
|
||||
KillMode=process
|
||||
Delegate=yes
|
||||
LimitNOFILE=infinity
|
||||
LimitNPROC=infinity
|
||||
LimitCORE=infinity
|
||||
TasksMax=infinity
|
||||
TimeoutStartSec=0
|
||||
Restart=always
|
||||
RestartSec=5s
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
OpenRC
|
||||
------
|
||||
|
||||
And an example openrc `/etc/init.d/k3s`:
|
||||
|
||||
```bash
|
||||
#!/sbin/openrc-run
|
||||
|
||||
depend() {
|
||||
after net-online
|
||||
need net
|
||||
}
|
||||
|
||||
start_pre() {
|
||||
rm -f /tmp/k3s.*
|
||||
}
|
||||
|
||||
supervisor=supervise-daemon
|
||||
name="k3s"
|
||||
command="/usr/local/bin/k3s"
|
||||
command_args="server >>/var/log/k3s.log 2>&1"
|
||||
|
||||
pidfile="/var/run/k3s.pid"
|
||||
respawn_delay=5
|
||||
|
||||
set -o allexport
|
||||
if [ -f /etc/environment ]; then source /etc/environment; fi
|
||||
if [ -f /etc/rancher/k3s/k3s.env ]; then source /etc/rancher/k3s/k3s.env; fi
|
||||
set +o allexport
|
||||
```
|
||||
|
||||
Alpine Linux
|
||||
------------
|
||||
|
||||
|
||||
Reference in New Issue
Block a user