Merge pull request #994 from layer5io/feat/cloud-docs-improvements

leecalcote · web-flow · commit 83d436d5361d · 2026-04-28T23:59:58.000-05:00
docs: make cloud overview more descriptive
diff --git a/content/en/cloud/concepts/_index.md b/content/en/cloud/concepts/_index.md
@@ -1,12 +1,39 @@
 ---
 title: Concepts
 weight: 2
+draft: false
 description: >
   An overview of Layer5 Cloud concepts and their relationships.
 ---
 
+The Layer5 Cloud provides a comprehensive suite of management tools for cloud-native infrastructure. Understanding the core entities and how they interact is essential for effectively managing your service meshes, clusters, and designs.
+
+## Core Entities
+
+The following concepts form the foundation of the Layer5 Cloud ecosystem:
+
+* **Workspaces:** Logical isolation boundaries for organizing team members, environments, and resources.
+* **Environments:** Specific deployment targets (e.g., Development, Staging, Production) within a Workspace.
+* **Designs:** Visual representations of your infrastructure patterns and service mesh configurations.
+* **Catalogs:** Repositories of reusable patterns and best practices shared across the community or organization.
+
 ![concepts-overview](images/concepts-overview.svg "image-center-shadow")
 
 This section explains the underlying concepts of Layer5 Cloud — the building blocks that the rest of the documentation assumes you understand.
 
 - [Meshery Server Registration](meshery-server-registration) — How a Meshery Server registers itself with Layer5 Cloud as its Remote Provider, how Cloud identifies an existing registration, and what fields are preserved across re-registration.
+
+---
+
+### Understanding Relationships
+
+To get the most out of Layer5 Cloud, it is important to understand how these components interact:
+
+| Concept | Relationship | Purpose |
+| :--- | :--- | :--- |
+| **User to Workspace** | Many-to-Many | Users can collaborate across multiple isolated workspaces. |
+| **Workspace to Environment** | One-to-Many | A single workspace can host multiple environments for lifecycle management. |
+| **Design to Catalog** | Many-to-One | Designs can be published to a catalog for broader consumption and version control. |
+
+### Next Steps
+For a deeper dive into the technical implementation of these concepts, please refer to our [Architecture Documentation](/docs/architecture).
diff --git a/content/en/cloud/getting-started/_index.md b/content/en/cloud/getting-started/_index.md
@@ -2,35 +2,49 @@
 title: Getting Started
 description: Learn how to effectively manage your organizations, teams, users, workspaces, environments, and more.
 weight: 1
+draft: false
 ---
-<!-- {{% pageinfo %}}
-Page under construction.
-{{% /pageinfo %}} -->
-<!-- Information in this section helps your user try your project themselves.
 
-* What do your users need to do to start using your project? This could include downloading/installation instructions, including any prerequisites or system requirements.
+The Layer5 Cloud provides a centralized management plane for your cloud-native infrastructure. This guide will help you set up your account and deploy your first design.
 
-* Introductory “Hello World” example, if appropriate. More complex tutorials should live in the Tutorials section.
+## Prerequisites
 
-Consider using the headings below for your getting started page. You can delete any that are not applicable to your project.
+Before you begin, ensure you have the following:
+* A [Layer5 Cloud account](https://cloud.layer5.io).
+* A running Kubernetes cluster (local or cloud-based).
+* [Meshery](https://docs.meshery.io/installation) installed and connected to your cluster.
 
-## Prerequisites
+## Installation and Setup
+
+Layer5 Cloud functions as a Remote Provider for Meshery. To get started:
 
-Are there any system requirements for using your project? What languages are supported (if any)? Do users need to already have any software or tools installed?
+1.  **Log in:** Navigate to your Meshery UI (usually `http://localhost:9081`).
+2.  **Select Provider:** On the login screen, select **Layer5 Cloud** from the provider dropdown.
+3.  **Authenticate:** You will be redirected to the Layer5 Cloud authentication page. Log in with your preferred identity provider (GitHub, Google, etc.).
 
-## Installation
+![layer5-cloud-provider](images/layer5-cloud-provider.svg "image-center-shadow")
 
-Where can your user find your project code? How can they install it (binaries, installable package, build from source)? Are there multiple options/versions they can install and how should they choose the right one for them?
+## Core Workflow
 
-## Setup
+Once authenticated, you can begin organizing your infrastructure using the following hierarchy:
 
-Is there any initial setup users need to do after installation to try your project?
+* **Organizations:** Create an Organization to manage your teams and billing.
+* **Workspaces:** Group your projects and resources logically.
+* **Environments:** Map your Kubernetes clusters to specific environments (e.g., Staging, Production).
 
 ## Try it out!
 
-Can your users test their installation, for example by running a command or deploying a Hello World example? -->
+To verify your setup, try deploying a sample design:
+
+1.  Navigate to the **Designs** section in the sidebar.
+2.  Click on **Import** and select a sample pattern from the Meshery Catalog.
+3.  Click **Deploy** and select your target Environment.
+
+---
+
+### Need Help?
+If you run into issues during setup, join our [Slack Community](http://slack.layer5.io) or check the [Troubleshooting Guide](/docs/troubleshooting).
+
 {{< alert type="info" title="Follow Along with Five" >}}
 Throughout these docs you'll follow Five — a Platform Engineer at Orbital Labs — and his colleagues as they set up organizations, configure workspaces, deploy designs, and navigate the occasional Friday-afternoon incident. [Meet Five and the full cast →]({{< relref "/cloud/about/_index.md" >}})
 {{< /alert >}}
-
-![layer5-cloud-provider](images/layer5-cloud-provider.svg "image-center-shadow")
diff --git a/content/en/cloud/identity/_index.md b/content/en/cloud/identity/_index.md
@@ -4,4 +4,23 @@ description: >
   Organizations, Teams, Users
 weight: 3
 categories: [Identity]
----
+---
+
+Organizations are the basic unit of multi-tenancy inside of Layer5 Cloud. The identity structure is highly flexible: organizations can have any number of teams, teams can have any number of users, and users can belong to any number of teams and organizations.
+
+Below is an overview of the core identity components within the Layer5 Cloud.
+
+## [Organizations](organizations)
+Organizations serve as the fundamental component of multi-tenancy within the Layer5 Cloud.
+
+They act as the top-level parent entity. All users and teams ultimately roll up to an organization. While Free plan users are limited to a single default organization, enterprise environments can leverage organizations to strictly isolate resources, billing, and access control across entirely different business units.
+
+## [Teams](teams)
+Outside of grouping users together, teams offer controlled access to workspaces and to workspace resources such as environments and managed and unmanaged connections.
+
+Administrators can create teams as child units below the top-level organization. This allows you to apply unique settings, permissions, and workspace access to a specific set of users without altering the parent organization's settings.
+
+## [Users](users)
+Each user account represents an individual collaborator. Individual user accounts exist beyond the bounds of organizations.
+
+Anyone who uses Layer5 Cloud signs into a user account, which acts as your sovereign identity. Your user account can independently own resources such as workspaces, designs, connections, and tokens. Any action taken on the platform—such as creating a design or reviewing a deployment request—is directly attributed to your individual user account, regardless of which teams or organizations you belong to.
diff --git a/content/en/cloud/overview/_index.md b/content/en/cloud/overview/_index.md
@@ -1,39 +1,27 @@
 ---
 title: Overview
-description: Here's where your user finds out if your project is for them.
-weight: 2
-categories: [Examples, Placeholders]
-tags: [test, docs]
-draft: true
+description: Learn how Layer5 Cloud centralizes management, visualization, and collaboration for your multi-cloud infrastructure.
+weight: 1
+categories: [Reference, Cloud]
+tags: [Cloud, Architecture, Governance]
+draft: false
 ---
-<!-- 
+
 {{% pageinfo %}}
-Page under construction.
+Layer5 Cloud is the control plane for your cloud-native infrastructure, providing deep insights and collaborative management across all your clusters.
 {{% /pageinfo %}}
 
+## What is Layer5 Cloud?
 
-The Overview is where your users find out about your project. Depending on the size of your docset, you can have a separate overview page (like this one) or put your overview contents in the Documentation landing page (like in the Docsy User Guide).
-
-Try answering these questions for your user in this page:
-
-## What is it?
-
-Introduce your project, including what it does or lets you do, why you would use it, and its primary goal (and how it achieves it). This should be similar to your README description, though you can go into a little more detail here if you want.
-
-## Why do I want it?
-
-Help your user know if your project will help them. Useful information can include:
-
-* **What is it good for?**: What types of problems does your project solve? What are the benefits of using it?
-
-* **What is it not good for?**: For example, point out situations that might intuitively seem suited for your project, but aren't for some reason. Also mention known limitations, scaling issues, or anything else that might let your users know if the project is not for them.
+Layer5 Cloud serves as the centralized management console and identity provider for the Layer5 ecosystem, specifically for **Kanvas** and **Meshery** deployments. It provides an extensible authorization framework that allows organizations to manage complex infrastructure with confidence.
 
-* **What is it *not yet* good for?**: Highlight any useful features that are coming soon.
+## Why use Layer5 Cloud?
 
-## Where should I go next?
+* **Collaborative Design**: Similar to Google Workspace or Figma, multiple team members can design and review infrastructure patterns in real-time.
+* **Unified Identity**: Manage organizations, teams, and users with granular Role-Based Access Control (RBAC).
+* **Content Catalog**: Host and share cloud-native patterns publicly or keep them private within your organization.
 
-Give your users next steps from the Overview. For example:
+## Next Steps
 
-* [Getting Started](/docs/getting-started/): Get started with $project
-* [Examples](/docs/examples/): Check out some example code!
- -->
+* [**Identity**](/cloud/identity): Learn about Organizations, Teams, and Users.
+* [**Security**](/cloud/security): Understand tokens, keychains, and permissions.
diff --git a/content/en/cloud/security/_index.md b/content/en/cloud/security/_index.md
@@ -1,10 +1,49 @@
 ---
 title: Security
-description: Tokens, Keychains, Keys, Roles
+description: Manage identity and access through Tokens, Keychains, Keys, and RBAC Roles.
 weight: 4
+draft: false
 categories: [Security]
-tags: [permissions]
+tags: [permissions, identity, authentication]
 ---
+Layer5 Cloud provides a multi-tenant security model designed to manage access across complex organizational structures. This section covers the core components of our Identity and Access Management (IAM) system.
 
+## Security Architecture
 
-![permission](/cloud/security/images/permissions.svg "image-center-shadow")
+The following diagram illustrates the relationship between Organizational Units, Roles, and the underlying Permissions:
+
+![permission](/cloud/security/images/permissions.svg "image-center-shadow")
+
+---
+
+## Organizational Units
+Layer5 Cloud uses a hierarchical structure to isolate resources and manage users at scale:
+* **Provider Organizations:** The top-level entity that can manage multiple tenant organizations.
+* **Tenant Organizations:** Individual customer or project-specific organizations (e.g., Layer5, Intel).
+* **Teams:** Logical groupings of users within an organization to facilitate collaborative management.
+* **Users:** Individual accounts that are members of teams and organizations.
+
+## Roles and Access Control
+Access is granted through Role-Based Access Control (RBAC). Roles are assigned at different levels of the organizational hierarchy:
+* **Organization Administrators:** Full control over an entire tenant organization.
+* **Organization Billing Managers:** Access restricted to subscription and financial management.
+* **Team Administrators:** Management of specific team resources and memberships.
+
+## Key Management and Tokens
+Beyond structural roles, Layer5 Cloud uses cryptographic and session-based security:
+
+### Keychains
+Keychains are collections of keys used to manage environment-specific access and signing. They allow for the logical grouping of related security credentials.
+
+### Keys
+Keys are the atomic unit of access control within the system. They are used for secure communication between Meshery and Layer5 Cloud, as well as for signing design patterns.
+
+### Tokens
+Tokens provide temporary, secure access to the platform.
+* **Session Tokens:** Used for web browser authentication.
+* **Personal Access Tokens (PATs):** Used for programmatic access via CLI or CI/CD pipelines.
+
+---
+
+### Need more detail?
+Check out the [Roles Reference](/docs/security/roles) for a complete matrix of permissions for each role.
