Skip to main content
This tutorial takes a Kubernetes cluster you already run, on any provider or on your own hardware, and brings it under Ankra in one afternoon. At the end the cluster is connected, has a default StorageClass, keeps its Stacks in a Git repository, gives you kubectl access through Ankra, and backs up its stateful Stacks into a vault. Each step does one thing and ends with something you can see. Where a step has its own page, this tutorial links to it for the details.

Before you start

  • A cluster and a kubeconfig for it with permission to create a namespace and cluster-wide RBAC, and Helm on the machine you run the install command from.
  • A role that may add clusters. Without it the connect page reads Your role does not allow adding clusters. Showing the install command needs the agents.manage permission. See Roles and Access.
  • A payment method on the organisation. Without one the connect page reads Add a payment method before you connect a cluster. See Billing.
  • A Git repository for the cluster’s definition, reachable through the Ankra GitHub App or Bitbucket Cloud.
  • An S3-compatible bucket, or permission for Ankra to create one, for backups. See Backups and Restore Points.
  • The Ankra CLI, logged in to the right organisation:

1. Connect the cluster

Open Infrastructure → Clusters → Add a cluster → Connect an existing cluster (/next/clusters/import), tab Install the agent. Name the cluster, say what it is for, and select Get the install command. On the next page select Show the install command. Check that kubectl points at the right cluster, then run the command exactly as shown: it installs the Ankra agent in the ankra namespace with this cluster’s token. The agent only opens outbound connections to Ankra, for its API calls and its command stream (the hosts and ports are on Cluster Agent); no inbound port is opened. Check: the page shows Waiting for the agent to connect, then <your cluster> is connected, usually within a minute. See Add a Cluster and Cluster Agent if it does not connect.

2. Give it a default StorageClass

Ankra installs no storage driver on a cluster you connect. Add-ons with volumes, managed services and pipeline caches rely on the cluster having a default StorageClass. Follow Set up storage on a cluster you connect: it shows how to check for one, how to mark one as the default, and what node-local volumes mean. Check: exactly one StorageClass carries storageclass.kubernetes.io/is-default-class: "true".

3. Make Git the source of truth

Open Infrastructure → Clusters → <your cluster> → Settings → GitOps. Under Repository the page reads No repository connected. Select Connect a repository, choose the repository and branch, and confirm with Connect repository. Ankra commits the cluster’s definition to the branch and from then on applies the changes pushed to it. See Connect a repository to a cluster for the GitHub App, and GitOps for the directory Ankra writes and how a sync works. Check: the Sync section shows the cluster in step with the repository, and the repository has a new commit with a clusters/ directory. From the CLI:

4. Get kubectl access

Open Infrastructure → Clusters → <your cluster> → Kubectl access (/next/clusters/<cluster-id>/access). Your access says whether you have kubectl access. An administrator gives access under Give access; a member allowed to elevate can select Give myself access… for a short time. Access is scoped and needs no static kubeconfig from the cluster. See Cluster Access, which also covers the ankra cluster access and ankra cluster kubeconfig commands. Check: Your access reads You have kubectl access to this cluster.

5. Take stock and declare Stacks

See what already runs: the cluster’s Kubernetes pages list workloads, storage and Helm releases, and the CLI lists the releases with their charts:
Ankra has no command or page that turns what already runs into a Stack. Workloads you deployed yourself keep running as they are, and Ankra deploys, tracks and backs up what a Stack declares. Decide which parts Ankra should own from now on, then declare them as add-ons and manifests in Stacks: in the portal, by committing the Stack to the repository from step 3, or with ankra cluster apply. See Stacks and the ImportCluster YAML Schema. Check: ankra cluster stacks list --cluster my-cluster lists your Stacks.

6. Turn on backups

Protection is a property of a Stack. Register a backup vault (or bring your own bucket), then protect each stateful Stack into it on a schedule. Check:
The command lists one row per Stack, and the Stacks you protected no longer read unprotected. A Stack Ankra could not assess reads unknown, which is not the same as unprotected.

What you have now

  • The Ankra agent connects the cluster to Ankra, outbound only.
  • One default StorageClass, so volumes bind.
  • A Git repository that holds the cluster’s Stacks and applies what you push.
  • kubectl access through Ankra instead of shared kubeconfigs.
  • Stacks for what Ankra manages, with the stateful ones backed up into a vault.

Where to go next