Skip to content

Connect a cluster

Seylo manages your cluster through a small agent that runs inside it. The agent makes one outbound, encrypted connection to Seylo; your cluster needs no inbound access, and Seylo stores no cluster or cloud credentials. The agent is a single Deployment with no Service, no Ingress, no NodePort and no inbound port.

On Seylo’s hosted service the agent connects to agent.seylo.in, on port 443: a host for agent connections only. You use the portal at portal.seylo.in; the agent never needs it. If your cluster’s egress is restricted, allow agent.seylo.in:443 before you run the command. See restricted networks.

  • admin in Seylo, and cluster-admin (or enough rights to create a namespace, ServiceAccount and RBAC objects) on the target cluster.

  • Helm 3. Install it with winget install Helm.Helm on Windows, brew install helm on macOS, or your Linux distribution’s package. Without Helm, there is a plain manifest instead (see step 2).

  • kubectl pointed at the cluster you mean to connect. Check with:

    Terminal window
    kubectl config current-context
  1. Describe the cluster.

    Admin → Clusters → Connect cluster. Give the cluster a name. Then choose which namespaces Seylo may change:

    • All namespaces (recommended). New namespaces are included as they appear.
    • Only the namespaces I list.

    Either way you can name namespaces Seylo must never change, such as kube-system.

    Then choose what to install. Each option on the page says exactly what it adds to your cluster.

    Option Default What it adds
    Seylo agent Always One pod in the seylo-agent namespace with a least-privilege ServiceAccount. It dials out to Seylo; nothing connects in
    Observability: metrics, logs, traces Recommended The seylo-observability chart in its own namespace. The data stays in your cluster. See observability
    Cost allocation with OpenCost On One read-only OpenCost pod in the observability chart, for cost per namespace and workload
    Read-only commands in containers Off Lets Nightshift run a fixed list of read-only commands while it troubleshoots. See commands in containers

    Choose Get the install command. This creates the cluster in Seylo and a one-time token. Nothing runs in your cluster until you run the command.

  2. Run the command.

    One command installs everything you chose, in order. It is shown for Bash and for PowerShell; run it where your kubectl points.

    The command contains a one-time token. It is shown once, it expires, and it can be used once. Treat it as a secret until it has been used.

    Other ways to install has a plain manifest for clusters without Helm: save it, run kubectl apply -f agent.yaml, and delete the file afterwards, because it contains the token.

    Below the command, the page shows the agent and each component as they come up. There is no need to refresh.

  3. Connected.

    When the agent connects, the page moves on by itself. There is nothing to save. Anything you chose that is not installed yet is listed with the command that installs it.

Before running a command you did not write, you can verify the signature of the image and chart it installs, and choose an RBAC posture first if you want a namespace-scoped agent.

The cluster waits under Admin → Clusters → Waiting for the agent. From there:

  • Resume takes you back to the install step. If you have not run the command yet, choose Issue a new command: the first token was shown once and the page no longer has it.
  • Cancel stops connecting it: Seylo deletes the record, and its unused install command stops working. If you already ran the command, remove the agent from the cluster with helm uninstall seylo-agent -n seylo-agent.

When the agent reaches Seylo but cannot connect, the page says why, for example:

  • The command’s one-time token expired before the agent used it, was already used, or was not accepted for this cluster. Issue a new command and run it unchanged. If the same command was also run in another cluster, remove the agent there.
  • The agent reported a connection failure at a named layer (DNS, the network connection, the proxy, TLS, the WebSocket upgrade, enrollment or the protocol version), with the agent’s own message and what to change.
  • Two agents are connecting as this cluster. Remove the extra install; Admin → Clusters lists both, with the commands.

An agent that cannot reach Seylo at all has no way to say why. If there is still no agent after three minutes, the page lists where to look:

Where to look Check with
kubectl was pointed at a different cluster kubectl config current-context
The agent pod is not running, for example its image cannot be pulled, or it cannot be scheduled. The pod’s events say which kubectl -n seylo-agent get pods
kubectl -n seylo-agent describe pods
Outbound HTTPS from the cluster to Seylo’s agent host (agent.seylo.in:443 on the hosted service) is blocked. The agent’s log names the layer that failed, on a line starting preflight FAIL [ kubectl -n seylo-agent logs deploy/seylo-agent
The command’s token expired or was already used Issue a new command and run it

More in troubleshooting the agent and restricted networks.

Admin → Clusters, then a cluster’s menu → Agent details:

  • the agent’s status;
  • the installed components, with the command for anything missing;
  • read-only commands in containers for this cluster;
  • reinstall or upgrade;
  • revoke the agent.

The same menu has Re-issue enrollment token, which issues a new one-time token on the Agent details page. A connected agent keeps working.

Do this once per version. One command, and it is the difference between “I pulled a container off the internet” and “I checked who built it”.

Both the image and the chart are signed with cosign keyless: the signature is made by the release workflow using its OIDC identity and recorded in the public Rekor transparency log. There is no key to distribute.

Terminal window
# The IMAGE.
cosign verify \
--certificate-identity-regexp '^https://github.com/seylo-inc/k8s-deploy/\.github/workflows/release-agent\.yml@refs/tags/agent-v' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/seylo-inc/seylo-agent:0.2.22
# The CHART. A Helm OCI artifact is signed the same way; `helm pull` on its
# own verifies nothing.
cosign verify \
--certificate-identity-regexp '^https://github.com/seylo-inc/k8s-deploy/\.github/workflows/release-agent\.yml@refs/tags/agent-v' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/seylo-inc/charts/seylo-agent:0.2.22

Expect Verified OK. If it fails, do not install — the bytes are not what we published.

Full detail, including the SBOM attestation and how to pin a digest: verify what you install.

The command on the Connect page does this for you, with your cluster’s ID, the agent’s Seylo address and the one-time token filled in. The commands below are what it runs for the agent, for reference or for your own automation.

Installs the published chart straight from the OCI registry. No helm repo add, no clone, no registry login.

Terminal window
helm upgrade --install seylo-agent \
oci://ghcr.io/seylo-inc/charts/seylo-agent --version 0.2.22 \
--namespace seylo-agent --create-namespace \
--set serverUrl=wss://agent.seylo.in/agent/connect \
--set clusterId=your-cluster-id \
--set enrollmentToken=k8sdt-enroll_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The image comes from the chart’s own defaults, at the digest that chart version was released with, so there is nothing to pass for it.

Namespace-scoped variant. watchNamespaces is required here: a namespace-scoped agent is bound with a Role inside each managed namespace and cannot list namespaces itself, so the chart refuses to render without it.

Terminal window
helm upgrade --install seylo-agent \
oci://ghcr.io/seylo-inc/charts/seylo-agent --version 0.2.22 \
--namespace seylo-agent --create-namespace \
--set serverUrl=wss://agent.seylo.in/agent/connect \
--set clusterId=your-cluster-id \
--set enrollmentToken=k8sdt-enroll_XXXX \
--set rbac.scope=namespaced \
--set 'watchNamespaces={prod,staging}'

A fixed list on a cluster-wide install. You can also pass watchNamespaces with the default cluster-wide RBAC. See a fixed namespace list on a cluster-wide install for what that costs.

Read it before you run it, if you would rather read than trust:

Terminal window
helm show values oci://ghcr.io/seylo-inc/charts/seylo-agent --version 0.2.22
helm template seylo-agent \
oci://ghcr.io/seylo-inc/charts/seylo-agent --version 0.2.22 \
--set serverUrl=wss://x/agent/connect --set clusterId=x --set enrollmentToken=x

A fixed namespace list on a cluster-wide install

Section titled “A fixed namespace list on a cluster-wide install”

A cluster-wide install has no namespace list unless you ask for one. On a cluster’s Agent details page that is the box Also limit the agent to a fixed list of namespaces, inside the cluster, which is off by default. With Helm it is the watchNamespaces value.

Without a list (the default), Seylo’s namespace policy decides where Seylo may act. You change it in the portal (Admin → Clusters, edit the cluster, Namespace policy), and Seylo sends it to the agent live. A new namespace, or a target you copy a namespace into, needs nothing on the cluster: no helm upgrade.

With a list, the agent never acts outside it, whatever Seylo allows. Seylo can narrow what the agent does inside the list, but it cannot widen the list remotely, by design. The list is how a platform team caps Seylo from inside its own cluster. A cap that Seylo could lift would last only until Seylo decided otherwise.

The cost: every namespace outside the list needs a helm upgrade on the cluster. The copy wizard shows the agent’s own list on its first step, before you submit, with the command. New namespace refuses the namespace when you create it, with the same message and Nothing was created. at the end. The message begins:

The agent's install limits it to namespaces [shop, shop-staging], so it would refuse "shop-uat". Seylo cannot widen that list.

Either add the namespace to the list, or remove the list:

Terminal window
helm upgrade seylo-agent oci://ghcr.io/seylo-inc/charts/seylo-agent --namespace seylo-agent --reset-then-reuse-values --set watchNamespaces=null

null removes the value; an empty {} does not. Removing the list works for a cluster-wide install only. A namespace-scoped install always needs its list.

By default the agent writes no custom resources: rbac.write.tier1.customResources is an empty list. If your teams edit cert-manager Certificates, KEDA ScaledObjects or similar through Seylo, name each group and resource in a values file:

seylo-agent-values.yaml
rbac:
write:
tier1:
customResources:
- apiGroup: cert-manager.io
resources: [certificates]
- apiGroup: keda.sh
resources: [scaledobjects]
Terminal window
helm upgrade --install seylo-agent \
oci://ghcr.io/seylo-inc/charts/seylo-agent --version 0.2.22 \
--namespace seylo-agent --create-namespace \
-f seylo-agent-values.yaml \
--set serverUrl=wss://agent.seylo.in/agent/connect \
--set clusterId=your-cluster-id \
--set enrollmentToken=k8sdt-enroll_XXXX

On a cluster-wide install a listed resource is writable in every namespace, because a ClusterRole applies everywhere. The chart refuses wildcards and built-in groups. What it accepts, what it refuses and the recommended starting list are in custom resources: an explicit list.

Terminal window
kubectl -n seylo-agent logs -f deploy/seylo-agent
# expect: ENROLLED (first install), then "reporting inventory every 30s"

In the portal, the cluster shows a green Agent: Connected chip with its version and last-seen time, and dashboard rows for that cluster carry a small agent badge so operators can see the data path.

Once connected, delete the one-time enrollment Secret:

Terminal window
kubectl -n seylo-agent delete secret seylo-agent-enrollment

See verify the install for what “connected” should actually look like.

Enrollment token Per-agent credential
Prefix k8sdt-enroll_ k8sdt-agent_
Lifetime ~1 hour, single use Long-lived, held by the agent
Where it lives The Secret you install with; delete it after The agent’s own Secret in your cluster
Stored by Seylo as A hash A hash

Neither is ever stored in plaintext by Seylo, and a token cannot be recovered from its hash. The enrollment token is never written to the audit log, and the install page uses a POST so a freshly issued token never appears in a URL — and therefore never in a reverse proxy’s access log.

After the first enrollment the agent holds its own credential, which survives upgrades. You do not need a new enrollment token to upgrade.