Skip to main content
logoTetrate Patch ServiceVersion: alpha

Connecting Your First Cluster

Connecting a cluster to Tetrate Patch Service installs the Tetrate agent, which reports the container images running in the cluster. From then on the console shows an always-current image inventory and its CVE exposure. This guide takes you through onboarding your first cluster: run one command, label the workloads you want reported, and confirm the first report arrives.

Before You Begin​

  • The tetrate CLI, installed as described in Installing the Tetrate CLI. The CLI is self-contained, so you do not need kubectl, Helm, or Git.
  • A kubeconfig context pointing at the cluster you want to connect.
  • Cluster-admin access to that cluster. Installing the agent creates cluster-scoped read permissions: the agent watches Deployments and DaemonSets, has no Pod access, and binds no ports.

Step 1: Open the Connect Cluster Page​

In the sidebar, open Clusters and click Connect cluster manually. The Connect Cluster page opens. If you have no clusters yet, the list is empty and the same buttons sit in the center of the page. The other button, Connect from cloud account, discovers clusters straight from an AWS account; if you have a whole fleet to connect, Connecting an AWS Account is the shorter path.

The empty Clusters view, with the Connect cluster manually and Connect from cloud account buttons centered on the page.

The page presents a set of instructions to help you register your clusters. If your organization uses the managed data plane, the page also shows Install a managed product (optional). Leave both selects empty: this guide connects the cluster agent-only, and a managed install onto a connected cluster later adopts the running agent, so nothing is lost by starting small. To install a product at the same time, see Installing a Managed Product.

The Connect Cluster page showing the optional managed product selects, the tetrate onboard command, and the tip about labeling workloads.

Step 2: Run the CLI Command​

Copy the command from the page and run it in a terminal:

tetrate onboard

The command looks at every context in your kubeconfig, shows what it would do, and asks which clusters to connect. Only your current context starts selected, so confirming without changing anything connects the cluster you are pointed at; press a to select them all. For each cluster it registers the cluster, applies the credentials the agent needs, and installs the agent.

The run opens with the plan, one row per context, and then the checklist:

CLUSTER           ACTION
payments-prod     onboard
payments-staging  onboard
kind-dev          onboard

3 to onboard

  Select clusters to onboard
  ↑↓/jk move · space toggles · a all · enter confirms · q aborts

> [x] payments-prod
  [ ] payments-staging
  [ ] kind-dev

  1 of 3 selected

Press enter to confirm. Each selected cluster gets its own numbered block, and the run closes with a report and the labeling reminder that Step 3 acts on:

Connecting cluster payments-prod

  [1/4] Checking cluster payments-prod… ✓
  [2/4] Preparing cluster payments-prod… ✓
  [3/4] Applying agent configuration… ✓
  [4/4] Installing Tetrate agent… ✓

Succeeded on 1 cluster(s).
  ✔ payments-prod

The agent reports Deployments and DaemonSets labeled with your customer label.
To see a workload's images and CVEs in the UI, label it:

  kubectl label deployment <name> dataplane.tetrate.io=acme
  kubectl label daemonset <name> dataplane.tetrate.io=acme

When your kubeconfig holds a single context, or you pass --kubecontext, there is nothing to choose: the command skips the plan and the checklist and runs the steps for that one cluster, with the account check as its first step.

The first command that needs the API opens your browser to sign in; there is no separate login command.

Each cluster is registered under the name its kube context suggests, reduced to a DNS-1123 label. You do not choose the name and there is no flag to override it: names are settled by the service, which keeps them unique for you. If another cluster already holds the name, this one is registered under a name derived from it and the summary says which.

Every step is idempotent, so a failure partway through leaves nothing to undo: fix the cause, run the same command again, and it converges on a connected cluster. Re-running never renames a cluster that is already registered.

If no machine with the CLI can reach the cluster, expand Manual connection on the page for the equivalent copy-paste commands, described in Connecting a Cluster Manually.

Step 3: Label the Workloads to Report​

Managed products

A managed product (like teg) already labels the workloads it installs, so clusters given one need no manual labeling and you can skip this step.

The agent reports Deployments and DaemonSets that carry your customer label, so a freshly connected cluster is connected but empty until you label something. Label the workloads you want inventoried, using the exact label shown on the Connect Cluster page for your organization:

kubectl label deployment <name> dataplane.tetrate.io=<customer-id>
kubectl label daemonset <name> dataplane.tetrate.io=<customer-id>

Labeling is yours to decide rather than something the Patch Service does for you: it is what scopes reporting to the workloads you want tracked.

Step 4: Verify the Cluster Is Reporting​

The cluster appears in the Clusters view with a Last report timestamp once its first snapshot arrives. Under its name, a small gray line names where it came from: kubeconfig for a cluster connected this way. Expand the cluster to see every container it reported, with the image, the version, and when it was observed.

A snapshot is the complete set of labeled containers running in the cluster and replaces the previous one, so the console shows what runs now, not a history. Clusters and the Agent explains what the agent watches and how reporting works.

An empty cluster is usually an unlabeled one

A cluster that connects and then shows no containers has almost always skipped Step 3. Check that the workloads you expect carry your customer label before treating it as a failed install.

Next Steps​