K3s Architecture
You set up k3s architecture by running one small binary on your server and agent nodes. This single file packs the control plane, local database, and node runner together. Teams often share one admin key file to manage these small clusters fast. That broad role gives every user full rights to delete apps or read secret keys. When a shared key leaks, anyone can change the whole cluster without leaving a user trail. How k3s architecture runs servers and agents Standard container tools split the
Your coding agents run with your access.
Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.
You set up k3s architecture by running one small binary on your server and agent nodes. This single file packs the control plane, local database, and node runner together. Teams often share one admin key file to manage these small clusters fast. That broad role gives every user full rights to delete apps or read secret keys. When a shared key leaks, anyone can change the whole cluster without leaving a user trail.
How k3s architecture runs servers and agents
Standard container tools split the control plane across many separate software parts. In contrast, k3s architecture puts all server tasks into a single process. The server node runs the API, the scheduler, and the loop controllers together. It also replaces the heavy distributed key store with a small built-in SQL database. This design cuts memory use and makes the cluster fast to boot on edge hardware.
Worker nodes are called agents in this setup. Each agent node runs the same binary file in a worker mode. The agent starts a local tunnel that dials back to the server node. Inside the agent, a lightweight container runtime starts and stops your app pods. A built-in network router handles traffic between pods and outside users.
To manage the cluster, engineers use a local config file that holds a client key. The API server checks this key and looks up role rules in the database. Role rules group cluster objects and list what actions a user can take. You bind a user or a group to a role to grant read or write rights.
Why native roles are not enough for live commands
Native role bindings solve the first part of cluster safety. They let you map your team members to specific namespaces and pod groups. A developer can get read rights on logs while admins keep write rights. The API server blocks any call that does not match a bound role rule.
Still, static role setup leaves a big gap during daily work. When an engineer needs to fix a broken app, they often need shell rights. Native roles only check if a user can open a shell session to a pod. Once the shell opens, the cluster cannot inspect what commands run inside that container. A user with exec rights can read raw database files or copy out secret tokens.
The same problem happens when pods talk to data stores. If an engineer queries a database through a cluster port, native roles do not read the SQL. Sensitive fields like emails, phone numbers, card numbers, and national IDs return in plain text. Only data masking rewrites matched fields in results before they reach the screen. Native cluster setup decides who logs in, not what individual commands or queries do in flight.
Zero Trust Architecture: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
How to tighten node and API permissions
You can make your cluster safer by splitting duties across small roles. First, stop sharing the root admin file that the server writes at startup. Create distinct user identities for each person on your team. Bind each person to a single namespace instead of the whole cluster.
Second, separate node join tokens from user login keys. Store the agent join token in a secret store and rotate it after adding nodes. Do not let normal users read the system namespace where node secrets live.
Third, turn on API audit logs on the server node. Audit logs write down which user called which API path and when. Keep in mind that native audit logs only show that a shell or port session started. They do not record the exact database queries or shell commands typed inside that session.
Govern kubectl and API calls in flight
Identity providers and Kubernetes RBAC decide who logs into a cluster. They cannot redact keys inside returned JSON objects or hold a risky delete call for review. By design, hoop.dev runs as an open-source proxy, a sidecar for your Kubernetes API, checking requests and responses without replacing RBAC.
First, hoop.dev guardrails refuse banned methods, paths, or headers before they run. Next, hoop.dev data masking rewrites sensitive keys in returned Secret, ConfigMap, and log responses in memory, and writes each decision to the audit trail. Explore the repo on GitHub.
Frequently asked questions
What is the difference between a server node and an agent node?
A server node runs the API, scheduler, state database, and local container runner. An agent node only runs the container runner and connects back to the server.
How does K3s store cluster state without a heavy key store?
It uses a built-in SQLite database on single servers to save memory. For multi-server setups, it can connect to an external SQL database or embedded datastore.
Why is the default admin config file risky to share?
The default file holds a client certificate that bypasses normal role checks. Anyone with that file can read all secrets and delete any workload without individual attribution.
Related guides
In this post