Skip to main content

Persistent admin console (Beta)

This topic describes the persistent admin console for Embedded Cluster 3.x — an optional, always-on web UI for browser-driven upgrades and operations.

Overview​

The persistent admin console is an opt-in web service that runs on a controller node and exposes a dashboard at https://<controller-hostname>:30080/console. From the dashboard, end users can:

  • View the currently installed application version and open configured application links
  • Check application status
  • See available updates, view release notes, and trigger an upgrade with a single click
  • Upload air gap release archives directly through the browser (no SSH required)
  • Generate a support bundle and download it for sharing with the vendor's support team
  • View node status, generate commands to add nodes, and remove nodes from the cluster

All of this works without SSH access to the controller.

The persistent admin console is not enabled by default. To enable it, run console install on a controller node after the application is installed. See Install the console below.

The initial application install and console setup require command-line access to a controller node. Once the console is running, end users can perform upgrades and configuration changes from the browser without command-line access.

note

For automated deployments (such as cloud marketplace offerings using cloud-init or user-data scripts), include console install in your provisioning script after the initial install completes. This gives end users browser-based access from first boot without any manual setup.

What enabling the console adds​

Installing and upgrading already happen in a browser. The installer serves a wizard that handles configuration, preflight checks, and the install or upgrade run itself, so an end user does not need a terminal for those steps. What the wizard does not do is stay available afterwards, because it belongs to an install or upgrade that someone started with a command on the host.

Enabling the persistent admin console adds a dashboard that is always there. From it, an end user can:

  • Check the installed version and channel, and open application links
  • Check application status
  • See available updates and read release notes
  • Upload an air gap release archive
  • Generate a support bundle and download it
  • View node roles and readiness, generate commands to add nodes, and remove nodes
  • Start an upgrade, or change configuration values at the current version with Redeploy

Upgrades and configuration changes started from the console hand off to the same wizard, so the console does not duplicate it. The practical difference is that nobody has to be at a terminal to begin.

The console does not provide Kubernetes operations. There is no way to inspect or delete Pods, read container logs, or view Secrets from it, so those need command-line access to a node through shell.

If your end users need cluster-level visibility without command-line access, package a tool that provides it as a Helm chart extension in your application. See Add Helm chart extensions.

Install the console​

Once the application is installed and running, install the persistent admin console on a controller node. The console serves its web UI from that controller's hostname.

  1. On a controller node, run the install command:

    sudo ./<app-slug> console install

    Replace <app-slug> with your application slug.

  2. (Optional) Use the --port flag to override the default port (30080):

    sudo ./<app-slug> console install --port 30443

  3. Verify the service is running:

    sudo systemctl is-active <app-slug>-console-web.service

    The output should be active.

  4. Open the console in your browser at https://<controller-hostname>:30080/console.

For the full set of flags, see console.

Choose a controller​

The console can be installed on any controller node in the cluster. Replicated recommends running it on the primary controller — the first controller node installed in the cluster — because that node is typically the one users already access for cluster operations.

If your release includes an app.k8s.io/v1beta1 Application resource with spec.descriptor.links, those links appear automatically on the console dashboard under Open <app-name>. No additional configuration is needed.

note

If you are upgrading from Embedded Cluster v2, any existing Application links carry over automatically.

Application status​

The dashboard shows the application status that the Replicated SDK reports, along with the components that are not ready. The status displays only when the release includes the SDK. For how the status is calculated and how to control which resources are reported, see Enable and understand application status.

Support bundles​

The console dashboard includes a Generate support bundle button that creates a support bundle directly on the host. Because the console runs as a systemd service on the host (not as a pod in the cluster), support bundle generation works even when the cluster is unhealthy or down.

The generated bundle is stored in the Embedded Cluster data directory. Ensure the filesystem hosting the data directory has sufficient free space for bundle generation. The data directory is also used for application images and persistent volume data, so large bundles on a constrained filesystem could impact available disk space.

After generation, the bundle can be downloaded from the console for sharing with the vendor's support team, or uploaded directly to the Vendor Portal from the console. See Upload to the vendor portal below.

Upload to the vendor portal (Beta)​

The console dashboard includes a Share button that sends a generated support bundle directly to the Vendor Portal, eliminating the need to download and share the bundle manually. After upload, the bundle is immediately available under the Troubleshoot tab in the Vendor Portal team account associated with the customer.

The Share button appears in the console only when all of the following are true:

  • The customer's license has Support Bundle Upload Enabled (Beta) turned on. For instructions, see Enable support bundle uploads.
  • The installation is online. The button does not appear in air gap installations.
  • The application includes the Replicated SDK version 1.17.0 or later as a chart dependency, and the SDK pod is running and reachable in the cluster. The console uploads bundles through the in-cluster SDK service, which exposes the upload endpoint starting in 1.17.0. If the SDK pod is unhealthy or unreachable, the Share button is hidden until the SDK becomes available again.

If any of these requirements are not met, the Share button is hidden and the bundle can still be downloaded from the console for manual sharing.

Manage nodes​

The Nodes page shows hosts, roles, and readiness. To add a node, select Add node and follow the instructions. Adding nodes requires a license with multi-node support enabled. For more information about applying license changes, see Refresh the license in Access and manage embedded clusters.

You can remove all non-controller nodes and all but one controller host. To remove a node:

  1. Select Delete for the host.
  2. Review the warnings. If required, select Force removal to acknowledge the risks of bypassing safety checks.
  3. Select Delete node.

Only one removal can run at a time. While removal is pending, you can select Cancel removal. If dispatch fails, use Retry dispatch to {controller} when available. If the controller executing the removal is permanently lost, contact Replicated support.

Before joining a removed node back into the cluster, run reset on that node. For more information about resetting a node, see Reset a machine in Access and manage embedded clusters.

For more information about adding nodes, see Configure multi-node clusters in Access and manage embedded clusters. For more information about removing nodes, see Remove nodes and reset machines in Access and manage embedded clusters.

Recover or move the console​

The console is hosted by a single controller. If the controller hosting the console is lost or the <app-slug>-console-web.service becomes unhealthy, rerun the install command on any controller node to bring it back up:

sudo ./<app-slug> console install

If the original controller is still healthy and you are recovering an unhealthy service, run the command on the original controller. If the original controller is lost, run the command on any other controller node. The console is stateless — the dashboard reads live data from the daemon, so moving it to a different controller is safe at any time.

Uninstall the console​

To uninstall the console from a controller:

sudo ./<app-slug> console uninstall

This stops and removes the <app-slug>-console-web.service systemd unit and frees the port. The cluster is not otherwise affected — the application continues running, and users can still upgrade with the upgrade command from the CLI. See Perform updates in embedded clusters.

Limitations​

The persistent admin console has the following limitations:

  • The console can only be installed on a single controller node at a time. Reinstall on a different controller to move it.

  • The console must be installed on a controller node; it cannot run on a worker node.

  • Running join commands, resetting a removed host, removing the last controller, and enabling HA for an existing air gap installation require command-line access. For more information about these operations, see Access and manage embedded clusters.

  • The cluster must have TLS configured at install time. The console reuses the cluster's TLS certificate to serve HTTPS on its port.

On this page