Release 0.12.0 / v1beta2 documentation update (#28)

* Update hetzner * Update aws example * Update command reference * Update config reference * Update getting started * Update integrations * Update system-requirements * Update upgrades * Update configuration-file.md * Update command-reference.md
Mirantis · Jul 1, 2020 · c8cb8e6 · c8cb8e6
1 parent 9d1b760
commit c8cb8e6
Show file tree

Hide file tree

Showing 10 changed files with 201 additions and 88 deletions.
diff --git a/docs/command-reference.md b/docs/command-reference.md
@@ -1,5 +1,12 @@
 # Mirantis Launchpad Command Reference
 
+## Common arguments
+
+* `--disable-telemetry` - Disables sending of analytics and telemetry data
+* `--accept-license` - Accept the [end user license agreement](https://github.com/Mirantis/launchpad/blob/master/LICENSE) 
+* `--debug` - Increase output verbosity
+* `--help` - Display command help
+
 ## Initialize a cluster config file
 
 `launchpad init`
@@ -13,7 +20,6 @@ The supported options are:
 * `--config` - Path to a cluster config file (default: `cluster.yaml`)
 * `--prune` - Automatically remove nodes that are not anymore part of cluster config yaml (default: `false`)
 
-
 ## Download a Client Bundle
 
 `launchpad download-bundle`
@@ -33,7 +39,6 @@ The supported options are:
 * `--name` - Name
 * `--email` - Email
 * `--company` - Company
-* `--accept-license` - Accept license
 
 ## Reset (uninstall) a cluster
 

diff --git a/docs/configuration-file.md b/docs/configuration-file.md
@@ -7,58 +7,76 @@ Mirantis Launchpad cluster configuration is described in a file that is in YAML
 The complete `cluster.yaml` reference for UCP clusters:
 
 ```yaml
-apiVersion: launchpad.mirantis.com/v1beta1
+apiVersion: launchpad.mirantis.com/v1beta2
 kind: UCP
 metadata:
   name: launchpad-ucp
 spec:
   hosts:
-  - address: 1.2.1.2
-    user: root
-    sshPort: 22
-    sshKeyPath: ~/.ssh/id_rsa
-    privateInterface: eth0
+  - address: 10.0.0.1
     role: manager
-  # - address: 1.3.1.3
-  #   user: root
-  #   sshKeyPath: ~/.ssh/id_rsa
-  #   privateInterface: ens5
-  #   role: worker
-  # - address: 1.4.1.4
-  #   user: docker
-  #   sshKeyPath: ~/.ssh/id_rsa
-  #   privateInterface: "Ethernet 3"
-  #   role: worker
-  # ucp:
-  #   version: 3.3.0-rc4
-  #   imageRepo: "docker.io/docker"
-  #   installFlags:
-  #   - --admin-username=admin
-  #   - --admin-password=orcaorcaorca
-  #   configFile: ./ucp-config.toml
-  #   configData: |-
-  #     [scheduling_configuration]
-  #       default_node_orchestrator = "kubernetes"
-  # engine:
-  #   version: 19.03.8-rc1
-  #   channel: test
-  #   repoURL: https://repos.mirantis.com
-  #   installURL: https://get.mirantis.com/
+    ssh:
+      user: root
+      port: 22
+      keyPath: ~/.ssh/id_rsa
+    privateInterface: eth0
+    environment:
+      http_proxy: http://example.com
+      NO_PROXY: 10.0.0.*
+    engineConfig:
+      debug: true
+      log-opts:
+        max-size: 10m
+        max-file: "3"
+  - address: 10.0.0.2
+    role: worker
+    winRM:
+        user: Administrator
+        port: 5986
+        useHTTPS: true
+        insecure: false
+        useNTLM: false
+        caCertPath: ~/.certs/cacert.pem
+        certPath: ~/.certs/cert.pem
+        keyPath: ~/.certs/key.pem
+        password: abcd1234
+  ucp:
+    version: 3.3.0-rc4
+    imageRepo: "docker.io/docker"
+    installFlags:
+    - --admin-username=admin
+    - --admin-password=orcaorcaorca
+    configFile: ./ucp-config.toml
+    configData: |-
+      [scheduling_configuration]
+        default_node_orchestrator = "kubernetes"
+    cloud:
+      provider: azure
+      configFile: ~/cloud-provider.conf
+      configData: |-
+        [Global]
+        region=RegionOne
+  engine:
+    version: 19.03.8-rc1
+    channel: test
+    repoURL: https://repos.mirantis.com
+    installURLLinux: https://get.mirantis.com/
+    installURLWindows: https://get.mirantis.com/install.ps1
 ```
 
 We follow Kubernetes like versioning and grouping the launchpad configuration, hence you'll see familiar attributes such as `kind` etc.
 
 ## `apiVersion`
 
-Currently only `launchpad.mirantis.com/v1beta1` is supported.
+Currently `launchpad.mirantis.com/v1beta1` and `launchpad.mirantis.com/v1beta2` are supported. A `v1beta1` configuration will still work unchanged, but `v1beta2` features such as `environment`, `engineConfig` and `winRM` can not be used with `v1beta2`.
 
 ## `kind`
 
 Currently only `UCP` is supported.
 
 ## `metadata`
 
-- `name` - Name of the cluster to be created. Affects only `launchpad` internal storage paths currently e.g. for client bundles.
+- `name` - Name of the cluster to be created. Affects only `launchpad` internal storage paths currently e.g. for client bundles and log files.
 
 ## `spec`
 
@@ -70,11 +88,31 @@ Specify the machines for the cluster.
 
 - `address` - Address of the machine. This needs to be an address to which `launchpad` tool can connect to with SSH protocol.
 - `user` - Username with sudo/admin permission to use for logging in (default: `root`)
-- `sshPort` - Host's ssh port (default: `22`)
-- `sshKeyPath` - A local file path to an ssh private key file (default `~/.ssh/id_rsa`)
+- `environment` - Key - value pairs in YAML map (hash, dictionary) syntax. Values will be updated to host environment.
+- `ssh` - SSH connection configuration options
+- `winRM` - WinRM connection configuration options
+- `engineConfig` - Docker Engine configuration in YAML mapping syntax, will be converted to `daemon.json`.
 - `privateInterface` - Discover private network address from the configured network interface (optional)
 - `role` - One of `manager` or `worker`, specifies the role of the machine in the cluster
 
+#### `ssh`
+
+- `user` - User to log in as (default: `root`)
+- `port` - Host's ssh port (default: `22`)
+- `keyPath` - A local file path to an ssh private key file (default `~/.ssh/id_rsa`)
+
+#### `winRM`
+
+- `port` - Host's WinRM listening port (default: `5986`)
+- `useHTTPS` - Set `true` to use HTTPS protocol. When false, plain HTTP is used. (default: `false`)
+- `insecure` - Set `true` to ignore SSL certificate validation errors (default: `false`)
+- `useNTLM` - Set `true` to use NTLM (default: `false`)
+- `caCertPath` - Path to CA Certificate file
+- `certPath` - Path to Certificate file
+- `keyPath` - Path to Key file
+- `user` - Windows account username (default: `Administrator`)
+- `password` - User account password
+
 ### `ucp`
 
 Specify options for UCP cluster itself.
@@ -84,15 +122,25 @@ Specify options for UCP cluster itself.
 - `installFlags` - Custom installation flags for UCP installation. You can get a list of supported installation options for a specific UCP version by running the installer container with `docker run -t -i --rm docker/ucp:3.3.0 install --help`. (optional)
 - `configFile` - The initial full cluster [configuration file](https://docs.mirantis.com/docker-enterprise/v3.1/dockeree-products/ucp/ucp-configure/ucp-configuration-file.html#configuration-options). (optional)
 - `configData` -  The initial full cluster [configuration file](https://docs.mirantis.com/docker-enterprise/v3.1/dockeree-products/ucp/ucp-configure/ucp-configuration-file.html#configuration-options) in embedded "heredocs" way. (optional)
+- `cloud` - Cloud provider configuration (optional)
+
+#### `cloud`
+
+Cloud provider configuration. 
 
+- `provider` - Provider name (currently azure and openstack (UCP 3.4.0+) are supported)
+- `configFile` - Path to cloud provider configuration file on local machine
+- `configData` - Inlined cloud provider configuration
+
 ### `engine`
 
  Specify options for Docker EE engine to be installed
 
 - `version` - The version of Docker EE engine to be installed or upgraded to. (default `19.03.8`)
 - `channel` - Which installation channel to use. One of `test` or `prod` (optional)
 - `repoURL` - Which repository URL to use for engine installation. (optional)
-- `installURL` - Where to download the initial installer script. (optional)
+- `installURLLinux` - Where to download the initial installer script for linux hosts. Also local paths can be used. (default: `https://get.mirantis.com/`)
+- `installURLWindows` - Where to download the initial installer script for windows hosts. Also local paths can be used. (default: `https://get.mirantis.com/install.ps1`)
 
-**Note:** Normally you should not need to specify anything else than the version for the engine. `repoUrl` and `installURL` are only usually used when installing from non-standard location, e.g. when running in disconnected datacenters.
+**Note:** Normally you should not need to specify anything else than the version for the engine. `repoUrl` and `installURLLinux/Windows` are only usually used when installing from non-standard location, e.g. when running in disconnected datacenters.
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -51,7 +51,7 @@ The cluster is configured using [a yaml file](configuration-file.md). In this ex
 Open up your favourite editor, and type something similar as in the example below. Once done, save the file as `cluster.yaml`. Naturally you need to adjust the example below to match your infrastructure details.
 
 ```yaml
-apiVersion: launchpad.mirantis.com/v1beta1
+apiVersion: launchpad.mirantis.com/v1beta2
 kind: UCP
 metadata:
   name: ucp-kube
@@ -64,10 +64,12 @@ spec:
   hosts:
   - address: 192.168.110.100
     role: manager
-    sshKeyPath: ~/.ssh/my_key
+    ssh:
+      keyPath: ~/.ssh/my_key
   - address: 192.168.110.101
     role: worker
-    sshKeyPath: ~/.ssh/my_key
+    ssh:
+      keyPath: ~/.ssh/my_key
 ```
 
 For more complex setups, there's a huge amount of [configuration options](configuration-file.md) available.
@@ -80,7 +82,7 @@ Once the cluster configuration file is ready, we can fire up the cluster. In the
 $ launchpad apply
 ```
 
-The `launchpad` tool connects to the infrastructure you've specified in the `cluster.yaml` with SSH connections and configures everything needed on the hosts. Within few minutes you should have your cluster up-and-running.
+The `launchpad` tool connects to the infrastructure you've specified in the `cluster.yaml` with SSH or WinRM connections and configures everything needed on the hosts. Within few minutes you should have your cluster up-and-running.
 
 ## Interact with your cluster
 

diff --git a/docs/integrations.md b/docs/integrations.md
@@ -8,7 +8,7 @@ When using cloud environments many people are using [Terraform](https://www.terr
 ```terraform
 output "ucp_cluster" {
   value = {
-    apiVersion = "launchpad.mirantis.com/v1beta1"
+    apiVersion = "launchpad.mirantis.com/v1beta2"
     kind = "UCP"
     spec = {
       ucp = {

diff --git a/docs/system-requirements.md b/docs/system-requirements.md
@@ -34,11 +34,14 @@ Mirantis Launchpad is a static binary that works on following operating systems:
 
 Note that Windows container images are typically larger than Linux container images. For this reason, you should provision more local storage for Windows nodes.
 
-### SSH
+### Remote management
 
-Launchpad will connect to machines via SSH. Thus, SSH is required to be enabled on host machines. Only password-less sudo capable SSH Key-Based authentication is supported.
+Launchpad will connect to Linux machines via SSH and to Windows machines via SSH or WinRM. Thus, SSH or WinRM is required to be enabled on host machines. Only passwordless sudo capable SSH Key-Based authentication is supported. On Windows the user needs to have Administrator privileges.
 
 #### Windows Machines
+
+##### SSH
+
 To enable SSH easily on Windows machines, you can look the following PowerShell snippets and modify them for your own needs and run it on each Windows machine:
 
 ```
@@ -66,7 +69,11 @@ ssh --% [email protected] powershell -c $ConfirmPreference = 'None'; Repair-
 
 To read more how to manage Windows with OpenSSH, you can refer the official documentation: https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_overview
 
+##### WinRM
+
+PowerShell Remoting over WinRM can be also used on Windows hosts as an alternative to SSH. To read more about how to manage Windows machines over WinRM: https://docs.microsoft.com/en-us/windows/win32/winrm/portal
+
 ### Ports Used
 
-When installing an UCP cluster, a series of ports need to be opened to incoming traffic. See [UCP documentation](https://docs.mirantis.com/docker-enterprise/v3.1/dockeree-products/ucp/install-ucp.html#ports-used) for more details.
+When installing a UCP cluster, a series of ports need to be opened to incoming traffic. See [UCP documentation](https://docs.mirantis.com/docker-enterprise/v3.1/dockeree-products/ucp/install-ucp.html#ports-used) for more details.
 
diff --git a/docs/upgrades.md b/docs/upgrades.md
@@ -7,17 +7,13 @@ Mirantis Launchpad allows users to upgrade their clusters with  single `launchpa
 Say you want to upgrade the Docker EE engine running in the cluster. You've bootsrapped the cluster with version `19.03.8` and want to upgrade to say `19.03.14`. What you'd need to do is to bump the engine version in your `cluster.yaml` file:
 
 ```yaml
-apiVersion: launchpad.mirantis.com/v1beta1
+apiVersion: launchpad.mirantis.com/v1beta2
 kind: UCP
 metadata:
   name: launchpad-ucp
 spec:
   hosts:
-  - address: 1.2.1.2
-    user: root
-    sshPort: 22
-    sshKeyPath: ~/.ssh/id_rsa
-    privateInterface: eth0
+  - address: 10.0.0.1
     role: manager
   engine:
     version: 19.03.14 # was previously 19.03.8
@@ -29,17 +25,13 @@ Once the file is ready, just re-run `launchpad apply` command. Launchpad will up
 When newer version of UCP is available you need to just bump the UCP version tag in the `cluster.yml`:
 
 ```yaml
-apiVersion: launchpad.mirantis.com/v1beta1
+apiVersion: launchpad.mirantis.com/v1beta2
 kind: UCP
 metadata:
   name: launchpad-ucp
 spec:
   hosts:
-  - address: 1.2.1.2
-    user: root
-    sshPort: 22
-    sshKeyPath: ~/.ssh/id_rsa
-    privateInterface: eth0
+  - address: 10.0.0.1
     role: manager
   ucp:
     version: 3.3.1
@@ -51,4 +43,4 @@ Once the file is ready, just re-run `launchpad apply` command. Launchpad will co
 
 ## Upgrading both Docker EE engine and UCP at the same time
 
-It is possible to also upgrade both the engine and UCP compoents at the same `launchpad apply` run. Launchpad will first upgrade the engines on all the nodes as described above and only after that it will upgrade UCP components.
+It is possible to also upgrade both the engine and UCP compoents at the same `launchpad apply` run. Launchpad will first upgrade the engines on all the nodes as described above and only after that it will upgrade UCP components.
diff --git a/examples/terraform/aws/main.tf b/examples/terraform/aws/main.tf
@@ -59,36 +59,44 @@ locals {
   managers = [
     for host in module.masters.machines : {
       address = host.public_ip
-      user    = "ubuntu"
       role    = host.tags["Role"]
       privateInterface = "ens5"
-      sshKeyPath = "./ssh_keys/${var.cluster_name}.pem"
+      ssh = {
+        user    = "ubuntu"
+        keyPath = "./ssh_keys/${var.cluster_name}.pem"
+      }
     }
   ]
   workers = [
     for host in module.workers.machines : {
       address = host.public_ip
-      user    = "ubuntu"
       role    = host.tags["Role"]
       privateInterface = "ens5"
-      sshKeyPath = "./ssh_keys/${var.cluster_name}.pem"
+      ssh = {
+        user    = "ubuntu"
+        keyPath = "./ssh_keys/${var.cluster_name}.pem"
+      }
     }
   ]
   windows_workers = [
     for host in module.windows_workers.machines : {
       address = host.public_ip
-      user    = "administrator"
       role    = host.tags["Role"]
       privateInterface = "Ethernet 2"
-      sshKeyPath = "./ssh_keys/${var.cluster_name}.pem"
+      winRM = {
+        user    = "Administrator"
+        password = var.windows_administrator_password
+        useHTTPS = true
+        insecure = true
+      }
     }
   ]
 }
 
 
 output "ucp_cluster" {
   value = {
-    apiVersion = "launchpad.mirantis.com/v1beta1"
+    apiVersion = "launchpad.mirantis.com/v1beta2"
     kind = "UCP"
     spec = {
       ucp = {