Skip to main content

Admin console (Beta)

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

Overview​

The admin console is a dashboard that the Embedded Cluster daemon serves at https://<hostname>:30000/console, where <hostname> is any controller node. If you set a different port with --api-port during installation, use that port instead. 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)
  • Edit configuration values and deploy them
  • 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 node.

The admin console is available automatically after the application is installed. There is nothing to enable. The initial application install requires command-line access to a node. After that, end users can perform upgrades and configuration changes from the browser without command-line access.

note

In Embedded Cluster versions earlier than 3.17.0-beta.1, the admin console is an opt-in service that you install with console install, and it listens on port 30080 by default. When you upgrade to 3.17.0-beta.1 or later, Embedded Cluster removes that service and serves the console from the daemon on the cluster's API port, which is 30000 for clusters that use the default ports. For more information, see Port requirements.

What 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.

The admin console is the dashboard that stays available. 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
  • Edit configuration values on the Config page, then apply them to the current version with Deploy or Redeploy

Upgrades 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. Configuration changes at the current version do not use the wizard. They are saved on the Config page and deployed from the console.

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.

Open the console​

  1. In a browser, go to https://<hostname>:30000, where <hostname> is a controller node or the load balancer in front of them. Embedded Cluster redirects to /console.

    If you set a different port with --api-port during installation, use that port.

  2. Log in with the password that was set with --installer-password during installation.

Which node serves the console​

Every controller node serves the console. Worker nodes do not. A controller that joins the cluster starts serving the console when its join finishes.

During an upgrade, the node where you run upgrade serves the console and the other nodes stop serving it. Each of the other controllers starts serving the console again when its own upgrade finishes.

If you open the console on a node that is not serving it, the page shows "Console unavailable on this node; use the node running the upgrade command."

For a multi-node installation, put a load balancer in front of the controller nodes so that users reach the console through the load balancer rather than a specific node. Use GET /console/healthz as the load balancer's health check. It returns 200 on a node that serves the console and 503 on a node that does not, so during an upgrade the load balancer sends users to the node running it.

In Embedded Cluster 3.17.0-beta.1 and 3.18.0-beta.1, only the node where you ran install, or most recently ran upgrade, serves the console. Controllers that joined on those versions start serving it after their first upgrade to 3.18.1-beta.1 or later.

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

Migration from Embedded Cluster v2 preserves the existing Application manifest. However, v3 uses the rendered descriptor URLs without KOTS ports URL rewriting. Update any links that depended on that rewriting to an address users can reach. See Application access and links.

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 is served by the Embedded Cluster daemon, which 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.

Limitations​

The admin console has the following limitations:

  • Worker nodes do not serve the console, and during an upgrade only the node running upgrade serves it. See Which node serves the console.

  • 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