diff --git a/docs/enterprise/installing-embedded-air-gap.mdx b/docs/enterprise/installing-embedded-air-gap.mdx index 918d9cea2e..81dff4b6c6 100644 --- a/docs/enterprise/installing-embedded-air-gap.mdx +++ b/docs/enterprise/installing-embedded-air-gap.mdx @@ -81,6 +81,10 @@ To install with Embedded Cluster in an air gap environment: sudo ./APP_SLUG install --license license.yaml --airgap-bundle APP_SLUG.airgap ``` Where `APP_SLUG` is the unique application slug. + + :::note + Embedded Cluster supports installation options such as installing behind a proxy and changing the data directory used by Embedded Cluster. For the list of flags supported with the Embedded Cluster `install` command, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install). + ::: 1. When prompted, enter a password for accessing the KOTS Admin Console. diff --git a/docs/enterprise/installing-embedded.mdx b/docs/enterprise/installing-embedded.mdx index e4a3e8aa7e..4e5e68d73e 100644 --- a/docs/enterprise/installing-embedded.mdx +++ b/docs/enterprise/installing-embedded.mdx @@ -47,6 +47,10 @@ To install an application with Embedded Cluster: Where: * `APP_SLUG` is the unique slug for the application. * `LICENSE_FILE` is the customer license. +
+ :::note + Embedded Cluster supports installation options such as installing behind a proxy and changing the data directory used by Embedded Cluster. For the list of flags supported with the Embedded Cluster `install` command, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install). + ::: 1. When prompted, enter a password for accessing the KOTS Admin Console. @@ -101,132 +105,4 @@ On the Admin Console dashboard, the application status changes from Missing to U ![Admin console dashboard showing ready status](/images/gitea-ec-ready.png) -[View a larger version of this image](/images/gitea-ec-ready.png) - -## Install Behind a Proxy Server {#proxy} - -The following flags can be used with the Embedded Cluster `install` command to install behind a proxy server: - - - - - - - - - - - - - - - - - - -
FlagDescription
`--http-proxy`Proxy server to use for HTTP
`--https-proxy`Proxy server to use for HTTPS
`--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 following are never proxied:

-
    -
  • Internal cluster communication (`localhost`, `127.0.0.1`, `.cluster.local`, `.svc`)
    • -
  • The CIDRs used for assigning IPs to Kubernetes Pods and Services. By default, the Pod CIDR is `10.244.0.0/16` and the Service CIDR `10.96.0.0/12`. For information about how to change these defaults, see [Set IP Address Ranges for Pods and Services](#set-ip-address-ranges-for-pods-and-services).
    • -
-

To ensure your app'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`.

-
- -#### Example - -```bash -sudo ./APP_SLUG install --license LICENSE_FILE \ - --http-proxy=HOST:PORT \ - --https-proxy=HOST:PORT \ - --no-proxy=LIST_OF_HOSTS -``` - -Where: - -* `LICENSE_FILE` is the customer's license -* `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. - -#### Requirement - -Proxy installations require Embedded Cluster 1.5.1 or later with Kubernetes 1.29 or later. For example, Embedded Cluster 1.6.0+k8s-1.29 supports installing behind a proxy, and 1.6.0+k8s-1.28 does not. For the latest version information, see [Embedded Cluster Release Notes](/release-notes/rn-embedded-cluster). - -#### 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. - -### Set IP Address Ranges for Pods and Services - -The following flags can be used with the Embedded Cluster `install` command to allocate IP address ranges for Pods and Services: - - - - - - - - - - - - - - -
FlagDescription
`--pod-cidr`The range of IP addresses that can be assigned to Pods, in CIDR notation. By default, the Pod CIDR is `10.244.0.0/16`.
`--service-cidr`The range of IP addresses that can be assigned to Services, in CIDR notation. By default, the Service CIDR is `10.96.0.0/12`.
- - -#### Example - -```bash -sudo ./my-app install --license license.yaml --pod-cidr 172.16.136.0/16 -``` - -#### Limitation - -The `--pod-cidr` and `--service-cidr` flags are not supported on Red Hat Enterprise Linux (RHEL) 9 operating systems. - -## Change Admin Console and LAM Ports {#adm-lam-ports} - -By default, the Admin Console and Local Artifact Mirror (LAM) run on ports 30000 and 50000, respectively. If these ports are occupied, you can select different ports. - -To choose different ports for the Admin Console and LAM during installation with Embedded Cluster, use the `--admin-console-port` and `--local-artifact-mirror-port` flags with the Embedded Cluster `install` command. - -For example: - -```bash -install --admin-console-port=20000 --local-artifact-mirror-port=40000 -``` - -The Embedded Cluster host preflight checks verify the default ports or the user-supplied ports, so users will be alerted before installation if they need to choose new port(s). For more information about the host preflight checks for Embedded Cluster, see [About Host Preflight Checks](/vendor/embedded-overview#about-host-preflight-checks). - -### 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)](/vendor/embedded-disaster-recovery). - -## Change the Default Data Directory {#data-dir} - -The default location of the data directory for Embedded Cluster is `/var/lib/embedded-cluster`. - -This directory can be modified by the user by passing the `--data-dir` flag to the `install` command. - -For example: - -```bash -sudo ./APP_SLUG install --data-dir /data/embedded-cluster --license license.yaml --airgap-bundle APP_SLUG.airgap -``` -Where `APP_SLUG` is the unique application slug. - -### Limtiations - -* 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](/vendor/embedded-disaster-recovery). - -* Replicated does not support using symlinks for the Embedded Cluster data directory. Use the `--data-dir` flag instead of symlinking `/var/lib/embedded-cluster`. \ No newline at end of file +[View a larger version of this image](/images/gitea-ec-ready.png) \ No newline at end of file diff --git a/docs/partials/embedded-cluster/_proxy-install-limitations.mdx b/docs/partials/embedded-cluster/_proxy-install-limitations.mdx new file mode 100644 index 0000000000..c34a5ebc2b --- /dev/null +++ b/docs/partials/embedded-cluster/_proxy-install-limitations.mdx @@ -0,0 +1,5 @@ +**Limitations:** + +* If any of your [Helm extensions](/reference/embedded-config#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. \ No newline at end of file diff --git a/docs/partials/embedded-cluster/_proxy-install-reqs.mdx b/docs/partials/embedded-cluster/_proxy-install-reqs.mdx new file mode 100644 index 0000000000..ab5df29fd5 --- /dev/null +++ b/docs/partials/embedded-cluster/_proxy-install-reqs.mdx @@ -0,0 +1 @@ +**Requirement:** Proxy installations require Embedded Cluster 1.5.1 or later with Kubernetes 1.29 or later. \ No newline at end of file diff --git a/docs/reference/embedded-cluster-install.mdx b/docs/reference/embedded-cluster-install.mdx new file mode 100644 index 0000000000..22541ff058 --- /dev/null +++ b/docs/reference/embedded-cluster-install.mdx @@ -0,0 +1,137 @@ +import ProxyLimitations from "../partials/embedded-cluster/_proxy-install-limitations.mdx" +import ProxyRequirements from "../partials/embedded-cluster/_proxy-install-reqs.mdx" + + +# 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](/enterprise/installing-embedded) or [Air Gap Installation with Embedded Cluster](/enterprise/installing-embedded). + +## Usage + +```bash +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-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)](/vendor/embedded-disaster-recovery).

+
`--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](/enterprise/installing-embedded-air-gap).
`--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](/vendor/embedded-disaster-recovery).
    • +
  • 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.

+ + +
`--https-proxy` +

Proxy server to use for HTTPS.

+ + +
`--local-artifact-mirror-port` +

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

+
`--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 following are never proxied:

+
    +
  • Internal cluster communication (`localhost`, `127.0.0.1`, `.cluster.local`, `.svc`)
    • +
  • The CIDRs used for assigning IPs to Kubernetes Pods and Services. By default, the Pod CIDR is `10.244.0.0/16` and the Service CIDR `10.96.0.0/12`. For information about how to change these defaults, see [Set IP Address Ranges for Pods and Services](#set-ip-address-ranges-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`.

+ + +
`--pod-cidr` +

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

+

**Limitation:** The `--pod-cidr` flag is not supported on Red Hat Enterprise Linux (RHEL) 9 operating systems.

+
`--service-cidr` +

The range of IP addresses that can be assigned to Services, in CIDR notation. **Default:** By default, the Service CIDR is `10.96.0.0/12`.

+

**Limitation:** The `--service-cidr` flags is not supported on Red Hat Enterprise Linux (RHEL) 9 operating systems.

+
+ +## Examples + +### Air Gap Install + +```bash +sudo ./myapp install --license license.yaml --airgap-bundle myapp.airgap +``` + +### Change the Admin Console and LAM Ports + +```bash +sudo ./myapp install --admin-console-port=20000 --local-artifact-mirror-port=40000 +``` + +### Change the Data Directory + +```bash +sudo ./my-app install --license license.yaml --data-dir /data/embedded-cluster +``` + +### Install Behind a Proxy + +```bash +sudo ./APP_SLUG install --license LICENSE_FILE \ + --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. + +### Set IP Address Range for Pods + +```bash +sudo ./my-app install --license license.yaml --pod-cidr 172.16.136.0/16 +``` \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 789d184649..a4b13907fb 100644 --- a/sidebars.js +++ b/sidebars.js @@ -348,6 +348,7 @@ const sidebars = { items: [ 'enterprise/installing-embedded', 'enterprise/installing-embedded-air-gap', + 'reference/embedded-cluster-install', ], }, {