From 20ca2f20af99be53ed7501c78ecc5dfe8f0f0755 Mon Sep 17 00:00:00 2001 From: Erik Wilson Date: Mon, 24 Jun 2019 17:13:11 -0700 Subject: [PATCH 1/7] Initial k3s docs --- content/k3s/_index.md | 5 + content/k3s/latest/_index.md | 4 + content/k3s/latest/en/_index.md | 35 ++ content/k3s/latest/en/building/_index.md | 46 +++ content/k3s/latest/en/configuration/_index.md | 291 +++++++++++++++ content/k3s/latest/en/installation/_index.md | 331 ++++++++++++++++++ content/k3s/latest/en/quick-start/_index.md | 44 +++ content/k3s/latest/en/roadmap/_index.md | 10 + content/k3s/latest/en/running/_index.md | 255 ++++++++++++++ 9 files changed, 1021 insertions(+) create mode 100644 content/k3s/_index.md create mode 100644 content/k3s/latest/_index.md create mode 100644 content/k3s/latest/en/_index.md create mode 100644 content/k3s/latest/en/building/_index.md create mode 100644 content/k3s/latest/en/configuration/_index.md create mode 100644 content/k3s/latest/en/installation/_index.md create mode 100644 content/k3s/latest/en/quick-start/_index.md create mode 100644 content/k3s/latest/en/roadmap/_index.md create mode 100644 content/k3s/latest/en/running/_index.md diff --git a/content/k3s/_index.md b/content/k3s/_index.md new file mode 100644 index 00000000000..cff765de06d --- /dev/null +++ b/content/k3s/_index.md @@ -0,0 +1,5 @@ +--- +title: K3S +weight: 1 +showBreadcrumb: false +--- diff --git a/content/k3s/latest/_index.md b/content/k3s/latest/_index.md new file mode 100644 index 00000000000..b0a33f90917 --- /dev/null +++ b/content/k3s/latest/_index.md @@ -0,0 +1,4 @@ +--- +title: K3S +showBreadcrumb: false +--- diff --git a/content/k3s/latest/en/_index.md b/content/k3s/latest/en/_index.md new file mode 100644 index 00000000000..6035751057e --- /dev/null +++ b/content/k3s/latest/en/_index.md @@ -0,0 +1,35 @@ +--- +title: "K3S - 5 less than k8s" +shortTitle: K3S +date: 2019-02-05T09:52:46-07:00 +name: "menu" +--- + +Lightweight Kubernetes. Easy to install, half the memory, all in a binary less than 40mb. + +Great for: + +* Edge +* IoT +* CI +* ARM +* Situations where a PhD in k8s clusterology is infeasible + +What is this? +--- + +k3s is intended to be a fully compliant Kubernetes distribution with the following changes: + +1. Legacy, alpha, non-default features are removed. Hopefully, you shouldn't notice the + stuff that has been removed. +2. Removed most in-tree plugins (cloud providers and storage plugins) which can be replaced + with out of tree addons. +3. Add sqlite3 as the default storage mechanism. etcd3 is still available, but not the default. +4. Wrapped in simple launcher that handles a lot of the complexity of TLS and options. +5. Minimal to no OS dependencies (just a sane kernel and cgroup mounts needed). k3s packages required + dependencies + * containerd + * Flannel + * CoreDNS + * CNI + * Host utilities (iptables, socat, etc) diff --git a/content/k3s/latest/en/building/_index.md b/content/k3s/latest/en/building/_index.md new file mode 100644 index 00000000000..da075e15a46 --- /dev/null +++ b/content/k3s/latest/en/building/_index.md @@ -0,0 +1,46 @@ +--- +title: "Building from Source" +weight: 10 +--- + +This section provides information on building k3s from source. + +See the [release](https://github.com/rancher/k3s/releases/latest) page for pre-built releases. + +The clone will be much faster on this repo if you do + + git clone --depth 1 https://github.com/rancher/k3s.git + +This repo includes all of Kubernetes history so `--depth 1` will avoid most of that. + +To build the full release binary run `make` and that will create `./dist/artifacts/k3s`. +Optionally to build the binaries without running linting or building docker images: +```sh +./scripts/build && ./scripts/package-cli +``` + +For development, you just need go 1.12 and a sane GOPATH. To compile the binaries run: +```bash +go build -o k3s +go build -o kubectl ./cmd/kubectl +go build -o hyperkube ./vendor/k8s.io/kubernetes/cmd/hyperkube +``` + +This will create the main executable, but it does not include the dependencies like containerd, CNI, +etc. To run a server and agent with all the dependencies for development run the following +helper scripts: +```bash +# Server +./scripts/dev-server.sh + +# Agent +./scripts/dev-agent.sh +``` + + +Kubernetes Source +----------------- + +The source code for Kubernetes is in `vendor/` and the location from which that is copied +is in `./vendor.conf`. Go to the referenced repo/tag and you'll find all the patches applied +to upstream Kubernetes. diff --git a/content/k3s/latest/en/configuration/_index.md b/content/k3s/latest/en/configuration/_index.md new file mode 100644 index 00000000000..ab9f1a0732a --- /dev/null +++ b/content/k3s/latest/en/configuration/_index.md @@ -0,0 +1,291 @@ +--- +title: "Configuration Info" +weight: 4 +--- + +This section contains information on using k3s with various configurations. + + +Auto-Deploying Manifests +------------------------ + +Any file found in `/var/lib/rancher/k3s/server/manifests` will automatically be deployed to +Kubernetes in a manner similar to `kubectl apply`. + +It is also possible to deploy Helm charts. k3s supports a CRD controller for installing charts. A YAML file specification can look as following (example taken from `/var/lib/rancher/k3s/server/manifests/traefik.yaml`): + +```yaml +apiVersion: helm.cattle.io/v1 +kind: HelmChart +metadata: + name: traefik + namespace: kube-system +spec: + chart: stable/traefik + set: + rbac.enabled: "true" + ssl.enabled: "true" +``` + +Keep in mind that `namespace` in your HelmChart resource metadata section should always be `kube-system`, because k3s deploy controller is configured to watch this namespace for new HelmChart resources. If you want to specify the namespace for the actual helm release, you can do that using `targetNamespace` key in the spec section: + +``` +apiVersion: helm.cattle.io/v1 +kind: HelmChart +metadata: + name: grafana + namespace: kube-system +spec: + chart: stable/grafana + targetNamespace: monitoring + set: + adminPassword: "NotVerySafePassword" + valuesContent: |- + image: + tag: master + env: + GF_EXPLORE_ENABLED: true + adminUser: admin + sidecar: + datasources: + enabled: true +``` + +Also note that besides `set` you can use `valuesContent` in the spec section. And it's okay to use both of them. + +k3s versions <= v0.5.0 used `k3s.cattle.io` for the api group of helmcharts, this has been changed to `helm.cattle.io` for later versions. + +Accessing Cluster from Outside +----------------------------- + +Copy `/etc/rancher/k3s/k3s.yaml` on your machine located outside the cluster as `~/.kube/config`. Then replace +"localhost" with the IP or name of your k3s server. `kubectl` can now manage your k3s cluster. + +Open Ports / Network Security +--------------------------- + +The server needs port 6443 to be accessible by the nodes. The nodes need to be able to reach +other nodes over UDP port 8472. This is used for flannel VXLAN. If you don't use flannel +and provide your own custom CNI, then 8472 is not needed by k3s. The node should not listen +on any other port. k3s uses reverse tunneling such that the nodes make outbound connections +to the server and all kubelet traffic runs through that tunnel. + +IMPORTANT. The VXLAN port on nodes should not be exposed to the world, it opens up your +cluster network to accessed by anyone. Run your nodes behind a firewall/security group that +disables access to port 8472. + +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 agent -s ${SERVER_URL} -t ${NODE_TOKEN} --docker & + +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 +-------- + +_**WARNING**:_ Some advanced magic, user beware + +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 +improve the usability. First ensure you have proper setup and support for user namespaces. Refer to the +[requirements section](https://github.com/rootless-containers/rootlesskit#setup) in rootlesskit for instructions. +In short, latest Ubuntu is your best bet for this to work. + + +**Issues w/ Rootless**: + +* **Ports** + + When running rootless a new network namespace is created. This means that k3s instance is running with networking + fairly detached from the host. The only way to access services run in k3s from the host is to setup port forwards + to the k3s network namespace. We have a controller that will automatically bind 6443 and service port below 1024 to the host with an offset of 10000. + + That means service port 80 will become 10080 on the host, but 8080 will become 8080 without any offset. + + Currently, only `LoadBalancer` services are automatically bound. + +* **Daemon lifecycle** + + Once you kill k3s and then start a new instance of k3s it will create a new network namespace, but it doesn't kill the old pods. So you are left + with a fairly broken setup. This is the main issue at the moment, how to deal with the network namespace. + + The issue is tracked in https://github.com/rootless-containers/rootlesskit/issues/65 + +* **Cgroups** + + Cgroups are not supported + +**Running w/ Rootless**: + +Just add `--rootless` flag to either server or agent. So run `k3s server --rootless` and then look for the message +`Wrote kubeconfig [SOME PATH]` for where your kubeconfig to access you cluster is. Becareful, if you use `-o` to write +the kubeconfig to a different directory it will probably not work. This is because the k3s instance in running in a different +mount namespace. + +Node Labels and Taints +---------------------- + +k3s server and agent can be configured with options `--node-label` and `--node-taint` which adds set of Labels and Taints to kubelet, the two options only adds labels/taints at registration time, so they can only be added once and not changed after that, an example to add new label is: +``` +k3s server \ + --node-label foo=bar \ + --node-label hello=world \ + --node-taint key1=value1:NoExecute +``` + +Flannel +------- + +Flannel is included by default, if you don't want flannel then run the agent with `--no-flannel` as follows + + k3s agent -u ${SERVER_URL} -t ${NODE_TOKEN} --no-flannel & + +In this setup you will still be required to install your own CNI driver. More info [here](https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#pod-network) + +CoreDNS +------- + +CoreDNS is deployed on start of the agent, to disable add `--no-deploy coredns` to the server + + k3s server --no-deploy coredns + +If you don't install CoreDNS you will need to install a cluster DNS provider yourself. + +Traefik +------- + +Traefik is deployed by default when starting the server; to disable it, start the server with `--no-deploy traefik` like this + + k3s server --no-deploy traefik + +Service Load Balancer +--------------------- + +k3s includes a basic service load balancer that uses available host ports. If you try to create +a load balancer that listens on port 80, for example, it will try to find a free host in the cluster +for port 80. If no port is available the load balancer will stay in Pending. + +To disable the embedded service load balancer (if you wish to use a different implementation like +MetalLB) just add `--no-deploy=servicelb` to the server on startup. + +Metrics Server +-------------- + +To add functionality for commands such as `k3s kubectl top node` metrics-server must be installed, +to install see the instructions located at https://github.com/kubernetes-incubator/metrics-server/. + +NOTE: By default the image used in `metrics-server-deployment.yaml` is valid only for amd64 devices, +this should be edited as appropriate for your architecture. As of this writing metrics-server provides +the following images relevant to k3s: `amd64:v0.3.3`, `arm64:v0.3.2`, and `arm:v0.3.2`. Further information +on the images provided through gcr.io can be found at https://console.cloud.google.com/gcr/images/google-containers/GLOBAL. + +Storage Backends +---------------- + +As of version 0.6.0, k3s can support various storage backends including: SQLite (default), MySQL, Postgres, and etcd, this enahancement depends on the following arguments that can be passed to k3s server: + +* `--storage-backend` _value_ + + Specify storage type etcd3 or kvsql [$`K3S_STORAGE_BACKEND`] + +* `--storage-endpoint` _value_ + + Specify etcd, Mysql, Postgres, or Sqlite (default) data source name [$`K3S_STORAGE_ENDPOINT`] + +* `--storage-cafile` _value_ + + SSL Certificate Authority file used to secure storage backend communication [$`K3S_STORAGE_CAFILE`] + +* `--storage-certfile` _value_ + + SSL certification file used to secure storage backend communication [$`K3S_STORAGE_CERTFILE`] + +* `--storage-keyfile` _value_ + + SSL key file used to secure storage backend communication [$`K3S_STORAGE_KEYFILE`] + +### MySQL + +To use k3s with MySQL storage backend, you can specify the following for insecure connection: + +``` +k3s server --storage-endpoint="mysql://" +``` +By default the server will attempt to connect to mysql using the mysql socket at `/var/run/mysqld/mysqld.sock` using the root user and with no password, k3s will also create a database with the name `kubernetes` if the database is not specified in the DSN. + +To override the method of connection, user/pass, and database name, you can provide a custom DSN, for example: + +``` +k3s server \ + --storage-endpoint="mysql://k3suser:k3spass@tcp(192.168.1.100:3306)/k3stest" +``` + +This command will attempt to connect to MySQL on host `192.168.1.100` on port `3306` with username `k3suser` and password `k3spass` and k3s will automatically create a new database with the name `k3stest` if it doesn't exist, for more information about the MySQL driver data source name, please refer to https://github.com/go-sql-driver/mysql#dsn-data-source-name + +To connect to MySQL securely, you can use the following example: +``` +k3s server \ + --storage-endpoint="mysql://k3suser:k3spass@tcp(192.168.1.100:3306)/k3stest" \ + --storage-cafile ca.crt \ + --storage-certfile mysql.crt \ + --storage-keyfile mysql.key +``` +The above command will use these certificates to generate the tls config to communicate with mysql securely. + + +### Postgres + +Connection to postgres can be established using the following command: + +``` +k3s server --storage-endpoint="postgres://" +``` + +By default the server will attempt to connect to postgres on localhost with using the `postgres` user and with `postgres` password, k3s will also create a database with the name `kubernetes` if the database is not specified in the DSN. + +To override the method of connection, user/pass, and database name, you can provide a custom DSN, for example: + +``` +k3s server \ + --storage-endpoint="postgres://k3suser:k3spass@192.168.1.100:5432/k3stest" +``` + +This command will attempt to connect to Postgres on host `192.168.1.100` on port `5432` with username `k3suser` and password `k3spass` and k3s will automatically create a new database with the name `k3stest` if it doesn't exist, for more information about the Postgres driver data source name, please refer to https://godoc.org/github.com/lib/pq + +To connect to Postgres securely, you can use the following example: + +``` +k3s server \ + --storage-endpoint="postgres://k3suser:k3spass@192.168.1.100:5432/k3stest?sslmode=verify-full" \ + --storage-certfile postgres.crt \ + --storage-keyfile postgres.key \ + --storage-cafile ca.crt +``` + +The above command will use these certificates to generate the tls config to communicate with postgres securely, note that the `sslmode` in the example is `verify-full` which verify that the certification presented by the server was signed by a trusted CA and the server host name matches the one in the certificate. + +### etcd + +Connection to etcd3 can be established using the following command: + +``` +k3s server --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: + +``` +k3s server \ + --storage-backend=etcd3 \ + --storage-endpoint="https://127.0.0.1:2379" \ + --storage-cafile ca.crt \ + --storage-certfile etcd.crt \ + --storage-keyfile etcd.key +``` \ No newline at end of file diff --git a/content/k3s/latest/en/installation/_index.md b/content/k3s/latest/en/installation/_index.md new file mode 100644 index 00000000000..cb7659e9a87 --- /dev/null +++ b/content/k3s/latest/en/installation/_index.md @@ -0,0 +1,331 @@ +--- +title: "Installation Options" +weight: 2 +--- + +This section contains information on flags and environment variables used for starting a k3s cluster. + +Install Script +-------------- + +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, eg: +```sh +curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=vX.Y.Z-rc1 sh - +``` + +To install just the server without an agent we can add a `INSTALL_K3S_EXEC` +environment variable to the command: +```sh +curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable-agent" sh - +``` + +The installer can also be run without performing downloads by setting `INSTALL_K3S_SKIP_DOWNLOAD=true`, eg: +```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_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 +------------------ +* `--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) Registring kubelet with set of labels + +* `--node-taint` _value_ + + (agent) Registring kubelet with set of taints + +Agent Options +------------------ + +* `--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) Registring kubelet with set of labels + +* `--node-taint` _value_ + + (agent) Registring 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](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/) (server) +- [kube-controller-manager](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/) (server) +- [kube-scheduler](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-scheduler/) (server) +- [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/) (agent) +- [kube-proxy](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-proxy/) (agent) + +Adding extra argument can be done by passing the following flags to server or agent: +``` +--kube-apiserver-arg value +--kube-scheduler-arg value +--kube-controller-arg value +--kubelet-arg value +--kube-proxy-arg value +``` +For example to add the following arguments `-v=9` and `log-file=/tmp/kubeapi.log` to the kube-apiserver, you should pass the following: +``` +k3s server --kube-apiserver-arg v=9 --kube-apiserver-arg log-file=/tmp/kubeapi.log +``` diff --git a/content/k3s/latest/en/quick-start/_index.md b/content/k3s/latest/en/quick-start/_index.md new file mode 100644 index 00000000000..a54bcb42627 --- /dev/null +++ b/content/k3s/latest/en/quick-start/_index.md @@ -0,0 +1,44 @@ +--- +title: "Quick-Start" +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. + +Install Script +-------------- +The k3s `install.sh` script provides a convenient way for installing to systemd or openrc, +to install k3s as a service just run: +```bash +curl -sfL https://get.k3s.io | sh - +``` + +A kubeconfig file is written to `/etc/rancher/k3s/k3s.yaml` and the service is automatically started or restarted. +The install script will install k3s and additional utilities, such as `kubectl`, `crictl`, `k3s-killall.sh`, and `k3s-uninstall.sh`, eg: + +```bash +sudo kubectl get nodes +``` + +`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, eg: +```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} +``` diff --git a/content/k3s/latest/en/roadmap/_index.md b/content/k3s/latest/en/roadmap/_index.md new file mode 100644 index 00000000000..2d175896074 --- /dev/null +++ b/content/k3s/latest/en/roadmap/_index.md @@ -0,0 +1,10 @@ +--- +title: "Road Map" +weight: 100 +--- + +Current items to implement before this is to be considered GA release: + +1. Multi-Server / High Availability (HA) +2. Documentation moved to Rancher +3. Automated tests for k3s specific features diff --git a/content/k3s/latest/en/running/_index.md b/content/k3s/latest/en/running/_index.md new file mode 100644 index 00000000000..1ed1655dc10 --- /dev/null +++ b/content/k3s/latest/en/running/_index.md @@ -0,0 +1,255 @@ +--- +title: "Running K3S" +weight: 3 +--- + +This section contains information for running k3s in various environments. + +Starting the Server +------------------ + +The installation script will auto-detect if your OS is using systemd or openrc. +When running with openrc logs will be created at `/var/log/k3s.log`, or with systemd in `/var/log/syslog` and viewed using `journalctl -u k3s`. + +When running the server manually you should get an output similar to: + +``` +$ k3s server +INFO[2019-01-22T15:16:19.908493986-07:00] Starting k3s dev +INFO[2019-01-22T15:16:19.908934479-07:00] Running kube-apiserver --allow-privileged=true --authorization-mode Node,RBAC --service-account-signing-key-file /var/lib/rancher/k3s/server/tls/service.key --service-cluster-ip-range 10.43.0.0/16 --advertise-port 6445 --advertise-address 127.0.0.1 --insecure-port 0 --secure-port 6444 --bind-address 127.0.0.1 --tls-cert-file /var/lib/rancher/k3s/server/tls/localhost.crt --tls-private-key-file /var/lib/rancher/k3s/server/tls/localhost.key --service-account-key-file /var/lib/rancher/k3s/server/tls/service.key --service-account-issuer k3s --api-audiences unknown --basic-auth-file /var/lib/rancher/k3s/server/cred/passwd --kubelet-client-certificate /var/lib/rancher/k3s/server/tls/token-node.crt --kubelet-client-key /var/lib/rancher/k3s/server/tls/token-node.key +Flag --insecure-port has been deprecated, This flag will be removed in a future version. +INFO[2019-01-22T15:16:20.196766005-07:00] Running kube-scheduler --kubeconfig /var/lib/rancher/k3s/server/cred/kubeconfig-system.yaml --port 0 --secure-port 0 --leader-elect=false +INFO[2019-01-22T15:16:20.196880841-07:00] Running kube-controller-manager --kubeconfig /var/lib/rancher/k3s/server/cred/kubeconfig-system.yaml --service-account-private-key-file /var/lib/rancher/k3s/server/tls/service.key --allocate-node-cidrs --cluster-cidr 10.42.0.0/16 --root-ca-file /var/lib/rancher/k3s/server/tls/token-ca.crt --port 0 --secure-port 0 --leader-elect=false +Flag --port has been deprecated, see --secure-port instead. +INFO[2019-01-22T15:16:20.273441984-07:00] Listening on :6443 +INFO[2019-01-22T15:16:20.278383446-07:00] Writing manifest: /var/lib/rancher/k3s/server/manifests/coredns.yaml +INFO[2019-01-22T15:16:20.474454524-07:00] Node token is available at /var/lib/rancher/k3s/server/node-token +INFO[2019-01-22T15:16:20.474471391-07:00] To join node to cluster: k3s agent -s https://10.20.0.3:6443 -t ${NODE_TOKEN} +INFO[2019-01-22T15:16:20.541027133-07:00] Wrote kubeconfig /etc/rancher/k3s/k3s.yaml +INFO[2019-01-22T15:16:20.541049100-07:00] Run: k3s kubectl +``` + +The output will likely be much longer as the agent will create a lot of logs. By default the server +will register itself as a node (run the agent). + +It is common and almost required these days that the control plane be part of the cluster. +To disable the agent when running the server use the `--disable-agent` flag, the agent can then be run as a separate process. + +Joining Nodes +------------- + +When the server starts it creates a file `/var/lib/rancher/k3s/server/node-token`. +Use the contents of that file as `NODE_TOKEN` and then running the agent manually: + + k3s agent --server https://myserver:6443 --token ${NODE_TOKEN} + +Or as a `K3S_TOKEN` environment variable using the install script: + + curl -sfL https://get.k3s.io | K3S_URL=https://myserver:6443 K3S_TOKEN=XXX sh - + +When running with 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`. + +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 + +[Install] +WantedBy=multi-user.target +``` + +OpenRC +------ + +And an excample openrc `/etc/init.d/k3s`: + +```bash +#!/sbin/openrc-run + +depend() { + after net-online + need net +} + +start_pre() { + rm -f /tmp/k3s.* +} + +supervisor=supervise-daemon +name="k3s" +command="/usr/local/bin/k3s" +command_args="server >>/var/log/k3s.log 2>&1" + +pidfile="/var/run/k3s.pid" +respawn_delay=5 + +set -o allexport +if [ -f /etc/environment ]; then source /etc/environment; fi +if [ -f /etc/rancher/k3s/k3s.env ]; then source /etc/rancher/k3s/k3s.env; fi +set +o allexport +``` + +Alpine Linux +------------ + +In order to pre-setup Alpine Linux you have to go through the following steps: + +```bash +echo "cgroup /sys/fs/cgroup cgroup defaults 0 0" >> /etc/fstab + +cat >> /etc/cgconfig.conf < 11s v1.13.2-k3s2 + d54c8b17c055 Ready 11s v1.13.2-k3s2 + db7a5a5a5bdd Ready 12s v1.13.2-k3s2 + +To run the agent only in Docker use the following `docker-compose-agent.yml` is in the root of this repo that +serves as an example of how to run k3s agent from Docker. Alternatively the Docker run command can also be used; + + sudo docker run \ + -d --tmpfs /run \ + --tmpfs /var/run \ + -e K3S_URL=${SERVER_URL} \ + -e K3S_TOKEN=${NODE_TOKEN} \ + --privileged rancher/k3s:vX.Y.Z + + sudo docker run \ + -d --tmpfs /run \ + --tmpfs /var/run \ + -e K3S_URL=https://k3s.example.com:6443 \ + -e K3S_TOKEN=XXX \ + --privileged rancher/k3s:vX.Y.Z + +Air-Gap Support +--------------- + +k3s supports pre-loading of containerd images by placing them in the `images` directory for the agent before starting, eg: +```sh +sudo mkdir -p /var/lib/rancher/k3s/agent/images/ +sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/ +``` +Images needed for a base install are provided through the releases page, additional images can be created with the `docker save` command. + +Offline Helm charts are served from the `/var/lib/rancher/k3s/server/static` directory, and Helm chart manifests may reference the static files with a `%{KUBERNETES_API}%` templated variable. For example, the default traefik manifest chart installs from `https://%{KUBERNETES_API}%/static/charts/traefik-X.Y.Z.tgz`. + +If networking is completely disabled k3s may not be able to start (ie ethernet unplugged or wifi disconnected), in which case it may be necessary to add a default route. For example: +```sh +sudo ip -c address add 192.168.123.123/24 dev eno1 +sudo ip route add default via 192.168.123.1 +``` + +k3s additionally provides a `--resolv-conf` flag for kubelets, which may help with configuring DNS in air-gap networks. + +Upgrades +-------- + +To upgrade k3s from an older version you can re-run the installation script using the same flags, eg: + +```sh +curl -sfL https://get.k3s.io | sh - +``` + +If you want to upgrade to specific version you can run the following command: + +```sh +curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=vX.Y.Z-rc1 sh - +``` + +Or to manually upgrade k3s: + +1. Download the desired version of k3s from [releases](https://github.com/rancher/k3s/releases/latest) +2. Install to an appropriate location (normally `/usr/local/bin/k3s`) +3. Stop the old version +4. Start the new version + +Restarting k3s is supported by the installation script for systemd and openrc. +To restart manually for systemd use: +```sh +sudo systemctl restart k3s +``` + +To restart manually for openrc use: +```sh +sudo service k3s restart +``` + +Upgrading an air-gap environment can be accomplished in the following manner: + +1. Download air-gap images and install if changed +2. Install new k3s binary (from installer or manual download) +3. Restart k3s (if not restarted automatically by installer) + +Uninstalling +------------ + +If you installed k3s with the help of `install.sh` script an uninstall script is generated during installation, which will be created on your server node at `/usr/local/bin/k3s-uninstall.sh` (or as `k3s-agent-uninstall.sh`). + +Hyperkube +--------- + +k3s is bundled in a nice wrapper to remove the majority of the headache of running k8s. If +you don't want that wrapper and just want a smaller k8s distro, the releases includes +the `hyperkube` binary you can use. It's then up to you to know how to use `hyperkube`. If +you want individual binaries you will need to compile them yourself from source From a677305090820fbce97d8b5af22fd8adf7c75106 Mon Sep 17 00:00:00 2001 From: Erik Wilson Date: Tue, 25 Jun 2019 08:48:59 -0700 Subject: [PATCH 2/7] Cleanup k3s docs --- content/k3s/latest/en/configuration/_index.md | 47 +++++++------------ content/k3s/latest/en/installation/_index.md | 45 +++++++++++------- content/k3s/latest/en/running/_index.md | 15 +++--- 3 files changed, 54 insertions(+), 53 deletions(-) diff --git a/content/k3s/latest/en/configuration/_index.md b/content/k3s/latest/en/configuration/_index.md index ab9f1a0732a..0135e5e41ed 100644 --- a/content/k3s/latest/en/configuration/_index.md +++ b/content/k3s/latest/en/configuration/_index.md @@ -79,9 +79,7 @@ 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 agent -s ${SERVER_URL} -t ${NODE_TOKEN} --docker & +yes then you just 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. @@ -132,9 +130,8 @@ mount namespace. Node Labels and Taints ---------------------- -k3s server and agent can be configured with options `--node-label` and `--node-taint` which adds set of Labels and Taints to kubelet, the two options only adds labels/taints at registration time, so they can only be added once and not changed after that, an example to add new label is: +k3s agents can be configured with options `--node-label` and `--node-taint` which adds set of Labels and Taints to kubelet, the two options only adds labels/taints at registration time, so they can only be added once and not changed after that, an example of options to add new label is: ``` -k3s server \ --node-label foo=bar \ --node-label hello=world \ --node-taint key1=value1:NoExecute @@ -143,27 +140,21 @@ k3s server \ Flannel ------- -Flannel is included by default, if you don't want flannel then run the agent with `--no-flannel` as follows - - k3s agent -u ${SERVER_URL} -t ${NODE_TOKEN} --no-flannel & +Flannel is included by default, if you don't want flannel then run the agent with `--no-flannel` option. In this setup you will still be required to install your own CNI driver. More info [here](https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#pod-network) CoreDNS ------- -CoreDNS is deployed on start of the agent, to disable add `--no-deploy coredns` to the server - - k3s server --no-deploy coredns +CoreDNS is deployed on start of the agent, to disable run the server with the `--no-deploy coredns` option. If you don't install CoreDNS you will need to install a cluster DNS provider yourself. Traefik ------- -Traefik is deployed by default when starting the server; to disable it, start the server with `--no-deploy traefik` like this - - k3s server --no-deploy traefik +Traefik is deployed by default when starting the server; to disable it, start the server with the `--no-deploy traefik` option. Service Load Balancer --------------------- @@ -172,16 +163,15 @@ k3s includes a basic service load balancer that uses available host ports. If y a load balancer that listens on port 80, for example, it will try to find a free host in the cluster for port 80. If no port is available the load balancer will stay in Pending. -To disable the embedded service load balancer (if you wish to use a different implementation like -MetalLB) just add `--no-deploy=servicelb` to the server on startup. +To disable the embedded load balancer run the server with the `--no-deploy servicelb` option. This is necessary if you wish to run a different load balancer, such as MetalLB. Metrics Server -------------- -To add functionality for commands such as `k3s kubectl top node` metrics-server must be installed, +To add functionality for commands such as `k3s kubectl top nodes` metrics-server must be installed, to install see the instructions located at https://github.com/kubernetes-incubator/metrics-server/. -NOTE: By default the image used in `metrics-server-deployment.yaml` is valid only for amd64 devices, +**NOTE** : By default the image used in `metrics-server-deployment.yaml` is valid only for **amd64** devices, this should be edited as appropriate for your architecture. As of this writing metrics-server provides the following images relevant to k3s: `amd64:v0.3.3`, `arm64:v0.3.2`, and `arm:v0.3.2`. Further information on the images provided through gcr.io can be found at https://console.cloud.google.com/gcr/images/google-containers/GLOBAL. @@ -189,7 +179,7 @@ on the images provided through gcr.io can be found at https://console.cloud.goog Storage Backends ---------------- -As of version 0.6.0, k3s can support various storage backends including: SQLite (default), MySQL, Postgres, and etcd, this enahancement depends on the following arguments that can be passed to k3s server: +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_ @@ -216,14 +206,13 @@ As of version 0.6.0, k3s can support various storage backends including: SQLite To use k3s with MySQL storage backend, you can specify the following for insecure connection: ``` -k3s server --storage-endpoint="mysql://" + --storage-endpoint="mysql://" ``` By default the server will attempt to connect to mysql using the mysql socket at `/var/run/mysqld/mysqld.sock` using the root user and with no password, k3s will also create a database with the name `kubernetes` if the database is not specified in the DSN. To override the method of connection, user/pass, and database name, you can provide a custom DSN, for example: ``` -k3s server \ --storage-endpoint="mysql://k3suser:k3spass@tcp(192.168.1.100:3306)/k3stest" ``` @@ -231,7 +220,6 @@ This command will attempt to connect to MySQL on host `192.168.1.100` on port `3 To connect to MySQL securely, you can use the following example: ``` -k3s server \ --storage-endpoint="mysql://k3suser:k3spass@tcp(192.168.1.100:3306)/k3stest" \ --storage-cafile ca.crt \ --storage-certfile mysql.crt \ @@ -245,7 +233,7 @@ The above command will use these certificates to generate the tls config to comm Connection to postgres can be established using the following command: ``` -k3s server --storage-endpoint="postgres://" + --storage-endpoint="postgres://" ``` By default the server will attempt to connect to postgres on localhost with using the `postgres` user and with `postgres` password, k3s will also create a database with the name `kubernetes` if the database is not specified in the DSN. @@ -253,7 +241,6 @@ By default the server will attempt to connect to postgres on localhost with usin To override the method of connection, user/pass, and database name, you can provide a custom DSN, for example: ``` -k3s server \ --storage-endpoint="postgres://k3suser:k3spass@192.168.1.100:5432/k3stest" ``` @@ -262,30 +249,30 @@ This command will attempt to connect to Postgres on host `192.168.1.100` on port To connect to Postgres securely, you can use the following example: ``` -k3s server \ - --storage-endpoint="postgres://k3suser:k3spass@192.168.1.100:5432/k3stest?sslmode=verify-full" \ + --storage-endpoint="postgres://k3suser:k3spass@192.168.1.100:5432/k3stest" \ --storage-certfile postgres.crt \ --storage-keyfile postgres.key \ --storage-cafile ca.crt ``` -The above command will use these certificates to generate the tls config to communicate with postgres securely, note that the `sslmode` in the example is `verify-full` which verify that the certification presented by the server was signed by a trusted CA and the server host name matches the one in the certificate. +The above command will use these certificates to generate the tls config to communicate with postgres securely. ### etcd Connection to etcd3 can be established using the following command: ``` -k3s server --storage-backend=etcd3 \ + --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: ``` -k3s server \ --storage-backend=etcd3 \ --storage-endpoint="https://127.0.0.1:2379" \ --storage-cafile ca.crt \ --storage-certfile etcd.crt \ --storage-keyfile etcd.key -``` \ No newline at end of file +``` + +The above command will use these certificates to generate the tls config to communicate with etcd securely. diff --git a/content/k3s/latest/en/installation/_index.md b/content/k3s/latest/en/installation/_index.md index cb7659e9a87..980deee37db 100644 --- a/content/k3s/latest/en/installation/_index.md +++ b/content/k3s/latest/en/installation/_index.md @@ -86,7 +86,10 @@ The full help text for the install script environment variables are as follows: 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) @@ -234,6 +237,8 @@ Server Options 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`] @@ -311,21 +316,29 @@ Customizing components As of v0.3.0 any of the following processes can be customized with extra flags: -- [kube-apiserver](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/) (server) -- [kube-controller-manager](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/) (server) -- [kube-scheduler](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-scheduler/) (server) -- [kubelet](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/) (agent) -- [kube-proxy](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-proxy/) (agent) +* `--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: -Adding extra argument can be done by passing the following flags to server or agent: ``` ---kube-apiserver-arg value ---kube-scheduler-arg value ---kube-controller-arg value ---kubelet-arg value ---kube-proxy-arg value -``` -For example to add the following arguments `-v=9` and `log-file=/tmp/kubeapi.log` to the kube-apiserver, you should pass the following: -``` -k3s server --kube-apiserver-arg v=9 --kube-apiserver-arg log-file=/tmp/kubeapi.log +--kube-apiserver-arg v=9 --kube-apiserver-arg log-file=/tmp/kubeapi.log ``` diff --git a/content/k3s/latest/en/running/_index.md b/content/k3s/latest/en/running/_index.md index 1ed1655dc10..4810494f109 100644 --- a/content/k3s/latest/en/running/_index.md +++ b/content/k3s/latest/en/running/_index.md @@ -8,7 +8,7 @@ This section contains information for running k3s in various environments. Starting the Server ------------------ -The installation script will auto-detect if your OS is using systemd or openrc. +The installation script will auto-detect if your OS is using systemd or openrc and start the service. When running with openrc logs will be created at `/var/log/k3s.log`, or with systemd in `/var/log/syslog` and viewed using `journalctl -u k3s`. When running the server manually you should get an output similar to: @@ -39,15 +39,16 @@ Joining Nodes ------------- When the server starts it creates a file `/var/lib/rancher/k3s/server/node-token`. -Use the contents of that file as `NODE_TOKEN` and then running the agent manually: - - k3s agent --server https://myserver:6443 --token ${NODE_TOKEN} - -Or as a `K3S_TOKEN` environment variable using the install script: +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 running with 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`. +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 ------- From 3d3ff0de4d58772f710619067b6e171c674a877d Mon Sep 17 00:00:00 2001 From: Erik Wilson Date: Wed, 26 Jun 2019 10:04:21 -0700 Subject: [PATCH 3/7] Update k3s docs per comments --- content/k3s/latest/en/configuration/_index.md | 6 +++--- content/k3s/latest/en/installation/_index.md | 12 ++++++------ content/k3s/latest/en/quick-start/_index.md | 4 ++-- content/k3s/latest/en/running/_index.md | 16 ++++++++++------ 4 files changed, 21 insertions(+), 17 deletions(-) diff --git a/content/k3s/latest/en/configuration/_index.md b/content/k3s/latest/en/configuration/_index.md index 0135e5e41ed..3c7e4728f76 100644 --- a/content/k3s/latest/en/configuration/_index.md +++ b/content/k3s/latest/en/configuration/_index.md @@ -83,7 +83,7 @@ yes then you just 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 +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 -------- @@ -93,7 +93,7 @@ _**WARNING**:_ Some advanced magic, user beware 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 improve the usability. First ensure you have proper setup and support for user namespaces. Refer to the -[requirements section](https://github.com/rootless-containers/rootlesskit#setup) in rootlesskit for instructions. +[requirements section](https://github.com/rootless-containers/rootlesskit#setup) in RootlessKit for instructions. In short, latest Ubuntu is your best bet for this to work. @@ -123,7 +123,7 @@ In short, latest Ubuntu is your best bet for this to work. **Running w/ Rootless**: Just add `--rootless` flag to either server or agent. So run `k3s server --rootless` and then look for the message -`Wrote kubeconfig [SOME PATH]` for where your kubeconfig to access you cluster is. Becareful, if you use `-o` to write +`Wrote kubeconfig [SOME PATH]` for where your kubeconfig to access you cluster is. Be careful, if you use `-o` to write the kubeconfig to a different directory it will probably not work. This is because the k3s instance in running in a different mount namespace. diff --git a/content/k3s/latest/en/installation/_index.md b/content/k3s/latest/en/installation/_index.md index 980deee37db..04cf298aebe 100644 --- a/content/k3s/latest/en/installation/_index.md +++ b/content/k3s/latest/en/installation/_index.md @@ -9,7 +9,7 @@ Install Script -------------- 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, eg: +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 - ``` @@ -20,7 +20,7 @@ environment variable to the command: curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable-agent" sh - ``` -The installer can also be run without performing downloads by setting `INSTALL_K3S_SKIP_DOWNLOAD=true`, eg: +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 @@ -228,11 +228,11 @@ The following information on server options is also available through `k3s serve * `--node-label` _value_ - (agent) Registring kubelet with set of labels + (agent) Registering kubelet with set of labels * `--node-taint` _value_ - (agent) Registring kubelet with set of taints + (agent) Registering kubelet with set of taints Agent Options ------------------ @@ -305,11 +305,11 @@ The following information on agent options is also available through `k3s agent * `--node-label` _value_ - (agent) Registring kubelet with set of labels + (agent) Registering kubelet with set of labels * `--node-taint` _value_ - (agent) Registring kubelet with set of taints + (agent) Registering kubelet with set of taints Customizing components ---------------------- diff --git a/content/k3s/latest/en/quick-start/_index.md b/content/k3s/latest/en/quick-start/_index.md index a54bcb42627..e24d414c2c1 100644 --- a/content/k3s/latest/en/quick-start/_index.md +++ b/content/k3s/latest/en/quick-start/_index.md @@ -15,7 +15,7 @@ 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`, eg: +The install script will install k3s and additional utilities, such as `kubectl`, `crictl`, `k3s-killall.sh`, and `k3s-uninstall.sh`, for example: ```bash sudo kubectl get nodes @@ -23,7 +23,7 @@ sudo kubectl get nodes `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, eg: +`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 - ``` diff --git a/content/k3s/latest/en/running/_index.md b/content/k3s/latest/en/running/_index.md index 4810494f109..3d085171d76 100644 --- a/content/k3s/latest/en/running/_index.md +++ b/content/k3s/latest/en/running/_index.md @@ -9,7 +9,11 @@ Starting the Server ------------------ The installation script will auto-detect if your OS is using systemd or openrc and start the service. -When running with openrc logs will be created at `/var/log/k3s.log`, or with systemd in `/var/log/syslog` and viewed using `journalctl -u k3s`. +When running with openrc logs will be created at `/var/log/k3s.log`, or with systemd in `/var/log/syslog` and viewed using `journalctl -u k3s`. An example of installing and auto-starting with the install script: + +```bash +curl -sfL https://get.k3s.io | sh - +``` When running the server manually you should get an output similar to: @@ -137,7 +141,7 @@ Then update **/etc/update-extlinux.conf** by adding: default_kernel_opts="... cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory" ``` -Than update the config and reboot +Then update the config and reboot: ```bash update-extlinux @@ -155,7 +159,7 @@ Running in Docker (and docker-compose) [k3d](https://github.com/rancher/k3d) is a utility designed to easily run k3s in Docker. It can be installed via the [brew](https://brew.sh/) utility for MacOS. `rancher/k3s` images are also available to run k3s server and agent from Docker. A `docker-compose.yml` is in the root of the k3s repo that -serves as an example of how to run k3s from Docker. To run from `docker-compose` from this repo run +serves as an example of how to run k3s from Docker. To run from `docker-compose` from this repo run: docker-compose up --scale node=3 # kubeconfig is written to current dir @@ -186,7 +190,7 @@ serves as an example of how to run k3s agent from Docker. Alternatively the Dock Air-Gap Support --------------- -k3s supports pre-loading of containerd images by placing them in the `images` directory for the agent before starting, eg: +k3s supports pre-loading of containerd images by placing them in the `images` directory for the agent before starting, for example: ```sh sudo mkdir -p /var/lib/rancher/k3s/agent/images/ sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/ @@ -206,7 +210,7 @@ k3s additionally provides a `--resolv-conf` flag for kubelets, which may help wi Upgrades -------- -To upgrade k3s from an older version you can re-run the installation script using the same flags, eg: +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 - @@ -253,4 +257,4 @@ 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 +you want individual binaries you will need to compile them yourself from source. From d84306758f88d835974eea602d1cac10d5eab2cc Mon Sep 17 00:00:00 2001 From: Erik Wilson Date: Wed, 26 Jun 2019 10:42:04 -0700 Subject: [PATCH 4/7] Add k3s card --- content/_index.html | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/content/_index.html b/content/_index.html index f51b656833e..f953b43275e 100644 --- a/content/_index.html +++ b/content/_index.html @@ -199,6 +199,33 @@ +
+
+

+ K3S + K3S +

+ +
+ +

Lightweight Kubernetes. Easy to install, half the memory, all in a binary less than 40mb.

+ +
+ + + +
+
+
From 3c7d5499c0ad11d80ffc4a8099057255cdddb917 Mon Sep 17 00:00:00 2001 From: Erik Wilson Date: Thu, 27 Jun 2019 13:33:19 -0700 Subject: [PATCH 5/7] Add the odd cow --- content/_index.html | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/content/_index.html b/content/_index.html index f953b43275e..ff450041074 100644 --- a/content/_index.html +++ b/content/_index.html @@ -226,6 +226,28 @@ + +
+

+ 
+
+                  ,        ,
+      ,-----------|'------'|
+     /.           '-'o  o|-'
+    |/|             | .. |
+      |   .________.'----'
+      |  ||        |  ||
+      \__|'        \__|'
+
+

+
From 0aefeeb2c6e5f738f64ad46a4ba70f066d9ef54a Mon Sep 17 00:00:00 2001 From: lvuch Date: Thu, 11 Jul 2019 09:02:43 -0700 Subject: [PATCH 6/7] addresses pr 1535 WIP --- content/_index.html | 142 ++++++++++++++++++++++---------------------- 1 file changed, 71 insertions(+), 71 deletions(-) diff --git a/content/_index.html b/content/_index.html index ff450041074..2284155c4f8 100644 --- a/content/_index.html +++ b/content/_index.html @@ -11,12 +11,12 @@

Rancher docs

@@ -45,20 +45,20 @@
@@ -90,25 +90,25 @@
-
+

2.x Rancher 2.x

- +
- +

Rancher manages all of your Kubernetes clusters everywhere, unifies them under centralized RBAC, monitors them and lets you easily deploy and manage workloads through an intuitive user interface.

- +

1.6 Rancher 1.6

- +
- +

If you haven't yet migrated to Rancher 2.x, you can still find documentation for 1.6 here. This is only for legacy users of the 1.6 product.

- +

OS RancherOS

- +
- +

RancherOS is the lightest, easiest way to run Docker in production. Engineered from the ground up for security and speed, it runs all system services and user workloads within Docker containers.

- +

RKE - Rancher Kubernetes Engine + Rancher Kubernetes Engine

- +
- +

Rancher Kubernetes Engine (RKE) is an extremely simple, lightning fast Kubernetes installer that works everywhere.

- +

K3S - K3S + K3S

- +
- +

Lightweight Kubernetes. Easy to install, half the memory, all in a binary less than 40mb.

- +
-
-
+
-->
From afafb68b9749521f29c54676148bb977101b8fdd Mon Sep 17 00:00:00 2001 From: lvuch Date: Thu, 11 Jul 2019 11:47:14 -0700 Subject: [PATCH 7/7] rip odd cow --- content/_index.html | 22 ---------------------- 1 file changed, 22 deletions(-) diff --git a/content/_index.html b/content/_index.html index 2284155c4f8..583a56f29b9 100644 --- a/content/_index.html +++ b/content/_index.html @@ -226,28 +226,6 @@
- -