Workspaces

​

What is a Workspace?

• Designs - Infrastructure configurations and deployment templates
• Environments - Collections of deployment targets and connections
• Team access - Permissions and collaboration settings

​

Key Features

​

Resource Sharing

• Share designs with specific teams or across the entire workspace
• Provide access to environments without exposing individual credentials
• Collaborate in real-time on infrastructure designs
• Track changes and activity across shared resources

​

Logical Grouping

• Project-based - Create workspaces for individual projects or applications
• Team-based - Organize by team responsibilities (platform, app team, SRE)
• Environment-based - Separate development, staging, and production workflows
• Domain-based - Group by business domain or service ownership

​

Access Control

• Grant workspace access to specific teams
• Control design ownership and editing permissions
• Manage environment access through workspace assignments
• Track user activity and audit resource changes

​

Workspace Structure

​

Data Model

type Workspace struct {
    ID             uuid.UUID    // Unique identifier
    Name           string       // Workspace name
    OrganizationID uuid.UUID    // Parent organization
    Description    string       // Purpose and details
    CreatedAt      time.Time    // Creation timestamp
    UpdatedAt      time.Time    // Last modification
    DeletedAt      sql.NullTime // Soft delete support
}

​

Resource Relationships

type WorkspacesEnvironmentsMapping struct {
    WorkspaceId   uuid.UUID
    EnvironmentId uuid.UUID
    CreatedAt     time.Time
    UpdatedAt     time.Time
}

type WorkspacesDesignsMapping struct {
    WorkspaceId uuid.UUID
    DesignId    uuid.UUID
    CreatedAt   time.Time
    UpdatedAt   time.Time
}

​

Working with Workspaces

​

Creating a Workspace

curl -X POST https://meshery.example.com/api/workspaces \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "Platform Team Production",
    "description": "Production infrastructure for platform services",
    "organization_id": "org-uuid-here"
  }'

1. Navigate to Workspaces section
2. Click “Create Workspace”
3. Enter name and description
4. Select organization (if applicable)
5. Click “Create”

​

Adding Resources to Workspaces

​

Adding Environments

POST /api/workspaces/{workspaceID}/environments/{environmentID}

• All connections in that environment become available
• Team members can deploy designs to those connections
• Environment credentials are managed separately for security

​

Adding Designs

POST /api/workspaces/{workspaceID}/designs/{designID}

• Makes the design visible to all workspace members
• Allows collaborative editing (based on permissions)
• Enables deployment to workspace environments
• Maintains design version history

​

Querying Workspace Resources

GET /api/workspaces?page=0&pagesize=25&orgID={orgID}

• page - Page number (default: 0)
• pagesize - Items per page (default: 20)
• search - Filter by name (greedy search)
• order - Sort by field (e.g., “name”, “created_at”)
• orgID - Organization filter (required)

GET /api/workspaces/{workspaceID}?orgID={orgID}

GET /api/workspaces/{workspaceID}/environments?page=0&pagesize=25

GET /api/workspaces/{workspaceID}/designs?page=0&pagesize=25

​

Workspace Relationships and Constraints

​

Organizations

• Workspaces belong to exactly one organization
• Organizations are the unit of tenancy in Meshery
• All resources created by users are owned by their organization
• Remote providers can extend organization capabilities (hierarchies, teams)

​

Environments

• A workspace can have zero or more environments
• The same environment can be assigned to multiple workspaces
• Removing an environment from a workspace doesn’t delete the environment
• Environment connections become available to all workspace members

​

Designs

• A design belongs to only one workspace at any given time
• Designs can be transferred between workspaces
• The design owner controls sharing and access permissions
• Cloning a design creates a new design owned by the cloner

​

Teams

• One or more teams can be granted access to a workspace
• Team members inherit workspace permissions
• Remote providers can offer fine-grained team permissions
• Access control is extensible through provider plugins

​

Use Cases and Patterns

​

Project-Based Workspaces

Workspace: "E-Commerce Platform"
├── Environments:
│   ├── ecommerce-prod (GKE cluster)
│   ├── ecommerce-staging (GKE cluster)
│   └── ecommerce-dev (local k3s)
└── Designs:
    ├── frontend-deployment
    ├── backend-services
    ├── database-config
    └── observability-stack

• Clear project boundaries
• Easy onboarding of new team members
• Project-specific resource isolation

​

Team-Based Workspaces

Workspace: "Platform Engineering"
├── Environments:
│   ├── shared-infrastructure (all clusters)
│   └── monitoring (Prometheus/Grafana)
└── Designs:
    ├── ingress-controller-base
    ├── cert-manager-setup
    └── cluster-monitoring

Workspace: "Application Team Alpha"
├── Environments:
│   ├── app-alpha-prod
│   └── app-alpha-dev
└── Designs:
    ├── microservice-template
    └── app-alpha-services

• Clear ownership and responsibilities
• Reduced blast radius of changes
• Team-specific configurations and templates

​

Environment-Based Workspaces

Workspace: "Production"
├── Environments: [all prod clusters]
└── Designs: [production-approved configurations]

Workspace: "Development"
├── Environments: [dev/test clusters]
└── Designs: [experimental configurations]

• Strong production/non-production separation
• Different approval workflows per workspace
• Reduced risk of accidental production changes

​

Best Practices

​

Naming Conventions

✅ Good:
- "platform-prod"
- "AppTeam-Alpha-Production"
- "data-platform-staging"

❌ Avoid:
- "workspace1"
- "test"
- "johns-workspace"

​

Access Management

1. Principle of least privilege: Only grant access to teams that need it
2. Regular audits: Review workspace membership quarterly
3. Clear ownership: Designate workspace owners for each workspace
4. Documentation: Maintain descriptions of workspace purpose and contents

​

Resource Organization

1. Logical grouping: Keep related designs and environments together
2. Avoid over-fragmentation: Don’t create too many small workspaces
3. Clear boundaries: Define what belongs in each workspace
4. Regular cleanup: Remove unused designs and environments

​

Design Management

1. Use templates: Create reusable design templates in shared workspaces
2. Version control: Leverage design versioning and snapshots
3. Documentation: Add descriptions to designs explaining their purpose
4. Testing: Test designs in non-production environments first

​

API Reference

​

Related Concepts

• Environments - Managing deployment targets and connections
• Designs - Infrastructure as code and deployment templates
• Connections - Integrations with Kubernetes and services
• Organizations - Multi-tenancy and user management