> For the complete documentation index, see [llms.txt](https://docs.qpoint.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qpoint.io/getting-started/qplane/configuration/organizations-and-environments.md).

# 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

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

{% hint style="info" %}
**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.
{% endhint %}

***

## 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:

```bash
# 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](/getting-started/qplane/installation/linux-binary.md), [Docker](/getting-started/qplane/installation/docker-container.md), [Helm](/getting-started/qplane/installation/helm-chart.md)) for detailed examples.

### Using Tags in Qplane

Once agents are tagged:

1. **Filter Traffic**: Navigate to Traffic → Logs, click filter icon, add tag filters (Environment=Production)
2. **Create Views**: Settings → Views → Add tag-based filters → Assign to team members
3. **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:**

1. **Do environments need different users?**
   * Yes → Use separate Organizations (Pattern C)
   * No → Use Installations or Tags (Pattern A or B)
2. **Do environments need separate registration tokens?**
   * Yes → Use separate Installations (Pattern A)
   * No → Use Tags (Pattern B)
3. **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             |

{% hint style="info" %}
**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.
{% endhint %}

### 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

{% hint style="info" %}
**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.
{% endhint %}

***

## 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.

***

## Configuration Sharing

{% hint style="warning" %}
**Important:** Configuration settings (stacks, plugins, routing, filters) are **organization-wide**. All installations within an organization share the same configuration.
{% endhint %}

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:**

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:**

* [Stacks & Plugins](/getting-started/qplane/configuration/stacks-and-plugins.md) - Configure traffic processing
* [Settings](/getting-started/qplane/configuration/settings.md) - Manage team members and RBAC
* [How It Fits Together](/getting-started/qplane/configuration/how-it-fits-together.md) - Understand the overall architecture