Connect a Kubernetes cluster

An organization can install one Satellite per Kubernetes cluster and grant access to selected workspaces. The Satellite reads Kubernetes or a configured source and returns the requested data. It needs a reachable HTTPS endpoint with a valid TLS certificate. Kubernetes access is available to selected organizations. Contact d5s to enable it.

The integration is called Kubernetes in chat and settings. The Kubernetes wheel marks cluster reads and access cards; connections are labeled Cluster followed by their configured name. Satellite is the component your operator installs inside the cluster.

Register and install

An organization owner or admin opens Organization settings -> Infrastructure access -> Kubernetes and registers a cluster. Use a name such as production-eu: lowercase letters, numbers, dots or hyphens, starting and ending with a letter or number. Registration returns an enrollment token once. Give it to the cluster operator through a secret manager. Install the Satellite release, using an enrollment Secret, a TLS Secret, explicitly permitted d5s callers and reviewed Kubernetes/source network destinations.

New installation examples enable common Kubernetes resource reads, events, pod logs and live metrics. Logs can contain application data; metrics require a working Kubernetes Metrics API. The source chart keeps these optional capabilities disabled unless configured. Sensitive configuration and node diagnostics remain separate operator choices. A requested read reports the installed capabilities; an organization admin then sets the organization ceiling and explicit workspace grants. Workspace grants cannot exceed the local permissions or organization ceiling.

Customer-managed HTTPS endpoints

In Organization settings → Infrastructure access → Kubernetes, open the cluster’s Installation tab. Under Connect and verify, enter the public HTTPS address and the enrollment token from its Kubernetes Secret. Choose Save and verify connection. A successful live read confirms the connection. If the read fails after saving, use Retry verification without entering the token again. Changing the address requires the token again. Configure workspace access separately in Access.

An organization owner or admin can also save a public HTTPS origin and the installation’s enrollment token through PUT /api/v1/organizations/{organization_id}/satellites/{installation_id}/endpoint. Use the token stored in that connector’s enrollment Secret. The token must match the installation. Saved tokens cannot be retrieved through the API.

The endpoint needs a publicly trusted TLS certificate. Internal, loopback and metadata addresses are blocked. Use the final endpoint address rather than a redirect. Private pilot endpoints continue to use operator-managed configuration.

Saving sets Configured, not a verified live connection. Request Service discovery to verify a live Kubernetes read. Updating the endpoint clears its prior verification; revocation removes its saved credential and rejects in-flight results. An endpoint change during a read also rejects that result. Saving an endpoint does not grant workspace access.

For Kubernetes APIs reached through a different backend port, set networkPolicy.controlPlanePorts to the required ports, for example [443, 6443]. On Cilium clusters where ordinary CIDR rules cannot reach the API server, enable networkPolicy.ciliumKubeApiServer. This requires Cilium’s CiliumNetworkPolicy resource and permits only the Kubernetes API entity on those ports. Check a live read after installation; a running Pod alone does not verify connectivity.

Reads only when requested

The Satellite reads data only when an authorized person or agent asks. The result returns in that request. The Configured indicator means an endpoint is set up; reachability is checked when you request a read. An unavailable endpoint returns an error.

Permissions are checked before a read runs and before its result is shown. Saved history does not keep raw results. Revoke an installation to stop new reads and in-flight results. Have the operator also remove network access to the endpoint, uninstall or rotate its Secret to revoke endpoint access itself. Credentials must never be supplied in an agent prompt.

Install a published release

Install Satellite 0.2.0 from the public OCI chart at oci://ghcr.io/d5s-tech/charts/d5s-satellite. Registry sign-in is not required. The chart pins the scanned image digest. Download binaries and checksums.

Create the enrollment and TLS Secrets in the release namespace using your secret manager. Keep tokens and private keys out of Helm values, Terraform state, source control and chat. The operator configures the endpoint, allowed callers and Kubernetes/source network destinations. Settings shows Helm, Terraform, Pulumi and Kubernetes YAML instructions with the same settings. Pin the chart version in IaC and review upgrades.

Use the installation ID and configuration shown for your cluster in Settings. After creating its namespace and Secrets, install with:

helm upgrade --install d5s-satellite \
  oci://ghcr.io/d5s-tech/charts/d5s-satellite \
  --version 0.2.0 \
  --namespace d5s-satellite \
  --values satellite-values.yaml --atomic --wait

The chart creates an internal Service, not a public endpoint or certificate. Route your public HTTPS address to that Service through your ingress or load balancer. Keep TLS on the connection to Satellite. If your ingress terminates TLS, it must forward to Satellite over HTTPS. Allow its source addresses in the chart's inbound rules and restrict external callers in your ingress or firewall. Then save the address under Connect and verify.

Add another cluster from chat

Ask the agent to add a Kubernetes cluster and provide its name. The agent can show an Add a Kubernetes cluster card even when other clusters are connected. Choose Add cluster to open the registration form with the supplied name. An organization owner or admin must confirm registration. Showing the card or opening the form does not register, install, or grant access to a cluster. Installation uses the release and instructions available in settings.

Allow this agent and Allow for this chat enable use of existing workspace clusters. Those controls do not add a cluster.

Manage cluster access

Open a cluster to use Access, Sources, or Installation. The dialog keeps its height when switching tabs. In Access, choose a workspace with the searchable picker. Disabled permissions explain whether the organization disabled them or the installation does not include them. Organization permissions applies to every workspace; workspace controls only narrow that access. Changes save automatically.

Sources shows installed sources and whether the selected workspace can use each one. Expand Find and configure sources for discovery and setup guidance. Installation shows release requirements and Before you install prerequisites. Copy installation details includes the cluster name, installation ID, and status, without tokens or credentials. For an existing cluster, update to a newer published release.

Choose an installation method

Choose Helm, Terraform, Pulumi, or Kubernetes YAML. Replace every placeholder before running an example. All four methods use the same chart and satellite-values.yaml. Configure your tools for the intended Kubernetes cluster. Create the namespace and enrollment and TLS Secrets before installation. The chart creates an internal Service; your network setup must make its authenticated HTTPS endpoint reachable from d5s. Register a public address in Connect and verify. Private endpoints require managed setup.

Helm is the recommended method. Terraform uses the Helm provider in your existing project. Pulumi uses a TypeScript Helm Release example. Kubernetes YAML uses Helm to render manifests, then kubectl diff and kubectl apply. Review the diff before applying; a diff exit code of 1 means changes were found. YAML apply does not remove resources omitted by later chart versions, so review removals when updating.

For an existing installation, keep your current deployment method. Merge starter values with your existing configuration. Switching tools requires a resource import or migration. Review starter permissions explains the diagnostic defaults and additional capabilities. The update examples omit capability settings for configured clusters, so operators can preserve their current choices. Enable logs and metrics for the intended workspace under Access; installing these capabilities alone does not grant agent access. A Configured label does not confirm a successful live connection; request Service discovery under Sources to check a live read.

Add read sources

In Organization settings -> Infrastructure access -> Kubernetes, an admin can ask a configured Satellite to discover Kubernetes Services. The results are read live and are not a stored cluster inventory. Copy a Service address as a starting point, or use a hosted HTTPS API. The cluster operator decides which endpoint and credential to install. Discovery alone grants no agent access.

The operator mounts an existing Secret containing sources.json. It lists at most 20 named sources. Each has an ID, a descriptive kind, one capability (logs, metrics, or dashboards), an adapter, and an origin. Loki, Prometheus, and Grafana adapters use fixed read paths. A JSON adapter supports a reviewed fixed GET path, query parameter, result array path, and output field mapping for other read APIs. Bearer or Basic credentials stay in the Secret and are never shown in the app. HTTP origins are limited to Kubernetes Service DNS names; hosted origins use HTTPS. The chart requires explicit egress destinations when sources are configured.

After the operator updates the Secret and restarts the Satellite, the next requested read reports the new source in the admin screen. The admin enables Observability in the organization ceiling and for each intended workspace, then switches on each source for that workspace. An agent sees only sources granted to its workspace. Removing a source from the installation removes its workspace grants. These controls are separate from Kubernetes pod logs and Metrics API access.

Reads return at most 100 mapped items from at most 64 KiB of upstream response data. The requested Loki time range is at most one hour. A JSON adapter does not impose an upstream time filter; use a read-only credential scoped by the source provider. The agent cannot choose an endpoint URL, API path, header, or extra returned field.

Enable node disk reports

An operator can optionally install a node disk report source. It is disabled by default and requires node-level privileges. Its report endpoints support fixed reads; they do not provide agent shell, exec, or cleanup access. Use a pinned, scanned image that includes this capability and the matching chart. A standalone Satellite binary alone does not install the report source.

After the operator installs and configures the source, an organization admin enables Observability and grants that source only to the intended workspaces. Ask the agent to list its sources, then query the node disk source with node=<Kubernetes-node-name> view=summary and a result limit of 100. The summary distinguishes root filesystem bytes, image filesystem bytes, pod ephemeral data, container writable layers and logs. Missing statistics are reported separately. These measurements overlap; do not add them as independent disk usage.

For details, use view=images or view=containers, also with limit 100. Each page reports full inventory counts, a snapshot, a page entry count and any continuation. Request the next page with the returned after and snapshot values. If the inventory changes, restart from the first page. Do not infer counts from a sample of Node images or an incomplete page.

Images referenced by existing containers or current workloads, pause images, pinned images and repositories outside the operator's application list remain protected. Candidate counts describe observed references; they do not prove reclaimable bytes or authorize deletion. Image content sizes share layers and are non-additive. Incomplete runtime or workload reads make candidate attribution unavailable. A denied or unavailable read is different from an empty successful result.

Run the standalone binary

Checksummed Linux amd64 and arm64 binaries are available for hosts outside Kubernetes. The binary supports operator-managed hosts with a Kubernetes kubeconfig, reviewed read permissions, and operator-configured inbound HTTPS. The Helm container remains the standard cluster install. Verify the published checksum before use, and keep the enrollment token and optional source configuration in a host secret manager. Host network rules must be reviewed separately because Helm NetworkPolicy applies only to the container.

Choose who can use the grant

In Who can use Kubernetes, choose Opt in per chat (the default) or Entire workspace. With opt-in, an attempted read returns a permission error to the agent. The agent decides whether access is needed for your request and can explicitly offer a setup card. Failed reads do not automatically display setup cards. The user can allow that chat with one click or turn that grant off again from the card. For a named agent, its owner or a workspace connector admin can grant the agent's persistent conversation. The card says Allow this agent to make that scope clear. Once a named agent has access, people who can reach it through a connected Slack channel or linked Slack direct message can request the enabled reads. Its scheduled runs can use the same access for reports. Only web chat and Slack can use Kubernetes access. Entire workspace lets all chats and agents use the enabled read categories. Revoking an installation or disabling a category prevents new reads and blocks in-flight results.

When a read category is disabled, the agent can continue with permitted reads or explicitly offer a setup card if that category matters for your request. That card names the category, cluster and workspace. An organization owner or admin can toggle the cluster ceiling and workspace permission directly in the card. Turning on the cluster ceiling does not enable any workspace grants; enable the intended workspace separately. Changes apply to only the selected category and scope. If the operator has not installed the capability, the card explains that instead of offering a switch. Observability sources also need an explicit source grant in Kubernetes settings. Disabling workspace Observability removes its source grants; choose those sources again if you re-enable it.

Kubernetes settings opens Organization settings -> Infrastructure access -> Kubernetes, keeping the originating workspace selected. Permission changes do not retry the read automatically; ask the agent to try again after enabling access. Other workspace members can ask an organization admin to change the permission.

Ask an agent about the cluster

The agent's kubectl tool accepts read commands such as get pods -n default, describe deployment/api -n default, get events -A, top node, and logs pod/api-123 -n default -c api --tail=50. config get-contexts lists granted clusters. With one available cluster (configured for HTTPS reads) the tool selects it automatically; with several, use --context <cluster-name>. Use -A, -l, --limit, and --continue to narrow or page large reads.

The tool runs read commands only. It does not give the agent a shell. Exec, port-forward, watch, and mutation commands are unavailable. Permissions are checked before a read runs and before its result is shown. Results return directly to the requesting agent. Saved history does not keep raw results, although the agent's written response may include details it chose to report.

Remove access

Remove a workspace grant to stop only that workspace. Revoke an installation to stop all workspaces and invalidate its credentials at d5s. The operator also removes or rotates the inbound endpoint credential. The operator then removes the Helm release and its Kubernetes Secrets. Updating an installation requires a newly scanned image digest through the operator's normal Helm or IaC review process; customer installations do not silently upgrade.