From c8cb8e643a9d8e2d6bd1603edeee55e477d2898f Mon Sep 17 00:00:00 2001 From: Kimmo Lehto Date: Wed, 1 Jul 2020 16:33:51 +0300 Subject: [PATCH] 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 --- docs/command-reference.md | 9 +- docs/configuration-file.md | 122 ++++++++++++------ docs/getting-started.md | 10 +- docs/integrations.md | 2 +- docs/system-requirements.md | 13 +- docs/upgrades.md | 18 +-- examples/terraform/aws/main.tf | 22 +++- .../aws/modules/windows_worker/main.tf | 84 +++++++++--- .../aws/modules/windows_worker/variables.tf | 3 + examples/terraform/hetzner/main.tf | 6 +- 10 files changed, 201 insertions(+), 88 deletions(-) diff --git a/docs/command-reference.md b/docs/command-reference.md index d18e34f..25a9bee 100644 --- 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 index 89074a1..a8bdaab 100644 --- a/docs/configuration-file.md +++ b/docs/configuration-file.md @@ -7,50 +7,68 @@ 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` @@ -58,7 +76,7 @@ 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,7 +122,16 @@ 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 @@ -92,7 +139,8 @@ Specify options for UCP cluster itself. - `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 index 07c1841..fc885e4 100644 --- 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 index 9747c16..f30ccbd 100644 --- 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 index 4de5c39..7d673a6 100644 --- 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 --% Administrator@1.2.1.2 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 index 23454b8..563ccfc 100644 --- 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. \ No newline at end of file +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 index 85f5611..aad42d0 100644 --- a/examples/terraform/aws/main.tf +++ b/examples/terraform/aws/main.tf @@ -59,28 +59,36 @@ 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 + } } ] } @@ -88,7 +96,7 @@ locals { output "ucp_cluster" { value = { - apiVersion = "launchpad.mirantis.com/v1beta1" + apiVersion = "launchpad.mirantis.com/v1beta2" kind = "UCP" spec = { ucp = { diff --git a/examples/terraform/aws/modules/windows_worker/main.tf b/examples/terraform/aws/modules/windows_worker/main.tf index afd7e15..483edf2 100644 --- a/examples/terraform/aws/modules/windows_worker/main.tf +++ b/examples/terraform/aws/modules/windows_worker/main.tf @@ -2,6 +2,13 @@ resource "aws_security_group" "worker" { name = "${var.cluster_name}-win-workers" description = "ucp cluster windows workers" vpc_id = var.vpc_id + + ingress { + from_port = 5985 + to_port = 5986 + protocol = "tcp" + cidr_blocks = ["0.0.0.0/0"] + } } locals { @@ -21,33 +28,62 @@ resource "aws_instance" "ucp_worker" { instance_type = var.worker_type iam_instance_profile = var.instance_profile_name ami = var.image_id - key_name = var.ssh_key vpc_security_group_ids = [var.security_group_id, aws_security_group.worker.id] subnet_id = var.subnet_ids[count.index % local.subnet_count] ebs_optimized = true user_data = < -# Install OpenSSH -Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0 -Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0 -Start-Service sshd -Set-Service -Name sshd -StartupType 'Automatic' - -# Configure ssh key authentication -mkdir c:\Users\Administrator\.ssh\ -Invoke-WebRequest http://169.254.169.254/2012-01-12/meta-data/public-keys/0/openssh-key -UseBasicParsing -OutFile c:\Users\Administrator\.ssh\authorized_keys -Repair-AuthorizedKeyPermission C:\users\Administrator\.ssh\authorized_keys -Icacls C:\users\Administrator\.ssh\authorized_keys /remove “NT SERVICE\sshd” - -$sshdConf = 'c:\ProgramData\ssh\sshd_config' -(Get-Content $sshdConf).replace('#PubkeyAuthentication yes', 'PubkeyAuthentication yes') | Set-Content $sshdConf -(Get-Content $sshdConf).replace('Match Group administrators', '#Match Group administrators') | Set-Content $sshdConf -(Get-Content $sshdConf).replace(' AuthorizedKeysFile __PROGRAMDATA__/ssh/administrators_authorized_keys', '# AuthorizedKeysFile __PROGRAMDATA__/ssh/administrators_authorized_keys') | Set-Content $sshdConf -restart-service sshd +$admin = [adsi]("WinNT://./administrator, user") +$admin.psbase.invoke("SetPassword", "${var.windows_administrator_password}") + +# Snippet to enable WinRM over HTTPS with a self-signed certificate +# from https://gist.github.com/TechIsCool/d65017b8427cfa49d579a6d7b6e03c93 +Write-Output "Disabling WinRM over HTTP..." +Disable-NetFirewallRule -Name "WINRM-HTTP-In-TCP" +Disable-NetFirewallRule -Name "WINRM-HTTP-In-TCP-PUBLIC" +Get-ChildItem WSMan:\Localhost\listener | Remove-Item -Recurse + +Write-Output "Configuring WinRM for HTTPS..." +Set-Item -Path WSMan:\LocalHost\MaxTimeoutms -Value '1800000' +Set-Item -Path WSMan:\LocalHost\Shell\MaxMemoryPerShellMB -Value '1024' +Set-Item -Path WSMan:\LocalHost\Service\AllowUnencrypted -Value 'false' +Set-Item -Path WSMan:\LocalHost\Service\Auth\Basic -Value 'true' +Set-Item -Path WSMan:\LocalHost\Service\Auth\CredSSP -Value 'true' + +New-NetFirewallRule -Name "WINRM-HTTPS-In-TCP" ` + -DisplayName "Windows Remote Management (HTTPS-In)" ` + -Description "Inbound rule for Windows Remote Management via WS-Management. [TCP 5986]" ` + -Group "Windows Remote Management" ` + -Program "System" ` + -Protocol TCP ` + -LocalPort "5986" ` + -Action Allow ` + -Profile Domain,Private + +New-NetFirewallRule -Name "WINRM-HTTPS-In-TCP-PUBLIC" ` + -DisplayName "Windows Remote Management (HTTPS-In)" ` + -Description "Inbound rule for Windows Remote Management via WS-Management. [TCP 5986]" ` + -Group "Windows Remote Management" ` + -Program "System" ` + -Protocol TCP ` + -LocalPort "5986" ` + -Action Allow ` + -Profile Public + +$Hostname = [System.Net.Dns]::GetHostByName((hostname)).HostName.ToUpper() +$pfx = New-SelfSignedCertificate -CertstoreLocation Cert:\LocalMachine\My -DnsName $Hostname +$certThumbprint = $pfx.Thumbprint +$certSubjectName = $pfx.SubjectName.Name.TrimStart("CN = ").Trim() + +New-Item -Path WSMan:\LocalHost\Listener -Address * -Transport HTTPS -Hostname $certSubjectName -CertificateThumbPrint $certThumbprint -Port "5986" -force + +Write-Output "Restarting WinRM Service..." +Stop-Service WinRM +Set-Service WinRM -StartupType "Automatic" +Start-Service WinRM EOF - lifecycle { ignore_changes = [ami] } @@ -56,4 +92,14 @@ EOF volume_type = "gp2" volume_size = var.worker_volume_size } + + connection { + type = "winrm" + user = "Administrator" + password = var.administrator_password + timeout = "10m" + https = "true" + insecure = "true" + port=5986 + } } diff --git a/examples/terraform/aws/modules/windows_worker/variables.tf b/examples/terraform/aws/modules/windows_worker/variables.tf index 02656a1..ac191b9 100644 --- a/examples/terraform/aws/modules/windows_worker/variables.tf +++ b/examples/terraform/aws/modules/windows_worker/variables.tf @@ -29,3 +29,6 @@ variable "worker_type" { variable "worker_volume_size" { default = 100 } + +variable "windows_administrator_password" { +} diff --git a/examples/terraform/hetzner/main.tf b/examples/terraform/hetzner/main.tf index 1f04f1f..e3ae59f 100644 --- a/examples/terraform/hetzner/main.tf +++ b/examples/terraform/hetzner/main.tf @@ -68,13 +68,15 @@ resource "hcloud_server" "worker" { output "ucp_cluster" { value = { - apiVersion = "launchpad.mirantis.com/v1beta1" + apiVersion = "launchpad.mirantis.com/v1beta2" kind = "UCP" spec = { hosts = [ for host in concat(hcloud_server.master, hcloud_server.worker) : { address = host.ipv4_address - user = "root" + ssh = { + user = "root" + } role = host.labels.role } ]