Skip to content

Commit 22cc142

Browse files
catherinelusecatherineluse
authored
Merge pull request #2430 from rancher/staging
Reorganize K3s installation options
2 parents d6e7309 + f47f80f commit 22cc142

File tree

4 files changed

+432
-159
lines changed

4 files changed

+432
-159
lines changed

‎content/k3s/latest/en/installation/install-options/_index.md‎

Lines changed: 11 additions & 159 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,16 @@ weight: 20
55

66
This page focuses on the options that can be used when you set up K3s for the first time:
77

8-
- [Installation script options](#installation-script-options)
9-
- [Installing K3s from the binary](#installing-k3s-from-the-binary)
8+
- [Options for installation with script](#options-for-installation-with-script)
9+
- [Options for installation from binary](#options-for-installation-from-binary)
1010
- [Registration options for the K3s server](#registration-options-for-the-k3s-server)
1111
- [Registration options for the K3s agent](#registration-options-for-the-k3s-agent)
12-
- [How to Use Flags and Environment Variables](#how-to-use-flags-and-environment-variables)
1312

1413
For more advanced options, refer to [this page.]({{<baseurl>}}/k3s/latest/en/advanced)
1514

16-
> 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.](#how-to-use-flags-and-environment-variables)
15+
> 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)
1716
18-
19-
# Installation Script Options
17+
### Options for Installation with Script
2018

2119
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.
2220

@@ -36,7 +34,7 @@ When using this method to install K3s, the following environment variables can b
3634
| `INSTALL_K3S_BIN_DIR` | Directory to install K3s binary, links, and uninstall script to, or use `/usr/local/bin` as the default. |
3735
| `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`. |
3836
| `INSTALL_K3S_SYSTEMD_DIR` | Directory to install systemd service and environment files to, or use `/etc/systemd/system` as the default. |
39-
| `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. For help, refer to [this example.](#example-b-install-k3s-exec) |
37+
| `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) |
4038
| `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-'. |
4139
| `INSTALL_K3S_TYPE` | Type of systemd service to create, will default from the K3s exec command if not specified.
4240

@@ -46,7 +44,7 @@ Setting `K3S_URL` without explicitly setting an exec command will default the co
4644

4745
When running the agent `K3S_TOKEN` must also be set.
4846

49-
# Installing K3s from the Binary
47+
### Options for Installation from Binary
5048

5149
As stated, the installation script is primarily concerned with configuring K3s to run as a service. If you choose to not use the script, you can run K3s simply by downloading the binary from our [release page](https://github.com/rancher/k3s/releases/latest), placing it on your path, and executing it. The K3s binary supports the following commands:
5250

@@ -59,159 +57,13 @@ Command | Description
5957
<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.
6058
<span class='nowrap'>`k3s help`</span> | Shows a list of commands or help for one command
6159

62-
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:
63-
64-
# Registration Options for the K3s Server
65-
66-
> 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.
67-
68-
```bash
69-
NAME:
70-
k3s server - Run management server
71-
72-
USAGE:
73-
k3s server [OPTIONS]
74-
75-
OPTIONS:
76-
-v value (logging) Number for the log level verbosity (default: 0)
77-
--vmodule value (logging) Comma-separated list of pattern=N settings for file-filtered logging
78-
--log value, -l value (logging) Log to file
79-
--alsologtostderr (logging) Log to standard error as well as file (if set)
80-
--bind-address value (listener) k3s bind address (default: 0.0.0.0)
81-
--https-listen-port value (listener) HTTPS listen port (default: 6443)
82-
--advertise-address value (listener) IP address that apiserver uses to advertise to members of the cluster (default: node-external-ip/node-ip)
83-
--advertise-port value (listener) Port that apiserver uses to advertise to members of the cluster (default: listen-port) (default: 0)
84-
--tls-san value (listener) Add additional hostname or IP as a Subject Alternative Name in the TLS cert
85-
--data-dir value, -d value (data) Folder to hold state default /var/lib/rancher/k3s or ${HOME}/.rancher/k3s if not root
86-
--cluster-cidr value (networking) Network CIDR to use for pod IPs (default: "10.42.0.0/16")
87-
--service-cidr value (networking) Network CIDR to use for services IPs (default: "10.43.0.0/16")
88-
--cluster-dns value (networking) Cluster IP for coredns service. Should be in your service-cidr range (default: 10.43.0.10)
89-
--cluster-domain value (networking) Cluster Domain (default: "cluster.local")
90-
--flannel-backend value (networking) One of 'none', 'vxlan', 'ipsec', 'host-gw', or 'wireguard' (default: "vxlan")
91-
--token value, -t value (cluster) Shared secret used to join a server or agent to a cluster [$K3S_TOKEN]
92-
--token-file value (cluster) File containing the cluster-secret/token [$K3S_TOKEN_FILE]
93-
--write-kubeconfig value, -o value (client) Write kubeconfig for admin client to this file [$K3S_KUBECONFIG_OUTPUT]
94-
--write-kubeconfig-mode value (client) Write kubeconfig with this mode [$K3S_KUBECONFIG_MODE]
95-
--kube-apiserver-arg value (flags) Customized flag for kube-apiserver process
96-
--kube-scheduler-arg value (flags) Customized flag for kube-scheduler process
97-
--kube-controller-manager-arg value (flags) Customized flag for kube-controller-manager process
98-
--kube-cloud-controller-manager-arg value (flags) Customized flag for kube-cloud-controller-manager process
99-
--datastore-endpoint value (db) Specify etcd, Mysql, Postgres, or Sqlite (default) data source name [$K3S_DATASTORE_ENDPOINT]
100-
--datastore-cafile value (db) TLS Certificate Authority file used to secure datastore backend communication [$K3S_DATASTORE_CAFILE]
101-
--datastore-certfile value (db) TLS certification file used to secure datastore backend communication [$K3S_DATASTORE_CERTFILE]
102-
--datastore-keyfile value (db) TLS key file used to secure datastore backend communication [$K3S_DATASTORE_KEYFILE]
103-
--default-local-storage-path value (storage) Default local storage path for local provisioner storage class
104-
--disable value (components) Do not deploy packaged components and delete any deployed components (valid items: coredns, servicelb, traefik, local-storage, metrics-server)
105-
--disable-scheduler (components) Disable Kubernetes default scheduler
106-
--disable-cloud-controller (components) Disable k3s default cloud controller manager
107-
--disable-network-policy (components) Disable k3s default network policy controller
108-
--node-name value (agent/node) Node name [$K3S_NODE_NAME]
109-
--with-node-id (agent/node) Append id to node name
110-
--node-label value (agent/node) Registering and starting kubelet with set of labels
111-
--node-taint value (agent/node) Registering kubelet with set of taints
112-
--docker (agent/runtime) Use docker instead of containerd
113-
--container-runtime-endpoint value (agent/runtime) Disable embedded containerd and use alternative CRI implementation
114-
--pause-image value (agent/runtime) Customized pause image for containerd or docker sandbox (default: "docker.io/rancher/pause:3.1")
115-
--private-registry value (agent/runtime) Private registry configuration file (default: "/etc/rancher/k3s/registries.yaml")
116-
--node-ip value, -i value (agent/networking) IP address to advertise for node
117-
--node-external-ip value (agent/networking) External IP address to advertise for node
118-
--resolv-conf value (agent/networking) Kubelet resolv.conf file [$K3S_RESOLV_CONF]
119-
--flannel-iface value (agent/networking) Override default flannel interface
120-
--flannel-conf value (agent/networking) Override default flannel config file
121-
--kubelet-arg value (agent/flags) Customized flag for kubelet process
122-
--kube-proxy-arg value (agent/flags) Customized flag for kube-proxy process
123-
--rootless (experimental) Run rootless
124-
--agent-token value (experimental/cluster) Shared secret used to join agents to the cluster, but not servers [$K3S_AGENT_TOKEN]
125-
--agent-token-file value (experimental/cluster) File containing the agent secret [$K3S_AGENT_TOKEN_FILE]
126-
--server value, -s value (experimental/cluster) Server to connect to, used to join a cluster [$K3S_URL]
127-
--cluster-init (experimental/cluster) Initialize new cluster master [$K3S_CLUSTER_INIT]
128-
--cluster-reset (experimental/cluster) Forget all peers and become a single cluster new cluster master [$K3S_CLUSTER_RESET]
129-
--secrets-encryption (experimental) Enable Secret encryption at rest
130-
--no-flannel (deprecated) use --flannel-backend=none
131-
--no-deploy value (deprecated) Do not deploy packaged components (valid items: coredns, servicelb, traefik, local-storage, metrics-server)
132-
--cluster-secret value (deprecated) use --token [$K3S_CLUSTER_SECRET]
133-
```
134-
135-
# Registration Options for the K3s Agent
136-
137-
> 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.
138-
139-
```bash
140-
NAME:
141-
k3s agent - Run node agent
142-
143-
USAGE:
144-
k3s agent [OPTIONS]
145-
146-
OPTIONS:
147-
-v value (logging) Number for the log level verbosity (default: 0)
148-
--vmodule value (logging) Comma-separated list of pattern=N settings for file-filtered logging
149-
--log value, -l value (logging) Log to file
150-
--alsologtostderr (logging) Log to standard error as well as file (if set)
151-
--token value, -t value (cluster) Token to use for authentication [$K3S_TOKEN]
152-
--token-file value (cluster) Token file to use for authentication [$K3S_TOKEN_FILE]
153-
--server value, -s value (cluster) Server to connect to [$K3S_URL]
154-
--data-dir value, -d value (agent/data) Folder to hold state (default: "/var/lib/rancher/k3s")
155-
--node-name value (agent/node) Node name [$K3S_NODE_NAME]
156-
--with-node-id (agent/node) Append id to node name
157-
--node-label value (agent/node) Registering and starting kubelet with set of labels
158-
--node-taint value (agent/node) Registering kubelet with set of taints
159-
--docker (agent/runtime) Use docker instead of containerd
160-
--container-runtime-endpoint value (agent/runtime) Disable embedded containerd and use alternative CRI implementation
161-
--pause-image value (agent/runtime) Customized pause image for containerd or docker sandbox (default: "docker.io/rancher/pause:3.1")
162-
--private-registry value (agent/runtime) Private registry configuration file (default: "/etc/rancher/k3s/registries.yaml")
163-
--node-ip value, -i value (agent/networking) IP address to advertise for node
164-
--node-external-ip value (agent/networking) External IP address to advertise for node
165-
--resolv-conf value (agent/networking) Kubelet resolv.conf file [$K3S_RESOLV_CONF]
166-
--flannel-iface value (agent/networking) Override default flannel interface
167-
--flannel-conf value (agent/networking) Override default flannel config file
168-
--kubelet-arg value (agent/flags) Customized flag for kubelet process
169-
--kube-proxy-arg value (agent/flags) Customized flag for kube-proxy process
170-
--rootless (experimental) Run rootless
171-
--no-flannel (deprecated) use --flannel-backend=none
172-
--cluster-secret value (deprecated) use --token [$K3S_CLUSTER_SECRET]
173-
```
174-
175-
### Node Labels and Taints for Agents
176-
177-
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.
178-
179-
Below is an example showing how to add labels and a taint:
180-
```bash
181-
--node-label foo=bar \
182-
--node-label hello=world \
183-
--node-taint key1=value1:NoExecute
184-
```
60+
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>.
18561

186-
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)
187-
188-
# How to Use Flags and Environment Variables
189-
190-
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.
191-
192-
### Example A: K3S_KUBECONFIG_MODE
193-
194-
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.
195-
196-
Using the flag `--write-kubeconfig-mode 644`:
197-
```bash
198-
$ curl -sfL https://get.k3s.io | sh -s - --write-kubeconfig-mode 644
199-
```
200-
Using the environment variable `K3S_KUBECONFIG_MODE`:
201-
```bash
202-
$ curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE="644" sh -s -
203-
```
62+
### Registration Options for the K3s Server
20463

205-
### Example B: INSTALL_K3S_EXEC
64+
For details on configuring the K3s server, refer to the [server configuration reference.]({{<baseurl>}}/k3s/latest/en/installation/install-options/server-config)
20665

207-
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.
20866

209-
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:
67+
### Registration Options for the K3s Agent
21068

211-
```bash
212-
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--no-flannel" sh -s -
213-
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server --no-flannel" sh -s -
214-
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server" sh -s - --no-flannel
215-
curl -sfL https://get.k3s.io | sh -s - server --no-flannel
216-
curl -sfL https://get.k3s.io | sh -s - --no-flannel
217-
```
69+
For details on configuring the K3s agent, refer to the [agent configuration reference.]({{<baseurl>}}/k3s/latest/en/installation/install-options/agent-config)

0 commit comments

Comments
 (0)