Skip to content

add embedded cluster cli docs reference #3429

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Aug 8, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/enterprise/installing-embedded-air-gap.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ To install with Embedded Cluster in an air gap environment:
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).
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 [install](/reference/embedded-cluster-install).
:::

1. When prompted, enter a password for accessing the KOTS Admin Console.
Expand Down
2 changes: 1 addition & 1 deletion docs/enterprise/installing-embedded.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ To install an application with Embedded Cluster:
* `LICENSE_FILE` is the customer license.
<br/>
:::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).
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 [install](/reference/embedded-cluster-install).
:::

1. When prompted, enter a password for accessing the KOTS Admin Console.
Expand Down
4 changes: 2 additions & 2 deletions docs/partials/embedded-cluster/_port-reqs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,10 +34,10 @@ The KOTS Admin Console requires that port 30000/TCP is open and available. Creat

Additionally, port 30000 must be accessible by nodes joining the cluster.

If port 30000 is occupied, you can select a different port for the Admin Console during installation. For more information, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install).
If port 30000 is occupied, you can select a different port for the Admin Console during installation. For more information, see [install](/reference/embedded-cluster-install).

#### LAM Port

The Local Artifact Mirror (LAM) requires that port 50000/TCP is open and available.

If port 50000 is occupied, you can select a different port for the LAM during installation. For more information, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install).
If port 50000 is occupied, you can select a different port for the LAM during installation. For more information, see [install](/reference/embedded-cluster-install).
2 changes: 1 addition & 1 deletion docs/partials/embedded-cluster/_requirements.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

* The disk on the host must have a maximum P99 write latency of 10 ms. This supports etcd performance and stability. For more information about the disk write latency requirements for etcd, see [Disks](https://etcd.io/docs/latest/op-guide/hardware/#disks) in _Hardware recommendations_ and [What does the etcd warning “failed to send out heartbeat on time” mean?](https://etcd.io/docs/latest/faq/) in the etcd documentation.

* The data directory used by Embedded Cluster must have 40Gi or more of total space and be less than 80% full. By default, the data directory is `/var/lib/embedded-cluster`. The directory can be changed by passing the `--data-dir` flag with the Embedded Cluster `install` command. For more information, see [Embedded Cluster Install Command Options](/reference/embedded-cluster-install).
* The data directory used by Embedded Cluster must have 40Gi or more of total space and be less than 80% full. By default, the data directory is `/var/lib/embedded-cluster`. The directory can be changed by passing the `--data-dir` flag with the Embedded Cluster `install` command. For more information, see [install](/reference/embedded-cluster-install).

Note that in addition to the primary data directory, Embedded Cluster creates directories and files in the following locations:

Expand Down
41 changes: 41 additions & 0 deletions docs/reference/embedded-cluster-admin-console.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# admin-console

This topic describes the options available with the Embedded Cluster `admin-console` command.

## Usage

```bash
sudo ./<app-slug> admin-console reset-password [flags]
```

## Subcommands

<table>
<tr>
<th width="35%">Command</th>
<th width="65%">Description</th>
</tr>
<tr>
<td>reset-password</td>
<td>
<p>Reset the Admin Console password. If no password is provided, you will be prompted to enter a new one.</p>
</td>
</tr>
</table>

## Flags

<table>
<tr>
<th width="30%">Flag</th>
<th width="20%">Type</th>
<th width="50%">Description</th>
</tr>
<tr>
<td>`-h, --help`</td>
<td></td>
<td>
<p>help for reset-password</p>
</td>
</tr>
</table>
60 changes: 60 additions & 0 deletions docs/reference/embedded-cluster-completion.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# completion

This topic describes the options available with the Embedded Cluster `completion` command.

## Usage

```bash
sudo ./<app-slug> completion [command]
```

## Subcommands

<table>
<tr>
<th width="35%">Command</th>
<th width="65%">Description</th>
</tr>
<tr>
<td>bash</td>
<td>
<p>Generate the autocompletion script for bash</p>
</td>
</tr>
<tr>
<td>fish</td>
<td>
<p>Generate the autocompletion script for fish</p>
</td>
</tr>
<tr>
<td>powershell</td>
<td>
<p>Generate the autocompletion script for powershell</p>
</td>
</tr>
<tr>
<td>zsh</td>
<td>
<p>Generate the autocompletion script for zsh</p>
</td>
</tr>
</table>

## Flags

<table>
<tr>
<th width="30%">Flag</th>
<th width="20%">Type</th>
<th width="50%">Description</th>
</tr>
<tr>
<td>`-h, --help`</td>
<td></td>
<td>
<p>help for completion</p>
</td>
</tr>
</table>

26 changes: 26 additions & 0 deletions docs/reference/embedded-cluster-enable-ha.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# enable-ha

This topic describes the options available with the Embedded Cluster `enable-ha` command.

## Usage

```bash
sudo ./<app-slug> enable-ha [flags]
```

## Flags

<table>
<tr>
<th width="30%">Flag</th>
<th width="20%">Type</th>
<th width="50%">Description</th>
</tr>
<tr>
<td>`-h, --help`</td>
<td></td>
<td>
<p>help for enable-ha</p>
</td>
</tr>
</table>
6 changes: 2 additions & 4 deletions docs/reference/embedded-cluster-install.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,15 @@ import ProxyRequirements from "../partials/embedded-cluster/_proxy-install-reqs.
import ProxyEnvVars from "../partials/embedded-cluster/_proxy-env-vars.mdx"
import DeprecatedPrivateCa from "../partials/embedded-cluster/_deprecated-private-ca.mdx"

# Embedded Cluster Install Command Options
# 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](/enterprise/installing-embedded) or [Air Gap Installation with Embedded Cluster](/enterprise/installing-embedded).

## Usage

```bash
sudo ./APP_SLUG install --license PATH_TO_LICENSE [flags]
sudo ./<app-slug> install --license <path-to-license> [flags]
```
* `APP_SLUG` is the unique application slug
* `PATH_TO_LICENSE` is the path to the customer license

## Flags

Expand Down
27 changes: 27 additions & 0 deletions docs/reference/embedded-cluster-join-print-command.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# join print-command

This topic describes the options available with the Embedded Cluster `join print-command` command. For more information about joining nodes, see [Manage Multi-Node Clusters with Embedded Cluster](/enterprise/embedded-manage-nodes).

## Usage

```bash
sudo ./<app-slug> join print-command [flags]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is a subcommand of join, so given the pattern elsewhere, this shouldn't be its own page but should be listed as a subcommand of join.

but then note that if we go that route, join is itself a command but it has subcommands. so it's not like admin-console where the top-level command does nothing and you need to provide a subcommand.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, I was thinking print-command might benefit from its own page since it has it's own use case (which does break the pattern).

I think if we do want to stick to the pattern and nest it under join, it'll still be fine since it can be described as a subcommand. However, if it has unique flags or something that you'd rather keep separate so as to not introduce confusion, we can leave it as its own page

```

## Flags

<table>
<tr>
<th width="30%">Flag</th>
<th width="20%">Type</th>
<th width="50%">Description</th>
</tr>
<tr>
<td>`-h, --help`</td>
<td></td>
<td>
<p>help for print-command</p>
</td>
</tr>
</table>

86 changes: 86 additions & 0 deletions docs/reference/embedded-cluster-join.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# join

This topic describes the options available with the Embedded Cluster `join` command. For more information about joining nodes, see [Manage Multi-Node Clusters with Embedded Cluster](/enterprise/embedded-manage-nodes).

## Usage

```bash
sudo ./<app-slug> join <url> <token> [flags]
```

```bash
sudo ./<app-slug> join [command]
```

## Subcommands

<table>
<tr>
<th width="35%">Command</th>
<th width="65%">Description</th>
</tr>
<tr>
<td>run-preflights</td>
<td>
<p>Run join host preflights for the application.</p>
</td>
</tr>
</table>

## Flags

<table>
<tr>
<th width="30%">Flag</th>
<th width="20%">Description</th>
<th width="50%">Description</th>
</tr>
<tr>
<td>`--airgap-bundle`</td>
<td>string</td>
<td>
<p>Path to the air gap bundle. If set, the installation will complete without internet access.</p>
</td>
</tr>
<tr>
<td>`-h, --help`</td>
<td></td>
<td>
<p>help for join</p>
</td>
</tr>
<tr>
<td>`--ignore-host-preflights`</td>
<td></td>
<td>
<p>Run host preflight checks, but prompt the user to continue if they fail instead of exiting.</p>
</td>
</tr>
<tr>
<td>`--network-interface`</td>
<td>string</td>
<td>
<p>The network interface to use for the cluster.</p>
</td>
</tr>
<tr>
<td>`--no-ha`</td>
<td></td>
<td>
<p>Do not prompt for or enable high availability.</p>
</td>
</tr>
<tr>
<td>`-y, --yes`</td>
<td></td>
<td>
<p>Assume yes to all prompts.</p>
</td>
</tr>
</table>

## Examples

```bash
sudo ./slackernews join 10.128.0.55:30000 dCH2tsK9xvucAIbME0RBs7z7
```
41 changes: 41 additions & 0 deletions docs/reference/embedded-cluster-reset.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# reset

This topic describes the options available with the Embedded Cluster `reset` command.

## Usage

```bash
sudo ./<app-slug> reset [flags]
```

## Flags

<table>
<tr>
<th width="30%">Flag</th>
<th width="20%">Type</th>
<th width="50%">Description</th>
</tr>
<tr>
<td>`--force`</td>
<td></td>
<td>
<p>Ignore errors encountered when resetting the node (implies --yes)</p>
</td>
</tr>
<tr>
<td>`-h, --help`</td>
<td></td>
<td>
<p>help for reset</p>
</td>
</tr>
<tr>
<td>`-y, --yes`</td>
<td></td>
<td>
<p>Assume yes to all prompts.</p>
</td>
</tr>
</table>

Loading