0.5.0 release updates (#101)

* Update documentation for 0.5.0 release * Update initialize_k0s.go * Update README.md * Update README.md * Try a bit different formatting * Finetune * More finetune * Update README.md * Update copyright * Update default version
k0sproject · Mar 3, 2021 · b423b28 · b423b28
1 parent 1ef1c5b
commit b423b28
Show file tree

Hide file tree

Showing 9 changed files with 194 additions and 39 deletions.
diff --git a/LICENSE b/LICENSE
@@ -194,7 +194,7 @@ The k0sctl binary will send anonymous telemetry when used.
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021, Mirantis Inc.
+   Copyright 2021, k0sctl authors.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/README.md b/README.md
@@ -2,6 +2,44 @@
 
 *A command-line bootstrapping and management tool for [k0s zero friction kubernetes](https://k0sproject.io/) clusters.*
 
+Example output of k0sctl deploying a k0s cluster:
+
+```sh
+$ k0sctl apply
+
+⠀⣿⣿⡇⠀⠀⢀⣴⣾⣿⠟⠁⢸⣿⣿⣿⣿⣿⣿⣿⡿⠛⠁⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀█████████ █████████ ███
+⠀⣿⣿⡇⣠⣶⣿⡿⠋⠀⠀⠀⢸⣿⡇⠀⠀⠀⣠⠀⠀⢀⣠⡆⢸⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀███          ███    ███
+⠀⣿⣿⣿⣿⣟⠋⠀⠀⠀⠀⠀⢸⣿⡇⠀⢰⣾⣿⠀⠀⣿⣿⡇⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀███          ███    ███
+⠀⣿⣿⡏⠻⣿⣷⣤⡀⠀⠀⠀⠸⠛⠁⠀⠸⠋⠁⠀⠀⣿⣿⡇⠈⠉⠉⠉⠉⠉⠉⠉⠉⢹⣿⣿⠀███          ███    ███
+⠀⣿⣿⡇⠀⠀⠙⢿⣿⣦⣀⠀⠀⠀⣠⣶⣶⣶⣶⣶⣶⣿⣿⡇⢰⣶⣶⣶⣶⣶⣶⣶⣶⣾⣿⣿⠀█████████    ███    ██████████
+
+INFO By continuing to use k0sctl you agree to these terms:
+INFO https://k0sproject.io/licenses/eula
+INFO ==> Running phase: Connect to hosts
+INFO ==> Running phase: Detect host operating systems
+INFO [ssh] 10.0.0.1:22: is running Ubuntu 20.10
+INFO [ssh] 10.0.0.2:22: is running Ubuntu 20.10
+INFO ==> Running phase: Prepare hosts
+INFO ==> Running phase: Gather host facts
+INFO [ssh] 10.0.0.1:22: discovered 10.12.18.133 as private address
+INFO ==> Running phase: Validate hosts
+INFO ==> Running phase: Gather k0s facts
+INFO ==> Running phase: Download k0s binaries on hosts
+INFO ==> Running phase: Configure k0s
+INFO [ssh] 10.0.0.1:22: validating configuration
+INFO ==> Running phase: Initialize the k0s cluster
+INFO [ssh] 10.0.0.1:22: installing k0s controller
+INFO ==> Running phase: Install workers
+INFO [ssh] 10.0.0.1:22: generating token
+INFO [ssh] 10.0.0.2:22: installing k0s worker
+INFO [ssh] 10.0.0.2:22: waiting for node to become ready
+INFO ==> Running phase: Disconnect from hosts
+INFO ==> Finished in 2m2s
+INFO k0s cluster version 0.11.0 is now installed
+INFO Tip: To access the cluster you can now fetch the admin kubeconfig using:
+INFO      k0sctl kubeconfig
+```
+
 ## Installation
 
 ### Install from the released binaries
@@ -14,7 +52,7 @@ As the released binaries aren't signed yet, on macOS and Windows, you must first
 
 If you have a working Go toolchain, you can use `go get` to install k0sctl to your `$GOPATH/bin`.
 
-```
+```sh
 $ GO111MODULE=on go get github.com/k0sproject/k0sctl
 ```
 
@@ -26,31 +64,53 @@ Scripts for installation via popular package managers such as Homebrew, Scoop or
 
 K0sctl is still in an early stage of development. Missing major features include at least:
 
-* Cluster upgrades are not yet possible
 * Windows targets are not yet supported
 * The released binaries have not been signed
-* Cluster uninstall and host clean up after failure is not there yet
 * Cluster backup and restore are not available yet
+* Nodes can't be removed
 
 ## Usage
 
-The main function of k0sctl is the `k0sctl apply` subcommand. Provided a configuration file, k0sctl will connect to the listed hosts and install k0s on them.
+### `k0sctl apply`
+
+The main function of k0sctl is the `k0sctl apply` subcommand. Provided a configuration file describing the desired cluster state, k0sctl will connect to the listed hosts, determines the current state of the hosts and configures them as needed to form a k0s cluster.
 
 The default location for the configuration file is `k0sctl.yaml` in the current working directory. To load a configuration from a different location, use:
 
-```
+```sh
 $ k0sctl apply --config path/to/k0sctl.yaml
 ```
 
-## Configuration file syntax
+If the configuration cluster version `spec.k0s.version` is greater than the version detected on the cluster, a cluster upgrade will be performed. If the configuration lists hosts that are not part of the cluster, they will be configured to run k0s and will be joined to the cluster.
 
-To generate a simple skeleton configuration file, you can use the `k0sctl init` subcommand:
+### `k0sctl init`
 
-```
-$ k0sctl init > k0sctl.yaml
+Generate a configuration template. Use `--k0s` to include an example `spec.k0s.config` k0s configuration block.
+
+### `k0sctl reset`
+
+Uninstall k0s from the hosts listed in the configuration.
+
+### `k0sctl kubeconfig`
+
+Connects to the cluster and outputs a kubeconfig file that can be used with `kubectl` or `kubeadm` to manage the kubernetes cluster.
+
+Example:
+
+```sh
+$ k0sctl kubeconfig --config path/to/k0sctl.yaml > k0s.config
+$ kubectl get node --kubeconfig k0s.config
+NAME      STATUS     ROLES    AGE   VERSION
+worker0   NotReady   <none>   10s   v1.20.2-k0s1
 ```
 
-### Example configuration
+## Configuration file
+
+The configuration file is in YAML format and loosely resembles the syntax used in Kubernetes. YAML anchors and aliases can be used.
+
+To generate a simple skeleton configuration file, you can use the `k0sctl init` subcommand.
+
+Configuration example:
 
 ```yaml
 apiVersion: k0sctl.k0sproject.io/v1beta1
@@ -68,7 +128,6 @@ spec:
   - role: worker
     ssh:
       address: 10.0.0.2
-      user: root
   k0s:
     version: 0.10.0
     instalFlags:
@@ -85,21 +144,115 @@ spec:
             version: v3.16.2
 ```
 
-### Configuration file `spec` fields
-
-* `hosts` A list of target hosts
-  * `role` One of `controller`, `worker` or if you want the controller to run workloads, use `controller+worker`
-  * `uploadBinary` When set to `true`, instead of having the hosts download the k0s binaries from the internet, k0sctl will download them to the local storage and upload to the target hosts
-  * `k0sBinaryPath` Upload a k0s binary from a local path to the host, useful for running a locally compiled development version
-  * `installFlags` A list of extra arguments passed to the `k0s install` command. See [k0s install command documentation](https://docs.k0sproject.io/main/cli/k0s_install/) for details
-  * `environment` A mapping of `string: value` pairs for setting the host's environment variables
-  * `ssh` SSH connection parameters
-    * `address` IP address or hostname of the remote host
-    * `port` SSH port, default is 22.
-    * `keyPath` Path to a SSH private key file, default is `~/.ssh/id_rsa`
-    * `user` Username to connect as, the default is `root`
-  * `localhost` You can use the local host that is running k0sctl as a cluster node
-    * `enabled` Set this to true to enable the localhost connection. You can leave out the SSH configuration
-* `k0s` K0s options
-  * `version` Target k0s version. Default is to use the latest released version
-  * `config` An embedded k0s cluster configuration. See [k0s configuration documentation](https://docs.k0sproject.io/main/configuration/) for details
+### Configuration Header Fields
+
+###### `apiVersion` &lt;string&gt; (required)
+
+The configuration file syntax version. Currently the only supported version is `k0sctl.k0sproject.io/v1beta1`.
+
+###### `kind` &lt;string&gt; (required)
+
+In the future, some of the configuration APIs can support multiple types of objects. For now, the only supported kind is `Cluster`.
+
+###### `spec` &lt;mapping&gt; (required)
+
+The main object definition, see [below](#configuration-spec)
+
+###### `metadata` &lt;mapping&gt; (optional)
+
+Information that can be used to uniquely identify the object.
+
+Example:
+
+```yaml
+metadata:
+  name: k0s-cluster-name
+```
+
+### Spec Fields
+
+##### `spec.hosts` &lt;sequence&gt; (required)
+
+A list of cluster hosts. Host requirements:
+
+* Currently only linux targets are supported
+* The user must either be root or have passwordless `sudo` access.
+* The host must fulfill the k0s system requirements
+
+See [host object documentation](#host-fields) below.
+
+##### `spec.k0s` &lt;mapping&gt; (optional)
+
+Settings related to the k0s cluster.
+
+See [k0s object documentation](#spec-fields) below.
+
+### Host Fields
+
+###### `spec.hosts[*].role` &lt;string&gt; (required)
+
+One of `controller`, `worker` or to set up a controller that can also run workloads, use `controller+worker`.
+
+###### `spec.hosts[*].uploadBinary` &lt;boolean&gt; (optional) (default: `false`)
+
+When `true`, the k0s binaries for target host will be downloaded and cached on the local host and uploaded to the target.
+When `false`, the k0s binary downloading is performed on the target host itself
+
+###### `spec.hosts[*].k0sBinaryPath` &lt;string&gt; (optional)
+
+A path to a file on the local host that contains a k0s binary to be uploaded to the host. Can be used to test drive a custom development build of k0s.
+
+###### `spec.hosts[*].installFlags` &lt;sequence&gt; (optional)
+
+Extra flags passed to the `k0s install` command on the target host. See `k0s install --help` for a list of options.
+
+###### `spec.hosts[*].environment` &lt;mapping&gt; (optional)
+
+List of key-value pairs to set to the target host's environment variables.
+
+Example:
+
+```yaml
+environment:
+  HTTP_PROXY: 10.0.0.1:443
+```
+
+##### `spec.hosts[*].ssh` &lt;mapping&gt; (optional)
+
+SSH connection options.
+
+###### `spec.hosts[*].ssh.address` &lt;string&gt; (required)
+
+IP address of the host
+
+###### `spec.hosts[*].ssh.user` &lt;string&gt; (optional) (default: `root`)
+
+Username to log in as.
+
+###### `spec.hosts[*].ssh.port` &lt;string&gt; (required)
+
+TCP port of the SSH service on the host.
+
+###### `spec.hosts[*].ssh.keyPath` &lt;string&gt; (optional) (default: `~/.ssh/id_rsa`)
+
+Path to a SSH private key file.
+
+##### `spec.hosts[*].localhost` &lt;mapping&gt; (optional)
+
+Localhost connection options. Can be used to use the local host running k0sctl as a node in the cluster.
+
+###### `spec.hosts[*].localhost.enabled` &lt;boolean&gt; (optional) (default: `false`)
+
+This must be set `true` to enable the localhost connection.
+
+### K0s Fields
+
+##### `spec.k0s.version` &lt;string&gt; (optional) (default: auto-discovery)
+
+The version of k0s to deploy. When left out, k0sctl will default to using the latest released version of k0s or the version already running on the cluster.
+
+##### `spec.k0s.config` &lt;mapping&gt; (optional) (default: auto-generated)
+
+Embedded k0s cluster configuration. See [k0s configuration documentation](https://docs.k0sproject.io/main/configuration/) for details.
+
+When left out, the output of `k0s default-config` will be used.
diff --git a/cmd/flags.go b/cmd/flags.go
@@ -83,9 +83,11 @@ func initConfig(ctx *cli.Context) error {
 	return ctx.Set("config", string(content))
 }
 
-func displayCopyright(_ *cli.Context) error {
-	fmt.Printf("k0sctl %s Copyright 2021, Mirantis Inc.\n", version.Version)
-	fmt.Println("Anonymized telemetry will be sent to Mirantis.")
+func displayCopyright(ctx *cli.Context) error {
+	fmt.Printf("k0sctl %s Copyright 2021, k0sctl authors.\n", version.Version)
+	if !ctx.Bool("disable-telemetry") {
+		fmt.Println("Anonymized telemetry of usage will be sent to the authors.")
+	}
 	fmt.Println("By continuing to use k0sctl you agree to these terms:")
 	fmt.Println("https://k0sproject.io/licenses/eula")
 	return nil

diff --git a/examples/footloose/k0sctl.yaml.example b/examples/footloose/k0sctl.yaml.example
@@ -11,4 +11,4 @@ spec:
         address: 127.0.0.1
         port: 9023
   k0s:
-    version: 0.11.0-beta1
+    version: 0.11.0
diff --git a/phase/configure_k0s.go b/phase/configure_k0s.go
@@ -19,7 +19,7 @@ type ConfigureK0s struct {
 
 // Title returns the phase title
 func (p *ConfigureK0s) Title() string {
-	return "Configure K0s"
+	return "Configure k0s"
 }
 
 // Run the phase

diff --git a/phase/download_binaries.go b/phase/download_binaries.go
@@ -21,7 +21,7 @@ type DownloadBinaries struct {
 
 // Title for the phase
 func (p *DownloadBinaries) Title() string {
-	return "Download binaries"
+	return "Download k0s binaries to local host"
 }
 
 // Prepare the phase

diff --git a/phase/download_k0s.go b/phase/download_k0s.go
@@ -17,7 +17,7 @@ type DownloadK0s struct {
 
 // Title for the phase
 func (p *DownloadK0s) Title() string {
-	return "Download K0s on the hosts"
+	return "Download k0s on hosts"
 }
 
 // Prepare the phase

diff --git a/phase/initialize_k0s.go b/phase/initialize_k0s.go
@@ -14,7 +14,7 @@ type InitializeK0s struct {
 
 // Title for the phase
 func (p *InitializeK0s) Title() string {
-	return "Initialize K0s Cluster"
+	return "Initialize the k0s cluster"
 }
 
 // Prepare the phase

diff --git a/phase/upload_binaries.go b/phase/upload_binaries.go
@@ -14,7 +14,7 @@ type UploadBinaries struct {
 
 // Title for the phase
 func (p *UploadBinaries) Title() string {
-	return "Upload binaries"
+	return "Upload k0s binaries to hosts"
 }
 
 // Prepare the phase