Organizations & Environments

Understanding how to structure your Qplane deployment using organizations, installations, and role-based access control (RBAC).

Hierarchy Overview

Qplane uses a flexible hierarchy that allows you to organize your infrastructure and control access at multiple levels:

Account (User)
  └── Organization 1
      ├── Installation 1 (Production)
      │   ├── Registration Token
      │   └── Connected Agents
      ├── Installation 2 (Staging)
      │   ├── Registration Token
      │   └── Connected Agents
      └── Installation 3 (Development)
          ├── Registration Token
          └── Connected Agents
  └── Organization 2
      ├── Installation 1 (Customer A - Production)
      └── Installation 2 (Customer A - Staging)
  └── Organization 3
      └── Installation 1 (Team B - Shared Environment)

Key Concepts:

  • Account: Your individual user account

  • Organization: Top-level isolation boundary (unlimited per account)

  • Installation: Environment within an organization (e.g., prod, staging, dev)

  • Registration Token: Unique credential for each installation to connect agents

  • Agents: Individual Qtap instances connected to an installation

Organizations

Organizations are the primary way to separate concerns in Qplane. Each organization is completely isolated with its own:

  • Configuration (stacks, plugins, routing rules)

  • Data (traffic, inventory, dashboards)

  • Team members and permissions

  • Installations and agents

When to Create Multiple Organizations

Separate customers or tenants:

Organization: Customer A
Organization: Customer B
Organization: Customer C

Separate business units or teams:

Organization: Engineering
Organization: Security
Organization: Platform

Separate testing from production:

Organization: Production
Organization: Non-Production

Creating an Organization

  1. Click the organization selector in the top-left corner

  2. Click + New Organization

  3. Enter an organization name

  4. Click Create

You can switch between organizations using the organization selector at any time.

Installations (Environments)

Installations represent environments within an organization. Each installation has:

  • A unique registration token for connecting agents

  • Its own set of connected agents

  • Shared configuration from the parent organization

Common Installation Patterns

Traditional environments:

Organization: My Company
  ├── Installation: Production
  ├── Installation: Staging
  └── Installation: Development

Geographic regions:

Organization: Global Infrastructure
  ├── Installation: US East
  ├── Installation: US West
  ├── Installation: EU Central
  └── Installation: APAC

Kubernetes clusters:

Organization: Platform Team
  ├── Installation: EKS Cluster 1 (us-east-1)
  ├── Installation: EKS Cluster 2 (us-west-2)
  └── Installation: GKE Cluster 1 (europe-west1)

Per-customer deployments:

Organization: SaaS Product
  ├── Installation: Customer A - Production
  ├── Installation: Customer A - Staging
  ├── Installation: Customer B - Production
  └── Installation: Customer B - Staging

Creating an Installation

  1. Navigate to Settings → Installations

  2. Click + Installation

  3. Enter an installation name (e.g., "Production", "Staging-US-East")

  4. Copy the generated registration token

  5. Use the token when deploying Qtap agents

Configuration is organization-wide: All installations in an organization share the same stacks, plugins, routing rules, and filters. Changes to configuration affect all installations within that organization.

Role-Based Access Control (RBAC)

Qplane provides granular roles to control user permissions across different aspects of the platform.

Roles

Full Access

Role
Permissions

Owner

Complete control with no restrictions

Administrator

Full account access except team management

Security Roles

Role
Permissions

Security Manager

Can modify security policies and vendor firewall configuration

Security Viewer

Read-only access to security policies and firewall settings

View Management

Role
Permissions

View Manager

Can create and manage organization views (RBAC filters)

Root Viewer

Can view inventory and traffic without custom views (bypasses view restrictions)

Traffic & Configuration

Role
Permissions

Traffic Manager

Can modify rules and configuration (stacks, rules, alerts, etc.)

Traffic Viewer

Read-only access to inventory, traffic, analytics, and errors

Limited Access

Role
Permissions

Payload Viewer

Can view payloads persisted via rules engine

Log Viewer

Can view traffic logs and errors

Key Distinction: "Manager" roles can modify, "Viewer" roles are read-only. The hierarchy goes from Owner (full control) down to specific read-only roles for different data types.

Inviting Team Members

  1. Navigate to Settings → Team

  2. Click + Invite Member

  3. Enter their email address

  4. Select a role from the list above

  5. Click Send Invitation

The user will receive an email invitation to join your organization.

Access Control Strategies

Qplane offers multiple ways to control access to your data:

Strategy 1: Organization-Level Separation

Use Case: Completely isolate different teams, customers, or environments

Approach: Create separate organizations

Example:

Organization: Production (Owners: SRE team)
  └── Installation: Production US
  └── Installation: Production EU

Organization: Development (Owners: Engineering team)
  └── Installation: Dev Environment
  └── Installation: QA Environment

Benefits:

  • Complete data isolation

  • Different teams manage different organizations

  • Independent configurations

Access Control:

  • SRE team has Owner access to Production organization only

  • Engineering team has Owner access to Development organization only

  • Security team could have Root Viewer access to both

Strategy 2: Installation-Level Identification

Use Case: Same team manages multiple environments, but you want to identify which environment generated traffic

Approach: Use a single organization with multiple installations

Example:

Organization: My Company
  ├── Installation: Production
  ├── Installation: Staging
  └── Installation: Development

Benefits:

  • Centralized configuration management

  • All team members see all environments

  • Easy to compare traffic across environments

Access Control:

  • All team members have access to all installations

  • Use views (see below) to filter data by environment if needed

Strategy 3: View-Based Filtering

Use Case: Granular access control within a single organization

Approach: Use Views to create filtered perspectives on your data

Example:

Organization: Platform Team
  └── Installation: Shared Kubernetes Cluster

Views:
  - "Payment Service" (filters to payment-api container)
    - Team: Alice, Bob (Payment team)
  - "Auth Service" (filters to auth-api container)
    - Team: Carol, Dave (Auth team)
  - "Frontend" (filters to web-frontend container)
    - Team: Eve, Frank (Frontend team)

How Views Work:

  1. Navigate to Settings → Views

  2. Click + New View

  3. Enter a name and description

  4. Add filters (by container, pod labels, domain, etc.)

  5. Assign team members who can use this view

Access Control:

  • Root Viewer role can see all data without a view

  • Non-Root Viewers only see data through their assigned views

  • Each view acts as a lens that filters Traffic, Inventory, and Dashboard pages

Views are UI-only filters: They don't change what Qtap captures or stores. They only control what users see in the Qplane dashboards. A user without access to a view will see "No Records" for data outside their view.

Recommended Patterns

Pattern 1: Environment Separation (Small Teams)

Best for: Small teams managing dev, staging, and production

Account: Your Account
  └── Organization: My Company
      ├── Installation: Production
      ├── Installation: Staging
      └── Installation: Development

Access:

  • Engineers: Traffic Manager role (can modify stacks, rules, alerts)

  • Leadership: Root Viewer role (can view all data)

  • On-call rotation: Traffic Viewer + Log Viewer roles (read-only access to troubleshoot)

Why it works: Simple structure, centralized configuration, everyone has visibility

Pattern 2: Multi-Tenant SaaS (Managed Service)

Best for: SaaS providers managing multiple customer environments

Account: Your Account
  ├── Organization: Customer A
  │   ├── Installation: Production
  │   └── Installation: Staging
  ├── Organization: Customer B
  │   ├── Installation: Production
  │   └── Installation: Staging
  └── Organization: Internal
      └── Installation: Our Infrastructure

Access:

  • Your team: Owner on all organizations

  • Customer A stakeholders: Traffic Viewer on Customer A organization only

  • Customer B stakeholders: Traffic Viewer on Customer B organization only

Why it works: Complete customer isolation, customers can view their own data

Pattern 3: Large Organization with Multiple Teams

Best for: Enterprises with many teams sharing infrastructure

Account: Your Account
  └── Organization: Company Platform
      └── Installation: Production Kubernetes Cluster

Views:
  - "Payment Services" → Payment team
  - "Auth Services" → Security team
  - "Data Pipeline" → Data team
  - "API Gateway" → Platform team
  - "Frontend Apps" → Product team

Access:

  • Platform team: Owner role (manages everything)

  • Individual teams: Traffic Viewer role + assigned views (see only their services)

  • Leadership: Root Viewer role (see everything without view restrictions)

Why it works: Centralized platform management, teams see only their services, no configuration conflicts

Pattern 4: Multi-Region Deployment

Best for: Teams managing multiple geographic regions or cloud providers

Account: Your Account
  └── Organization: Global Platform
      ├── Installation: AWS US-East-1
      ├── Installation: AWS US-West-2
      ├── Installation: GCP Europe-West1
      └── Installation: Azure East-Asia

Access:

  • Global SRE team: Owner role

  • Regional teams: Traffic Manager role (can modify configs for all regions)

  • Regional on-call: Traffic Viewer role (read-only access to their region via views)

Why it works: One configuration applied globally, installation names identify traffic source

Configuration Sharing

Important: Configuration settings (stacks, plugins, routing, filters) are organization-wide. All installations within an organization share the same configuration.

This means:

  • ✅ Change a stack → affects all installations in the organization

  • ✅ Add a routing rule → applies to all installations in the organization

  • ✅ Update filters → filters all installations in the organization

If you need different configurations:

  • Create separate organizations (each has independent configuration)

  • Example: "Production" organization with strict error-only capture, "Development" organization with full debug capture

Decision Matrix

Use this matrix to decide how to structure your deployment:

Need
Solution

Completely isolate customer data

Separate organizations per customer

Different configurations for prod vs dev

Separate organizations (one for prod, one for dev)

Same config everywhere, just identify source

Single organization, multiple installations

Limit team access to specific services

Single organization, use Views

Geographic/region identification

Single organization, installations per region

Multi-cloud visibility

Single organization, installations per cloud/cluster

Next Steps

Set up your organization structure:

  1. Decide on your organization strategy using the patterns above

  2. Create organizations via the organization selector

  3. Create installations for each environment

Configure access control:

  1. Invite team members via Settings → Team

  2. Assign appropriate roles (Owner, Administrator, Root Viewer)

  3. Create Views if you need granular filtering

Deploy agents:

  1. Get registration tokens from Settings → Installations

  2. Deploy Qtap agents with the appropriate token

  3. Verify agents are connected

Related Documentation:

PreviousConfigurationNextAlerting

Last updated