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.
Before you start
Section titled “Before you start”-
adminin Seylo, andcluster-admin(or enough rights to create a namespace, ServiceAccount and RBAC objects) on the target cluster. -
Helm 3. Install it with
winget install Helm.Helmon Windows,brew install helmon 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
Connect a cluster
Section titled “Connect a cluster”-
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-agentnamespace with a least-privilege ServiceAccount. It dials out to Seylo; nothing connects inObservability: metrics, logs, traces Recommended The seylo-observabilitychart in its own namespace. The data stays in your cluster. See observabilityCost 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.
-
Run the command.
One command installs everything you chose, in order. It is shown for Bash and for PowerShell; run it where your
kubectlpoints.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.
-
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.
If you leave the page
Section titled “If you leave the page”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.
If the agent does not connect
Section titled “If the agent does not connect”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 podskubectl -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.
Manage the agent later
Section titled “Manage the agent later”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.
Verify the signature first
Section titled “Verify the signature first”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.
# 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.22Expect 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.
Install by hand
Section titled “Install by hand”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.
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_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXThe 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.
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:
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=xOther ways to install on the Connect page renders the full manifest. Save it and apply it:
kubectl apply -f agent.yamlThe file contains the one-time enrollment token. Treat it as a secret, and delete it once the agent is connected.
There is no way to fetch the manifest by putting the token in a web address. Addresses are kept in proxy logs and browser history, so Seylo refuses a token sent that way. If you sent one, re-issue the token on the cluster’s install page, because the old one has to be treated as seen.
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:
helm upgrade seylo-agent oci://ghcr.io/seylo-inc/charts/seylo-agent --namespace seylo-agent --reset-then-reuse-values --set watchNamespaces=nullnull 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.
Let the agent write custom resources
Section titled “Let the agent write custom resources”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:
rbac: write: tier1: customResources: - apiGroup: cert-manager.io resources: [certificates] - apiGroup: keda.sh resources: [scaledobjects]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_XXXXOn 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.
Confirm it worked
Section titled “Confirm it worked”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:
kubectl -n seylo-agent delete secret seylo-agent-enrollmentSee verify the install for what “connected” should actually look like.
How the two secrets work
Section titled “How the two secrets work”| 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.
- Choose an RBAC posture — what the agent may do
- Verify the install
- Behind a proxy or TLS inspection?
- It installed but never connected
- Upgrade the agent
- Remove Seylo from a cluster — every command, and what Seylo keeps