Skip to content

Understanding Groups

Jump to bottom
Andrew den Hertog edited this page Dec 3, 2025 · 1 revision

Understanding Groups

Groups are the organizational structure within Codex Web. This guide explains how groups work, roles within groups, and how to work effectively within your group's resource constraints.

What are Groups?

A group in Codex Web represents a team, department, or organization. Each group:

  • Isolated Environment: Has its own Kubernetes namespace
  • Resource Quotas: Defined limits on CPU, memory, storage, and pods
  • Member Access: Contains users with specific roles
  • Workspace Container: Holds multiple workspaces created by members
  • Shared Resources: All workspaces share the group's resource pool

Example Group Structure

Group: "Engineering Team"
├── Members: 10 users
├── Resource Quota:
│   ├── CPU: 20 cores
│   ├── Memory: 40 GB
│   ├── Storage: 500 GB
│   └── Max Pods: 50
└── Workspaces: 15 active workspaces

Group Membership and Roles

Users can belong to multiple groups and have different roles in each group.

Member Role

Permissions:

  • View group details (name, description, resource quotas)
  • View list of group members
  • Create workspaces within the group
  • Manage their own workspaces
  • View group resource usage

Cannot:

  • Add or remove group members
  • Modify group settings
  • Delete other users' workspaces
  • Change resource quotas

Group Admin Role

Permissions:

  • All member permissions, plus:
  • Manage any workspace in the group (start, stop, delete)
  • View detailed resource usage by workspace
  • Monitor all group workspaces

Cannot:

  • Add or remove group members (Platform Admin only)
  • Modify group resource quotas (Platform Admin only)
  • Create or delete groups (Platform Admin only)

When to Use Group Admin:

  • Team leads who need to manage team workspaces
  • DevOps engineers managing development environments
  • Managers overseeing resource usage

Platform Admin Role

Platform admins have complete access across all groups. See Admin Overview for details.

Viewing Your Groups

Groups Page

Navigate to Groups to see:

Group List

  • All groups you belong to
  • Your role in each group
  • Current member count
  • Resource usage indicators

Group Details Click on a group to view:

  • Full group information
  • Complete member list
  • Resource usage breakdown
  • Active workspaces in the group

Understanding Group Information

Each group displays:

Field Description
Name Internal identifier for the group
Display Name Human-readable group name
Description Purpose and notes about the group
Namespace Kubernetes namespace (technical detail)
Member Count Total users in the group
Your Role Your permission level in this group

Group Resource Quotas

Every group has defined resource limits that all workspaces share.

Resource Types

CPU (Cores)

  • Measured in CPU cores
  • Example: 10 cores means 10 simultaneous CPU-bound processes
  • Shared across all running workspaces

Memory (RAM)

  • Measured in GB or GiB
  • Example: 40 GB total memory pool
  • Allocated per workspace based on resource tier

Storage (Persistent)

  • Measured in GB or GiB
  • Example: 500 GB total persistent storage
  • Each workspace gets allocated storage

Pods (Workspaces)

  • Maximum number of concurrent workspaces
  • Example: 50 pods = up to 50 workspaces
  • Includes both running and stopped workspaces

Viewing Resource Usage

In Group Details:

CPU:     15 / 20 cores (75%)
Memory:  28 / 40 GB (70%)
Storage: 350 / 500 GB (70%)
Pods:    12 / 50 (24%)

Color Coding:

  • 🟢 Green (0-70%): Healthy usage
  • 🟡 Yellow (70-90%): Approaching limit
  • 🔴 Red (90-100%): Near or at capacity

Working Within Resource Constraints

Before Creating a Workspace

  1. Check your group's available resources
  2. Choose an appropriate resource tier
  3. Verify the group has capacity

Example: If your group has 5 GB memory remaining and you need a Small Team workspace (4 GB), you have enough. An Enterprise workspace (8 GB) would exceed the quota.

When Resources Are Limited

If workspace creation fails:

  1. Check current group resource usage
  2. Identify idle workspaces you can stop
  3. Contact group members about stopping unused workspaces
  4. Request a quota increase from platform admin (if justified)

Strategies for Efficient Resource Use:

Stop Idle Workspaces

  • Stop workspaces when not actively developing
  • Files are preserved in persistent storage
  • Frees resources for other team members

Choose Appropriate Tiers

  • Don't over-provision resources
  • Start small and scale up if needed
  • Match tier to actual workload

Coordinate with Team

  • Communicate about resource-intensive work
  • Schedule large builds/compilations
  • Stagger workspace usage during peak times

Clean Up Regularly

  • Delete workspaces no longer needed
  • Remove old test environments
  • Consolidate similar workspaces

Group Resource Monitoring

For Members

Check Group Page:

  • View real-time resource usage
  • See how many workspaces are running
  • Identify when quotas are approaching limits

Check Your Workspaces:

  • View individual workspace resource consumption
  • Monitor your contribution to group usage
  • Optimize your resource usage

For Group Admins

Additional Visibility:

  • See all workspaces in the group
  • Identify resource-heavy workspaces
  • Monitor usage trends
  • Plan capacity needs

Admin Actions:

  • Stop idle workspaces to free resources
  • Delete abandoned workspaces
  • Communicate with team about usage
  • Request quota adjustments from platform admin

Multiple Group Membership

Users can belong to multiple groups simultaneously.

Benefits

Separation of Concerns:

  • Personal projects in one group
  • Work projects in another
  • Different resource pools for different purposes

Different Roles:

  • Member in "Engineering" group
  • Group Admin in "QA Team" group
  • Appropriate permissions for each context

Managing Multiple Groups

When Creating Workspaces:

  • Carefully select which group to use
  • Consider which group has available resources
  • Think about who needs access to the workspace

Best Practices:

  • Name workspaces clearly to indicate purpose
  • Use descriptions to note which project/group
  • Keep related work in the same group

Group Best Practices

For All Members

Be a Good Citizen:

  • Stop workspaces when done working
  • Don't hoard resources
  • Delete unused workspaces
  • Monitor your resource usage

Communication:

  • Notify team before resource-intensive work
  • Coordinate with group admin on needs
  • Share knowledge about efficient practices

Resource Awareness:

  • Understand group quotas
  • Check available resources before creating workspaces
  • Choose appropriate resource tiers

For Group Admins

Monitoring:

  • Regularly review group resource usage
  • Identify and address resource waste
  • Track usage trends over time

Member Support:

  • Help members understand resource constraints
  • Assist with workspace issues
  • Communicate quota changes

Capacity Planning:

  • Monitor group growth
  • Anticipate future resource needs
  • Work with platform admin on quota adjustments

Common Scenarios

Scenario 1: "I can't create a workspace"

Possible Causes:

  • Group resource quota exceeded
  • Too many workspaces in group
  • Insufficient permissions

Solutions:

  1. Check group resource usage
  2. Stop or delete idle workspaces
  3. Choose a smaller resource tier
  4. Contact group admin

Scenario 2: "My workspace is running slow"

Check:

  • Individual workspace resource usage
  • Group overall resource usage
  • If group is near quota limits

Actions:

  • Stop unused workspaces in the group
  • Restart your workspace
  • Consider upgrading to larger resource tier
  • Contact group admin if persistent

Scenario 3: "I need more resources"

Options:

  1. Stop other workspaces you're not using
  2. Choose a higher resource tier (if group has capacity)
  3. Work with group admin to identify available resources
  4. Request quota increase (through platform admin)

Scenario 4: "I belong to wrong group"

Contact:

  • Your group admin (for group membership)
  • Platform admin (to change group assignments)

Only platform admins can add/remove users from groups.

Group Lifecycle

Joining a Group

Groups are created by platform admins. To join a group:

  1. Platform admin must add you
  2. You'll see the group appear in your Groups list
  3. You can immediately create workspaces in that group

Leaving a Group

To leave a group:

  1. Contact platform admin
  2. Ensure your workspaces are deleted or transferred
  3. Platform admin removes you from group

Note: You cannot leave a group while you have workspaces in it.

Technical Details

Kubernetes Namespaces

Each group maps to a Kubernetes namespace with the pattern:

{namespace-prefix}-{groupId}

This provides:

  • Resource isolation
  • Network policies
  • Quota enforcement
  • Security boundaries

For Most Users: You don't need to know these details. Group admins and platform admins may need this for troubleshooting.

Next Steps

Getting Help

Group-Related Questions:

  • Contact your group admin
  • Check group resource usage in the UI
  • Review this guide

Membership Issues:

  • Contact platform admin
  • Provide your user ID and desired group

← Getting Started | Managing Workspaces →

Clone this wiki locally