[Enhancement] Docs: update for v5 (first iteration) (#682)

Author: iwilltry42

cmd/cluster/clusterCreate.go

@@ -298,16 +298,16 @@ func NewCmdClusterCreate() *cobra.Command {
 	cmd.Flags().StringArrayP("env", "e", nil, "Add environment variables to nodes (Format: `KEY[=VALUE][@NODEFILTER[;NODEFILTER...]]`\n - Example: `k3d cluster create --agents 2 -e \"HTTP_PROXY=my.proxy.com@server:0\" -e \"SOME_KEY=SOME_VAL@server:0\"`")
 	_ = ppViper.BindPFlag("cli.env", cmd.Flags().Lookup("env"))
 
-	cmd.Flags().StringArrayP("volume", "v", nil, "Mount volumes into the nodes (Format: `[SOURCE:]DEST[@NODEFILTER[;NODEFILTER...]]`\n - Example: `k3d cluster create --agents 2 -v /my/path@agent[0,1] -v /tmp/test:/tmp/other@server:0`")
+	cmd.Flags().StringArrayP("volume", "v", nil, "Mount volumes into the nodes (Format: `[SOURCE:]DEST[@NODEFILTER[;NODEFILTER...]]`\n - Example: `k3d cluster create --agents 2 -v /my/path@agent:0,1 -v /tmp/test:/tmp/other@server:0`")
 	_ = ppViper.BindPFlag("cli.volumes", cmd.Flags().Lookup("volume"))
 
-	cmd.Flags().StringArrayP("port", "p", nil, "Map ports from the node containers (via the serverlb) to the host (Format: `[HOST:][HOSTPORT:]CONTAINERPORT[/PROTOCOL][@NODEFILTER]`)\n - Example: `k3d cluster create --agents 2 -p 8080:80@agent:0 -p 8081@agent[1]`")
+	cmd.Flags().StringArrayP("port", "p", nil, "Map ports from the node containers (via the serverlb) to the host (Format: `[HOST:][HOSTPORT:]CONTAINERPORT[/PROTOCOL][@NODEFILTER]`)\n - Example: `k3d cluster create --agents 2 -p 8080:80@agent:0 -p 8081@agent:1`")
 	_ = ppViper.BindPFlag("cli.ports", cmd.Flags().Lookup("port"))
 
-	cmd.Flags().StringArrayP("k3s-node-label", "", nil, "Add label to k3s node (Format: `KEY[=VALUE][@NODEFILTER[;NODEFILTER...]]`\n - Example: `k3d cluster create --agents 2 --k3s-node-label \"my.label@agent[0,1]\" --k3s-node-label \"other.label=somevalue@server:0\"`")
+	cmd.Flags().StringArrayP("k3s-node-label", "", nil, "Add label to k3s node (Format: `KEY[=VALUE][@NODEFILTER[;NODEFILTER...]]`\n - Example: `k3d cluster create --agents 2 --k3s-node-label \"my.label@agent:0,1\" --k3s-node-label \"other.label=somevalue@server:0\"`")
 	_ = ppViper.BindPFlag("cli.k3s-node-labels", cmd.Flags().Lookup("k3s-node-label"))
 
-	cmd.Flags().StringArrayP("runtime-label", "", nil, "Add label to container runtime (Format: `KEY[=VALUE][@NODEFILTER[;NODEFILTER...]]`\n - Example: `k3d cluster create --agents 2 --runtime-label \"my.label@agent[0,1]\" --runtime-label \"other.label=somevalue@server:0\"`")
+	cmd.Flags().StringArrayP("runtime-label", "", nil, "Add label to container runtime (Format: `KEY[=VALUE][@NODEFILTER[;NODEFILTER...]]`\n - Example: `k3d cluster create --agents 2 --runtime-label \"my.label@agent:0,1\" --runtime-label \"other.label=somevalue@server:0\"`")
 	_ = ppViper.BindPFlag("cli.runtime-labels", cmd.Flags().Lookup("runtime-label"))
 
 	/* k3s */

docgen/README.md

@@ -6,12 +6,10 @@ The code will output files in [`../docs/usage/commands/`](../docs/usage/commands
 
 ## Run
 
-- may required a `replace github.com/rancher/k3d/v4 => PATH/TO/LOCAL/REPO` in the `go.mod`
-
 ```bash
 # ensure that you're in the docgen dir, as the relative path to the docs/ dir is hardcoded
 cd docgen
 
 # run
-go run ./main.go
+./run.sh
 ```

docgen/go.mod

@@ -10,10 +10,13 @@ require (
 	github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
 	github.com/google/gofuzz v1.2.0 // indirect
 	github.com/rancher/k3d/v4 v4.4.7-0.20210709062205-c5f7884f7870
-	github.com/spf13/cobra v1.1.3
+	github.com/sirupsen/logrus v1.8.1
+	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/v4 => /PATH/TO/YOUR/REPO/DIRECTORY

docgen/go.sum

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+REPLACE_PLACEHOLDER="/PATH/TO/YOUR/REPO/DIRECTORY"
+
+CURR_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+[ -d "$CURR_DIR" ] || { echo "FATAL: no current dir (maybe running in zsh?)";  exit 1; }
+
+REPO_DIR=${CURR_DIR%"/docgen"}
+
+echo "$REPO_DIR"
+
+sed -i "s%$REPLACE_PLACEHOLDER%$REPO_DIR%" "$CURR_DIR/go.mod"
+
+go mod tidy
+
+go mod vendor
+
+go run ./main.go

docgen/run.sh

@@ -29,6 +29,7 @@ k3d cluster [flags]
 * [k3d](k3d.md)	 - https://k3d.io/ -> Run k3s in Docker!
 * [k3d cluster create](k3d_cluster_create.md)	 - Create a new cluster
 * [k3d cluster delete](k3d_cluster_delete.md)	 - Delete cluster(s).
+* [k3d cluster edit](k3d_cluster_edit.md)	 - [EXPERIMENTAL] Edit cluster(s).
 * [k3d cluster list](k3d_cluster_list.md)	 - List cluster(s)
 * [k3d cluster start](k3d_cluster_start.md)	 - Start existing k3d cluster(s)
 * [k3d cluster stop](k3d_cluster_stop.md)	 - Stop existing k3d cluster(s)

docs/usage/commands/k3d_cluster.md

@@ -31,27 +31,29 @@ k3d cluster create NAME [flags]
   -i, --image string                                                   Specify k3s image that you want to use for the nodes
       --k3s-arg ARG@NODEFILTER[;@NODEFILTER]                           Additional args passed to k3s command (Format: ARG@NODEFILTER[;@NODEFILTER])
                                                                         - Example: `k3d cluster create --k3s-arg "--disable=traefik@server:0"
+      --k3s-node-label KEY[=VALUE][@NODEFILTER[;NODEFILTER...]]        Add label to k3s node (Format: KEY[=VALUE][@NODEFILTER[;NODEFILTER...]]
+                                                                        - 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)
-  -l, --label KEY[=VALUE][@NODEFILTER[;NODEFILTER...]]                 Add label to node container (Format: KEY[=VALUE][@NODEFILTER[;NODEFILTER...]]
-                                                                        - Example: `k3d cluster create --agents 2 -l "my.label@agent[0,1]" -l "other.label=somevalue@server:0"`
       --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 to the host (Format: [HOST:][HOSTPORT:]CONTAINERPORT[/PROTOCOL][@NODEFILTER])
-                                                                        - Example: `k3d cluster create --agents 2 -p 8080:80@agent:0 -p 8081@agent[1]`
+  -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-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"`
   -s, --servers int                                                    Specify how many servers you want to create
       --servers-memory string                                          Memory limit imposed on the server nodes [From docker]
       --subnet 172.28.0.0/16                                           [Experimental: IPAM] Define a subnet for the newly created container network (Example: 172.28.0.0/16)
       --timeout duration                                               Rollback changes if cluster couldn't be created in specified duration.
       --token string                                                   Specify a cluster token. By default, we generate one.
   -v, --volume [SOURCE:]DEST[@NODEFILTER[;NODEFILTER...]]              Mount volumes into the nodes (Format: [SOURCE:]DEST[@NODEFILTER[;NODEFILTER...]]
-                                                                        - Example: `k3d cluster create --agents 2 -v /my/path@agent[0,1] -v /tmp/test:/tmp/other@server:0`
+                                                                        - Example: `k3d cluster create --agents 2 -v /my/path@agent:0,1 -v /tmp/test:/tmp/other@server:0`
       --wait                                                           Wait for the server(s) to be ready before returning. Use '--timeout DURATION' to not wait forever. (default true)
 ```
 

docs/usage/commands/k3d_cluster_create.md

@@ -0,0 +1,32 @@
+## k3d cluster edit
+
+[EXPERIMENTAL] Edit cluster(s).
+
+### Synopsis
+
+[EXPERIMENTAL] Edit cluster(s).
+
+```
+k3d cluster edit CLUSTER [flags]
+```
+
+### Options
+
+```
+  -h, --help                                                               help for edit
+      --port-add [HOST:][HOSTPORT:]CONTAINERPORT[/PROTOCOL][@NODEFILTER]   [EXPERIMENTAL] Map ports from the node containers (via the serverlb) to the host (Format: [HOST:][HOSTPORT:]CONTAINERPORT[/PROTOCOL][@NODEFILTER])
+                                                                            - Example: `k3d node edit k3d-mycluster-serverlb --port-add 8080:80`
+```
+
+### Options inherited from parent commands
+
+```
+      --timestamps   Enable Log timestamps
+      --trace        Enable super verbose output (trace logging)
+      --verbose      Enable verbose output (debug logging)
+```
+
+### SEE ALSO
+
+* [k3d cluster](k3d_cluster.md)	 - Manage cluster(s)
+

docs/usage/commands/k3d_cluster_edit.md

@@ -4,10 +4,48 @@ Generate completion scripts for [bash, zsh, fish, powershell | psh]
 
 ### Synopsis
 
-Generate completion scripts for [bash, zsh, fish, powershell | psh]
+To load completions:
+
+Bash:
+
+	$ source <(k3d completion bash)
+
+	# To load completions for each session, execute once:
+	# Linux:
+	$ k3d completion bash > /etc/bash_completion.d/k3d
+	# macOS:
+	$ k3d completion bash > /usr/local/etc/bash_completion.d/k3d
+
+Zsh:
+
+	# If shell completion is not already enabled in your environment,
+	# you will need to enable it.  You can execute the following once:
+
+	$ echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+	# To load completions for each session, execute once:
+	$ k3d completion zsh > "${fpath[1]}/k3d"
+
+	# You will need to start a new shell for this setup to take effect.
+
+fish:
+
+	$ k3d completion fish | source
+
+	# To load completions for each session, execute once:
+	$ k3d completion fish > ~/.config/fish/completions/k3d.fish
+
+PowerShell:
+
+	PS> k3d completion powershell | Out-String | Invoke-Expression
+
+	# To load completions for every new session, run:
+	PS> k3d completion powershell > k3d.ps1
+	# and source this file from your PowerShell profile.
+
 
 ```
-k3d completion SHELL [flags]
+k3d completion SHELL
 ```
 
 ### Options

docs/usage/commands/k3d_completion.md

@@ -3,7 +3,7 @@
 
 
 ```
-k3d config migrate INPUT OUTPUT [flags]
+k3d config migrate INPUT [OUTPUT] [flags]
 ```
 
 ### Options

docs/usage/commands/k3d_config_migrate.md

@@ -29,6 +29,7 @@ k3d node [flags]
 * [k3d](k3d.md)	 - https://k3d.io/ -> Run k3s in Docker!
 * [k3d node create](k3d_node_create.md)	 - Create a new k3s node in docker
 * [k3d node delete](k3d_node_delete.md)	 - Delete node(s).
+* [k3d node edit](k3d_node_edit.md)	 - [EXPERIMENTAL] Edit node(s).
 * [k3d node list](k3d_node_list.md)	 - List node(s)
 * [k3d node start](k3d_node_start.md)	 - Start an existing k3d node
 * [k3d node stop](k3d_node_stop.md)	 - Stop an existing k3d node

docs/usage/commands/k3d_node.md

@@ -20,8 +20,9 @@ k3d node create NAME [flags]
       --memory string            Memory limit imposed on the node [From docker]
       --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.
-      --wait                     Wait for the node(s) to be ready before returning.
+      --wait                     Wait for the node(s) to be ready before returning. (default true)
 ```
 
 ### Options inherited from parent commands

docs/usage/commands/k3d_node_create.md

@@ -0,0 +1,32 @@
+## k3d node edit
+
+[EXPERIMENTAL] Edit node(s).
+
+### Synopsis
+
+[EXPERIMENTAL] Edit node(s).
+
+```
+k3d node edit NODE [flags]
+```
+
+### Options
+
+```
+  -h, --help                                                               help for edit
+      --port-add [HOST:][HOSTPORT:]CONTAINERPORT[/PROTOCOL][@NODEFILTER]   [EXPERIMENTAL] (serverlb only!) Map ports from the node container to the host (Format: [HOST:][HOSTPORT:]CONTAINERPORT[/PROTOCOL][@NODEFILTER])
+                                                                            - Example: `k3d node edit k3d-mycluster-serverlb --port-add 8080:80`
+```
+
+### Options inherited from parent commands
+
+```
+      --timestamps   Enable Log timestamps
+      --trace        Enable super verbose output (trace logging)
+      --verbose      Enable verbose output (debug logging)
+```
+
+### SEE ALSO
+
+* [k3d node](k3d_node.md)	 - Manage node(s)
+

docs/usage/commands/k3d_node_edit.md

@@ -7,7 +7,7 @@ List node(s)
 List node(s).
 
 ```
-k3d node list [NAME [NAME...]] [flags]
+k3d node list [NODE [NODE...]] [flags]
 ```
 
 ### Options

docs/usage/commands/k3d_node_list.md

@@ -7,7 +7,7 @@ Start an existing k3d node
 Start an existing k3d node.
 
 ```
-k3d node start NAME [flags]
+k3d node start NODE [flags]
 ```
 
 ### Options

docs/usage/commands/k3d_node_start.md

@@ -64,18 +64,14 @@ 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`
 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[*]'`
+  - volume: /my/host/path:/path/in/node # same as `--volume '/my/host/path:/path/in/node@server:0;agent:*'`
     nodeFilters:
       - server:0
-      - agent[*]
+      - agent:*
 ports:
   - port: 8080:80 # same as `--port '8080:80@loadbalancer'`
     nodeFilters:
       - loadbalancer
-labels:
-  - label: foo=bar # same as `--label 'foo=bar@agent[1]'`
-    nodeFilters:
-      - agent[1]
 env:
   - envVar: bar=baz # same as `--env 'bar=baz@server:0'`
     nodeFilters:
@@ -101,12 +97,20 @@ options:
     extraArgs: # additional arguments passed to the `k3s server|agent` command; same as `--k3s-arg`
       - arg: --tls-san=my.host.domain
         nodeFilters:
-          - server[*]
+          - server:*
+    nodeLabels:
+      - label: foo=bar # same as `--k3s-node-label 'foo=bar@agent:1'` -> this results in a Kubernetes node label
+        nodeFilters:
+          - agent:1
   kubeconfig:
     updateDefaultKubeconfig: true # add new cluster to your default Kubeconfig; same as `--kubeconfig-update-default` (default: true)
     switchCurrentContext: true # also set current-context to the new cluster's context; same as `--kubeconfig-switch-context` (default: true)
   runtime: # runtime (docker) specific options
     gpuRequest: all # same as `--gpus all`
+    labels:
+      - label: bar=baz # same as `--runtime-label 'bar=baz@agent:1'` -> this results in a runtime (docker) container label
+        nodeFilters:
+          - agent:1
 
 ```
 

docs/usage/configfile.md

@@ -256,11 +256,11 @@
       },
       "examples": [
         "loadbalancer",
-        "server[*]",
+        "server:*",
         "server:0",
-        "agent[1]",
+        "agent:1",
         "all"
       ]
     }
   }
-}
+}