Skip to content

Add limitation about the first controller node #3485

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.

Sign up for GitHub

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 1 commit into from
Aug 27, 2025
Merged

Add limitation about the first controller node #3485

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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: 2 additions & 0 deletions docs/enterprise/embedded-manage-nodes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ Multi-node clusters with Embedded Cluster have the following limitations:

* Setting node roles with the Embedded Cluster Config [roles](/reference/embedded-config#roles-beta) key is Beta.

* The first node added to the cluster is always a controller and cannot be assigned any custom roles. For more information about configuring node roles, see [roles](/reference/embedded-config#roles-beta) in _Embedded Cluster Config_.

Copy link
Contributor Author

@paigecalvert paigecalvert Aug 27, 2025

Choose a reason for hiding this comment

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

^ this is in the "Manage Multi-Node Clusters" topic, which explains how to join nodes during/after install in the Admin Console/cli

* The same Embedded Cluster data directory used at installation is used for all nodes joined to the cluster. This is either the default `/var/lib/embedded-cluster` directory or the directory set with the [`--data-dir`](/reference/embedded-cluster-install#flags) flag. You cannot choose a different data directory for Embedded Cluster when joining nodes.

* More than one controller node should not be joined at the same time. When joining a controller node, a warning is printed that explains that the user should not attempt to join another node until the controller node joins successfully.
Expand Down
14 changes: 8 additions & 6 deletions docs/reference/embedded-config.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,11 @@ To install your application with Embedded Cluster, an Embedded Cluster Config mu

The Embedded Cluster Config lets you define several aspects of the Kubernetes cluster that will be created.

### Limitation
### Limitations
Copy link
Contributor Author

@paigecalvert paigecalvert Aug 27, 2025

Choose a reason for hiding this comment

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

^ main limitations section of the Embedded Cluster Config reference. Making it clearer that there are additional limitations specific to the individual properties in the config


* The Embedded Cluster Config does not support the use of Go template functions, including [KOTS template functions](/reference/template-functions-about).

For additional property-specific limitations, see the sections below.
* There are additional, property-specific limitations. For more information, see the sections below.

### Example

Expand Down Expand Up @@ -79,10 +79,6 @@ For a full list of versions, see the [Embedded Cluster Release Notes](/release-n

## roles (Beta)

:::note
Support for setting node roles is Beta.
:::

You can optionally customize node roles in the Embedded Cluster Config using the `roles` key.

A common use case for customizing node roles is to assign workloads to specific nodes. For example, if your application has graphics processing unit (GPU) workloads, you could create a `custom` role that will add a `gpu=true` label to any node that is assigned the role. This allows you to then schedule GPU workloads on nodes labled `gpu=true`.
Expand Down Expand Up @@ -113,6 +109,12 @@ spec:
gpu: "true" # Label applied to "gpu" nodes
```

### Limitations

* Defining node roles with the `roles` key is Beta.

* The first node added to the cluster is always a controller and cannot be assigned any custom roles. You can add custom labels to the first node by setting the `labels` field in the `roles.controller` key.

Copy link
Contributor Author

@paigecalvert paigecalvert Aug 27, 2025

Choose a reason for hiding this comment

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

^ added these limitations to the roles key description in Embedded Cluster Config reference topic

Added a sentence about how you can still add labels by setting the roles.controller.labels key (not sure if this is helpful or not)

### roles.controller

In the `roles.controller` key, you can set the following fields to customize the default controller role:
Expand Down
Loading