Rancher Projects and Centralized Auth: How to Stop Handing Out Cluster-Wide kubeconfigs

If your team manages more than one Kubernetes cluster, you've probably hit the same wall: every new engineer needs a kubeconfig, every namespace needs its own RoleBindings, and when someone leaves, you're grepping clusters for stale access. Rancher's answer to this is a combination of centralized authentication and its Project abstraction — and used together, they let you grant scoped, multi-namespace access across clusters from one place.

The thesis of this post: Rancher Projects are the right unit of access control for most platform teams, but only if you treat Rancher as the single source of truth and resist the urge to hand-edit RBAC on downstream clusters.

What a Rancher Project actually is

Kubernetes has namespaces, but namespaces are a poor fit for how teams work. A team usually owns several namespaces — dev, staging, maybe a shared tooling namespace — and you end up duplicating RoleBindings, ResourceQuotas, and NetworkPolicies in each one.

A Rancher Project is a layer above namespaces. You create a Project inside a cluster, move namespaces into it, and then define quotas, member roles, and (optionally) network isolation once, at the Project level. Rancher translates that into the underlying Kubernetes RBAC objects for you. A user added to a Project with the "Member" role gets working access to every namespace in that Project — and to any namespace you add later — without you touching kubectl.

Two things worth knowing:

• Projects are per-cluster. There is no global Project spanning clusters; you grant access per cluster, though the same identity flows everywhere.
• Namespaces can only belong to one Project at a time. Plan your grouping before you migrate namespaces in.

Centralized authentication: one login, many clusters

Rancher supports external identity providers including Active Directory, LDAP, GitHub, and several OIDC/SAML options. Once configured, authentication happens at the Rancher manager, and Rancher issues kubeconfig tokens that proxy through it. The practical effect:

• Engineers download a kubeconfig from Rancher that works against every cluster they have access to — one file, multiple contexts.
• Revoking access is a single operation: remove the user from Projects (or disable them in the IdP), and their tokens stop working across all managed clusters.
• Authorization still lands as real Kubernetes RBAC on the downstream clusters, so audit logs on those clusters remain meaningful.

This is the feature that usually sells the platform team: onboarding becomes "add the person to the right Projects" instead of "generate certs, write RoleBindings, distribute kubeconfigs."

A worked example: onboarding a payments team

Say you have an imported cluster called prod-eu and a new team that owns payments-dev and payments-staging. The flow, all from the Rancher UI (or the Rancher API if you prefer automation):

1. In prod-eu, create a Project named payments.
2. Set a Project-level ResourceQuota, e.g. 16 CPU / 32Gi memory total, with per-namespace limits so one namespace can't consume the whole budget.
3. Move payments-dev and payments-staging into the Project.
4. Add the team's IdP group (e.g. an AD group) as Project Members, and one senior engineer as Project Owner.
5. Each engineer goes to the cluster's page in Rancher, clicks "Download kubeconfig," and selects the context for the cluster.

Verification is straightforward and worth doing: as one of the new users, run kubectl get pods -n payments-dev (should succeed) and kubectl get pods -n kube-system (should be forbidden). Also check that the quota actually bites by attempting a deployment that would exceed it. Don't assume the role mapping worked — prove it with a denied request, not just an allowed one.

Registering clusters: the agent model

None of this works until Rancher manages the cluster. Importing an existing cluster generates a registration command — a kubectl apply of a manifest — that you run against the downstream cluster with cluster-admin credentials. It deploys the cattle-cluster-agent, which opens a secure outbound tunnel back to the Rancher manager. No inbound firewall rules to the downstream cluster are needed, which is why this works for clusters behind NAT or in other clouds.

After applying, check that the agent pods are running in the cattle-system namespace and that the cluster shows "Active" in the Rancher dashboard. If it sits in "Pending" or "Unavailable," the usual culprits are outbound network restrictions or a Rancher server URL the agent can't reach or doesn't trust (self-signed certificates are a classic).

The trade-offs you should accept up front

The manager is a management-plane single point of failure. If Rancher goes down, your workloads keep running — but nobody can authenticate through Rancher-issued kubeconfigs, and you lose the management UI. Mitigate by running the Rancher manager in an HA configuration (a three-node install on its own dedicated cluster is the standard recommendation) and keeping at least one break-glass, direct-to-cluster credential stored safely offline.

Configuration drift is real. Rancher writes RBAC and quotas into the downstream cluster, but nothing stops someone with direct cluster access from editing those objects with kubectl. Rancher will often reconcile its own resources back, but not everything is reconciled, and the UI becomes a lie. The discipline rule: if it's visible in Rancher, change it in Rancher (or via its API/Terraform provider), never by hand.

Agent overhead is small but nonzero. The cluster and node agents consume CPU and memory on downstream nodes. On tiny edge clusters, measure before you commit.

Where to start

Pick one non-production cluster, import it, wire up your identity provider, and build a single Project with a quota and a test user. Verify access with both an allowed and a denied kubectl call. If that workflow feels better than your current kubeconfig sprawl — and it usually does — you have your template for rolling it out to the rest of the fleet.