Skip to main content

Embedded Cluster Install Command Options

This topic describes the options available with the Embedded Cluster install command. For more information about how to install with Embedded Cluster, see Online Installation with Embedded Cluster or Air Gap Installation with Embedded Cluster.

Usage

sudo ./APP_SLUG install --license LICENSE_FILE [flags]
  • APP_SLUG is the unique application slug
  • LICENSE_FILE is the customer's license

Flags

FlagDescription
--admin-console-password

Set the password for the Admin Console. The password must be at least six characters in length. If not set, the user is prompted to provide an Admin Console password.

--admin-console-port

Port on which to run the KOTS Admin Console. Default: By default, the Admin Console runs on port 30000.

Limitation: It is not possible to change the port for the Admin Console during a restore with Embedded Cluster. For more information, see Disaster Recovery for Embedded Cluster (Alpha).

--airgap-bundleThe Embedded Cluster air gap bundle used for installations in air-gapped environments with no outbound internet access. For information about how to install in an air-gapped environment, see Air Gap Installation with Embedded Cluster.
--cidr

The range of IP addresses that can be assigned to Pods and Services, in CIDR notation. Default: By default, the CIDR block is 10.244.0.0/16.

--data-dir

The data directory used by Embedded Cluster. Default: /var/lib/embedded-cluster

Limitations:

  • The data directory for Embedded Cluster cannot be changed after the cluster is installed.
  • If you use the --data-dir flag to change the data directory during installation, then you must use the same location when restoring in a disaster recovery scenario. For more information about disaster recovery with Embedded Cluster, see Disaster Recovery for Embedded Cluster.
  • Replicated does not support using symlinks for the Embedded Cluster data directory. Use the --data-dir flag instead of symlinking /var/lib/embedded-cluster.
--http-proxy

Proxy server to use for HTTP.

Requirement: Proxy installations require Embedded Cluster 1.5.1 or later with Kubernetes 1.29 or later.

Limitations:

  • If any of your Helm extensions make requests to the internet, the given charts need to be manually configured so that those requests are made to the user-supplied proxy server instead. Typically, this requires updating the Helm values to set HTTP proxy, HTTPS proxy, and no proxy. Note that this limitation applies only to network requests made by your Helm extensions. The proxy settings supplied to the install command are used to pull the containers required to run your Helm extensions.

  • Proxy settings cannot be changed after installation or during upgrade.

--https-proxy

Proxy server to use for HTTPS.

Requirement: Proxy installations require Embedded Cluster 1.5.1 or later with Kubernetes 1.29 or later.

Limitations:

  • If any of your Helm extensions make requests to the internet, the given charts need to be manually configured so that those requests are made to the user-supplied proxy server instead. Typically, this requires updating the Helm values to set HTTP proxy, HTTPS proxy, and no proxy. Note that this limitation applies only to network requests made by your Helm extensions. The proxy settings supplied to the install command are used to pull the containers required to run your Helm extensions.

  • Proxy settings cannot be changed after installation or during upgrade.

--local-artifact-mirror-port

Port on which to run the Local Artifact Mirror (LAM). Default: By default, the LAM runs on port 50000.

--network-interface

The name of the network interface to bind to for the Kubernetes API. A common use case of --network-interface is for multi-node clusters where node communication should happen on a particular network. Default: If a network interface is not provided, the first valid, non-local network interface is used.

--no-proxy

Comma-separated list of hosts for which not to use a proxy.

For single-node installations, pass the IP address of the node where you are installing. For multi-node installations, when deploying the first node, pass the list of IP addresses for all nodes in the cluster (typically in CIDR notation). The network interface's subnet will automatically be added to the no-proxy list if the node's IP address is not already included.

The following are never proxied:

  • Internal cluster communication (localhost, 127.0.0.1, .cluster.local, .svc)
  • The CIDR block used for assigning IPs to Kubernetes Pods and Services. By default, the CIDR block is 10.244.0.0/16. For information about how to change this default, see Set IP Address Range for Pods and Services.

To ensure your application's internal cluster communication is not proxied, use fully qualified domain names like my-service.my-namespace.svc or my-service.my-namespace.svc.cluster.local.

Requirement: Proxy installations require Embedded Cluster 1.5.1 or later with Kubernetes 1.29 or later.

Limitations:

  • If any of your Helm extensions make requests to the internet, the given charts need to be manually configured so that those requests are made to the user-supplied proxy server instead. Typically, this requires updating the Helm values to set HTTP proxy, HTTPS proxy, and no proxy. Note that this limitation applies only to network requests made by your Helm extensions. The proxy settings supplied to the install command are used to pull the containers required to run your Helm extensions.

  • Proxy settings cannot be changed after installation or during upgrade.

--private-ca

The path to trusted certificate authority (CA) certificates. Using the --private-ca flag ensures that the CA is trusted by the installation. KOTS writes the CA certificates provided with the --private-ca flag to a ConfigMap in the cluster.

The KOTS PrivateCACert template function returns the ConfigMap containing the private CA certificates supplied with the --private-ca flag. You can use this template function to mount the ConfigMap so your containers trust the CA too.

Examples

Air Gap Install

sudo ./myapp install --license license.yaml --airgap-bundle myapp.airgap

Change the Admin Console and LAM Ports

sudo ./myapp install --license license.yaml --admin-console-port=20000 --local-artifact-mirror-port=40000

Change the Data Directory

sudo ./my-app install --license license.yaml --data-dir /data/embedded-cluster

Install Behind a Proxy

sudo ./APP_SLUG install --license license.yaml \
--http-proxy=HOST:PORT \
--https-proxy=HOST:PORT \
--no-proxy=LIST_OF_HOSTS

Where:

  • HOST:PORT is the host and port of the proxy server
  • LIST_OF_HOSTS is the list of hosts to not proxy. For example, the IP address of the node where you are installing. Or, for multi-node clusters, the list of IP addresses for all nodes in the cluster, typically in CIDR notation.

Install Behind an MITM Proxy

sudo ./APP_SLUG install --license license.yaml --private-ca /path/to/private-ca-bundle \
--http-proxy=http://10.128.0.0:3300 \
--https-proxy=http://10.128.0.0:3300 \
--no-proxy=123.89.46.4,10.96.0.0/16,*.example.com

Set Admin Console Password

sudo ./my-app install --license license.yaml --admin-console-password password

Set IP Address Range for Pods and Services

sudo ./my-app install --license license.yaml --cidr 172.16.136.0/16

Use a Specific Network Interface

sudo ./my-app install --license license.yaml --network-interface eno167777