install

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 <path-to-license> [flags]

Flags

Flag	Description
--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-bundle	The 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. Requirement: Embedded Cluster 1.16.0 or later.
--config-values	Path to the ConfigValues file for the application. The ConfigValues file can be used to pass the application configuration values from the command line during installation, such as when performing automated installations as part of CI/CD pipelines. For more information, see Automate Installation with Embedded Cluster. Requirement: Embedded Cluster 1.18.0 and later.
--data-dir	The data directory used by Embedded Cluster. Default: /var/lib/embedded-cluster Requirement: Embedded Cluster 1.16.0 or later. Limitations: The data directory for Embedded Cluster cannot be changed after the cluster is installed. For multi-node installations, the same data directory that is supplied at installation is used for all nodes joined to the cluster. You cannot choose a different data directory when joining nodes with the Embedded Cluster join command. For more information about joining nodes, see Add Nodes to a Cluster in Managing Multi-Node Clusters with Embedded Cluster. 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. Embedded Cluster 2.4.0 and later also respects the http_proxy, https_proxy, and no_proxy environment variables for installing behind a proxy. When set, flags take precedence over environment variables. Additionally, lowercase environment variables (http_proxy) take precedence over uppercase (HTTP_PROXY). Because the install command runs with sudo, environment variables must be available in sudo's environment. Use sudo -E to preserve the current user's environment, or pass variables explicitly with sudo env http_proxy=... https_proxy=.... Requirements: Proxy installations require Embedded Cluster 1.5.1 or later with Kubernetes 1.29 or later. When installing behind a proxy, you need to set both the HTTP and HTTPS proxy. You can set them using the --http-proxy and --https-proxy flags, or using the http_proxy and https_proxy environment variables. If you don't set one or both flags, Embedded Cluster uses the corresponding environment variable. If you don't use an HTTP proxy, set the HTTP proxy to the same host and port as your HTTPS proxy server. 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. Embedded Cluster 2.4.0 and later also respects the http_proxy, https_proxy, and no_proxy environment variables for installing behind a proxy. When set, flags take precedence over environment variables. Additionally, lowercase environment variables (http_proxy) take precedence over uppercase (HTTP_PROXY). Because the install command runs with sudo, environment variables must be available in sudo's environment. Use sudo -E to preserve the current user's environment, or pass variables explicitly with sudo env http_proxy=... https_proxy=.... Requirements: Proxy installations require Embedded Cluster 1.5.1 or later with Kubernetes 1.29 or later. When installing behind a proxy, you need to set both the HTTP and HTTPS proxy. You can set them using the --http-proxy and --https-proxy flags, or using the http_proxy and https_proxy environment variables. If you don't set one or both flags, Embedded Cluster uses the corresponding environment variable. If you don't use an HTTP proxy, set the HTTP proxy to the same host and port as your HTTPS proxy server. 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.
--ignore-app-preflights	When --ignore-app-preflights is passed, the application-specific preflight checks are skipped. This is useful when performing automated (headless) installations because it ensures that any warnings or failures from application preflight checks do not prevent the installation from proceeding. Requirement: Embedded Cluster 2.11.0 or later.
--ignore-host-preflights	When --ignore-host-preflights is passed, the host preflight checks are still run, but the user is prompted and can choose to continue with the installation if preflight failures occur. Additionally, the Admin Console still runs any application-specific preflight checks before the application is deployed. For more information about the Embedded Cluster host preflight checks, see About Host Preflight Checks in Using Embedded Cluster. Ignoring host preflight checks is not recommended for production installations.
-l, --license	Path to the customer license file
--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. Embedded Cluster 2.4.0 and later also respects the http_proxy, https_proxy, and no_proxy environment variables for installing behind a proxy. When set, flags take precedence over environment variables. Additionally, lowercase environment variables (http_proxy) take precedence over uppercase (HTTP_PROXY). Because the install command runs with sudo, environment variables must be available in sudo's environment. Use sudo -E to preserve the current user's environment, or pass variables explicitly with sudo env http_proxy=... https_proxy=.... Requirements: Proxy installations require Embedded Cluster 1.5.1 or later with Kubernetes 1.29 or later. When installing behind a proxy, you need to set both the HTTP and HTTPS proxy. You can set them using the --http-proxy and --https-proxy flags, or using the http_proxy and https_proxy environment variables. If you don't set one or both flags, Embedded Cluster uses the corresponding environment variable. If you don't use an HTTP proxy, set the HTTP proxy to the same host and port as your HTTPS proxy server. 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.
(Deprecated) --private-ca	note The --private-ca flag is deprecated. In Embedded Cluster 2.6.0 and later, it is no longer necessary to provide the path to a certificate authority (CA) with the --private-ca flag because Embedded Cluster automatically uses all CAs that are trusted by the host operating system. For more information about how to use these CAs in your application containers, see PrivateCACert in Static Context. If you pass the --private-ca flag with the install command, the flag is not used and a deprecation message is displayed. The path to trusted certificate authority (CA) certificates. In Embedded Cluster 2.4.0 and earlier, CAs provided with the --private-ca flag are written to a ConfigMap in the cluster that can then be accessed with the PrivateCACert template function.
--tls-cert	A custom TLS certificate for securing the Admin Console. When used with --tls-key, allows users performing automated (headless) installations to provide a custom TLS certificate and key from the command line rather than through the Admin Console UI. Requirement: Embedded Cluster 2.11.0 or later.
--tls-key	A custom TLS key for securing the Admin Console. When used with --tls-cert, allows users performing automated (headless) installations to provide a custom TLS certificate and key from the command line rather than through the Admin Console UI. Requirement: Embedded Cluster 2.11.0 or later.
-y, --yes	In Embedded Cluster 1.21.0 and later, pass the --yes flag to provide an affirmative response to any user prompts for the command. For example, you can pass --yes with the --ignore-host-preflights flag to ignore host preflight checks during automated installations. Requirement: Embedded Cluster 1.21.0 and later

Examples

Air Gap Install

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

Change the Admin Console and LAM Ports

sudo ./my-app 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

Headless (Automated) install

sudo ./my-app install --license license.yaml \
  --config-values configvalues.yaml \
  --admin-console-password password

Install Behind a Proxy

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

Where:

• HOST is the proxy server hostname.
• PORT is the proxy server port.
• 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.

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