Release 1.0 documentation updates (#47)

* Revert "Roll back yaml filename for now (#46)"

This reverts commit 8543948.

* Version 1.0 documentation update

* The address is not always for SSH

* Fix link

* Hooks were reversed

README.md

@@ -1,7 +1,5 @@
 # Mirantis Launchpad
 
-**Note:** Mirantis Launchpad is currently BETA.
-
 Mirantis Launchpad CLI tool ("**launchpad**") simplifies and automates deploying [Docker Enterprise](https://www.mirantis.com/software/docker/docker-enterprise/) on public clouds (like AWS or Azure), private clouds (like OpenStack or VMware), virtualization platforms (like VirtualBox, VMware Workstation, Parallels, etc.), or bare metal.
 
 Launchpad can also provide full cluster lifecycle management. Multi-manager, high availability clusters, defined as having sufficient node capacity to move active workloads around while updating, can be upgraded with no downtime.

docs/command-reference.md

@@ -12,7 +12,7 @@ Optional arguments that can be used with any of the `launchpad` commands.
 
 ## Initialize Launchpad
 
-Intializes the cluster config file, usually called cluster.yaml.
+Intializes the cluster config file, usually called launchpad.yaml.
 
 `launchpad init`
 
@@ -26,7 +26,7 @@ initialize or upgrade a cluster.
 The supported options are:
 
 * `--config` - Path to a cluster config file, including the filename
-(default: `cluster.yaml`)
+(default: `launchpad.yaml`)
 * `--prune` - Remove nodes that are no longer in the cluster config yaml
 (default: `false`)
 * `--force` - Continue installation when prerequisite validation fails
@@ -35,7 +35,7 @@ The supported options are:
 ## Download a client bundle
 
 The client bundle contains a private and public key pair that authorizes
-Launchpad to interact with
+Launchpad to interact with 
 [UCP CLI](https://docs.mirantis.com/docker-enterprise/v3.1/dockeree-products/ucp/user-access.html#cli-access).
 
 `launchpad download-bundle`
@@ -45,7 +45,7 @@ The supported options are:
 * `--username` - Username
 * `--password` - Password
 * `--config` - Path to a cluster config file, including the filename
-(default: `cluster.yaml`)
+(default: `launchpad.yaml`)
 
 ## Register
 
@@ -67,7 +67,7 @@ To reset or uninstall a UCP cluster.
 
 The supported options are:
 
-* `--config` - Path to a cluster config file, including the filename (default: `cluster.yaml`)
+* `--config` - Path to a cluster config file, including the filename (default: `launchpad.yaml`)
 
 ## Related topics
 

docs/configuration-file.md

@@ -1,20 +1,27 @@
 # Mirantis Launchpad Configuration File
 
-Mirantis Launchpad cluster configuration is described in YAML format. You can create and modify yaml files using your favorite text editor. The default name for this file is cluster.yaml, although other file names could be used.
+Mirantis Launchpad cluster configuration is described in YAML format. You can create and modify yaml files using your favorite text editor. The default name for this file is launchpad.yaml, although other file names could be used.
 
 ## Configuration File Reference
 
-The complete `cluster.yaml` file looks something like this, but with values determined by your specific configuration.
+The complete `launchpad.yaml` file looks something like this, but with values determined by your specific configuration.
 
 ```yaml
-apiVersion: launchpad.mirantis.com/v1beta3
+apiVersion: launchpad.mirantis.com/v1
 kind: DockerEnterprise
 metadata:
   name: launchpad-ucp
 spec:
   hosts:
   - address: 10.0.0.1
     role: manager
+    hooks:
+      apply:
+        before:
+          - ls -al > test.txt
+        after:
+          - cat test.txt
+          - rm test.txt
     ssh:
       user: root
       port: 22
@@ -46,8 +53,11 @@ spec:
       user: root
       port: 22
       keyPath: ~/.ssh/id_rsa
+  - address: 127.0.0.1
+    role: worker
+    localhost: true
   ucp:
-    version: "3.3.0"
+    version: "3.3.3"
     imageRepo: "docker.io/docker"
     installFlags:
     - --admin-username=admin
@@ -82,7 +92,7 @@ We follow Kubernetes-like versioning and grouping in launchpad configuration so
 
 ## `apiVersion`
 
-The latest API version is `launchpad.mirantis.com/v1beta3`, but earlier configuration file syntaxes should still work without support for the changes and additions in later versions.
+The latest API version is `launchpad.mirantis.com/v1`, but earlier configuration file syntaxes should still work without support for the changes and additions in later versions.
 
 ## `kind`
 
@@ -101,31 +111,32 @@ The specification for the cluster.
 
 The machines that the cluster runs on.
 
-- `address` - Address of the SSH server that `launchpad` can connect to using
-SSH protocol
+- `address` - Address of the server that `launchpad` can connect to using the selected [connection](#host-connection-options) method
 - `privateInterface` - Private network address for the configured network
 interface (default: `eth0`)
-- `ssh` - [SSH](#ssh) Secure Shell (SSH) connection configuration options
-- `winRM` - [WinRM](#winrm) Windows Remote Management (WinRM) connection
-configuration options
 - `role` - Role of the machine in the cluster. Possible values are:
    - `manager`
    - `worker`
    - `dtr`
-- `environment` - Key - value pairs in YAML mapping syntax. Values are updated
-to host environment (optional)
-- `engineConfig` - Docker Engine configuration in YAML mapping syntax, will be
-converted to `daemon.json` (optional)
+- `environment` - Key - value pairs in YAML mapping syntax. Values are updated to host environment (optional)
+- `engineConfig` - Docker Engine configuration in YAML mapping syntax, will be converted to `daemon.json` (optional)
+- `hooks` - [Hooks](#hooks) configuration for running commands before or after stages (optional)
+
+#### Host connection options
 
-#### `ssh`
+- `ssh` - [SSH](#ssh) Secure Shell (SSH) connection configuration options
+- `winRM` - [WinRM](#winrm) Windows Remote Management (WinRM) connection configuration options
+- `localhost` - Target is the local host where launchpad is running (boolean, default: false)
+
+##### `ssh`
 
 SSH configuration options.
 
 - `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`
+##### `winRM`
 
 WinRM configuration options.
 
@@ -139,6 +150,23 @@ WinRM configuration options.
 - `certPath` - Path to Certificate file (optional)
 - `keyPath` - Path to Key file (optional)
 
+#### Hooks configuration options
+
+Host hooks can be used to have launchpad run commands on the host before or after operation stages.
+
+- `apply` - Hooks for the [apply](#apply) operation (optional)
+- `reset` - Hooks for the [reset](#reset) operation (optional)
+
+##### Apply
+
+- `before`- A list of commands to run on the host before the "Preparing host" phase (optional)
+- `after`- A list of commands to run on the host before the "Disconnect" phase when the apply was succesful (optional)
+
+##### Reset
+
+- `before`- A list of commands to run on the host before the "Uninstall" phase (optional)
+- `after`- A list of commands to run on the host before the "Disconnect" phase when the reset was succesful (optional)
+
 ### `ucp`
 
 Specify options for the UCP cluster itself.

docs/getting-started.md

@@ -77,10 +77,10 @@ INFO[0022] Registration completed!
 
 The cluster is configured using [a yaml file](configuration-file.md). In this example we setup a simple 2 node UCP cluster using Kubernetes. One node is used for UCP and one is a worker node.
 
-Open up your favorite editor, and type something similar to the example below. Once done, save the file as `cluster.yaml`. Adjust the example below to meet your infrastructure requirements. This model should work to deploy hosts on most public clouds.
+Open up your favorite editor, and type something similar to the example below. Once done, save the file as `launchpad.yaml`. Adjust the example below to meet your infrastructure requirements. This model should work to deploy hosts on most public clouds.
 
 ```yaml
-apiVersion: launchpad.mirantis.com/v1beta3
+apiVersion: launchpad.mirantis.com/v1
 kind: DockerEnterprise
 metadata:
   name: ucp-kube
@@ -101,10 +101,10 @@ spec:
       keyPath: ~/.ssh/my_key
 ```
 
-If you're deploying on VirtualBox or other desktop virtualization solution and are using ‘bridged’ networking, you’ll need to make a few minor adjustments to your cluster.yaml (see below) — deliberately setting a –pod-cidr to ensure that pod IP addresses don’t overlap with node IP addresses (the latter are in the 192.168.x.x private IP network range on such a setup), and supplying appropriate labels for the target nodes’ private IP network cards using the privateInterface parameter (this typically defaults to ‘enp0s3’ on Ubuntu 18.04 — other Linux distributions use similar nomenclature). You may also need to set the username to use for logging into the host.
+If you're deploying on VirtualBox or other desktop virtualization solution and are using ‘bridged’ networking, you’ll need to make a few minor adjustments to your launchpad.yaml (see below) — deliberately setting a –pod-cidr to ensure that pod IP addresses don’t overlap with node IP addresses (the latter are in the 192.168.x.x private IP network range on such a setup), and supplying appropriate labels for the target nodes’ private IP network cards using the privateInterface parameter (this typically defaults to ‘enp0s3’ on Ubuntu 18.04 — other Linux distributions use similar nomenclature). You may also need to set the username to use for logging into the host.
 
 ```yaml
-apiVersion: launchpad.mirantis.com/v1beta3
+apiVersion: launchpad.mirantis.com/v1
 kind: DockerEnterprise
 metadata:
   name: my-ucp
@@ -135,13 +135,13 @@ If you are familiar with [Terraform](https://www.terraform.io/), you can automat
 
 ## Bootstrap your cluster
 
-Once the cluster configuration file is ready, we can fire up the cluster. In the same directory where you created the `cluster.yaml` file, run:
+Once the cluster configuration file is ready, we can fire up the cluster. In the same directory where you created the `launchpad.yaml` file, run:
 
 ```
 $ launchpad apply
 ```
 
-The `launchpad` tool uses with SSH or WinRM to connect to the infrastructure you've specified in the `cluster.yaml` and configures everything needed on the hosts. Within few minutes you should have your cluster up and running.
+The `launchpad` tool uses with SSH or WinRM to connect to the infrastructure you've specified in the `launchpad.yaml` and configures everything needed on the hosts. Within few minutes you should have your cluster up and running.
 
 ## Connect to your cluster
 
@@ -153,7 +153,7 @@ INFO[0021] UCP cluster admin UI: https://test-ucp-cluster-master-lb-895b79a08e57
 INFO[0021] You can also download the admin client bundle with the following command: launchpad download-bundle --username <username> --password <password>
 ```
 
-By default, the admin username is `admin`. If you did not supply the password in with `cluster.yaml` or via the `installFlags` option like `--admin-password=supersecret`, the generated admin password will be displayed in the install flow:
+By default, the admin username is `admin`. If you did not supply the password in with `launchpad.yaml` or via the `installFlags` option like `--admin-password=supersecret`, the generated admin password will be displayed in the install flow:
 ```
 INFO[0083] 127.0.0.1:  time="2020-05-26T05:25:12Z" level=info msg="Generated random admin password: wJm-TzIzQrRNx7d1fWMdcscu_1pN5Xs0"
 ```

docs/host-configuration.md

@@ -12,22 +12,21 @@ Hosts must be configured to allow:
   - Public and private cloud Windows Server images are normally configured for WinRM by default, which Launchpad supports.
   - If installing Linux on a desktop (e.g., VirtualBox) VM, you will need to install and enable the SSH server (e.g., OpenSSH) as part of initial OS installation, or access the running VM via the built-in remote terminal and install, configure, and enable OpenSSH manually, later. Google 'install ssh server <your chosen Linux>' for OS-specific tutorials and instructions.
   - Alternatively, Launchpad also supports SSH connections to Windows Server hosts. Enabling SSH on Windows Server will typically require post-launch configuration, and can be scripted for enablement at VM launch. See [system requirements](system-requirements.md) or [this blog](https://www.mirantis.com/blog/today-i-learned-how-to-enable-ssh-with-keypair-login-on-windows-server-2019/).
-
+  - Launchpad can also use the local host without a remote connection
 
 * _For hosts accessed via SSH: remote login using private key:_ — Launchpad, like most deployment tools, uses encryption keys rather than passwords to authenticate to hosts. You will need to create or use an existing keypair, copy the public key to an appropriate location on each host, configure SSH on hosts to permit SSH authentication using a key instead of a password(then restart the sshd server), and store the keypair (or just the private key) in an appropriate location on your deployer machine, with appropriate permissions. Google 'enable SSH with keys <your chosen Linux>' for OS-specific tutorials and instructions on creating and using SSH keypairs.
   - Keywise login is the default for Linux instances on most public and private cloud platforms. Typically, you can use the platform to create an SSH keypair (or upload a private key created elsewhere, e.g., on your deployer machine), and assign this key to VMs at launch.
   - For Linux hosts on desktop virtualization, assuming you're installing a new OS on each VM, you'll need to configure keywise SSH access after installing OpenSSH. This entails creating a private key, copying it to each host, then reconfiguring SSH on each host to use private keys instead of passwords before restarting the sshd service.
   - For Windows hosts, access via SSH and keys must be configured manually after first boot, or can be automated. See [system requirements](system-requirements.md) or [this blog](https://www.mirantis.com/blog/today-i-learned-how-to-enable-ssh-with-keypair-login-on-windows-server-2019/). It's also possible to use WinRM for connecting to Windows hosts.
 
-
 * _For Linux hosts: passwordless sudo_ — Most Linux operating systems now default to enabling login by a privileged user with sudo permissions, rather than by 'root.' This is safer than permitting direct login by root (which is also prevented by the default configuration of most SSH servers). Launchpad requires that the user be allowed to issue 'sudo' commands without being prompted to enter a password.
   - This is the default for Linux instances on most public and private cloud platforms. The username you create at VM launch will have passwordless sudo privileges.
   - If installing Linux on a desktop (e.g., VirtualBox) VM, you will typically need to configure passwordless sudo after first boot of a newly-installed OS. Google 'configure passwordless sudo <your chosen Linux>' for tutorials and instructions.
   - On Windows hosts, the Administrator account is given all privileges by default, and Launchpad can escalate permissions at need without a password. If when using WinRM you get `http 401` error, it is possibly due to a password policy. You need to have a sufficiently complex password, such as `,,UCP..Example123..`.
 
 * _Configure Docker logging to enable auto-rotation and manage retention_ * — Additionally, we recommend configuring evaluation hosts, especially those with smaller SSDs/HDDs, to enable basic Docker log rotation and managing old-file retention, thus avoiding filling up cluster storage with retained logs.
 
-This can be done by defining Docker engine configuration in cluster.yaml, for example:
+This can be done by defining Docker engine configuration in launchpad.yaml, for example:
 
 ```yaml
 ...

docs/integrations.md

@@ -1,15 +1,15 @@
 # Integrating with Mirantis Launchpad
 
-Mirantis Launchpad is distributed as a binary executable. The main integration point with cluster management is the `launchpad apply` command and the input [`cluster.yaml`](configuration-file.md) configuration for the cluster. As the configuration is in YAML format you can integrate other tooling with it. One of the common use cases uses infrastructure management tooling such as Terraform.
+Mirantis Launchpad is distributed as a binary executable. The main integration point with cluster management is the `launchpad apply` command and the input [`launchpad.yaml`](configuration-file.md) configuration for the cluster. As the configuration is in YAML format you can integrate other tooling with it. One of the common use cases uses infrastructure management tooling such as Terraform.
 
 ## Terraform with Mirantis Launchpad
 
-When using cloud environments many people use [Terraform](https://www.terraform.io/) to manage the infrastructure declaratively. The easiest way to integrate Terraform to Mirantis Launchpad is to use [Terraform output](https://www.terraform.io/docs/configuration/outputs.html) values to specify the whole [`cluster.yaml`](configuration-file.md) structure.
+When using cloud environments many people use [Terraform](https://www.terraform.io/) to manage the infrastructure declaratively. The easiest way to integrate Terraform to Mirantis Launchpad is to use [Terraform output](https://www.terraform.io/docs/configuration/outputs.html) values to specify the whole [`launchpad.yaml`](configuration-file.md) structure.
 
 ```terraform
 output "ucp_cluster" {
   value = {
-    apiVersion = "launchpad.mirantis.com/v1beta3"
+    apiVersion = "launchpad.mirantis.com/v1"
     kind = "UCP"
     spec = {
       ucp = {
@@ -26,10 +26,10 @@ output "ucp_cluster" {
 }
 ```
 
-Terraform is currently limited to output json format. To convert the json to yaml, you can use a tool called [`yq`](https://github.com/mikefarah/yq) that converts the json to yaml so you can use command piping to convert the Terraform output to `cluster.yaml`.
+Terraform is currently limited to output json format. To convert the json to yaml, you can use a tool called [`yq`](https://github.com/mikefarah/yq) that converts the json to yaml so you can use command piping to convert the Terraform output to `launchpad.yaml`.
 
 ```
-terraform output -json | yq r --prettyPrint - ucp_cluster.value > cluster.yaml
+terraform output -json | yq r --prettyPrint - ucp_cluster.value > launchpad.yaml
 ```
 
 You can now use the `launchpad apply` command, and Launchpad will install all the needed cluster components.