Skip to Content
Adding ClustersAdding your first cluster

Adding your first cluster

This guide takes you from registering a cluster in Core Platform Portal to seeing its agents report successfully. Choose one of two paths:

PathWhat you needWhat happens
Local clusterA running Docker runtime on your computercorectl creates a Kubernetes cluster with k3d and installs both platform agents.
Remote clusterAn existing Kubernetes cluster and a working kubeconfigcorectl installs agents on the cluster you select.

The remote path also works for an existing local cluster. It does not provision a cloud cluster; create that cluster with your cloud provider first. For remote or production onboarding, work with CECG to confirm the intended cluster setup before connecting it; these steps do not establish support for every Kubernetes distribution or deployment configuration.

Before you start

You need access to Core Platform Portal  and administrator access in the Context where you want to add the cluster. Sign in and select that Context. If you do not yet have access, contact your platform administrator; for hosted onboarding, contact CECG.

Install the CLI and its dependencies with Homebrew:

brew trust coreeng/public brew install coreeng/public/coreplatform corectl version

The package includes corectl and k3d. See CLI installation for supported systems and manual installation. corectl includes its own Helm and Kubernetes clients, so separate Helm and kubectl installations are not required.

Your computer must be able to reach the Portal and download the published agent charts. The cluster must be able to pull the agent images and reach the Core Platform API to enroll and send reports.

Use the command generated by your Portal: it includes your Context and, when needed, your instance URL. Examples below use core-platform/engineering; replace it with your full Context key. corectl opens a browser for sign-in when needed.

Create a local cluster

  1. Start your Docker runtime.

  2. In Portal, select Clusters in the sidebar, then Connect Cluster.

  3. Choose Create a new local cluster, then Continue.

  4. Enter a name such as local-trial. The name will also be used for the k3d cluster, so choose one that is not already in use on your computer. Use lowercase letters, numbers, and hyphens, starting and ending with a letter or number (up to 63 characters). The tier defaults to dev; expand Advanced if you need to change it.

  5. Select Continue to setup to register it, then copy the displayed install command and run it in your terminal. For example:

    corectl agent install local-trial --context core-platform/engineering --create-local
  6. Wait for corectl to finish and for the Portal checklist to confirm both agents have enrolled and sent fresh reports. Select Done.

The command creates the local cluster, installs the Runtime Agent, enables management, and installs the Control Agent. The Runtime Agent reports cluster state; the Control Agent applies platform-managed configuration. corectl saves a private kubeconfig for this cluster without changing your default Kubernetes context. Keep Docker running while you use the cluster.

You can also start from Create local cluster on Home, which opens the local cluster details directly. See Get started locally to continue from Home through your first application deployment.

Connect a remote cluster

Before registering, make sure your computer can reach the Kubernetes API and your kubeconfig gives you permission to install the Cluster System release, including its namespace and cluster RBAC. Any cloud authentication helper used by the kubeconfig must be installed and signed in. corectl uses your existing access; it does not create cloud credentials.

  1. In Portal, select Clusters in the sidebar, then Connect Cluster.

  2. Choose Connect an existing cluster, then Continue.

  3. Enter a registration name such as customer-dev and choose the appropriate tier: pre-dev, dev, or prod.

  4. Select Connect Cluster, then copy and run the install command:

    corectl agent install customer-dev --context core-platform/engineering
  5. When prompted, select the Kubernetes context for the cluster you intend to connect. Check the target carefully before proceeding. You can select it explicitly instead:

    corectl agent install customer-dev --context core-platform/engineering --kube-context my-remote-cluster

    Add --kubeconfig /path/to/config if the credentials are in a separate file. Otherwise, corectl uses KUBECONFIG or ~/.kube/config.

  6. Wait for installation to complete and for Portal to confirm a fresh Runtime Agent report. Select Done.

--context selects your Core Platform Context. --kube-context selects the Kubernetes cluster. The Portal registration name does not have to match the Kubernetes context name, and corectl does not change your kubeconfig’s current context.

Enable platform management

The remote install command above installs the Runtime Agent for observation. To let Core Platform manage an eligible cluster, enable management after the Runtime Agent is reporting:

corectl agent enable-management customer-dev --context core-platform/engineering

corectl remembers the Kubernetes target from the successful installation on this computer. This command installs the Control Agent; confirm that it is reporting in Portal too. Management eligibility and existing ownership are checked before installation.

For a new registration that you already intend to manage, you can combine the initial installation and management steps by adding --enable-management to corectl agent install. Local creation does this automatically.

Check the connection

List clusters in the same Context:

corectl get clusters --context core-platform/engineering

Open the cluster in Portal and check for a fresh Runtime Agent report. For a managed cluster, check the Control Agent as well. A registration appearing in the list alone does not confirm a successful installation: check both the terminal result and the Portal agent status.

You can now inspect cluster health. To deploy your first application, continue to Deploying Applications; adding a cluster does not by itself complete the GitHub, template, or deployment-target setup for application creation.

If installation does not complete

  • Connect Cluster is unavailable: check that you selected the intended Context and have administrator access there.
  • Local creation fails: check that Docker is running and k3d is installed. If the cluster was already created, use the retry command printed by corectl; do not repeat --create-local to recover an existing cluster. Keep the private kubeconfig that corectl saved.
  • Kubernetes access fails: check the selected kubeconfig and Kubernetes context, network access to the API, permissions, and any cloud authentication helper.
  • An agent does not report: check the terminal’s failed stage and the Portal checklist. Check that the cluster can pull the images and reach the Core Platform API, then follow the reported retry instructions.

For recovery, upgrades, and removal, see Install and manage cluster agents. Uninstalling agents does not delete the Kubernetes cluster or its Portal registration.