diff --git a/content/k3s/latest/en/advanced/_index.md b/content/k3s/latest/en/advanced/_index.md index 62628f1e7f9..6e6f488b7c3 100644 --- a/content/k3s/latest/en/advanced/_index.md +++ b/content/k3s/latest/en/advanced/_index.md @@ -104,10 +104,3 @@ To run the agent only in Docker, use `docker-compose up node`. Alternatively the -e K3S_TOKEN=${NODE_TOKEN} \ --privileged rancher/k3s:vX.Y.Z -Hyperkube ---------- - -k3s is bundled in a nice wrapper to remove the majority of the headache of running k8s. If -you don't want that wrapper and just want a smaller k8s distro, the releases includes -the `hyperkube` binary you can use. It's then up to you to know how to use `hyperkube`. If -you want individual binaries you will need to compile them yourself from source. diff --git a/content/k3s/latest/en/installation/_index.md b/content/k3s/latest/en/installation/_index.md index ca16b4cd5e8..4d60414d649 100644 --- a/content/k3s/latest/en/installation/_index.md +++ b/content/k3s/latest/en/installation/_index.md @@ -1,24 +1,24 @@ --- -title: "Installation Options" +title: "Installation" weight: 20 --- -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. +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. ### Installation Options * [Single Master Installation]({{< baseurl >}}/k3s/latest/en/installation/single-server/) - Install k3s on a single Linux host. Single master installs are recommended for development and test environments, as setup is simple and the cluster doesn't have to be readily available for a user-base. + Install k3s on a single Linux host. Single master installs are recommended for development, test, or production environments where the cluster doesn't have to be readily available for a user-base and some downtime is acceptible. * [High Availability (HA) Installation]({{< baseurl >}}/k3s/latest/en/installation/ha/) - Install k3s on two or more Linux hosts. High Availability installs are recommended for production environments. + Install k3s on two or more Linux hosts. High Availability installs are recommended for production environments that cannot tolerate any downtime. * [Air-Gap Installation]({{< baseurl >}}/k3s/latest/en/installation/airgap/) - Install k3s in an air-gapped environment. High Availability is recommended for production environments. + Install k3s in an air-gapped environment. High Availability is recommended for production environments that cannot tolerate any downtime. ### Uninstalling -If you installed k3s with the help of the `install.sh` script an uninstall script is generated during installation, which will be created on your node at `/usr/local/bin/k3s-uninstall.sh` (or as `k3s-agent-uninstall.sh`). \ No newline at end of file +If you installed k3s with the help of the `install.sh` script an uninstall script is generated during installation, which will be created on your node at `/usr/local/bin/k3s-uninstall.sh` (or as `k3s-agent-uninstall.sh`). diff --git a/content/k3s/latest/en/installation/ha/_index.md b/content/k3s/latest/en/installation/ha/_index.md index 9f08e206638..7d6f5920a9b 100644 --- a/content/k3s/latest/en/installation/ha/_index.md +++ b/content/k3s/latest/en/installation/ha/_index.md @@ -6,16 +6,16 @@ weight: 30 >**Important:** High-Availability (HA) was introduced in the v0.10.0 release of k3s and is _experimental_. Our v1.0 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 +For production environments that cannot tolerate down time, 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 and 11.5 # Recommended Architecture -![k3s HA]({{< baseurl >}}/img/k3s/k3s-production-setup-v4.svg) +![k3s HA]({{< baseurl >}}/img/k3s/k3s-production-setup-v5.svg) This image depicts a k3s HA install with two load balancers: * A load balancer to expose workloads to external traffic -* A load balancer to expose the Kubernetes API for worker node registration and admin access via `kubectl` +* A load balancer to expose the Kubernetes API for clients such as kubectl and to expose a stable k3s worker registration endpoint -The HA database shown should be a single endpoint k3s can access such as a load balancer. The worker registration / kubernetes API load balancer is needed if the master nodepool will be auto scaling and thus master nodes are ephemeral. Port 6443 is used for worker (agent) node registration and the Kubernetes API. +The external database shown should be a single endpoint k3s can access. The worker registration / kubernetes API load balancer is needed if the master nodepool will be auto scaling and thus master nodes are ephemeral. Port 6443 is used for worker (agent) node registration and the Kubernetes API. Installation Outline -------------------- @@ -24,7 +24,7 @@ Installation Outline 3. Join worker nodes ### Create Database for Cluster Datastore -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. +The first step for setting up High Availability (HA) is to create the database for the backend (cluster datastore). As of v0.10.0 release (Experimental HA) we are currently supporting PostgreSQL 10.7-R1 thru 11.5-R1. ### Create Master Nodes Following the [Node Requirements]({{< baseurl >}}/k3s/latest/en/installation/node-requirements/) page, provision at least two machines. @@ -33,10 +33,15 @@ On the first machine, run the following command to install k3s and connect it to >**Note:** You may wish to taint the master nodes. They will run the kubelet by default and be scheduleable. You can only add node labels and taints during the install process. If you wish to do this, use the `--node-taint` flag. For example `--node-taint key1=value1:NoExecute` the following examples do not include this flag. +>If your master node pool will be auto-scaling, we recommend using the `--cluster-secret` flag instead of the default node-token. For example, this will make it easier to write user-data. The following examples include this optional flag. + ``` -curl -fL https://get.k3s.io | sh -s - server --storage-endpoint='postgres://username:password@hostname:5432/dbname' --bootstrap-save +curl -fL https://get.k3s.io | sh -s - server --storage-endpoint='postgres://username:password@hostname:5432/dbname' --cluster-secret='mysecret' --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. + +The cluster-secret can contain any Unicode, although you should avoid single and double quotes and make sure the contents are terminal-friendly. + +Note: You may want to provide the database password and cluster-secret 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. @@ -49,14 +54,16 @@ Ensure that both of the nodes are in a Ready state such as with `k3s kubectl get ### 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` +Run the following command to join a worker node to the master nodes. We are leveraging the cluster-secret here. Since our master nodes were set up to use this, so too must any agent nodes. ``` -curl -sfL https://get.k3s.io | K3S_URL=https:/:6443 K3S_TOKEN=XXX sh - +curl -sfL https://get.k3s.io | K3S_URL=https:/:6443 K3S_CLUSTER_SECRET='mysecret' sh - ``` Provide the IP or DNS in place of `` this can be any one master node. k3s automatically handles load balancing the master nodes. +Note: You may want to provide the cluster-secret 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. + # Cluster Datastore Options >**Note:** As of v0.10.0 release (Experimental HA) we are currently supporting PostgreSQL 10.7-R1 thru 11.5-R1. diff --git a/content/k3s/latest/en/installation/node-requirements/_index.md b/content/k3s/latest/en/installation/node-requirements/_index.md index b52919459a8..bc2d3bcc814 100644 --- a/content/k3s/latest/en/installation/node-requirements/_index.md +++ b/content/k3s/latest/en/installation/node-requirements/_index.md @@ -7,8 +7,8 @@ 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. -## Pre-requisites -* Two nodes cannot have the same hostname. If all your nodes have the same hostname, pass `--node-name` or `$K3S_NODE_NAME` with a unique name for each node you add to the cluster. +## Prerequisites +* Two nodes cannot have the same hostname. If all your nodes have the same hostname, pass `--node-name` or set `$K3S_NODE_NAME` with a unique name for each node you add to the cluster. ## Operating Systems diff --git a/content/k3s/latest/en/installation/single-server/_index.md b/content/k3s/latest/en/installation/single-server/_index.md index 6bd6dd1ca4f..942c566f2d6 100644 --- a/content/k3s/latest/en/installation/single-server/_index.md +++ b/content/k3s/latest/en/installation/single-server/_index.md @@ -3,9 +3,7 @@ title: "Single Master Install" weight: 20 --- ->**Note:** This section contains information on flags and environment variables used for starting a single-master -(non-HA) k3s cluster. A High-Availability (HA) k3s cluster is required for production. A single server install is -intended only for development and testing environments. +>**Note:** This section contains information on flags and environment variables used for starting a single-master (non-HA) k3s cluster. A High-Availability (HA) k3s cluster is recommended for production environments that cannot tolerate down time. Installation ------------ @@ -16,8 +14,7 @@ k3s is easy to install. To install the latest version, simply run: curl -sfL https://get.k3s.io | sh - ``` -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: +The install script will attempt to download the latest release. To specify a 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 - ``` diff --git a/content/k3s/latest/en/quick-start/_index.md b/content/k3s/latest/en/quick-start/_index.md index dba7ccd0253..a81b5c72370 100644 --- a/content/k3s/latest/en/quick-start/_index.md +++ b/content/k3s/latest/en/quick-start/_index.md @@ -3,7 +3,8 @@ title: "Quick-Start Guide" weight: 10 --- ->**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-Availiability solution. The [installation options](../installation) section covers in greater detail how k3s can be setup. +>**Note:** The intent of this guide is to quickly launch a cluster with default options. It is suitable for production environments if you can accept some downtime in production (e.g. on the Edge). A High-Availiability solution should be utilized if down time is not acceptible. +The [installation options](../installation) section covers in greater detail how k3s can be set up. > New to Kubernetes? The official Kubernetes docs already have some great tutorials outlining the basics [here](https://kubernetes.io/docs/tutorials/kubernetes-basics/). @@ -18,10 +19,10 @@ 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`, `ctr`, `k3s-killall.sh`, and `k3s-uninstall.sh`. -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: +To install on worker nodes and add them to the cluster, we should pass `K3S_URL` along with the `K3S_TOKEN` environment variable. `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: ```bash -curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=XXX sh - +curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken sh - ``` 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. diff --git a/static/img/k3s/k3s-production-setup-v4.svg b/static/img/k3s/k3s-production-setup-v4.svg deleted file mode 100644 index c2fa54c57d7..00000000000 --- a/static/img/k3s/k3s-production-setup-v4.svg +++ /dev/null @@ -1 +0,0 @@ -k3s-production-setup-v2 \ No newline at end of file diff --git a/static/img/k3s/k3s-production-setup-v5.svg b/static/img/k3s/k3s-production-setup-v5.svg new file mode 100644 index 00000000000..cb50963c422 --- /dev/null +++ b/static/img/k3s/k3s-production-setup-v5.svg @@ -0,0 +1,2018 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +