Connecting a Kubernetes cluster to Landfall

The Landfall Kubernetes agent runs inside your cluster and dials out to Landfall, so nothing in the cluster has to be reachable from the internet. It answers a fixed list of read-only questions, and only for an incident the cluster is part of.

• As a source: an agent token Landfall mints for the cluster, which you pass to the agent's Helm chart.
• As a trigger: not yet. See Opening incidents from Kubernetes.

How it works

• Outbound only. The agent opens HTTPS connections to Landfall and holds a long poll on its own job queue. A read in an incident becomes a job on that queue; the agent runs it and posts the answer back, usually within a tenth of a second. It has no inbound port, Service or Ingress.
• Quiet until involved. A cluster is read only for an incident it is part of. A person adds it to the incident, and any member of the organization can take it out again. Agents can do neither. Outside an incident, including for widgets on a dashboard, a cluster answers nothing.
• Read-only by construction. The agent's ClusterRole grants get, list and watch only, with no write verb and nothing on Secrets or ConfigMaps. Every object is stripped (managed fields, the last-applied annotation, environment variable values, annotations outside an allow-list) and every string is redacted before it is sent.
• Standard parts. The agent is an OpenTelemetry Collector distribution built from upstream receivers. Landfall's own code is the extension that speaks to Landfall and answers reads.

What you'll need

• Kubernetes 1.27 or later, and Helm 3.
• Outbound HTTPS from the cluster to api.landfalls.ai, directly or through a proxy.
• metrics-server in the cluster, if you want current CPU and memory. Every other read works without it.
• An admin on your Landfall organization.

1. Add the cluster in Landfall

1. Integrations → Context sources → Kubernetes cluster → Add cluster

   In the left menu, open Integrations and choose Kubernetes cluster under Context sources. Under Cluster name, type the name the room will use (for example prod-eu) and click Add cluster. Landfall mints a token for this cluster and shows one helm install command with it, under Install the agent. Copy it now. The token is shown once. Then click I have copied it.

   app.landfalls.ai · Integrations · Kubernetes cluster

   

2. Install the agent in the cluster

1. Run the install command

   TerminalCopy

   helm install landfall-agent oci://public.ecr.aws/r9i3z7v6/charts/landfall-agent \
     --namespace landfall --create-namespace \
     --set landfall.apiUrl=https://api.landfalls.ai \
     --set landfall.connectionId=prod-eu \
     --set token=lfa_...

   The chart puts the token in a Secret. To keep it out of your shell history, create the Secret yourself and pass --set existingSecret=<name> instead. Raise the memory limit with the size of the cluster; the Reference has the table.

2. Watch it connect

   Within a minute the cluster reads Connected in the same panel, with the agent's version, the Kubernetes version and the node count.

   app.landfalls.ai · Integrations · Kubernetes cluster

   

What it looks like

Once a person adds the cluster to an incident, the room's chat shows a card saying the cluster is part of this investigation, with a Remove from investigation button. From then on Beacon and every agent in the room can read it for this incident, and widgets on the room's canvas can chart it.

app.landfalls.ai · War room

What Beacon can read

A cluster answers only for an incident it is part of. The room has no control for adding one yet. A member of the organization adds it with one call to Landfall's API, using a personal API key from Your settings → API keys. The connection id is the landfall.connectionId value in the install command. An agent's own session is refused.

curl -X POST https://api.landfalls.ai/o/<your-org>/incidents/<incident id>/clusters/<connection id>/involve \
  -H "Authorization: Bearer lf_key_..."

A cluster cannot be added to a resolved incident, and adding one twice is refused. Remove from investigation on the room's card takes it out at once.

These operations reach Beacon and every agent that joins the room through get_signal_catalog and query_signals. How the agents fit with every other integration is on Integrations architecture.

Opening incidents from Kubernetes

Not yet. The agent answers questions for incidents that already exist; it does not open them. Open incidents from the alerts you already have, for example through Alertmanager or the other pages under Triggering integrations, and add the cluster to the incident.

Troubleshooting

States you will see

app.landfalls.ai · Integrations · Kubernetes cluster

Reference