[Docs] v5 update (#740)

k3d-io · Sep 17, 2021 · 3b9d837 · 3b9d837
1 parent bfe1efb
commit 3b9d837
Show file tree

Hide file tree

Showing 37 changed files with 229 additions and 166 deletions.
diff --git a/docgen/go.mod b/docgen/go.mod
@@ -3,20 +3,11 @@ module github.com/rancher/k3d/docgen
 go 1.16
 
 require (
-	github.com/Microsoft/go-winio v0.4.17 // indirect
-	github.com/containerd/cgroups v0.0.0-20210414074453-680c246289fb // indirect
-	github.com/containerd/containerd v1.5.0-rc.1 // indirect
-	github.com/containerd/continuity v0.0.0-20210315143101-93e15499afd5 // indirect
-	github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
 	github.com/google/gofuzz v1.2.0 // indirect
-	github.com/rancher/k3d/v5 v4.4.7-0.20210709062205-c5f7884f7870
-	github.com/sirupsen/logrus v1.8.1
+	github.com/rancher/k3d/v5 v5.0.0-00010101000000-000000000000
 	github.com/spf13/cobra v1.2.1
-	golang.org/x/net v0.0.0-20210410081132-afb366fc7cd1 // indirect
 	golang.org/x/oauth2 v0.0.0-20210413134643-5e61552d6c78 // indirect
 	golang.org/x/term v0.0.0-20210406210042-72f3dc4e9b72 // indirect
-	k8s.io/utils v0.0.0-20210305010621-2afb4311ab10 // indirect
-	sigs.k8s.io/structured-merge-diff/v4 v4.1.1 // indirect
 )
 
 replace github.com/rancher/k3d/v5 => /PATH/TO/YOUR/REPO/DIRECTORY
diff --git a/docgen/go.sum b/docgen/go.sum
diff --git a/docgen/run.sh b/docgen/run.sh
@@ -16,3 +16,7 @@ go mod tidy
 go mod vendor
 
 go run ./main.go
+
+sed -i "s%$REPO_DIR%$REPLACE_PLACEHOLDER%" "$CURR_DIR/go.mod"
+
+rm -r "$CURR_DIR/vendor"
diff --git a/docs/.pages b/docs/.pages
@@ -1,6 +1,6 @@
 nav:
   - index.md
   - usage
-  - internals
+  - design
   - faq
-collapse: false
+collapse: false
diff --git a/docs/internals/.pages → docs/design/.pages b/docs/internals/.pages → docs/design/.pages
@@ -1,5 +1,5 @@
-title: Internals
+title: Design
 nav:
-  - defaults.md
   - project.md
+  - defaults.md
   - networking.md
diff --git a/docs/design/defaults.md b/docs/design/defaults.md
@@ -0,0 +1,60 @@
+# Defaults
+
+## k3d reserved settings
+
+When you create a K3s cluster in Docker using k3d, we make use of some K3s configuration options, making them "reserved" for k3d.
+This means, that overriding those options with your own may break the cluster setup.
+
+### Environment Variables
+
+The following K3s environment variables are used to configure the cluster:
+
+| Variable | K3d Default | Configurable? |
+|----------|-------------|---------------|
+| `K3S_URL`| `https://$CLUSTERNAME-server-0:6443` | no |
+| `K3S_TOKEN`| random | yes (`--token`) |
+| `K3S_KUBECONFIG_OUTPUT`| `/output/kubeconfig.yaml` | no |
+
+## k3d Loadbalancer
+
+By default, k3d creates an Nginx loadbalancer alongside the clusters it creates to handle the port-forwarding.
+The loadbalancer can partly be configured using k3d-defined settings.
+
+| Nginx setting | k3d default | k3d setting |
+|-------------|-------------|-------------|
+| `proxy_timeout` (default for all server stanzas) | `600` (s) | `settings.defaultProxyTimeout` |  |
+|`worker_connections` | `1024` | `settings.workerConnections` |
+
+### Overrides
+
+- Example via CLI: `k3d cluster create --lb-config-override settings.defaultProxyTimeout=900`
+- Example via Config File:
+
+  ```yaml
+  # ... truncated ...
+  k3d:
+    loadbalancer:
+      configOverrides:
+        - settings.workerConnections=2048
+  ```
+
+## Multiple server nodes
+
+- by default, when `--server` > 1 and no `--datastore-x` option is set, the first server node (server-0) will be the initializing server node
+  - the initializing server node will have the `--cluster-init` flag appended
+  - all other server nodes will refer to the initializing server node via `--server https://<init-node>:6443`
+
+## API-Ports
+
+- by default, we expose the API-Port (`6443`) by forwarding traffic from the default server loadbalancer (nginx container) to the server node(s)
+- port `6443` of the loadbalancer is then mapped to a specific (`--api-port` flag) or a random (default) port on the host system
+
+## Kubeconfig
+
+- if `--kubeconfig-update-default` is set, we use the default loading rules to get the default kubeconfig:
+  - First: kubeconfig specified via the KUBECONFIG environment variable (error out if multiple are specified)
+  - Second: default kubeconfig in home directory (e.g. `$HOME/.kube/config`)
+
+## Networking
+
+- [by default, k3d creates a new (docker) network for every cluster](./networking)
diff --git a/docs/internals/networking.md → docs/design/networking.md b/docs/internals/networking.md → docs/design/networking.md
diff --git a/docs/internals/project.md → docs/design/project.md b/docs/internals/project.md → docs/design/project.md
diff --git a/docs/faq/.pages b/docs/faq/.pages
@@ -1,3 +1,4 @@
 title: FAQ
 nav:
-  - faq.md
+  - faq.md
+collapse: true
diff --git a/docs/faq/faq.md b/docs/faq/faq.md
@@ -1,4 +1,4 @@
-# FAQ / Nice to know
+# FAQ
 
 ## Issues with BTRFS
 

diff --git a/docs/index.md b/docs/index.md
@@ -2,12 +2,14 @@
 
 ![k3d](static/img/k3d_logo_black_blue.svg)
 
-**This page is targeting k3d v5.0.0 and newer!**
+## What is k3d?
 
 k3d is a lightweight wrapper to run [k3s](https://github.com/rancher/k3s) (Rancher Lab's minimal Kubernetes distribution) in docker.
 
 k3d makes it very easy to create single- and multi-node [k3s](https://github.com/rancher/k3s) clusters in docker, e.g. for local development on Kubernetes.
 
+**Note:** k3d is a **community-driven project**, that is supported by Rancher (SUSE) and it's not an official Rancher (SUSE) project.
+
 ??? Tip "View a quick demo"
     <asciinema-player src="/static/asciicast/20200715_k3d.01.cast" cols=200 rows=32></asciinema-player>
 
@@ -25,7 +27,8 @@ k3d makes it very easy to create single- and multi-node [k3s](https://github.com
 
 ## Requirements
 
-- [docker](https://docs.docker.com/install/)
+- [**docker**](https://docs.docker.com/install/) to be able to use k3d at all
+- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) to interact with the Kubernetes cluster
 
 ## Releases
 

diff --git a/docs/internals/defaults.md b/docs/internals/defaults.md
diff --git a/docs/static/css/extra.css b/docs/static/css/extra.css
@@ -23,10 +23,28 @@
     position: relative;
 }
 
+/* This is equal to light mode */
 [data-md-color-primary=black] .md-tabs {
+
+    /* Set color of the tab bar */
     background-color: #0DCEFF;
 }
 
+/* Dark Mode */
+[data-md-color-scheme="slate"] .md-header {
+    /* keep black backgroud of title bar (header) */
+    background-color: black;
+}
+
+/* Tab Bar */
 .md-tabs {
     color: black;
 }
+
+.md-tabs__item {
+    font-weight: bolder;
+}
+
+.md-tabs__link--active {
+    text-decoration: underline;
+}
diff --git a/docs/usage/.pages b/docs/usage/.pages
@@ -1,7 +1,9 @@
-title: Usage
+title: Guides
 nav:
-  - commands
   - configfile.md
   - kubeconfig.md
   - multiserver.md
-  - guides
+  - registries.md
+  - exposing_services.md
+  - advanced
+  - commands
diff --git a/docs/usage/advanced/.pages b/docs/usage/advanced/.pages
@@ -0,0 +1,4 @@
+title: Advanced Guides
+nav:
+  - calico.md
+  - cuda.md
diff --git a/docs/usage/guides/calico.md → docs/usage/advanced/calico.md b/docs/usage/guides/calico.md → docs/usage/advanced/calico.md
diff --git a/docs/usage/guides/calico.yaml → docs/usage/advanced/calico.yaml b/docs/usage/guides/calico.yaml → docs/usage/advanced/calico.yaml
diff --git a/docs/usage/guides/cuda.md → docs/usage/advanced/cuda.md b/docs/usage/guides/cuda.md → docs/usage/advanced/cuda.md
diff --git a/docs/usage/guides/cuda/Dockerfile → docs/usage/advanced/cuda/Dockerfile b/docs/usage/guides/cuda/Dockerfile → docs/usage/advanced/cuda/Dockerfile
diff --git a/docs/usage/guides/cuda/build.sh → docs/usage/advanced/cuda/build.sh b/docs/usage/guides/cuda/build.sh → docs/usage/advanced/cuda/build.sh
diff --git a/docs/usage/guides/cuda/config.toml.tmpl → docs/usage/advanced/cuda/config.toml.tmpl b/docs/usage/guides/cuda/config.toml.tmpl → docs/usage/advanced/cuda/config.toml.tmpl
diff --git a/docs/usage/guides/cuda/cuda-vector-add.yaml → .../usage/advanced/cuda/cuda-vector-add.yaml b/docs/usage/guides/cuda/cuda-vector-add.yaml → .../usage/advanced/cuda/cuda-vector-add.yaml
diff --git a/.../guides/cuda/device-plugin-daemonset.yaml → ...dvanced/cuda/device-plugin-daemonset.yaml b/.../guides/cuda/device-plugin-daemonset.yaml → ...dvanced/cuda/device-plugin-daemonset.yaml
diff --git a/docs/usage/commands/k3d_cluster_create.md b/docs/usage/commands/k3d_cluster_create.md
@@ -35,15 +35,16 @@ k3d cluster create NAME [flags]
                                                                         - Example: `k3d cluster create --agents 2 --k3s-node-label "my.label@agent:0,1" --k3s-node-label "other.label=somevalue@server:0"`
       --kubeconfig-switch-context                                      Directly switch the default kubeconfig's current-context to the new cluster's context (requires --kubeconfig-update-default) (default true)
       --kubeconfig-update-default                                      Directly update the default kubeconfig with the new cluster's context (default true)
+      --lb-config-override strings                                     Use dotted YAML path syntax to override nginx loadbalancer settings
       --network string                                                 Join an existing network
-      --no-hostip                                                      Disable the automatic injection of the Host IP as 'host.k3d.internal' into the containers and CoreDNS
       --no-image-volume                                                Disable the creation of a volume for importing images
       --no-lb                                                          Disable the creation of a LoadBalancer in front of the server nodes
       --no-rollback                                                    Disable the automatic rollback actions, if anything goes wrong
   -p, --port [HOST:][HOSTPORT:]CONTAINERPORT[/PROTOCOL][@NODEFILTER]   Map ports from the node containers (via the serverlb) to the host (Format: [HOST:][HOSTPORT:]CONTAINERPORT[/PROTOCOL][@NODEFILTER])
                                                                         - Example: `k3d cluster create --agents 2 -p 8080:80@agent:0 -p 8081@agent:1`
       --registry-config string                                         Specify path to an extra registries.yaml file
-      --registry-create                                                Create a k3d-managed registry and connect it to the cluster
+      --registry-create NAME[:HOST][:HOSTPORT]                         Create a k3d-managed registry and connect it to the cluster (Format: NAME[:HOST][:HOSTPORT]
+                                                                        - Example: `k3d cluster create --registry-create mycluster-registry:0.0.0.0:5432`
       --registry-use stringArray                                       Connect to one or more k3d-managed registries running locally
       --runtime-label KEY[=VALUE][@NODEFILTER[;NODEFILTER...]]         Add label to container runtime (Format: KEY[=VALUE][@NODEFILTER[;NODEFILTER...]]
                                                                         - Example: `k3d cluster create --agents 2 --runtime-label "my.label@agent:0,1" --runtime-label "other.label=somevalue@server:0"`

diff --git a/docs/usage/commands/k3d_cluster_delete.md b/docs/usage/commands/k3d_cluster_delete.md
@@ -13,8 +13,9 @@ k3d cluster delete [NAME [NAME ...] | --all] [flags]
 ### Options
 
 ```
-  -a, --all    Delete all existing clusters
-  -h, --help   help for delete
+  -a, --all             Delete all existing clusters
+  -c, --config string   Path of a config file to use
+  -h, --help            help for delete
 ```
 
 ### Options inherited from parent commands

diff --git a/docs/usage/commands/k3d_node_create.md b/docs/usage/commands/k3d_node_create.md
@@ -15,13 +15,15 @@ k3d node create NAME [flags]
 ```
   -c, --cluster string           Select the cluster that the node shall connect to. (default "k3s-default")
   -h, --help                     help for create
-  -i, --image string             Specify k3s image used for the node(s) (default "docker.io/rancher/k3s:v1.20.0-k3s2")
+  -i, --image string             Specify k3s image used for the node(s) (default "docker.io/rancher/k3s:v1.21.4-k3s2")
       --k3s-node-label strings   Specify k3s node labels in format "foo=bar"
       --memory string            Memory limit imposed on the node [From docker]
+  -n, --network strings          Add node to (another) runtime network
       --replicas int             Number of replicas of this node specification. (default 1)
       --role string              Specify node role [server, agent] (default "agent")
       --runtime-label strings    Specify container runtime labels in format "foo=bar"
       --timeout duration         Maximum waiting time for '--wait' before canceling/returning.
+  -t, --token string             Override cluster token (required when connecting to an external cluster)
       --wait                     Wait for the node(s) to be ready before returning. (default true)
 ```
 

diff --git a/docs/usage/configfile.md b/docs/usage/configfile.md
@@ -1,9 +1,8 @@
-# Config File
+# Using Config Files
 
-## Introduction
+The config file feature is **available as of k3d v4.0.0**
 
-As of k3d v4.0.0, released in January 2021, k3d ships with configuration file support for the `k3d cluster create` command.  
-This allows you to define all the things that you defined with CLI flags before in a nice and tidy YAML (as a Kubernetes user, we know you love it ;) ).
+## Introduction
 
 !!! info "Syntax & Semantics"
     The options defined in the config file are not 100% the same as the CLI flags.  
@@ -62,6 +61,7 @@ kubeAPI: # same as `--api-port myhost.my.domain:6445` (where the name would reso
   hostPort: "6445" # where the Kubernetes API listening port will be mapped to on your host system
 image: rancher/k3s:v1.20.4-k3s1 # same as `--image rancher/k3s:v1.20.4-k3s1`
 network: my-custom-net # same as `--network my-custom-net`
+subnet: "172.28.0.0/16" # same as `--subnet 172.28.0.0/16`
 token: superSecretToken # same as `--token superSecretToken`
 volumes: # repeatable flags are represented as YAML lists
   - volume: /my/host/path:/path/in/node # same as `--volume '/my/host/path:/path/in/node@server:0;agent:*'`
@@ -77,8 +77,10 @@ env:
     nodeFilters:
       - server:0
 registries: # define how registries should be created or used
-  create:
-    name: registry.localhost # creates a default registry to be used with the cluster; same as `--registry-create registry.localhost`
+  create: # creates a default registry to be used with the cluster; same as `--registry-create registry.localhost`
+    name: registry.localhost
+    host: "0.0.0.0"
+    hostPort: "5000"
   use:
     - k3d-myotherregistry:5000 # some other k3d-managed registry; same as `--registry-use 'k3d-myotherregistry:5000'`
   config: | # define contents of the `registries.yaml` file (or reference a file); same as `--registry-config /path/to/config.yaml`
@@ -93,6 +95,9 @@ options:
     disableLoadbalancer: false # same as `--no-lb`
     disableImageVolume: false # same as `--no-image-volume`
     disableRollback: false # same as `--no-Rollback`
+    loadbalancer:
+      configOverrides:
+        - settings.workerConnections=2048
   k3s: # options passed on to K3s itself
     extraArgs: # additional arguments passed to the `k3s server|agent` command; same as `--k3s-arg`
       - arg: --tls-san=my.host.domain
@@ -129,4 +134,4 @@ For example, you use the same config file to create three clusters which only ha
 ## References
 
 - k3d demo repository: <https://github.com/iwilltry42/k3d-demo/blob/main/README.md#config-file-support>
-- SUSE Blog: <https://www.suse.com/c/introduction-k3d-run-k3s-docker-src/> (Search fo `The “Configuration as Code” Way`)
+- SUSE Blog: <https://www.suse.com/c/introduction-k3d-run-k3s-docker-src/> (Search for `The “Configuration as Code” Way`)
diff --git a/docs/usage/guides/exposing_services.md → docs/usage/exposing_services.md b/docs/usage/guides/exposing_services.md → docs/usage/exposing_services.md
diff --git a/docs/usage/guides/.pages b/docs/usage/guides/.pages
diff --git a/docs/usage/multiserver.md b/docs/usage/multiserver.md
@@ -1,12 +1,12 @@
 # Creating multi-server clusters
 
 !!! info "Important note"
-    For the best results (and less unexpected issues), choose 1, 3, 5, ... server nodes.
+    For the best results (and less unexpected issues), choose 1, 3, 5, ... server nodes. (Read more on etcd quorum on [etcd.io](https://etcd.io/docs/v3.3/faq/#why-an-odd-number-of-cluster-members))
     At least 2 cores and 4GiB of RAM are recommended.
 
-## Embedded etcd (old: dqlite)
+## Embedded etcd
 
-Create a cluster with 3 server nodes using k3s' embedded etcd (old: dqlite) database.
+Create a cluster with 3 server nodes using k3s' embedded etcd database.
 The first server to be created will use the `--cluster-init` flag and k3d will wait for it to be up and running before creating (and connecting) the other server nodes.
 
 ```bash
@@ -23,4 +23,4 @@ k3d node create newserver --cluster multiserver --role server
 
 !!! important "There's a trap!"
     If your cluster was initially created with only a single server node, then this will fail.  
-    That's because the initial server node was not started with the `--cluster-init` flag and thus is not using the etcd (old: dqlite) backend.
+    That's because the initial server node was not started with the `--cluster-init` flag and thus is not using the etcd backend.