K3s: [Documentation] A bunch of random little changes for docs

[cjellick]

I did a pass of reviewing the docs and identified these mostly minor changes. I may be wrong in some of my feedback. Don't take it for gospel.

https://rancher.com/docs/k3s/latest/en/quick-start/

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 section covers in greater detail how k3s can be setup.

• [x] _We should take care to note that for a lot of low-stakes prod setups, single node is fine, like “or production environments that can tolerate downtime of the kubernetes control plane.” Also state that downtime of the control plane does not create downtime in the running containers/_

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

• [x] _From just this guide, I have no idea what the values of k3s_token or k3s_cluster_secret should be._

https://rancher.com/docs/k3s/latest/en/installation/

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.

• [x] _Same note as above: don't block single-node out of production completely._

https://rancher.com/docs/k3s/latest/en/installation/node-requirements/

k3s is very lightweight, but has some minimum requirements as outlined below.

• [x] _Generally, capitalization should be K3s. We probably need to do an audit across all the docs for capitalization. Very low priority_

In a separate conversation a month or so ago we (not sure who all) suggested k3s should always be lowercase.

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.

• [x] _seems like we should say "pass --node-name or set $..."_

Networking

• [x] _In this section, add a table or outline of ports for better readability._

Let's do this after v1.0 release or if we have spare time around this time as a lower-priority.

https://rancher.com/docs/k3s/latest/en/installation/single-server/

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.

• [x] _Same note about production needing to be HA_

To specify a specific version for download we can use the

• [x] _Too many specif*s. Sounds weird._

Server Options and Agent Options

• [x] _These sections are probably out of date. Need repulled from the cli. I don't really like that we bullet list the flags. I'm not sure what would be better. Maybe a table. Maybe literally a code block that contains the help text? I also don't like that the agent flags are duplicated in the server options section. I'm not 100% sure how to make this better, but I know I don't like it as-is._

Note https://github.com/rancher/k3s/issues/1035 is being used to track general cli changes but the other comments are valid here; for example the look of the flags in the docs.

To install with a specific flag we can use the INSTALL_K3S_EXEC environment variable. For example

• [x] _The example could be improved if it contained more than argument to pass._

The full help text for the install script environment variables are as follows: - K3S_*

• [x] _This section is weird. I don't know what we are trying to accomplish by having the help text in a code block or quote block or whatever it is rather than just saying it._

If set to ‘skip’ will not create symlinks, ‘force’ will overwrite, default will symlink if command does not exist in path.

• [x] _This could be improved by explaining or at least summarzing what symlinks are created, like "The installation process creates symlinks for x, y, and z..._

INSTALL_K3S_EXEC or script arguments

• [x] _What is “or script arguments”? Confusing._

I agree; I'm not quite sure what it means - need to sync with Erik.

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-’.

• [x] _This documentation just isn't clear. This part in particular is confusing "will default from the k3s exec command." I think it could be clarified with an example._

--data-dir value, -d value
Folder to hold state default /var/lib/rancher/k3s or ${HOME}/.rancher/k3s if not root

• [x] _Should say directory instead of folder (I guess I dont REALLY care)_

This is a CLI help issue that will have to be addressed via https://github.com/rancher/k3s/issues/1601

--write-kubeconfig-mode value
Write kubeconfig with this mode [$K3S_KUBECONFIG_MODE]

• [x] _I'm guessing the input is like 0644, but this could be improved with an example._

This is a CLI help issue that will have to be addressed via https://github.com/rancher/k3s/issues/1601

--no-deploy value
Do not deploy packaged components (val

• [x] _add local-storage and metrics-server_

Tracked in https://github.com/rancher/k3s/issues/1035 so I'll check this off as complete as will be handled separately.

--kube-apiserver-arg value
Customized flag for kube-apiserver process

• [x] _Could use an example_

https://github.com/rancher/k3s/issues/1601

--advertise-address value
IP address that apiserver uses to advertise to members of the cluster

• [x] _I'm not sure a new user would understhand exactly what this does._

https://github.com/rancher/k3s/issues/1601

--docker
(agent) Use docker instead of containerd

• [x] _Do you think we need to clarify that this causes us to use the host docker daemon?_

I don't think so -- just my opinion; leaving it as-is for now.

https://rancher.com/docs/k3s/latest/en/advanced/

This whole doc is laid out in a confusing way. Was not clear to me that the “Alpine Linux” section was an alternative to the install script. This is layout thing, so don't need to do until we finish the current refactor and see how things are.

• [x] _The running in docker section should be broken out into its own thing, maybe the faq._

As we recently discussed 11/11/19 probably no? FAQ should be fairly quick questions and answers which can hyperlink to sections in docs if needed. We may want to revisit this later with another solution. Needs discussion. -- actually we can handle via https://github.com/rancher/k3s/issues/1582

• [x] _Air-gap support isn’t clear enough. Should be a step-by-step walk-through guide._

Agree. I am going to handle this separately in this issue: https://github.com/rancher/k3s/issues/1051 as such I've marked it as resolved by checking the checkbox here.

When running the server manually you should get an output similar to:

• [x] _I think the word "an" in the sentence is awkward_

Respectfully disagree here. We should use the proper article and thus "an" (followed by vowel-sound). Ex: "I'll be there in an hour"

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:
…
k3s additionally provides a --resolv-conf flag for kubelets, which may help with configuring DNS in air-gap networks.

• [x] _Too non-commital. Says things like "may" and "might". We need to solidify._ Note this is now moved into the airgap doc will need to address there.

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).

• [x] _should be “the help of THE install.sh script”. missing the the_

Must have already been fixed in an unrelated PR recently so I checked this one off as done.

hyperkube

• [x] _We should add more explanation. This is what I caught from either Hussein or Erik: K3s includes userspace utilities and containerd, hypekube includes some changes that we have made to k8s for k3s here: https://github.com/rancher/kubernetes/commits/v1.16.2-k3s.1_

We completely removed the little hyperkube section per our conversations recently. We plan to eventually remove support so we are starting with docs.

https://rancher.com/docs/k3s/latest/en/configuration/

• [x] _helm integration should have its own dedicated page I think. Not sure. This is layout thing, so don't need to do until we finish the current refactor and see how things are._

Open Ports / Network Securitylink

• [x] _Should be a table or outline of ports_

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

• [ ] _This needs improved. What is the config.Node that it is referencing?_

Metrics Server

• [x] _make sure we update to reflect that its in by default_

Already to be addressed in this separate issue: https://github.com/rancher/k3s/issues/991

Storage backends

• [x] _layout thing: think this should be its own page_

Already has bee moved to the ha install page as it made sense to go there. See https://github.com/rancher/docs/pull/1985 for details.

Specify etcd, Mysql, Postgres, or Sqlite (default) data source name [$K3S_STORAGE_ENDPOINT]

• [x] _For me, it looks like there is a space between $ and K on the docs site. We probably cannot do anything about this_

Nothing we can do, we can tweak styling in a separate issue if needed.

[cjellick]

Can we change "Installation Options" to just "Installation". Thats what we call it in the rancher docs

[cjellick]

Ok, one final set of tweaks are needed for the HA diagram:

• The arrow between Kubectl and Load Balancer should not be bi-directional. It should only flow from kubectl to LB
• The arrows between Load Balancer and Server nodes should not be bi-directional. They should only flow from LB to Server nodes
• The connections between Server nodes and External Database should have an arrow that flows from Server nodes to the External Database

[cjellick]

On https://rancher.com/docs/k3s/latest/en/installation/ha/

A load balancer to expose the Kubernetes API for worker node registration and admin access via kubectl

This should be reworded to "A load balancer to expose the Kubernetes API for clients such as kubectl and to expose a stable k3s worker registration endpoint"

The current wording conflates the k8s api with node registration.

[cjellick]

On https://rancher.com/docs/k3s/latest/en/installation/ha/

The HA database shown should be a single endpoint k3s can access such as a load balancer.

Drop "such as a load balancer". As previously discussed, the topic of load balanced sql databases is not a can of worms we need to open.

[davidnuzik]

Moved to v1.x - Backlog milestone to review post-kubecon release. There are some unaddressed valid concerns in this issue that are lower priority. Otherwise most of the checked off items (and all comments on the issue so far) will be addressed in https://github.com/rancher/docs/pull/1990

[davidnuzik]

Remaining issues have either been resolved in other recent updates to docs or as a part of my new PR https://github.com/rancher/docs/pull/2410

I have two remaining areas I need to investigate as outlined below.

Advanced:

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

• [ ] _This needs improved. What is the config.Node that it is referencing?_

Airgap:

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:
…
k3s additionally provides a --resolv-conf flag for kubelets, which may help with configuring DNS in air-gap networks.

• [x] _Too non-commital. Says things like "may" and "might". We need to solidify._ Note this is now moved into the airgap doc will need to address there.

[davidnuzik]

Changes in, assign to Hussein to work on remaining part:

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

_This needs improved. What is the config.Node that it is referencing?_

[davidnuzik]

Closing this as it's complete - we'll handle the remaining area via https://github.com/rancher/k3s/issues/1932