Skip to content

Commit 917da85

Browse files
paigecalvertpaigecalvert
committed
Embedded Cluster task-oriented topics
1 parent 2f9f50b commit 917da85

File tree

6 files changed

+155
-133
lines changed

6 files changed

+155
-133
lines changed

‎docs/vendor/embedded-access-cluster.mdx‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Accessing Embedded Clusters
2+
3+
This topic describes how to access the cluster provisioned by Embedded Cluster using kubectl.
4+
5+
## Overview
6+
7+
With Embedded Cluster, end-users are rarely supposed to need to use the CLI. Typical workflows, like updating the application and the cluster, are driven through the Admin Console.
8+
9+
Nonetheless, there are times when vendors or their customers need to use the CLI for development or troubleshooting.
10+
11+
## Access the Cluster
12+
13+
To access the cluster and use other included binaries:
14+
15+
1. SSH onto a controller node.
16+
17+
1. Use the Embedded Cluster shell command to start a shell with access to the cluster:
18+
19+
```
20+
sudo ./APP_SLUG shell
21+
```
22+
23+
The output looks similar to the following:
24+
```
25+
__4___
26+
_ \ \ \ \ Welcome to APP_SLUG debug shell.
27+
<'\ /_/_/_/ This terminal is now configured to access your cluster.
28+
((____!___/) Type 'exit' (or CTRL+d) to exit.
29+
\0\0\0\0\/ Happy hacking.
30+
~~~~~~~~~~~
31+
root@alex-ec-2:/home/alex# export KUBECONFIG="/var/lib/embedded-cluster/k0s/pki/admin.conf"
32+
root@alex-ec-2:/home/alex# export PATH="$PATH:/var/lib/embedded-cluster/bin"
33+
root@alex-ec-2:/home/alex# source <(kubectl completion bash)
34+
root@alex-ec-2:/home/alex# source /etc/bash_completion
35+
```
36+
37+
The appropriate kubeconfig is exported, and the location of useful binaries like kubectl and Replicated’s preflight and support-bundle plugins is added to PATH.
38+
39+
:::note
40+
You cannot run the `shell` command on worker nodes.
41+
:::
42+
43+
1. Use the available binaries as needed.
44+
45+
**Example**:
46+
47+
```bash
48+
kubectl version
49+
```
50+
```
51+
Client Version: v1.29.1
52+
Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
53+
Server Version: v1.29.1+k0s
54+
```
55+
56+
1. Type `exit` or **Ctrl + D** to exit the shell.
57+
58+
:::note
59+
If you encounter a typical workflow where your customers have to use the Embedded Cluster shell, reach out to Alex Parker at [email protected]. These workflows might be candidates for additional Admin Console functionality.
60+
:::

‎docs/vendor/embedded-host-preflights.mdx‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# About Embedded Cluster Host Preflight Checks
2+
3+
This topic describes the host preflight checks that run as part of installation with Emebdded Cluster, including information about how to skip host preflights.
4+
5+
## Overview
6+
7+
During installation, Embedded Cluster automatically runs a default set of _host preflight checks_. The default host preflight checks are designed to verify that the installation environment meets the requirements for Embedded Cluster, such as:
8+
* The system has sufficient disk space
9+
* The system has at least 2G of memory and 2 CPU cores
10+
* The system clock is synchronized
11+
12+
For Embedded Cluster requirements, see [Requirements](#requirements). For the full default host preflight spec for Embedded Cluster, see [`host-preflight.yaml`](https://github.com/replicatedhq/embedded-cluster/blob/main/pkg/preflights/host-preflight.yaml) in the `embedded-cluster` repository in GitHub.
13+
14+
If any of the host preflight checks fail, installation is blocked and a message describing the failure is displayed. For more information about host preflight checks for installations on VMs or bare metal servers, see [About Host Preflights](preflight-support-bundle-about#host-preflights).
15+
16+
## Limitations
17+
18+
Embedded Cluster host preflight checks have the following limitations:
19+
20+
* The default host preflight checks for Embedded Cluster cannot be modified, and vendors cannot provide their own custom host preflight spec for Embedded Cluster.
21+
* Host preflight checks do not check that any application-specific requirements are met. For more information about defining preflight checks for your application, see [Defining Preflight Checks](/vendor/preflight-defining).
22+
23+
## Skip Host Preflight Checks
24+
25+
You can skip host preflight checks by passing the `--skip-host-preflights` flag with the Embedded Cluster `install` command. For example:
26+
27+
```bash
28+
sudo ./my-app install --license license.yaml --skip-host-preflights
29+
```
30+
31+
When you skip host preflight checks, the Admin Console still runs any application-specific preflight checks that are defined in the release before the application is deployed.
32+
33+
:::note
34+
Skipping host preflight checks is _not_ recommended for production installations.
35+
:::

‎docs/vendor/embedded-install-assets-api.mdx‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Serve Embedded Cluster Installation Assets Using the Vendor API
2+
3+
This topic describes how to serve the installation assets for Replicated Embedded Cluster using the Vendor API v3.
4+
5+
## Overview
6+
7+
To install with Embedded Cluster, you need to download the Embedded Cluster installer binary and a license. Air gap installations also require an air gap bundle. Some vendors already have a portal where their customers can log in to access documentation or download artifacts. In cases like this, you can serve the Embedded Cluster installation essets yourself using the Replicated Vendor API, rather than having customers download the assets from the Replicated app service using a curl command during installation.
8+
9+
## Serve Assets with the API
10+
11+
To serve Embedded Cluster installation assets with the Vendor API v3:
12+
13+
1. If you have not done so already, create an API token for the Vendor API. See [Using the Vendor API v3](/reference/vendor-api-using#api-token-requirement).
14+
15+
1. Call the [Get an Embedded Cluster release](https://replicated-vendor-api.readme.io/reference/getembeddedclusterrelease) endpoint to download the assets needed to install your application with Embedded Cluster. Your customers must take this binary and their license and copy them to the machine where they will install your application.
16+
17+
Note the following:
18+
19+
* (Recommended) Provide the `customerId` query parameter so that the customer’s license is included in the downloaded tarball. This mirrors what is returned when a customer downloads the binary directly using the Replicated app service and is the most useful option. Excluding the `customerId` is useful if you plan to distribute the license separately.
20+
21+
* If you do not provide any query parameters, this endpoint downloads the Embedded Cluster binary for the latest release on the specified channel. You can provide the `channelSequence` query parameter to download the binary for a particular release.

‎docs/vendor/embedded-overview.mdx‎

Lines changed: 7 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import EmbeddedClusterSupportBundle from "../partials/support-bundles/_generate-
77
import EcConfig from "../partials/embedded-cluster/_ec-config.mdx"
88
import EmbeddedClusterPortRequirements from "../partials/embedded-cluster/_port-reqs.mdx"
99

10-
# Using Embedded Cluster
10+
# Overview of Embedded Cluster
1111

1212
This topic describes how to use the Replicated Embedded Cluster to configure, install, and manage your application in an embedded Kubernetes cluster.
1313

@@ -79,11 +79,11 @@ Embedded Cluster has the following limitations:
7979

8080
## Quick Start
8181

82-
You can use the following steps to get started quickly with Embedded Cluster. More detailed documentation is available below.
82+
If you already have a release for your application in the Vendor Portal that supports installation with Replicated KOTS, you can use the following steps to get started quickly with Embedded Cluster:
8383

8484
1. Create a new customer or edit an existing customer and select the **Embedded Cluster Enabled** license option. Save the customer.
8585

86-
1. Create a new release that includes your application. In that release, create an Embedded Cluster Config that includes, at minimum, the Embedded Cluster version you want to use. See the Embedded Cluster [GitHub repo](https://github.com/replicatedhq/embedded-cluster/releases) to find the latest version.
86+
1. Create a new release that includes your application as well as the KOTS custom resources. In that release, create an Embedded Cluster Config that includes, at minimum, the Embedded Cluster version you want to use. See the Embedded Cluster [GitHub repo](https://github.com/replicatedhq/embedded-cluster/releases) to find the latest version.
8787

8888
Example Embedded Cluster Config:
8989

@@ -135,54 +135,6 @@ To install with Embedded Cluster, you can follow the customer-specific instructi
135135

136136
[View a larger version of this image](/images/embedded-cluster-install-dialog.png)
137137

138-
### (Optional) Serve Installation Assets Using the Vendor API
139-
140-
To install with Embedded Cluster, you need to download the Embedded Cluster installer binary and a license. Air gap installations also require an air gap bundle. Some vendors already have a portal where their customers can log in to access documentation or download artifacts. In cases like this, you can serve the Embedded Cluster installation essets yourself using the Replicated Vendor API, rather than having customers download the assets from the Replicated app service using a curl command during installation.
141-
142-
To serve Embedded Cluster installation assets with the Vendor API:
143-
144-
1. If you have not done so already, create an API token for the Vendor API. See [Using the Vendor API v3](/reference/vendor-api-using#api-token-requirement).
145-
146-
1. Call the [Get an Embedded Cluster release](https://replicated-vendor-api.readme.io/reference/getembeddedclusterrelease) endpoint to download the assets needed to install your application with Embedded Cluster. Your customers must take this binary and their license and copy them to the machine where they will install your application.
147-
148-
Note the following:
149-
150-
* (Recommended) Provide the `customerId` query parameter so that the customer’s license is included in the downloaded tarball. This mirrors what is returned when a customer downloads the binary directly using the Replicated app service and is the most useful option. Excluding the `customerId` is useful if you plan to distribute the license separately.
151-
152-
* If you do not provide any query parameters, this endpoint downloads the Embedded Cluster binary for the latest release on the specified channel. You can provide the `channelSequence` query parameter to download the binary for a particular release.
153-
154-
### About Host Preflight Checks
155-
156-
During installation, Embedded Cluster automatically runs a default set of _host preflight checks_. The default host preflight checks are designed to verify that the installation environment meets the requirements for Embedded Cluster, such as:
157-
* The system has sufficient disk space
158-
* The system has at least 2G of memory and 2 CPU cores
159-
* The system clock is synchronized
160-
161-
For Embedded Cluster requirements, see [Requirements](#requirements). For the full default host preflight spec for Embedded Cluster, see [`host-preflight.yaml`](https://github.com/replicatedhq/embedded-cluster/blob/main/pkg/preflights/host-preflight.yaml) in the `embedded-cluster` repository in GitHub.
162-
163-
If any of the host preflight checks fail, installation is blocked and a message describing the failure is displayed. For more information about host preflight checks for installations on VMs or bare metal servers, see [About Host Preflights](preflight-support-bundle-about#host-preflights).
164-
165-
#### Limitations
166-
167-
Embedded Cluster host preflight checks have the following limitations:
168-
169-
* The default host preflight checks for Embedded Cluster cannot be modified, and vendors cannot provide their own custom host preflight spec for Embedded Cluster.
170-
* Host preflight checks do not check that any application-specific requirements are met. For more information about defining preflight checks for your application, see [Defining Preflight Checks](/vendor/preflight-defining).
171-
172-
#### Skip Host Preflight Checks
173-
174-
You can skip host preflight checks by passing the `--skip-host-preflights` flag with the Embedded Cluster `install` command. For example:
175-
176-
```bash
177-
sudo ./my-app install --license license.yaml --skip-host-preflights
178-
```
179-
180-
When you skip host preflight checks, the Admin Console still runs any application-specific preflight checks that are defined in the release before the application is deployed.
181-
182-
:::note
183-
Skipping host preflight checks is _not_ recommended for production installations.
184-
:::
185-
186138
## About Managing Multi-Node Clusters with Embedded Cluster
187139

188140
This section describes managing nodes in multi-node clusters created with Embedded Cluster.
@@ -211,83 +163,11 @@ For more information about creating HA multi-node clusters with Embedded Cluster
211163

212164
For more information about updating, see [Performing Updates with Embedded Cluster](/enterprise/updating-embedded).
213165

214-
## Access the Cluster
215-
216-
With Embedded Cluster, end-users are rarely supposed to need to use the CLI. Typical workflows, like updating the application and the cluster, are driven through the Admin Console.
217-
218-
Nonetheless, there are times when vendors or their customers need to use the CLI for development or troubleshooting.
219-
220-
To access the cluster and use other included binaries:
221-
222-
1. SSH onto a controller node.
223-
224-
1. Use the Embedded Cluster shell command to start a shell with access to the cluster:
225-
226-
```
227-
sudo ./APP_SLUG shell
228-
```
229-
230-
The output looks similar to the following:
231-
```
232-
__4___
233-
_ \ \ \ \ Welcome to APP_SLUG debug shell.
234-
<'\ /_/_/_/ This terminal is now configured to access your cluster.
235-
((____!___/) Type 'exit' (or CTRL+d) to exit.
236-
\0\0\0\0\/ Happy hacking.
237-
~~~~~~~~~~~
238-
root@alex-ec-2:/home/alex# export KUBECONFIG="/var/lib/embedded-cluster/k0s/pki/admin.conf"
239-
root@alex-ec-2:/home/alex# export PATH="$PATH:/var/lib/embedded-cluster/bin"
240-
root@alex-ec-2:/home/alex# source <(kubectl completion bash)
241-
root@alex-ec-2:/home/alex# source /etc/bash_completion
242-
```
243-
244-
The appropriate kubeconfig is exported, and the location of useful binaries like kubectl and Replicated’s preflight and support-bundle plugins is added to PATH.
245-
246-
:::note
247-
You cannot run the `shell` command on worker nodes.
248-
:::
249-
250-
1. Use the available binaries as needed.
251-
252-
**Example**:
253-
254-
```bash
255-
kubectl version
256-
```
257-
```
258-
Client Version: v1.29.1
259-
Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
260-
Server Version: v1.29.1+k0s
261-
```
262-
263-
1. Type `exit` or **Ctrl + D** to exit the shell.
264-
265-
:::note
266-
If you encounter a typical workflow where your customers have to use the Embedded Cluster shell, reach out to Alex Parker at [email protected]. These workflows might be candidates for additional Admin Console functionality.
267-
:::
268-
269-
## Reset a Node
270-
271-
Resetting a node removes the cluster and your application from that node. This is useful for iteration, development, and when mistakes are made, so you can reset a machine and reuse it instead of having to procure another machine.
272-
273-
If you want to completely remove a cluster, you need to reset each node individually.
274-
275-
When resetting a node, OpenEBS PVCs on the node are deleted. Only PVCs created as part of a StatefulSet will be recreated automatically on another node. To recreate other PVCs, the application will need to be redeployed.
276-
277-
To reset a node:
278-
279-
1. SSH onto the machine. Ensure that the Embedded Cluster binary is still available on that machine.
280-
281-
1. Run the following command to reset the node and automatically reboot the machine to ensure that transient configuration is also reset:
166+
## Troubleshoot with Support Bundles
282167

283-
```
284-
sudo ./APP_SLUG reset
285-
```
286-
Where `APP_SLUG` is the unique slug for the application.
168+
<SupportBundleIntro/>
287169

288-
:::note
289-
Pass the `--no-prompt` flag to disable interactive prompts. Pass the `--force` flag to ignore any errors encountered during the reset.
290-
:::
170+
<EmbeddedClusterSupportBundle/>
291171

292172
## Additional Use Cases
293173

@@ -306,10 +186,4 @@ toolkit:
306186
value: /etc/k0s/containerd.d/nvidia.toml
307187
- name: CONTAINERD_SOCKET
308188
value: /run/k0s/containerd.sock
309-
```
310-
311-
## Troubleshoot with Support Bundles
312-
313-
<SupportBundleIntro/>
314-
315-
<EmbeddedClusterSupportBundle/>
189+
```

‎docs/vendor/embedded-reset.mdx‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Resetting a Node
2+
3+
This topic describes how to use the Embedded Cluster `reset` command to reset a node.
4+
5+
## Overview
6+
7+
Resetting a node removes the cluster and your application from that node. This is useful for iteration, development, and when mistakes are made, so you can reset a machine and reuse it instead of having to procure another machine.
8+
9+
If you want to completely remove a cluster, you need to reset each node individually.
10+
11+
When resetting a node, OpenEBS PVCs on the node are deleted. Only PVCs created as part of a StatefulSet will be recreated automatically on another node. To recreate other PVCs, the application will need to be redeployed.
12+
13+
## Reset a Node
14+
15+
To reset a node:
16+
17+
1. SSH onto the machine. Ensure that the Embedded Cluster binary is still available on that machine.
18+
19+
1. Run the following command to reset the node and automatically reboot the machine to ensure that transient configuration is also reset:
20+
21+
```
22+
sudo ./APP_SLUG reset
23+
```
24+
Where `APP_SLUG` is the unique slug for the application.
25+
26+
:::note
27+
Pass the `--no-prompt` flag to disable interactive prompts. Pass the `--force` flag to ignore any errors encountered during the reset.
28+
:::

‎sidebars.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -238,11 +238,15 @@ const sidebars = {
238238
'enterprise/installing-embedded-air-gap',
239239
'enterprise/installing-embedded-automation',
240240
'reference/embedded-cluster-install',
241+
'vendor/embedded-install-assets-api',
241242
],
242243
},
243244
'enterprise/embedded-manage-nodes',
244245
'enterprise/updating-embedded',
246+
'vendor/embedded-access-cluster',
245247
'vendor/embedded-disaster-recovery',
248+
'vendor/embedded-host-preflights',
249+
'vendor/embedded-reset',
246250
],
247251
},
248252
{

0 commit comments

Comments
 (0)