Isolating Docker Endpoints by Team in Portainer: A Practical RBAC Setup

The Problem: Shared Portainer, Leaky Visibility

You run a single Portainer instance that manages Docker hosts for multiple teams—platform, data engineering, and a few product squads. Today, everyone who logs in sees every endpoint. A platform engineer can accidentally restart a data-science GPU node; a product developer can view logs from the payments stack. You need each team to see only the endpoints they own, without standing up separate Portainer instances.

Portainer's built-in Role-Based Access Control (RBAC) solves this at the endpoint level. The mechanism is straightforward: create a team, assign it to one or more endpoints with a specific role, and add users to that team. Users who aren't on a team linked to an endpoint simply don't see it in the UI or API. This post walks through a concrete setup, the trade-offs you accept, and how to verify it works.

Core Concepts: Organizations, Teams, Endpoints, Roles

Portainer groups access control around four objects:

• Organization – a top-level container for teams and users (Community Edition has a single default organization).
• Team – a named group of users (e.g., platform-team, data-team).
• Endpoint – a Docker host or Kubernetes cluster managed by Portainer (local, remote via Agent, or Edge).
• Role – the permission set granted to a team on an endpoint: Administrator (full control), Standard User (deploy stacks, manage containers, networks, volumes), or Read-Only (view only).

A user must belong to at least one team that has an explicit endpoint assignment. No assignment means the endpoint is invisible to that user. Permissions are evaluated at the endpoint level; you cannot restrict a team to a single container or image within an endpoint using core RBAC alone.

Worked Example: Isolating Two Teams to Separate Endpoints

Assume you have two Docker hosts already registered in Portainer:

• endpoint-1 (name: platform-prod, ID: 2)
• endpoint-2 (name: data-gpu-cluster, ID: 3)

You want the platform team to manage only platform-prod and the data team to manage only data-gpu-cluster.

Step 1: Create Teams

In the admin UI, go to Settings → Access Control → Teams and add two teams:

Team name: platform-team
Team name: data-team

No users yet—just the empty teams.

Step 2: Assign Teams to Endpoints with Roles

Still under Settings → Access Control → Teams, open each team and add an endpoint association:

• platform-team → Endpoint platform-prod (ID 2) → Role: Standard User
• data-team → Endpoint data-gpu-cluster (ID 3) → Role: Standard User

Do not assign either team to the other endpoint. Save each assignment.

Step 3: Create Test Users and Add to Teams

Go to Settings → Access Control → Users → Add user:

Username: alice-platform
Password: (set or invite via email)
Team membership: platform-team

Username: bob-data
Password: (set or invite via email)
Team membership: data-team

Both users are regular (non-admin) accounts.

Step 4: Verify Isolation

1. Open an incognito browser window. Log in as alice-platform.
2. Confirm the left navigation shows only platform-prod under Endpoints. data-gpu-cluster is absent.
3. Log out, log in as bob-data. Confirm only data-gpu-cluster appears.
4. As an admin, verify the team-to-endpoint matrix under Settings → Access Control → Endpoints shows the expected assignments.

If a user sees no endpoints at all, they likely have no team membership or the team lacks an endpoint assignment. Session tokens may cache the old view; have the user log out and back in (or wait for token expiry) if changes don't appear immediately.

Trade-offs and Limitations

• Endpoint granularity only. You cannot say "team X may manage only the payments stack on endpoint Y." If a team has Standard User on an endpoint, they can deploy any stack, start any container, and attach to any network on that host.
• Community vs. Business Edition gating. Core RBAC (teams, endpoints, three roles) is in Community Edition. Fine-grained registry permissions, stack-level restrictions, and audit logging may require Business Edition depending on your Portainer version. Check Settings → About and the release notes for your exact version.
• RBAC is not Docker daemon security. Portainer RBAC controls what the UI and API allow. It does not replace rootless Docker, user namespaces, host firewalls, or TLS-authenticated Docker daemon sockets. A user with docker CLI access to the host bypasses Portainer entirely.
• Session refresh delay. Team membership or endpoint assignment changes may not reflect until the user's JWT expires or they re-authenticate. Plan for a short propagation window.

Practical Verification Checklist

After any RBAC change, run through this quick checklist:

1. Admin UI: Settings → Access Control → Teams – confirm each team has exactly the intended endpoint-role rows.
2. Admin UI: Settings → Access Control → Endpoints – verify the matrix shows green checkmarks only where expected.
3. Test login: incognito window per test user – confirm endpoint list matches assignment.
4. API spot-check (optional): GET /api/endpoints with the user's JWT – response should contain only permitted endpoint objects.

Closing Action

If you're running a single Portainer instance for multiple teams, start by mapping each team to the exact endpoints they should manage. Create the teams, assign endpoints with the least-privilege role (usually Standard User), add users, and verify with an incognito login. Document the team-to-endpoint matrix in your runbook so on-call engineers can audit it during incidents. When you need finer control—per-stack or per-registry—evaluate whether Business Edition features or a separate authorization layer (e.g., OPA policies on the Docker daemon) fit your threat model.