# 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.qpoint.io/getting-started/qplane/configuration/organizations-and-environments.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.