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 (with optional tags)
      ├── Installation 2 (Staging)
      │   ├── Registration Token
      │   └── Connected Agents (with optional tags)
      └── Installation 3 (Development)
          ├── Registration Token
          └── Connected Agents (with optional tags)
  └── Organization 2
      ├── Installation 1 (Customer A - Production)
      └── Installation 2 (Customer A - Staging)
  └── Organization 3
      └── Installation 1 (Team B - Shared Environment)
          └── Connected Agents
              - Agent with tags: Environment:Prod,Region:US-East
              - Agent with tags: Environment:Staging,Region:EU-West

Key Concepts:

Account: Your individual user account
Organization: Top-level isolation boundary (unlimited per account) - separate users, configs, data
Installation: Token boundary within an organization (e.g., prod, staging, dev, or clusters)
Registration Token: Unique credential for each installation to connect agents
Agents: Individual Qtap instances (typically DaemonSets in Kubernetes) connected to an installation
Agent Tags: Optional key:value metadata on agents for UI filtering within Qplane dashboards

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

Click the organization selector in the top-left corner
Click + New Organization
Enter an organization name
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

Navigate to Settings → Installations
Click + Installation
Enter an installation name (e.g., "Production", "Staging-US-East")
Copy the generated registration token
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.

Agent Tags

Agent tags are optional key:value pairs (e.g., Environment:Production,Region:US-East) that you pass when starting Qtap agents. Tags appear in Qplane dashboards and enable UI-level filtering of traffic, inventory, and logs.

When to Use Tags

Tags provide soft partitioning - they don't change what gets captured or create access boundaries, but they let you filter within Qplane:

Filter dashboards: "Show only Production traffic"
Compare across dimensions: "US-East vs EU-West error rates"
Create Views: "Payment team sees only Region:US-East traffic"
Flexible organization without creating multiple installations

Setting Tags

Tags are passed via the --tags CLI flag when starting Qtap:

# Linux binary
qtap --registration-token=$TOKEN --tags="Environment:Production,Region:US-East"

# Docker
docker run ... \
  -e QTAP_ENVIRONMENT="Production" \
  -e QTAP_REGION="US-East" \
  us-docker.pkg.dev/qpoint-edge/public/qtap:v0 \
  --registration-token=$TOKEN \
  --tags="Environment:${QTAP_ENVIRONMENT},Region:${QTAP_REGION}"

# Helm
helm install qtap qpoint/qtap \
  --set registrationToken=$TOKEN \
  --set extraArgs="{--tags=Environment:Production\,Region:US-East}"

See installation guides (Linux Binary, Docker, Helm) for detailed examples.

Using Tags in Qplane

Once agents are tagged:

Filter Traffic: Navigate to Traffic → Logs, click filter icon, add tag filters (Environment=Production)
Create Views: Settings → Views → Add tag-based filters → Assign to team members
Monitor Agents: Settings → Deploy → Environments → See all connected agents with their tags

Three Ways to Partition

Qplane offers three complementary levels of partitioning. You can use them individually or combine them depending on your needs:

Level

Separation Type

Use When

Example

Organizations

Hard - separate users, configs, data

Need complete isolation

Separate orgs for customers, or prod vs dev with different teams

Installations

Medium - separate tokens

Need token boundaries

Prod vs staging, or multi-cluster

Tags

Soft - UI filtering only

Just need to filter dashboards

Environment, region, cluster name

The same deployment can be organized multiple ways:

Pattern A: Use Installations for Environments

Best for: Teams that want hard token boundaries between environments

Organization: MyCompany
  Installation: Production (token A)
    └── Agents with tags: Region:US-East, Region:EU-West
  Installation: Staging (token B)
    └── Agents with tags: Region:US-East

Why:

✅ Separate registration tokens (security boundary)
✅ Can use Views to limit staging access to certain users
✅ Still use tags for regional filtering within each environment

Pattern B: Use Tags for Environments

Best for: Teams that want one token across all environments

Organization: MyCompany
  Installation: All-Clusters (one token)
    └── Agents with tags:
        - Environment:Production,Region:US-East
        - Environment:Production,Region:EU-West
        - Environment:Staging,Region:US-East

Why:

✅ Simpler: one registration token
✅ Easier config management (one installation)
✅ Use Views to filter prod vs staging in UI
⚠️ No token boundary between environments

Pattern C: Use Organizations for Environments

Best for: Teams that need separate user access and different configs

Organization: Production
  └── Installation: Prod-Cluster
      └── Agents (maybe tagged by region)

Organization: Staging
  └── Installation: Staging-Cluster
      └── Agents (maybe tagged by region)

Why:

✅ Complete isolation (different configs possible)
✅ Different users per environment
✅ Strictest separation
⚠️ More overhead (managing multiple orgs)

Choosing Your Pattern

Ask yourself:

Do environments need different users?
- Yes → Use separate Organizations (Pattern C)
- No → Use Installations or Tags (Pattern A or B)
Do environments need separate registration tokens?
- Yes → Use separate Installations (Pattern A)
- No → Use Tags (Pattern B)
Do environments need different configurations?
- Yes → Use separate Organizations (Pattern C)
- No → Single organization works

Most common: Pattern A (Installations for environments, Tags for regions/clusters)

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

Navigate to Settings → Team
Click + Invite Member
Enter their email address
Select a role from the list above
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:

Navigate to Settings → Views
Click + New View
Enter a name and description
Add filters (by container, pod labels, domain, etc.)
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

Alternative with tags: Could use single installation with Environment:Production and Environment:Staging tags if you don't need separate tokens. Filter environments using tag-based Views.

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

Alternative with tags: If regions share the same environment (e.g., all production), use one installation with tags like Region:US-East, Region:EU-West, Cloud:AWS, Cloud:GCP. Filter regions in dashboards using tag filters or Views.

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)

Different users for prod vs dev

Separate organizations

Separate tokens for prod vs dev

Separate installations (Production, Staging)

Same config + same token, just filter UI

Single installation + agent tags (Environment:Prod, Environment:Staging)

Limit team access to specific services

Single organization, use Views (can filter by tags)

Geographic/region identification

Single installation + agent tags (Region:US-East, Region:EU-West) OR multiple installations

Multi-cloud visibility

Single installation + agent tags (Cloud:AWS, Cloud:GCP) OR multiple installations

Filter by cluster in multi-cluster deployment

Agent tags (Cluster:EKS-Prod-1, Cluster:GKE-Prod-2)

Compare metrics across dimensions

Agent tags + Qplane dashboard filters

Next Steps

Set up your organization structure:

Decide on your organization strategy using the patterns above
Create organizations via the organization selector
Create installations for each environment

Configure access control:

Invite team members via Settings → Team
Assign appropriate roles (Owner, Administrator, Root Viewer)
Create Views if you need granular filtering

Deploy agents:

Get registration tokens from Settings → Installations
Deploy Qtap agents with the appropriate token
Verify agents are connected

Related Documentation:

Stacks & Plugins - Configure traffic processing
Settings - Manage team members and RBAC
How It Fits Together - Understand the overall architecture

PreviousConfiguration NextAlerting

Last updated 1 month ago

Hierarchy Overview

Organizations

When to Create Multiple Organizations

Creating an Organization

Installations (Environments)

Common Installation Patterns

Creating an Installation

Agent Tags

When to Use Tags

Setting Tags

Using Tags in Qplane

Three Ways to Partition

Pattern A: Use Installations for Environments

Pattern B: Use Tags for Environments

Pattern C: Use Organizations for Environments

Choosing Your Pattern

Role-Based Access Control (RBAC)

Roles

Inviting Team Members

Access Control Strategies

Strategy 1: Organization-Level Separation

Strategy 2: Installation-Level Identification

Strategy 3: View-Based Filtering

Recommended Patterns

Pattern 1: Environment Separation (Small Teams)

Pattern 2: Multi-Tenant SaaS (Managed Service)

Pattern 3: Large Organization with Multiple Teams

Pattern 4: Multi-Region Deployment

Configuration Sharing

Decision Matrix

Next Steps