Skip to content

Commit 20a7505

Browse files
paigecalvertpaigecalvert
authored
Merge pull request #2755 from replicatedhq/113899
Add Embedded Cluster install command reference
2 parents 120f542 + a521afd commit 20a7505

File tree

6 files changed

+153
-129
lines changed

6 files changed

+153
-129
lines changed

‎docs/enterprise/installing-embedded-air-gap.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,10 @@ To install with Embedded Cluster in an air gap environment:
8585
sudo ./APP_SLUG install --license license.yaml --airgap-bundle APP_SLUG.airgap
8686
```
8787
Where `APP_SLUG` is the unique application slug.
88+
89+
:::note
90+
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).
91+
:::
8892

8993
1. When prompted, enter a password for accessing the KOTS Admin Console.
9094

‎docs/enterprise/installing-embedded.mdx‎

Lines changed: 5 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,10 @@ To install an application with Embedded Cluster:
4747
Where:
4848
* `APP_SLUG` is the unique slug for the application.
4949
* `LICENSE_FILE` is the customer license.
50+
<br/>
51+
:::note
52+
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).
53+
:::
5054

5155
1. When prompted, enter a password for accessing the KOTS Admin Console.
5256

@@ -101,132 +105,4 @@ On the Admin Console dashboard, the application status changes from Missing to U
101105

102106
![Admin console dashboard showing ready status](/images/gitea-ec-ready.png)
103107

104-
[View a larger version of this image](/images/gitea-ec-ready.png)
105-
106-
## Install Behind a Proxy Server {#proxy}
107-
108-
The following flags can be used with the Embedded Cluster `install` command to install behind a proxy server:
109-
110-
<table>
111-
<tr>
112-
<th width="35%">Flag</th>
113-
<th width="65%">Description</th>
114-
</tr>
115-
<tr>
116-
<td>`--http-proxy`</td>
117-
<td>Proxy server to use for HTTP</td>
118-
</tr>
119-
<tr>
120-
<td>`--https-proxy`</td>
121-
<td>Proxy server to use for HTTPS</td>
122-
</tr>
123-
<tr>
124-
<td>`--no-proxy`</td>
125-
<td>
126-
<p>Comma-separated list of hosts for which not to use a proxy.</p>
127-
<p>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).</p>
128-
<p>The following are never proxied:</p>
129-
<ul>
130-
<li>Internal cluster communication (`localhost`, `127.0.0.1`, `.cluster.local`, `.svc`)</li>
131-
<li>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).</li>
132-
</ul>
133-
<p>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`.</p>
134-
</td>
135-
</tr>
136-
</table>
137-
138-
#### Example
139-
140-
```bash
141-
sudo ./APP_SLUG install --license LICENSE_FILE \
142-
--http-proxy=HOST:PORT \
143-
--https-proxy=HOST:PORT \
144-
--no-proxy=LIST_OF_HOSTS
145-
```
146-
147-
Where:
148-
149-
* `LICENSE_FILE` is the customer's license
150-
* `HOST:PORT` is the host and port of the proxy server
151-
* `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.
152-
153-
#### Requirement
154-
155-
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).
156-
157-
#### Limitations
158-
159-
* 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.
160-
161-
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.
162-
163-
* Proxy settings cannot be changed after installation or during upgrade.
164-
165-
### Set IP Address Ranges for Pods and Services
166-
167-
The following flags can be used with the Embedded Cluster `install` command to allocate IP address ranges for Pods and Services:
168-
169-
<table>
170-
<tr>
171-
<th width="35%">Flag</th>
172-
<th width="65%">Description</th>
173-
</tr>
174-
<tr>
175-
<td>`--pod-cidr`</td>
176-
<td>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`.</td>
177-
</tr>
178-
<tr>
179-
<td>`--service-cidr`</td>
180-
<td>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`.</td>
181-
</tr>
182-
</table>
183-
184-
185-
#### Example
186-
187-
```bash
188-
sudo ./my-app install --license license.yaml --pod-cidr 172.16.136.0/16
189-
```
190-
191-
#### Limitation
192-
193-
The `--pod-cidr` and `--service-cidr` flags are not supported on Red Hat Enterprise Linux (RHEL) 9 operating systems.
194-
195-
## Change Admin Console and LAM Ports {#adm-lam-ports}
196-
197-
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.
198-
199-
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.
200-
201-
For example:
202-
203-
```bash
204-
install --admin-console-port=20000 --local-artifact-mirror-port=40000
205-
```
206-
207-
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).
208-
209-
### Limitation
210-
211-
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).
212-
213-
## Change the Default Data Directory {#data-dir}
214-
215-
The default location of the data directory for Embedded Cluster is `/var/lib/embedded-cluster`.
216-
217-
This directory can be modified by the user by passing the `--data-dir` flag to the `install` command.
218-
219-
For example:
220-
221-
```bash
222-
sudo ./APP_SLUG install --data-dir /data/embedded-cluster --license license.yaml --airgap-bundle APP_SLUG.airgap
223-
```
224-
Where `APP_SLUG` is the unique application slug.
225-
226-
### Limtiations
227-
228-
* The data directory for Embedded Cluster cannot be changed after the cluster is installed.
229-
230-
* 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).
231-
232-
* Replicated does not support using symlinks for the Embedded Cluster data directory. Use the `--data-dir` flag instead of symlinking `/var/lib/embedded-cluster`.
108+
[View a larger version of this image](/images/gitea-ec-ready.png)

‎docs/partials/embedded-cluster/_proxy-install-limitations.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
**Limitations:**
2+
3+
* 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.
4+
5+
* Proxy settings cannot be changed after installation or during upgrade.

‎docs/partials/embedded-cluster/_proxy-install-reqs.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
**Requirement:** Proxy installations require Embedded Cluster 1.5.1 or later with Kubernetes 1.29 or later.

‎docs/reference/embedded-cluster-install.mdx‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
import ProxyLimitations from "../partials/embedded-cluster/_proxy-install-limitations.mdx"
2+
import ProxyRequirements from "../partials/embedded-cluster/_proxy-install-reqs.mdx"
3+
4+
5+
# Embedded Cluster Install Command Options
6+
7+
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).
8+
9+
## Usage
10+
11+
```bash
12+
sudo ./APP_SLUG install --license LICENSE_FILE [flags]
13+
```
14+
* `APP_SLUG` is the unique application slug
15+
* `LICENSE_FILE` is the customer's license
16+
17+
## Flags
18+
19+
<table>
20+
<tr>
21+
<th width="35%">Flag</th>
22+
<th width="65%">Description</th>
23+
</tr>
24+
<tr>
25+
<td>`--admin-console-port`</td>
26+
<td>
27+
<p>Port on which to run the KOTS Admin Console. **Default**: By default, the Admin Console runs on port 30000.</p>
28+
<p>**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).</p>
29+
</td>
30+
</tr>
31+
<tr>
32+
<td>`--airgap-bundle`</td>
33+
<td>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).</td>
34+
</tr>
35+
<tr>
36+
<td>`--data-dir`</td>
37+
<td>
38+
<p>The data directory used by Embedded Cluster. **Default**: `/var/lib/embedded-cluster`</p>
39+
<p>**Limitations:**</p>
40+
<ul>
41+
<li>The data directory for Embedded Cluster cannot be changed after the cluster is installed.</li>
42+
<li>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).</li>
43+
<li>Replicated does not support using symlinks for the Embedded Cluster data directory. Use the `--data-dir` flag instead of symlinking `/var/lib/embedded-cluster`.</li>
44+
</ul>
45+
</td>
46+
</tr>
47+
<tr>
48+
<td>`--http-proxy`</td>
49+
<td>
50+
<p>Proxy server to use for HTTP.</p>
51+
<ProxyRequirements/>
52+
<ProxyLimitations/>
53+
</td>
54+
</tr>
55+
<tr>
56+
<td>`--https-proxy`</td>
57+
<td>
58+
<p>Proxy server to use for HTTPS.</p>
59+
<ProxyRequirements/>
60+
<ProxyLimitations/>
61+
</td>
62+
</tr>
63+
<tr>
64+
<td>`--local-artifact-mirror-port`</td>
65+
<td>
66+
<p>Port on which to run the Local Artifact Mirror (LAM). **Default**: By default, the LAM runs on port 50000.</p>
67+
</td>
68+
</tr>
69+
<tr>
70+
<td>`--no-proxy`</td>
71+
<td>
72+
<p>Comma-separated list of hosts for which not to use a proxy.</p>
73+
<p>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).</p>
74+
<p>The following are never proxied:</p>
75+
<ul>
76+
<li>Internal cluster communication (`localhost`, `127.0.0.1`, `.cluster.local`, `.svc`)</li>
77+
<li>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).</li>
78+
</ul>
79+
<p>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`.</p>
80+
<ProxyRequirements/>
81+
<ProxyLimitations/>
82+
</td>
83+
</tr>
84+
<tr>
85+
<td>`--pod-cidr`</td>
86+
<td>
87+
<p>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`.</p>
88+
<p>**Limitation:** The `--pod-cidr` flag is not supported on Red Hat Enterprise Linux (RHEL) 9 operating systems.</p>
89+
</td>
90+
</tr>
91+
<tr>
92+
<td>`--service-cidr`</td>
93+
<td>
94+
<p>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`.</p>
95+
<p>**Limitation:** The `--service-cidr` flags is not supported on Red Hat Enterprise Linux (RHEL) 9 operating systems.</p>
96+
</td>
97+
</tr>
98+
</table>
99+
100+
## Examples
101+
102+
### Air Gap Install
103+
104+
```bash
105+
sudo ./myapp install --license license.yaml --airgap-bundle myapp.airgap
106+
```
107+
108+
### Change the Admin Console and LAM Ports
109+
110+
```bash
111+
sudo ./myapp install --admin-console-port=20000 --local-artifact-mirror-port=40000
112+
```
113+
114+
### Change the Data Directory
115+
116+
```bash
117+
sudo ./my-app install --license license.yaml --data-dir /data/embedded-cluster
118+
```
119+
120+
### Install Behind a Proxy
121+
122+
```bash
123+
sudo ./APP_SLUG install --license LICENSE_FILE \
124+
--http-proxy=HOST:PORT \
125+
--https-proxy=HOST:PORT \
126+
--no-proxy=LIST_OF_HOSTS
127+
```
128+
Where:
129+
130+
* `HOST:PORT` is the host and port of the proxy server
131+
* `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.
132+
133+
### Set IP Address Range for Pods
134+
135+
```bash
136+
sudo ./my-app install --license license.yaml --pod-cidr 172.16.136.0/16
137+
```

‎sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -348,6 +348,7 @@ const sidebars = {
348348
items: [
349349
'enterprise/installing-embedded',
350350
'enterprise/installing-embedded-air-gap',
351+
'reference/embedded-cluster-install',
351352
],
352353
},
353354
{

0 commit comments

Comments
 (0)