install

The install command installs MKE on the specified node. Specifically, the command initializes a new swarm, promotes the specified node into a manager node, and installs MKE.

The following customizations are possible when installing MKE:

  • Customize the MKE web server certificates:

    1. Create a volume named ucp-controller-server-certs.

    2. Copy the ca.pem, cert.pem, and key.pem files to the root directory.

    3. Run the install` command with the --external-server-cert flag.

  • Customize the license used by MKE using one of the following options:

    • Bind mount the file at /config/docker_subscription.lic in the tool. For example:

      -v /path/to/my/config/docker_subscription.lic:/config/docker_subscription.lic
      
    • Specify the --license $(cat license.lic) option.

If you plan to join more nodes to the swarm, open the following ports in your firewall:

  • 443 or the value of --controller-port

  • 2376 or the value of --swarm-port

  • 2377 or the Swarm gRPC port

  • 6443 or the value of --kube-apiserver-port

  • 179, 10250, 12376, 12379, 12380, 12381, 12382, 12383, 12384, 12385, 12386, 12387, 12388, 12390

  • 4789 (UDP) and 7946 (TCP/UDP) for overlay networking

For more information, refer to Open ports to incoming traffic.

Note

If you are installing MKE on a public cloud platform, see the cloud-specific MKE installation documentation for the following platforms:


To use the install command:

docker container run --rm -it \
  --name ucp \
  -v /var/run/docker.sock:/var/run/docker.sock \
  mirantis/ucp:3.x.y \
  install <command-options>

Options

Option

Description

--debug, -D

Enables debug mode.

--jsonlog

Produces JSON-formatted output for easier parsing.

--interactive, -i

Runs in interactive mode, prompting for configuration values.

--admin-password <value>

Sets the MKE administrator password, $UCP_ADMIN_PASSWORD.

--admin-username <value>

Sets the MKE administrator user name, $UCP_ADMIN_USER.

--azure-ip-count <value>

Configures the number of IP addresses to be provisioned for each Azure Virtual Machine.

Default: 128.

binpack

Sets the Docker Swarm scheduler to binpack mode, for backward compatibility.

--cloud-provider <value>

Sets the cluster cloud provider.

Valid values: aws, azure, gce.

--cni-installer-url <value>

Sets a URL that points to a Kubernetes YAML file that is used as an installer for the cluster CNI plugin. If specified, the default CNI plugin is not installed. If the URL uses the HTTPS scheme, no certificate verification is performed.

--controller-port <value>

Sets the port for the web UI and the API

Default: 443.

--data-path-addr <value>

Sets the address or interface to use for data path traffic, $UCP_DATA_PATH_ADDR.

Format: IP address or network interface name

--disable-tracking

Disables anonymous tracking and analytics.

--disable-usage

Disables anonymous usage reporting.

--dns-opt <value>

Sets the DNS options for the MKE containers, $DNS_OPT.

--dns-search <value>

Sets custom DNS search domains for the MKE containers, $DNS_SEARCH.

--dns <value>

Sets custom DNS servers for the MKE containers, $DNS.

--enable-profiling

Enables performance profiling.

--existing-config

Sets to use the latest existing MKE configuration during the installation. The installation will fail if a configuration is not found.

--external-server-cert

Customizes the certificates used by the MKE web server.

--external-service-lb <value>

Sets the IP address of the load balancer where you can expect to reach published services.

--force-insecure-tcp

Forces the installation to continue despite unauthenticated Mirantis Container Runtime ports.

--force-minimums

Forces the installation to occur even if the system does not meet the minimum requirements.

--host-address <value>

Sets the network address that advertises to other nodes, $UCP_HOST_ADDRESS.

Format: IP address or network interface name

--iscsiadm-pathvalue <value>

Sets the path to the host iscsiadm binary. This option is applicable only when --storage-iscsi is specified.

--kube-apiserver-port <value>

Sets the port for the Kubernetes API server.

Default: 6443.

--kv-snapshot-count <value>

Sets the number of changes between key-value store snapshots, $KV_SNAPSHOT_COUNT.

Default: 20000.

--kv-timeout <value>

Sets the timeout in milliseconds for the key-value store, $KV_TIMEOUT.

Default: 5000.

--license <value>

Adds a license, $UCP_LICENSE.

Format: “$(cat license.lic)”

--nodeport-range <value>

Sets the allowed port range for Kubernetes services of NodePort type.

Default: 32768-35535.

--pod-cidr <values>

Sets Kubernetes cluster IP pool for the Pods to be allocated from.

Default: 192.168.0.0/16.

--preserve-certs

Sets so that certificates are not generated if they already exist.

--pull <value>

Pulls MKE images.

Valid values: always, missing, and never

Default: missing.

--random

Sets the Docker Swarm scheduler to random mode, for backward compatibility.

--registry-password <value>

Sets the password to use when pulling images, $REGISTRY_PASSWORD.

--registry-username <value>

Sets the user name to use when pulling images, $REGISTRY_USERNAME.

--san <value>

Adds subject alternative names to certificates, $UCP_HOSTNAMES.

For example: --san www2.acme.com

--service-cluster-ip-range <value>

Sets the Kubernetes cluster IP Range for services.

Default: 10.96.0.0/16.

--skip-cloud-provider-check

Disables checks which rely on detecting which cloud provider, if any, the cluster is currently running on.

--storage-expt-enabled

Enables experimental features in Kubernetes storage.

--storage-iscsi

Enables ISCSI-based PersistentVolumes in Kubernetes.

--swarm-experimental

Enables Docker Swarm experimental features, for backward compatibility.

--swarm-grpc-port <value>

Sets the port for communication between nodes.

Default: 2377.

--swarm-port <value>

Sets the port for the Docker Swarm manager, for backward compatibility.

Default: 2376.

--unlock-key <value>

Sets the unlock key for this swarm-mode cluster, if one exists, $UNLOCK_KEY.

--unmanaged-cni

Indicates that Calico is the CNI provider, managed by MKE. Calico is the default CNI provider.

--kubelet-data-root

Configures the kubelet data root directory on Linux when performing new MKE installations.

--containerd-root

Configures the containerd root directory on Linux when performing new MKE installations. Any non-root directory containerd customizations must be made along with the root directory customizations prior to installation and with the --containerd-root flag omitted.

--ingress-controller

Configures the HTTP ingress controller for the management of traffic that originates outside the cluster.

--calico-ebpf-enabled

Sets whether Calico eBPF mode is enabled.

When specifying --calico-ebpf-enabled, do not use --kube-default-drop-masq-bits or --kube-proxy-mode.

--kube-default-drop-masq-bits

Sets whether MKE uses Kubernetes default values for iptables drop and masquerade bits.

--kube-proxy-mode

Sets the operational mode for kube-proxy.

Valid values: iptables, ipvs, disabled

Default: iptables.

--kube-protect-kernel-defaults

Protects kernel parameters from being overridden by kubelet.

Default: false.

Important

When enabled, kubelet can fail to start if the following kernel parameters are not properly set on the nodes before you install MKE or before adding a new node to an existing cluster:

vm.panic_on_oom=0
vm.overcommit_memory=1
kernel.panic=10
kernel.panic_on_oops=1
kernel.keys.root_maxkeys=1000000
kernel.keys.root_maxbytes=25000000

For more information, refer to Configure kernel parameters.

--swarm-only

Configures MKE in Swarm-only mode, which supports only Docker Swarm orchestration.

--windows-containerd-root <value>

Sets the root directory for containerd on Windows.

--secure-overlay

Enables IPSec network encryption using SecureOverlay in Kubernetes.

--calico-ip-auto-method <value>

Allows the user to set the method for autodetecting the IPv4 address for the host. When specified, IP autodetection method is set for calico-node.

--calico-vxlan

Sets the calico CNI dataplane to VXLAN.

Default: VXLAN.

vxlan-vni <value>

Sets the vxlan-vni ID. Note that dataplane must be set to VXLAN.

Valid values: 10000 - 20000.

Default: 10000.

--cni-mtu <value>

Sets the MTU for CNI interfaces. Calculate MTU size based on which overlay is in use. For user-specific configuration, subtract 20 bytes for IPIP or 50 bytes for VXLAN.

Default: 1480 for IPIP, 1450 for VXLAN.

--windows-kubelet-data-root <value>

Sets the data root directory for kubelet on Windows.

--default-node-orchestrator <value>

Sets the default node orchestrator for the cluster.

Valid values: swarm, kubernetes.

Default: swarm.

--iscsidb-path <value>

Sets the absolute path to host iscsi DB. Verify that --storage-iscsi is specified. Note that Symlinks are not allowed.

--kube-proxy-disabled

Disables kube-proxy. This option is activated by --calico-ebpf-enabled, and it cannot be used in combination with --kube-proxy-mode.

--cluster-label <value>

Sets the cluster label that is employed for usage reporting.

SELinux

Installing MKE on a manager node with SELinux enabled at the daemon and the operating system levels requires that you include --security-opt label=disable with your install command. This flag disables SELinux policies on the installation container. The MKE installation container mounts and configures the Docker socket as part of the MKE installation container. Therefore, omitting this flag will result in the failure of your MKE installation with the following error:

FATA[0000] unable to get valid Docker client: unable to ping Docker
daemon: Got permission denied while trying to connect to the Docker
daemon socket at unix:///var/run/docker.sock:
Get http://%2Fvar%2Frun%2Fdocker.sock/_ping:
dial unix /var/run/docker.sock: connect: permission denied -
If SELinux is enabled on the Docker daemon, make sure you run
MKE with "docker run --security-opt label=disable -v /var/run/docker.sock:/var/run/docker.sock ..."

To install MKE with SELinux enabled at the daemon level:

docker container run -rm -it \
  --name ucp \
  --security-opt label=disable \
  -v /var/run/docker.sock:/var/run/docker.sock \
  mirantis/ucp:3.x.y \
  install <command-options>