How to Configure K3s Kubeconfig

Published
Length
3 min read

Luis Felipe Dias

All posts

To set up your k3s kubeconfig, copy the default cluster file to your local machine. Then replace the local loopback address with the public IP of your server node. Many teams share this single file across laptops and build servers to save time. When that file holds broad cluster admin rights, every user gets full control over all workloads. A single mistake can delete namespaces or expose secret values to the whole team. How the native k3s kubeconfig workflow works When you install the cluste

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.

To set up your k3s kubeconfig, copy the default cluster file to your local machine. Then replace the local loopback address with the public IP of your server node. Many teams share this single file across laptops and build servers to save time. When that file holds broad cluster admin rights, every user gets full control over all workloads. A single mistake can delete namespaces or expose secret values to the whole team.

How the native k3s kubeconfig workflow works

When you install the cluster, the server writes a credential file to a local folder. By default, only the root user on that host can read this file. It holds three main parts: the cluster address, the user key, and the context link. The cluster section stores the server URL and the root certificate authority data. The user section holds a client certificate and a private key for login checks.

To run commands from a laptop, an engineer copies this file off the server. They must edit the server address field so it points to a reachable network IP. The server certificate must also match that external IP or DNS name during TLS checks. If the IP changes, you must add the new address to the server TLS config. Once updated, the local client tool reads this file on every command you send.

You can merge several cluster files into one local config file on your workstation. Contexts let you switch between a test cluster and a live cluster in seconds. Still, the default file uses a static client certificate with full admin rights. Anyone who holds that file can act as the top admin until the certificate expires.

How to scope roles and permissions for team members

Sharing the default root credential file across an engineering team creates major security risks. Instead, admins should create dedicated roles and role bindings inside the cluster for each group. You can bind a role to a single namespace so developers only touch their own apps. A read-only role lets support staff check pod logs without changing any running services.

After you define roles, you must issue unique credentials for each person or service account. Some teams create short-lived tokens tied to a central identity provider through OpenID Connect. When an engineer logs in, the identity provider checks their group and returns a token. The cluster API server reads that token and enforces the matching role rules.

End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Where static cluster credential files fall short

Native role rules decide who can reach the cluster API and which resource types they touch. They do not inspect what happens inside an active shell session or a pod command. Once a user has rights to run a pod shell, they can run any binary inside. They can read local files, inspect memory, or pull raw database records through that pod.

Static files on laptops also create a long-term key rotation problem for security teams. If an engineer leaves the team, revoking a client certificate inside the cluster is hard. You often have to rotate the whole certificate authority and reissue files to every user. Native logs also record that a shell session started, not the exact commands run inside. Plus, raw pod logs often display customer emails, phone numbers, or card numbers in plain text. Without field masking in flight, those sensitive values flow straight to the user screen.

Check Kubernetes API requests and responses on the wire

Kubernetes RBAC decides who may call the API server. RBAC does not check response payloads or split listing Secret names from reading Secret values when a role grants get access. With hoop.dev, you run an open-source proxy, a sidecar for your Kubernetes API, inline on the API connection. On every kubectl or API call an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human review.

On each call, hoop.dev guardrails read the method, normalized path, and headers to refuse bad deletes or full Secret reads with a 403 error, or hold risky calls for approval. On the way back, hoop.dev data masking walks JSON responses by key and masks matched values in Secrets, ConfigMaps, and pod logs in memory. View the project on GitHub.

Frequently asked questions

Where does the cluster store the default credential file on the server?

The installer writes the file to the system config folder under the rancher directory. By default, only the system root account has permission to read or copy this file. You can adjust file read modes during setup if non-root local users need it.

Why does my remote client fail with a certificate authority error?

The default server certificate only trusts the local loopback address and the private host IP. When you reach the server over a public IP, TLS checks fail by default. You must add your external IP or domain to the server TLS config and restart it.

How can I stop sharing the root admin file with developers?

Create namespace roles and bind them to specific user accounts or service accounts in the cluster. Generate a separate credential file that contains only the scoped token for that specific role. Never distribute the original server admin file outside of your core platform setup scripts.

The query runs. The emails stay hidden.