Skip to content

Commit

Permalink
Update documentation for release 1.1 (#59)
Browse files Browse the repository at this point in the history 
* Update documentation for release 1.1

* in with

* Remove manual reboot notice

* Add note about stdin, add exec+describe

* Update pruning and admin credentials

* Rename ucp/dtr to mke/msr

* ReplicaIDs

* apiVersion

* Update command reference

* Universal Control Plane to Mirantis Kubernetes Engine

* Use config piping
  • Loading branch information
@kke
kke authored Nov 30, 2020
1 parent adac5d6 commit 1dffc70
Show file tree
Hide file tree
Showing 39 changed files with 438 additions and 275 deletions.
105 changes: 90 additions & 15 deletions docs/command-reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ Optional arguments that can be used with any of the `launchpad` commands.

* `--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)
* `--disable-upgrade-check` - Don't check for a launchpad upgrade
* `--debug` - Increase output verbosity
* `--help` - Display command help

Expand All @@ -25,28 +26,81 @@ initialize or upgrade a cluster.

The supported options are:

* `--config` - Path to a cluster config file, including the filename
* `--config` - Path to a cluster config file, including the filename (default: `launchpad.yaml`, read from stdin: `-`)
(default: `launchpad.yaml`)
* `--prune` - Remove nodes that are no longer in the cluster config yaml
(default: `false`)
* `--force` - Continue installation when prerequisite validation fails
(default: `false`)
* `--disable-redact` - Do not hide sensitive information in the output
(default: `false`)
* `--confirm` - Request confirmation for every command to be run on the remote hosts
(default: `false`)

## Download a client bundle
## Download client configuration

The client bundle contains a private and public key pair that authorizes
Launchpad to interact with
[UCP CLI](https://docs.mirantis.com/docker-enterprise/v3.1/dockeree-products/ucp/user-access.html#cli-access).
The MKE client bundle contains a private and public key pair that authorizes
Launchpad to interact with the [MKE CLI](https://docs.mirantis.com/docker-enterprise/v3.1/dockeree-products/ucp/user-access.html#cli-access).

`launchpad download-bundle`
`launchpad client-config`

The supported options are:

* `--username` - Username
* `--password` - Password
* `--config` - Path to a cluster config file, including the filename
* `--config` - Path to a cluster config file, including the filename (default: `launchpad.yaml`, read from stdin: `-`)
(default: `launchpad.yaml`)

**Note:** The configuration must include the MKE credentials, example:

```yaml
apiVersion: launchpad.mirantis.com/mke/v1.1
kind: mke
spec:
mke:
adminUsername: admin
adminPassword: password
```
## Reset or uninstall a cluster
To reset or uninstall an MKE cluster.
`launchpad reset`

The supported options are:

* `--config` - Path to a cluster config file, including the filename (default: `launchpad.yaml`, read from stdin: `-`)
* `--force` - Required when running non-interactively (default: `false`)
* `--disable-redact` - Do not hide sensitive information in the output
(default: `false`)
* `--confirm` - Request confirmation for every command to be run on the remote hosts
(default: `false`)

## Execute a command or run a remote terminal on a host

You can use launchpad to run commands or an interactive terminal on the hosts in the configuration.

`launchpad exec`

The supported options are:

* `--config` - Path to a cluster config file, including the filename (default: `launchpad.yaml`, read from stdin: `-`)
* `--target value` - Target host (example: address[:port])
* `--interactive` - Run interactive (default: false)
* `--first` - Use the first target found in configuration (default: false)
* `--role value` - Use the first target having this role in configuration
* `[command]` - The command to run. When blank, will run the default shell.

## Show cluster status

`launchpad describe`

The supported options are:

* `--config` - Path to a cluster config file, including the filename (default: `launchpad.yaml`, read from stdin: `-`)
* `--disable-redact` - Do not hide sensitive information in the output
(default: `false`)
* `--confirm` - Request confirmation for every command to be run on the remote hosts
(default: `false`)
* `[report name]` - Currently supported reports: `config`, `hosts`, `mke`, `msr`

## Register

Registers a user.
Expand All @@ -59,15 +113,36 @@ The supported options are:
* `--email` - Email
* `--company` - Company

## Reset or uninstall a cluster

To reset or uninstall a UCP cluster.
## Generate shell auto-completions

`launchpad reset`
`launchpad completion`

The supported options are:

* `--config` - Path to a cluster config file, including the filename (default: `launchpad.yaml`)
* `--shell` - Generate completions for the specified shell. Supported shells are bash, zsh and fish. (default: `$SHELL`)

### Installing the completion scripts:

These examples will place the completion script into the most common directory for most systems, on some systems the paths may be different. Usually this needs a restart of the shell session, the second command can be used to load the completions immediately to the current shell session without restarting.

Bash:
```
$ launchpad completion -s bash > /etc/bash_completion.d/launchpad
$ source /etc/bash_completion.d/launchpad
```

Zsh:
```
$ launchpad completion -s zsh > /usr/local/share/zsh/site-functions/_launchpad
$ source /usr/local/share/zsh/site-functions/_launchpad
```

Fish:
```
$ launchpad completion -s fish > ~/.config/fish/completions/launchpad.fish
$ source ~/.config/fish/completions/launchpad.fish
```

## Related topics

Expand Down
103 changes: 72 additions & 31 deletions docs/configuration-file.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@ Mirantis Launchpad cluster configuration is described in YAML format. You can cr
The complete `launchpad.yaml` file looks something like this, but with values determined by your specific configuration.

```yaml
apiVersion: launchpad.mirantis.com/v1
kind: DockerEnterprise
apiVersion: launchpad.mirantis.com/mke/v1.1
kind: mke+msr
metadata:
name: launchpad-ucp
name: launchpad-mke
spec:
hosts:
- address: 10.0.0.1
Expand Down Expand Up @@ -48,22 +48,24 @@ spec:
certPath: ~/.certs/cert.pem
keyPath: ~/.certs/key.pem
- address: 10.0.0.3
role: dtr
role: msr
imageDir: ./dtr-images
ssh:
user: root
port: 22
keyPath: ~/.ssh/id_rsa
- address: 127.0.0.1
role: worker
localhost: true
ucp:
mke:
version: "3.3.3"
imageRepo: "docker.io/docker"
adminUsername: admin
adminPassword: "$MKE_ADMIN_PASSWORD"
installFlags:
- --admin-username=admin
- --admin-password=orcaorcaorca
- --default-node-orchestrator=kubernetes
licenseFilePath: ./docker-enterprise.lic
configFile: ./ucp-config.toml
configFile: ./mke-config.toml
configData: |-
[scheduling_configuration]
default_node_orchestrator = "kubernetes"
Expand All @@ -73,30 +75,58 @@ spec:
configData: |-
[Global]
region=RegionOne
dtr:
msr:
version: 2.8.1
imageRepo: "docker.io/docker"
installFlags:
- --dtr-external-url dtr.example.com
- --ucp-insecure-tls
replicaConfig: sequential
replicaIDs: sequential
engine:
version: "19.03.8"
channel: stable
repoURL: https://repos.mirantis.com
installURLLinux: https://get.mirantis.com/
installURLWindows: https://get.mirantis.com/install.ps1
cluster:
prune: true
```
We follow Kubernetes-like versioning and grouping in launchpad configuration so you'll see familiar attributes such as `kind`.

## Environment variable substitution

When reading the configuration file, launchpad will replace any strings starting with a dollar sign with values from the local host's environment variables. Example:

```yaml
apiVersion: launchpad.mirantis.com/mke/v1.1
kind: mke
spec:
mke:
installFlags:
- --admin-password="$MKE_ADMIN_PASSWORD"
```

Very simple bash-like expressions are supported:

Expression | Meaning
-- | --
${var} | Value of var (same as $var)
${var-$DEFAULT} | If var not set, evaluate expression as $DEFAULT
${var:-$DEFAULT} | If var not set or is empty, evaluate expression as $DEFAULT
${var=$DEFAULT} | If var not set, evaluate expression as $DEFAULT
${var:=$DEFAULT} | If var not set or is empty, evaluate expression as $DEFAULT
${var+$OTHER} | If var set, evaluate expression as $OTHER, otherwise as empty string
${var:+$OTHER} | If var set, evaluate expression as $OTHER, otherwise as empty string
$$var | Escape expressions. Result will be $var.

## `apiVersion`

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.
The latest API version is `launchpad.mirantis.com/mke/v1.1`, but earlier configuration file versions should still work without changes if you do not intend to use any of the added features of the current version.

## `kind`

Currently only `DockerEnterprise` is supported.
Currently `mke` and `mke+msr` are supported. In future releases you may have to use `mke+msr` when the configuration contains MSR elements, for now it's informational.

## `metadata`

Expand All @@ -117,10 +147,11 @@ interface (default: `eth0`)
- `role` - Role of the machine in the cluster. Possible values are:
- `manager`
- `worker`
- `dtr`
- `msr`
- `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)
- `imageDir` - Path to a directory containing `.tar`/`.tar.gz` files produced by `docker save`. The images from that directory will be uploaded and `docker load` is used to load them.

#### Host connection options

Expand Down Expand Up @@ -167,52 +198,62 @@ Host hooks can be used to have launchpad run commands on the host before or afte
- `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`
### `mke`

Specify options for the UCP cluster itself.
Specify options for the MKE cluster itself.

- `version` - Which version of UCP we should install or upgrade to (default `3.3.0`)
- `imageRepo` - Which image repository we should use for UCP installation (default `docker.io/docker`)
- `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)
- `version` - Which version of MKE we should install or upgrade to (default `3.3.3`)
- `imageRepo` - Which image repository we should use for MKE installation (default `docker.io/docker`)
- `adminUsername` - MKE administrator username (default: `admin`)
- `adminPassword`- MKE administrator password (default: auto-generate)
- `installFlags` - Custom installation flags for MKE installation. You can get a list of supported installation options for a specific MKE version by running the installer container with `docker run -t -i --rm docker/ucp:3.3.0 install --help`. (optional)
- `licenseFilePath` - Optional. A path to Docker Enterprise license file.
- `configFile` - Optional. The initial full cluster [configuration file](https://docs.mirantis.com/docker-enterprise/v3.1/dockeree-products/ucp/ucp-configure/ucp-configuration-file.html).
- `configData` - Optional. The initial full cluster [configuration file](https://docs.mirantis.com/docker-enterprise/v3.1/dockeree-products/ucp/ucp-configure/ucp-configuration-file.html) in embedded "heredocs" way. Heredocs allows you to define a mulitiline string while maintaining the original formatting and indenting
- `cloud` - Optional. Cloud provider configuration

**Note:** The MKE installer will automatically generate an administrator password unless provided and it will be displayed in clear text in the output and persisted in the logs. The automatically generated password must be configured in the `launchpad.yaml` for any subsequent runs or they will fail.

#### `cloud`

Cloud provider configuration.

- `provider` - Provider name (currently aws, azure and openstack (UCP 3.3.3+) are supported) (optional)
- `provider` - Provider name (currently aws, azure and openstack (MKE 3.3.3+) are supported) (optional)
- `configFile` - Path to cloud provider configuration file on local machine (optional)
- `configData` - Inlined cloud provider configuration (optional)

### `dtr`
### `msr`

Specify options for the DTR cluster.
Specify options for the MSR cluster.

- `version` - Which version of DTR we should install or upgrade to (default `2.8.1`)
- `imageRepo` - Which image repository we should use for DTR installation (default `docker.io/docker`)
- `installFlags` - Custom installation flags for DTR installation. You can get a list of supported installation options for a specific DTR version by running the installer container with `docker run -t -i --rm docker/dtr:2.8.1 install --help`. (optional)
- `version` - Which version of MSR we should install or upgrade to (default `2.8.3`)
- `imageRepo` - Which image repository we should use for MSR installation (default `docker.io/mirantis`)
- `installFlags` - Custom installation flags for MSR installation. You can get a list of supported installation options for a specific MSR version by running the installer container with `docker run -t -i --rm mirantis/dtr:2.8.3 install --help`. (optional)

**Note**: `launchpad` will inherit the UCP flags which are needed by DTR to perform installation, joining and removal of nodes. There's no need to include the following install flags in the `installFlags` section of `dtr`:
- `--ucp-username` (inherited from UCP's `--admin-username` flag)
- `--ucp-password` (inherited from UCP's `--admin-password` flag)
- `--ucp-url` (inherited from UCP's `--san` flag or intelligently selected based on other configuration variables)
**Note**: `launchpad` will inherit the MKE flags which are needed by MSR to perform installation, joining and removal of nodes. There's no need to include the following install flags in the `installFlags` section of `msr`:
- `--ucp-username` (inherited from MKE's `--admin-username` flag or `spec.mke.adminUsername`)
- `--ucp-password` (inherited from MKE's `--admin-password` flag or `spec.mke.adminPassword`)
- `--ucp-url` (inherited from MKE's `--san` flag or intelligently selected based on other configuration variables)

- `replicaConfig` - Set to `sequential` to generate sequential replica id's for cluster members, for example `000000000001`, `000000000002`, etc. (default: `random`)
- `replicaIDs` - Set to `sequential` to generate sequential replica id's for cluster members, for example `000000000001`, `000000000002`, etc. (default: `random`)

### `engine`

Specify options for Docker Engine - Enterprise to be installed

- `version` - The version of engine that you want to install or upgraded to. (default `19.03.8`)
- `version` - The version of engine that you want to install or upgraded to. (default `19.03.12`)
- `channel` - Installation channel to use. One of `test` or `prod` (optional)
- `repoURL` - Repository URL to use for engine installation. (optional)
- `installURLLinux` - Where to download the initial installer script for linux hosts. Local paths can also 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:** In most scenarios, you should not need to specify `repoUrl` and `installURLLinux/Windows`, which are only usually used when installing from a non-standard location like a disconnected datacenter.
**Note:** In most scenarios, you should not need to specify `repoUrl` and `installURLLinux/Windows`, which are only usually used when installing from a non-standard location like a disconnected datacenter.

### `cluster`

Specify options not specific to any of the individual components.

- `prune` - Set to `true` to remove nodes that are known by the cluster but not listed in the `launchpad.yaml`.

## Related topics

Expand Down
Loading

0 comments on commit 1dffc70

Please sign in to comment.