Merge pull request #986 from layer5io/feat/narrative-970-roles

[Docs] Illustrate cloud/security/roles with Provider Admin to Org Admin to Team Admin chain

Author: leecalcote

content/en/cloud/security/roles/_index.md

@@ -213,4 +213,36 @@ Team owners carry the team administrator role, and may be joined in their team a
 The entitlement of "team owner" is automatically bestowed to the creator of a team. The individual user who created a given team initially is therefore granted certain administrative privileges beyond that of other team administrators. Specifically, team owners retain the sole permission to delete the team.
 
 For more information, see [Teams](/cloud/identity/teams).
+{{< /alert >}}
+
+## Example: The Orbital Labs Role Hierarchy
+
+The following illustrates how Provider Admin, Org Admin, and Team Admin roles stack in practice across the Orbital Labs ecosystem. See [Meet Five and the Cast](/cloud/about) for the full narrative.
+
+<img src="/images/five/layer5-five-mascot-means-business.svg" alt="Five means business" style="width:90px; float:right; margin-left:1.5rem; margin-bottom:1rem;" />
+
+{{< cardpane >}}
+{{% card header="**Dr. Aiko Sato** — Provider Admin" %}}
+**Organization:** Constellation Cloud  
+**Scope:** All tenants (Orbital Labs, Stellar Dynamics, and others)
+
+Dr. Aiko Sato holds the Provider Admin role at Constellation Cloud, the MSP that manages Orbital Labs as a tenant. Provider Admins can perform CRUD on all resources across all tenant organizations. Dr. Sato has seen every misconfigured RBAC policy known to humankind, which is why she documents each one.
+{{% /card %}}
+{{% card header="**Maya Chen** — Organization Administrator" %}}
+**Organization:** Orbital Labs  
+**Scope:** All resources within Orbital Labs
+
+Maya Chen holds the Org Admin role for Orbital Labs. She manages user accounts, team membership, workspace creation, and role assignments within Orbital Labs. She also serves as Team Admin for the Development team — an Org Admin may administer any team in their organization.
+{{% /card %}}
+{{% card header="**Zara Osei** — Team Administrator" %}}
+**Organization:** Orbital Labs  
+**Team:** Infrastructure  
+**Scope:** Infrastructure team members and their workspace access
+
+Zara Osei holds the Team Admin role for Orbital Labs' Infrastructure team. She manages keychain assignments for Five and controls which environments the Infrastructure team can access. Access requests go through Zara's 48-hour SLA — no exceptions, no matter how urgent Five thinks the situation is.
+{{% /card %}}
+{{< /cardpane >}}
+
+{{< alert type="info" >}}
+Role assignments are org-scoped. Dr. Aiko's Provider Admin role spans all tenants; Maya's Org Admin role applies only within Orbital Labs; Zara's Team Admin role applies only to the Infrastructure team within Orbital Labs.
 {{< /alert >}}

content/en/cloud/spaces/environments.md

@@ -42,3 +42,50 @@ Connections are an integral part of Environment. These are cloud native resource
 Credentials in an Environment are the keys to securely authenticate and access managed connections. For example, valid Prometheus secrets or Kubernetes API tokens are essential credentials for securely interacting with these managed resources.
 
 > See "[Credentials](https://docs.meshery.io/concepts/logical/credentials)" in Meshery Docs for more information.
+
+## Example: Orbital Labs Environment Setup
+
+The following illustrates how Five and Zara set up multi-cloud environments at Orbital Labs, spanning AWS, GCP, and Azure. See [Meet Five and the Cast](/cloud/about) for the full seed inventory.
+
+### Environment Inventory
+
+| Environment | Workspace | Cloud Provider | Connections |
+|---|---|---|---|
+| `prod-aws` | orbital-production | AWS | EKS cluster, RDS (PostgreSQL), S3, CloudFront, SQS |
+| `prod-gcp` | orbital-production | GCP | GKE cluster, Cloud SQL, Cloud Storage, Pub/Sub |
+| `staging-aws` | orbital-staging | AWS | EKS cluster, S3, ElastiCache |
+| `staging-azure` | orbital-staging | Azure | AKS cluster, Azure Blob Storage, Azure Service Bus |
+| `dev-local` | orbital-dev | Local | kind (local Kubernetes), LocalStack (AWS emulation) |
+| `stellar-enterprise` | stellar-main | Azure | AKS, Azure SQL, Azure API Management, Azure AD |
+
+### Connecting prod-aws
+
+Five connects Orbital Labs' primary AWS production environment to Layer5 Cloud:
+
+1. Navigate to **Environments** and click **Create Environment**
+2. Name it `prod-aws` and save
+3. Add connections one at a time — each connection is a discrete cloud resource:
+   - **EKS cluster** — the compute layer for deployed workloads
+   - **RDS (PostgreSQL)** — the managed database instance
+   - **S3 bucket** — object storage for design artifacts and state
+   - **CloudFront distribution** — CDN layer for the frontend
+   - **SQS queue** — async messaging between services
+4. Zara assigns `prod-aws` to the `orbital-production` workspace, making all five connections available to Infrastructure team members
+
+### Adding prod-gcp for Multi-Cloud Coverage
+
+Five repeats the process for GCP to give Orbital Labs multi-cloud flexibility:
+
+1. Create environment `prod-gcp`
+2. Add connections:
+   - **GKE cluster** — Google Kubernetes Engine compute
+   - **Cloud SQL** — managed relational database on GCP
+   - **Cloud Storage bucket** — GCP object storage
+   - **Pub/Sub topic** — async messaging on GCP
+3. Zara assigns `prod-gcp` to `orbital-production` alongside `prod-aws`
+
+Both environments are now available to any design deployed within the `orbital-production` workspace.
+
+{{< alert type="info" title="dev-local for Getting Started" >}}
+The `dev-local` environment uses a local Kubernetes cluster (kind) and LocalStack to emulate AWS services — no cloud credentials required. If you are following along with these docs for the first time, start with `dev-local` in the `orbital-dev` workspace.
+{{< /alert >}}

content/en/cloud/spaces/workspaces.md

@@ -84,3 +84,33 @@ Workspaces enhance collaboration within your teams, providing a structured envir
 {{< alert type="info" title="Looking for Practical Workspace Management?" >}}
 For a step-by-step guide on how to create, edit, and manage your workspaces, see the [Managing Workspaces](/cloud/spaces/managing-workspaces/) documentation.
 {{< /alert >}}
+
+## Example: Orbital Labs Workspace Setup
+
+The following illustrates how Five and Maya set up workspaces at Orbital Labs to segment access across infrastructure and development workflows. See [Meet Five and the Cast](/cloud/about) for the full seed inventory.
+
+### Workspace Inventory
+
+| Workspace | Owner Org | Teams with Access | Environments |
+|---|---|---|---|
+| `orbital-production` | Orbital Labs | Infrastructure only | `prod-aws` (EKS + RDS + S3 + CloudFront + SQS), `prod-gcp` (GKE + Cloud SQL + Cloud Storage + Pub/Sub) |
+| `orbital-staging` | Orbital Labs | Infrastructure + Development | `staging-aws` (EKS + S3 + ElastiCache), `staging-azure` (AKS + Azure Blob + Azure Service Bus) |
+| `orbital-dev` | Orbital Labs | Development only | `dev-local` (kind + LocalStack) |
+
+### Creating orbital-staging
+
+Five creates the `orbital-staging` workspace to give the Development team a shared environment for feature-branch testing — without handing them the keys to production.
+
+**Steps Five follows:**
+1. Navigate to **Workspaces** and click **Create Workspace**
+2. Name the workspace `orbital-staging`
+3. Save — the workspace is created with no team access and no environments assigned
+
+**Maya then assigns team access:**
+1. Open the `orbital-staging` workspace settings
+2. Add the **Infrastructure** team — enabling Zara and Five to manage environment connections
+3. Add the **Development** team — enabling Rex and Jordan to deploy designs and use connections
+
+{{< alert type="info" title="Why both teams?" >}}
+Infrastructure owns the environments (Zara assigns connections); Development owns the designs (Rex and Jordan deploy them). Assigning both teams to `orbital-staging` gives each group the access it needs without elevating Development's access to `orbital-production`.
+{{< /alert >}}