Skip to content

Commit 41fc03b

Browse files
paigecalvertpaigecalvert
authored
Merge branch 'main' into ec-requirements-update
2 parents 49c8261 + 8ee5861 commit 41fc03b

File tree

60 files changed

+1206
-686
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

60 files changed

+1206
-686
lines changed

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

Lines changed: 95 additions & 54 deletions
Large diffs are not rendered by default.

‎docs/enterprise/installing-embedded.mdx‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
import Prerequisites from "../partials/install/_ec-prereqs.mdx"
2+
3+
# Online Installation with Embedded Cluster (Beta)
4+
5+
This topic describes how to install an application in an online (internet-connected) environment with the Replicated Embedded Cluster installer. For information about air gap installations with Embedded Cluster, see [Air Gap Installation with Embedded Cluster (Beta)](/enterprise/installing-embedded-air-gap).
6+
7+
## Prerequisites
8+
9+
Before you install, complete the following prerequisites:
10+
11+
<Prerequisites/>
12+
13+
## Install
14+
15+
To install an application with Embedded Cluster:
16+
17+
1. In the [Vendor Portal](https://vendor.replicated.com), go to **Customers** and click on the target customer. Click **Install instructions > Embedded Cluster**.
18+
19+
![Customer install instructions drop down button](/images/customer-install-instructions-dropdown.png)
20+
21+
[View a larger version of this image](/images/customer-install-instructions-dropdown.png)
22+
23+
The **Embedded Cluster install instructions** dialog is displayed.
24+
25+
<img alt="Embedded cluster install instruction dialog" src="/images/embedded-cluster-install-dialog.png" width="500px"/>
26+
27+
[View a larger version of this image](/images/embedded-cluster-install-dialog.png)
28+
29+
1. (Optional) In the **Embedded Cluster install instructions** dialog, under **Select a version**, select a specific application version to install. By default, the latest version is selected.
30+
31+
1. SSH onto the machine where you will install.
32+
33+
1. Run the first command in the **Embedded Cluster install instructions** dialog to download the installation assets as a `.tgz`.
34+
35+
1. Run the second command to extract the `.tgz`. The will produce the following files:
36+
37+
* The installer
38+
* The license
39+
40+
1. Run the third command to install the release:
41+
42+
```bash
43+
sudo ./APP_SLUG install --license LICENSE_FILE
44+
```
45+
Where:
46+
* `APP_SLUG` is the unique slug for the application.
47+
* `LICENSE_FILE` is the customer license.
48+
49+
1. When prompted, enter a password for accessing the KOTS Admin Console.
50+
51+
The installation command takes a few minutes to complete. During installation, Embedded Cluster completes tasks to prepare the cluster and install KOTS in the cluster. Embedded Cluster also automatically runs a default set of [_host preflight checks_](/vendor/embedded-overview#about-host-preflight-checks) which verify that the environment meets the requirements for the installer.
52+
53+
1. When the installation command completes, go to the URL provided in the output to access the Admin Console.
54+
55+
**Example output:**
56+
57+
```bash
58+
✔ Host files materialized
59+
? Enter an Admin Console password: ********
60+
? Confirm password: ********
61+
✔ Host files materialized!
62+
✔ Host preflights succeeded!
63+
✔ Node installation finished!
64+
✔ Storage is ready!
65+
✔ Embedded Cluster Operator is ready!
66+
✔ Admin Console is ready!
67+
✔ Additional components are ready!
68+
Visit the admin console to configure and install gitea-kite: http://104.155.145.60:30000
69+
```
70+
At this point, the cluster is provisioned and the KOTS Admin Console is deployed, but the application is not yet installed.
71+
72+
1. Bypass the browser TLS warning by clicking **Continue to Setup**.
73+
74+
1. Click **Advanced > Proceed**.
75+
76+
1. On the HTTPS page, upload your own private key and certificacte or select **Self-signed**.
77+
78+
By default, a self-signed TLS certificate is used to secure communication between your browser and the Admin Console. You will see a warning in your browser every time you access the Admin Console unless you upload your own certificate.
79+
80+
1. On the login page, enter the Admin Console password that you created during installation and click **Log in**.
81+
82+
1. On the **Nodes** page, you can view details about the VM where you installed, including its node role, status, CPU, and memory. Optionally, add nodes before deploying the application. Click **Continue**.
83+
84+
1. On the config screen, complete the fields for the application configuration options and then click **Continue**.
85+
86+
1. On the **Preflight checks** page, the application-specific preflight checks run automatically. Preflight checks are conformance tests that run against the target namespace and cluster to ensure that the environment meets the minimum requirements to support the application. Click **Deploy**.
87+
88+
:::note
89+
Replicated recommends that you address any warnings or failures, rather than dismissing them. Preflight checks help ensure that your environment meets the requirements for application deployment.
90+
:::
91+
92+
:::note
93+
If the application does not include preflight checks, next to the target version on the dashboard, click **Deploy** then **Yes, Deploy** to install the application.
94+
:::
95+
96+
The Admin Console dashboard opens.
97+
98+
On the Admin Console dashboard, the application status changes from Missing to Unavailable while the application is being installed. When the installation is complete, the status changes to Ready. For example:
99+
100+
![Admin console dashboard showing ready status](/images/gitea-ec-ready.png)
101+
102+
[View a larger version of this image](/images/gitea-ec-ready.png)
103+
104+
## Install Behind a Proxy Server {#proxy}
105+
106+
The following flags can be used with the Embedded Cluster `install` command to install behind a proxy server:
107+
108+
<table>
109+
<tr>
110+
<th width="35%">Flag</th>
111+
<th width="65%">Description</th>
112+
</tr>
113+
<tr>
114+
<td>`--http-proxy`</td>
115+
<td>Proxy server to use for HTTP</td>
116+
</tr>
117+
<tr>
118+
<td>`--https-proxy`</td>
119+
<td>Proxy server to use for HTTPS</td>
120+
</tr>
121+
<tr>
122+
<td>`--no-proxy`</td>
123+
<td>
124+
<p>Comma-separated list of hosts for which not to use a proxy.</p>
125+
<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>
126+
<p>The following are never proxied:</p>
127+
<ul>
128+
<li>Internal cluster communication (`localhost`, `127.0.0.1`, `.cluster.local`, `.svc`)</li>
129+
<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>
130+
</ul>
131+
<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>
132+
</td>
133+
</tr>
134+
</table>
135+
136+
#### Example
137+
138+
```bash
139+
sudo ./APP_SLUG install --license LICENSE_FILE \
140+
--http-proxy=HOST:PORT \
141+
--https-proxy=HOST:PORT \
142+
--no-proxy=LIST_OF_HOSTS
143+
```
144+
145+
Where:
146+
147+
* `LICENSE_FILE` is the customer's license
148+
* `HOST:PORT` is the host and port of the proxy server
149+
* `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.
150+
151+
#### Requirement
152+
153+
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).
154+
155+
#### Limitations
156+
157+
* 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.
158+
159+
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.
160+
161+
* Proxy settings cannot be changed after installation or during upgrade.
162+
163+
### Set IP Address Ranges for Pods and Services
164+
165+
The following flags can be used with the Embedded Cluster `install` command to allocate IP address ranges for Pods and Services:
166+
167+
<table>
168+
<tr>
169+
<th width="35%">Flag</th>
170+
<th width="65%">Description</th>
171+
</tr>
172+
<tr>
173+
<td>`--pod-cidr`</td>
174+
<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>
175+
</tr>
176+
<tr>
177+
<td>`--service-cidr`</td>
178+
<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>
179+
</tr>
180+
</table>
181+
182+
183+
#### Example
184+
185+
```bash
186+
sudo ./my-app install --license license.yaml --pod-cidr 172.16.136.0/16
187+
```
188+
189+
#### Limitation
190+
191+
The `--pod-cidr` and `--service-cidr` flags are not supported on Red Hat Enterprise Linux (RHEL) 9 operating systems.

‎docs/enterprise/installing-existing-cluster-airgapped.mdx‎

Lines changed: 35 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,10 @@
1-
import AppInstallIntroAirGap from "../partials/install/_install-app-admin-console-intro-air-gap.mdx"
21
import IntroExisting from "../partials/install/_intro-existing.mdx"
3-
import KotsAbout from "../partials/install/_kots-about.mdx"
42
import IntroAirGap from "../partials/install/_intro-air-gap.mdx"
53
import PrereqsExistingCluster from "../partials/install/_prereqs-existing-cluster.mdx"
64
import AirGapBundle from "../partials/install/_airgap-bundle-prereq.mdx"
75
import LicenseFile from "../partials/install/_license-file-prereq.mdx"
86
import DownloadKotsBundle from "../partials/install/_download-kotsadm-bundle.mdx"
97
import InstallCommandPrompts from "../partials/install/_kots-install-prompts.mdx"
10-
import ContinueToInstall from "../partials/install/_continue-to-install-step.mdx"
11-
import InstallApp from "../partials/install/_install-app-admin-console.mdx"
128
import AppNameUI from "../partials/install/_placeholder-app-name-UI.mdx"
139
import InstallKotsCliAirGap from "../partials/install/_install-kots-cli-airgap.mdx"
1410
import PushKotsImages from "../partials/install/_push-kotsadm-images.mdx"
@@ -45,13 +41,9 @@ Complete the following prerequisites:
4541

4642
* <DownloadKotsBundle/>
4743

48-
## Install KOTS {#air-gap}
44+
## Install {#air-gap}
4945

50-
This procedure describes how to install KOTS in your existing cluster using the `kotsadm.tar.gz` air gap bundle.
51-
52-
<KotsAbout/>
53-
54-
To install KOTS:
46+
To install KOTS and an application in an air gap existing cluster:
5547

5648
1. <InstallKotsCliAirGap/>
5749

@@ -75,10 +67,39 @@ To install KOTS:
7567

7668
1. <InstallCommandPrompts/>
7769

78-
1. <ContinueToInstall/>
70+
1. Access the Admin Console on port 8800. If the port forward is active, go to [http://localhost:8800](http://localhost:8800) to access the Admin Console.
71+
72+
If you need to reopen the port forward to the Admin Console, run the following command:
73+
74+
```shell
75+
kubectl kots admin-console -n NAMESPACE
76+
```
77+
Replace `NAMESPACE` with the namespace where KOTS is installed.
78+
79+
1. Log in with the password that you created during installation.
80+
81+
1. Upload your license file.
82+
83+
1. Upload the `.airgap` application air gap bundle.
84+
85+
1. On the config screen, complete the fields for the application configuration options and then click **Continue**.
86+
87+
1. On the **Preflight checks** page, the application-specific preflight checks run automatically. Preflight checks are conformance tests that run against the target namespace and cluster to ensure that the environment meets the minimum requirements to support the application. Click **Deploy**.
88+
89+
:::note
90+
Replicated recommends that you address any warnings or failures, rather than dismissing them. Preflight checks help ensure that your environment meets the requirements for application deployment.
91+
:::
92+
93+
1. (Minimal RBAC Only) If you are installing with minimal role-based access control (RBAC), KOTS recognizes if the preflight checks failed due to insufficient privileges. When this occurs, a kubectl CLI preflight command displays that lets you manually run the preflight checks. The Admin Console then automatically displays the results of the preflight checks. Click **Deploy**.
94+
95+
![kubectl CLI preflight command](/images/kubectl-preflight-command.png)
96+
97+
[View a larger version of this image](/images/kubectl-preflight-command.png)
98+
99+
The Admin Console dashboard opens.
79100

80-
## Install and Deploy the Application {#install-app}
101+
On the Admin Console dashboard, the application status changes from Missing to Unavailable while the Deployment is being created. When the installation is complete, the status changes to Ready. For example:
81102

82-
<AppInstallIntroAirGap/>
103+
![Admin Console dashboard](/images/kotsadm-dashboard-graph.png)
83104

84-
<InstallApp/>
105+
[View a larger version of this image](/images/kotsadm-dashboard-graph.png)

‎docs/enterprise/installing-existing-cluster-automation.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,10 @@ For more information about the advanced options for the `kots install` command,
4343

4444
For a tutorial that demonstrates how to install a sample application using the KOTS CLI, see [KOTS Tutorial (CLI)](/vendor/tutorial-cli-setup).
4545

46+
## Limitation
47+
48+
Replicated Embedded Cluster does not support headless installations with the KOTS CLI.
49+
4650
## Prerequisite
4751

4852
Create a ConfigValues file to define the configuration settings for the application. For air gap environments, ensure that you can access the ConfigValues file that you create from your installation environment.

‎docs/enterprise/installing-existing-cluster.mdx‎

Lines changed: 33 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,8 @@
1-
import AppInstallIntroOnline from "../partials/install/_install-app-admin-console-intro-online.mdx"
21
import IntroExisting from "../partials/install/_intro-existing.mdx"
3-
import KotsAbout from "../partials/install/_kots-about.mdx"
42
import PrereqsExistingCluster from "../partials/install/_prereqs-existing-cluster.mdx"
53
import AirGapBundle from "../partials/install/_airgap-bundle-prereq.mdx"
64
import LicenseFile from "../partials/install/_license-file-prereq.mdx"
75
import InstallCommandPrompts from "../partials/install/_kots-install-prompts.mdx"
8-
import ContinueToInstall from "../partials/install/_continue-to-install-step.mdx"
9-
import InstallApp from "../partials/install/_install-app-admin-console.mdx"
106
import AppNameUI from "../partials/install/_placeholder-app-name-UI.mdx"
117

128
# Online Installation in Existing Clusters
@@ -20,13 +16,9 @@ Complete the following prerequisites:
2016
<PrereqsExistingCluster/>
2117
<LicenseFile/>
2218

23-
## Install KOTS {#online}
19+
## Install {#online}
2420

25-
This procedure describes how to install KOTS in your existing cluster.
26-
27-
<KotsAbout/>
28-
29-
To install KOTS:
21+
To install KOTS and the application in an existing cluster:
3022

3123
1. Run one of these commands to install the Replicated KOTS CLI and KOTS. As part of the command, you also specify a name and version for the application that you will install as part of the [Install and Deploy the Application](#install-app) procedure that follows.
3224

@@ -63,10 +55,37 @@ To install KOTS:
6355

6456
1. <InstallCommandPrompts/>
6557

66-
1. <ContinueToInstall/>
58+
1. Access the Admin Console on port 8800. If the port forward is active, go to [http://localhost:8800](http://localhost:8800) to access the Admin Console.
59+
60+
If you need to reopen the port forward to the Admin Console, run the following command:
61+
62+
```shell
63+
kubectl kots admin-console -n NAMESPACE
64+
```
65+
Replace `NAMESPACE` with the namespace where KOTS is installed.
66+
67+
1. Log in with the password that you created during installation.
68+
69+
1. Upload your license file.
70+
71+
1. On the config screen, complete the fields for the application configuration options and then click **Continue**.
72+
73+
1. On the **Preflight checks** page, the application-specific preflight checks run automatically. Preflight checks are conformance tests that run against the target namespace and cluster to ensure that the environment meets the minimum requirements to support the application. Click **Deploy**.
74+
75+
:::note
76+
Replicated recommends that you address any warnings or failures, rather than dismissing them. Preflight checks help ensure that your environment meets the requirements for application deployment.
77+
:::
78+
79+
1. (Minimal RBAC Only) If you are installing with minimal role-based access control (RBAC), KOTS recognizes if the preflight checks failed due to insufficient privileges. When this occurs, a kubectl CLI preflight command displays that lets you manually run the preflight checks. The Admin Console then automatically displays the results of the preflight checks. Click **Deploy**.
80+
81+
![kubectl CLI preflight command](/images/kubectl-preflight-command.png)
82+
83+
[View a larger version of this image](/images/kubectl-preflight-command.png)
84+
85+
The Admin Console dashboard opens.
6786

68-
## Install and Deploy the Application {#install-app}
87+
On the Admin Console dashboard, the application status changes from Missing to Unavailable while the Deployment is being created. When the installation is complete, the status changes to Ready. For example:
6988

70-
<AppInstallIntroOnline/>
89+
![Admin Console dashboard](/images/kotsadm-dashboard-graph.png)
7190

72-
<InstallApp/>
91+
[View a larger version of this image](/images/kotsadm-dashboard-graph.png)

0 commit comments

Comments
 (0)