Group Management

This guide covers creating, configuring, and managing groups in Codex Web.

Understanding Groups

What is a Group?

A group in Codex Web represents an organizational unit (team, department, project) with:

Isolation:

Dedicated Kubernetes namespace
Network isolation
Resource boundaries

Resources:

CPU quota
Memory quota
Storage quota
Pod limit (max workspaces)

Membership:

Multiple users
Role-based access (Member, Group Admin)
Shared resource pool

Workspaces:

Container for multiple workspaces
Workspaces consume group resources
All members can create workspaces

Group Architecture

Group: "Engineering Team"
├── Kubernetes Namespace: "codex-platform-grp123"
├── Resource Quota:
│   ├── CPU: 20 cores
│   ├── Memory: 40 GB
│   ├── Storage: 500 GB
│   └── Pods: 50
├── Members:
│   ├── alice@example.com (admin)
│   ├── bob@example.com (member)
│   └── charlie@example.com (member)
└── Workspaces:
    ├── workspace-001 (Alice, 2 CPU, 4 GB)
    ├── workspace-002 (Bob, 1 CPU, 2 GB)
    └── workspace-003 (Charlie, 4 CPU, 8 GB)

Group Properties

Property	Description	Example
ID	Unique identifier	`grp_abc123def456`
Name	Internal name	`engineering-team`
Display Name	Human-readable name	`Engineering Team`
Description	Purpose of the group	`Development workspaces for eng team`
Namespace	Kubernetes namespace	`codex-platform-engineering-team`
Resource Quota	Resource limits	CPU, Memory, Storage, Pods
Member Count	Number of users	`15`

Creating Groups

Prerequisites

✅ You must be a Platform Admin
✅ Decide on group purpose and members
✅ Determine appropriate resource quotas
✅ Choose unique namespace name

Planning a New Group

Before Creation:

Define Purpose:
- What team/project is this for?
- Expected number of members?
- Typical workload characteristics?
Estimate Resources:
- How many concurrent workspaces?
- Average workspace size?
- Peak usage scenarios?
Choose Namespace:
- Follow naming convention
- Check if name available
- Keep it short and descriptive

Namespace Naming Conventions

Format:

{prefix}-{group-name}

Examples:

✅ codex-platform-engineering
✅ codex-platform-data-science
✅ codex-platform-project-alpha
❌ my-namespace (no prefix)
❌ codex-platform-engineering-team-for-backend-services (too long)

Rules:

Lowercase only
Use hyphens, not underscores
Max 63 characters
Start with letter
End with alphanumeric
Must be unique across platform

Creation Process

Via Admin UI (if available)

Navigate to Admin Panel → Groups
Click Create Group
Fill in group information:

Name (required)
- Internal identifier
- Used in API calls
- Example: engineering-team
Display Name (required)
- Shown in UI
- Human-readable
- Example: Engineering Team
Description (optional)
- Purpose and notes
- Example: Development workspaces for engineering team
Namespace (required)
- Kubernetes namespace name
- Must be unique
- Example: codex-platform-engineering-team
Resource Quota:
- CPU: 20 (cores)
- Memory: 40Gi
- Storage: 500Gi
- Pods: 50
Click Create Group

Via API

export TOKEN="your-jwt-token"
export API_URL="https://your-codex.com/api"

curl -X POST "${API_URL}/groups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "engineering-team",
    "displayName": "Engineering Team",
    "description": "Development workspaces for engineering",
    "namespace": "codex-platform-engineering-team",
    "resourceQuota": {
      "cpu": "20",
      "memory": "40Gi",
      "storage": "500Gi",
      "pods": 50
    }
  }'

Response:

{
  "id": "grp_abc123def456",
  "name": "engineering-team",
  "displayName": "Engineering Team",
  "description": "Development workspaces for engineering",
  "namespace": "codex-platform-engineering-team",
  "resourceQuota": {
    "cpu": "20",
    "memory": "40Gi",
    "storage": "500Gi",
    "pods": 50
  },
  "memberCount": 1,
  "createdAt": "2024-12-03T10:00:00Z"
}

What Happens During Creation

Validation:
- Check namespace uniqueness
- Verify resource quota values
- Validate naming conventions
Database Creation:
- Group record created in DynamoDB
- Unique group ID generated
- Initial member count set to 1 (creator)
Kubernetes Resources:
- Namespace created
- ResourceQuota applied
- Labels applied:
  - vscode-platform/group-id
  - vscode-platform/group-name
- NetworkPolicy created (optional)
Creator Added:
- Admin who created group is added as member
- Member count incremented
Audit Log:
- Action logged
- Includes creator, timestamp, details

Post-Creation Steps

Verify Creation:

# Get group details
curl -H "Authorization: Bearer $TOKEN" \
  "${API_URL}/groups/${GROUP_ID}"

# Verify namespace exists
kubectl get namespace codex-platform-engineering-team

# Check resource quota
kubectl get resourcequota -n codex-platform-engineering-team

Add Members:

Add users to the group
Assign group admin roles as needed
Communicate group availability

Documentation:

Record group purpose
Note resource allocations
Document ownership

Configuring Resource Quotas

Understanding Quotas

Resource quotas limit group resource consumption:

CPU (Cores):

Measured in CPU cores
Example: 20 = 20 CPU cores
Can be fractional: 0.5 = half a core

Memory:

Measured in bytes (with units)
Common units: Gi (Gibibytes), Mi (Mebibytes)
Example: 40Gi = 40 GiB of RAM

Storage:

Measured in bytes (with units)
Persistent volume storage
Example: 500Gi = 500 GiB disk space

Pods:

Number of pods (workspaces)
Integer value
Example: 50 = max 50 workspaces

Default Quotas

Recommended starting quotas by team size:

Team Size	CPU	Memory	Storage	Pods
Small (1-5)	10 cores	20 GB	200 GB	20
Medium (6-15)	20 cores	40 GB	500 GB	50
Large (16-30)	50 cores	100 GB	1 TB	100
Enterprise (31+)	100 cores	200 GB	2 TB	200

Adjust based on:

Workload intensity
Workspace sizes
Concurrent usage patterns
Peak requirements

Updating Resource Quotas

Via API:

curl -X PATCH "${API_URL}/groups/${GROUP_ID}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceQuota": {
      "cpu": "30",
      "memory": "60Gi",
      "storage": "750Gi",
      "pods": 75
    }
  }'

Via Kubernetes (direct):

kubectl apply -f - <<EOF
apiVersion: v1
kind: ResourceQuota
metadata:
  name: group-quota
  namespace: codex-platform-engineering-team
spec:
  hard:
    limits.cpu: "30"
    limits.memory: 60Gi
    persistentvolumeclaims: "75"
EOF

Important:

Update both database and Kubernetes
Monitor for impact on running workspaces
Communicate changes to group members
Log the change in audit trail

Quota Planning

Calculate Needs:

Total CPU = (# members) × (avg workspace CPUs) × (concurrency factor)
Total Memory = (# members) × (avg workspace memory) × (concurrency factor)
Total Storage = (# members) × (avg workspace storage)
Total Pods = (# members) × (avg workspaces per member)

Concurrency factor: 0.6-0.8 (not all members use at once)

Example:

10 members
Average: 2 CPU, 4 GB memory per workspace
Concurrency: 70% (7 concurrent workspaces)
Result:
- CPU: 10 × 2 × 0.7 = 14 cores → provision 20 cores (buffer)
- Memory: 10 × 4 × 0.7 = 28 GB → provision 40 GB
- Storage: 10 × 50 GB = 500 GB
- Pods: 10 × 2 = 20 → provision 30 (buffer)

Managing Group Members

Viewing Group Members

Via UI:

Go to Groups
Click group name
View Members tab

Via API:

curl -H "Authorization: Bearer $TOKEN" \
  "${API_URL}/groups/${GROUP_ID}/members"

Adding Members to Group

Via API:

curl -X POST "${API_URL}/groups/${GROUP_ID}/members" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "usr_123456",
    "role": "member"
  }'

Alternative (via user management):

curl -X POST "${API_URL}/admin/users/usr_123456/groups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "grp_abc123",
    "role": "member"
  }'

Roles:

member - Standard access
admin - Group admin privileges

Removing Members from Group

Via API:

curl -X DELETE "${API_URL}/groups/${GROUP_ID}/members/usr_123456" \
  -H "Authorization: Bearer $TOKEN"

Prerequisites:

User must not have active workspaces in the group
Delete or transfer workspaces first

Setting Group Admin Role

Promote to Group Admin:

curl -X POST "${API_URL}/admin/users/usr_123456/groups/${GROUP_ID}/promote" \
  -H "Authorization: Bearer $TOKEN"

Demote from Group Admin:

curl -X POST "${API_URL}/admin/users/usr_123456/groups/${GROUP_ID}/demote" \
  -H "Authorization: Bearer $TOKEN"

Bulk Member Operations

Add Multiple Users:

#!/bin/bash
GROUP_ID="grp_abc123"
USERS=("usr_001" "usr_002" "usr_003")

for USER_ID in "${USERS[@]}"; do
  curl -X POST "${API_URL}/groups/${GROUP_ID}/members" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"userId\": \"$USER_ID\", \"role\": \"member\"}"
  echo "Added $USER_ID"
done

Monitoring Groups

Resource Usage Monitoring

View Current Usage:

curl -H "Authorization: Bearer $TOKEN" \
  "${API_URL}/groups/${GROUP_ID}/usage"

Response:

{
  "cpu": {
    "used": "15",
    "total": "20",
    "percentage": 75
  },
  "memory": {
    "used": "28Gi",
    "total": "40Gi",
    "percentage": 70
  },
  "storage": {
    "used": "350Gi",
    "total": "500Gi",
    "percentage": 70
  },
  "pods": {
    "used": 12,
    "total": 50,
    "percentage": 24
  }
}

Via Kubernetes:

# Get resource usage
kubectl describe resourcequota -n codex-platform-engineering-team

# View pods in namespace
kubectl get pods -n codex-platform-engineering-team

# Check PVC usage
kubectl get pvc -n codex-platform-engineering-team

Identifying Resource Issues

High Utilization (>90%):

# Find groups near limits
curl -H "Authorization: Bearer $TOKEN" \
  "${API_URL}/groups" | jq '.[] | select(.usage.cpu.percentage > 90)'

Action Items:

Identify resource-heavy workspaces
Contact group members
Stop idle workspaces
Consider quota increase

Low Utilization (<30%):

Group may be over-provisioned
Consider reducing quota
Free resources for other groups

Workspace Inventory

List Group Workspaces:

curl -H "Authorization: Bearer $TOKEN" \
  "${API_URL}/workspaces?groupId=${GROUP_ID}"

Analyze Usage:

# Count by status
curl -H "Authorization: Bearer $TOKEN" \
  "${API_URL}/workspaces?groupId=${GROUP_ID}" | \
  jq 'group_by(.status) | map({status: .[0].status, count: length})'

Updating Groups

Editable Fields

Can Update:

Display name
Description
Resource quotas

Cannot Update:

Group ID (immutable)
Name (immutable)
Namespace (immutable)
Creation date

Update Process

Via API:

curl -X PATCH "${API_URL}/groups/${GROUP_ID}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Engineering Team (Updated)",
    "description": "Updated description",
    "resourceQuota": {
      "cpu": "30",
      "memory": "60Gi",
      "storage": "750Gi",
      "pods": 75
    }
  }'

What Updates:

Database record immediately
Kubernetes ResourceQuota updated
Member count recalculated
Audit log created

Deleting Groups

Before Deletion

⚠️ WARNING: Group deletion is permanent!

Pre-Deletion Checklist:

✅ Verify group should be deleted
✅ Check for active workspaces
✅ Notify all group members
✅ Delete all workspaces first
✅ Remove all group members
✅ Document the deletion
✅ Get management approval

Deletion Requirements

Cannot Delete If:

❌ Group has active workspaces
❌ Group has pending operations

Must Do First:

Delete all workspaces in group
Remove all members (optional)
Ensure no pending operations

Deletion Process

Via API:

curl -X DELETE "${API_URL}/groups/${GROUP_ID}" \
  -H "Authorization: Bearer $TOKEN"

What Happens:

Validation:
- Verify no workspaces exist
- Check permissions
Member Removal:
- All users removed from group
- Member count set to zero
Kubernetes Cleanup:
- Namespace deleted
- All resources removed
- PVCs deleted
- ResourceQuota removed
Database Deletion:
- Group record deleted
- ID freed
Audit Log:
- Deletion recorded
- Includes admin who deleted
- Records timestamp

Post-Deletion

Immediate Effects:

Group disappears from UI
Members lose access
Namespace removed
Resources freed

Cannot Undo:

Deletion is permanent
Must recreate group from scratch
Same namespace can be reused

Best Practices

Group Organization

Alignment:

Match organizational structure
One group per team/department
Consider project-based groups
Avoid too many small groups

Naming:

Consistent naming scheme
Clear, descriptive names
Document group purposes
Maintain group registry

Ownership:

Assign group owner
Document in description
Owner coordinates resources
Owner point of contact

Resource Management

Right-Sizing:

Start conservative
Monitor actual usage
Adjust based on data
Don't over-provision

Monitoring:

Weekly resource checks
Alert at 80% utilization
Track trends over time
Plan for growth

Optimization:

Regular cleanup of idle workspaces
Encourage workspace stopping
Rebalance resources between groups
Delete abandoned workspaces

Member Management

Onboarding:

Add new members promptly
Communicate group details
Explain resource limits
Provide documentation

Offboarding:

Remove members when they leave
Transfer/delete their workspaces
Update group documentation
Revoke access immediately

Role Assignment:

Designate group admins appropriately
Document role assignments
Review quarterly
Update as needed

Documentation

Group Records:

Group: Engineering Team
ID: grp_abc123
Owner: eng-manager@example.com
Purpose: Development workspaces for engineering
Members: 15
Resources: 20 CPU, 40 GB memory, 500 GB storage
Created: 2024-01-15
Notes: Increased quota on 2024-06-01 due to team growth

Maintain:

Group purposes
Ownership information
Resource history
Major changes
Member lists

Troubleshooting

Group Creation Fails

Error: "Namespace already exists"

# Check if namespace exists
kubectl get namespace codex-platform-engineering-team

# Use different namespace name or delete existing

Error: "Invalid resource quota"

Verify quota format
Check values are positive
Ensure units are correct (Gi, not GB)
Verify cluster has capacity

Cannot Delete Group

Error: "Group has active workspaces"

# List workspaces
curl -H "Authorization: Bearer $TOKEN" \
  "${API_URL}/workspaces?groupId=${GROUP_ID}"

# Delete each workspace
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "${API_URL}/admin/workspaces/${WORKSPACE_ID}"

Resource Quota Not Applied

Check Kubernetes:

# View resource quota
kubectl get resourcequota -n codex-platform-engineering-team -o yaml

# Check for errors
kubectl describe resourcequota -n codex-platform-engineering-team

Reapply if needed:

curl -X PATCH "${API_URL}/groups/${GROUP_ID}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resourceQuota": {...}}'

Next Steps

User Account Management - Managing group members
Workspace Administration - Managing group workspaces
Privilege Guidelines - Understanding group roles

← Privilege Guidelines | Workspace Administration →

Group Management

Group Management

Table of Contents

Understanding Groups

What is a Group?

Group Architecture

Group Properties

Creating Groups

Prerequisites

Planning a New Group

Namespace Naming Conventions

Creation Process

Via Admin UI (if available)

Via API

What Happens During Creation

Post-Creation Steps

Configuring Resource Quotas

Understanding Quotas

Default Quotas

Updating Resource Quotas

Quota Planning

Managing Group Members

Viewing Group Members

Adding Members to Group

Removing Members from Group

Setting Group Admin Role

Bulk Member Operations

Monitoring Groups

Resource Usage Monitoring

Identifying Resource Issues

Workspace Inventory

Updating Groups

Editable Fields

Update Process

Deleting Groups

Before Deletion

Deletion Requirements

Deletion Process

Post-Deletion

Best Practices

Group Organization

Resource Management

Member Management

Documentation

Troubleshooting

Group Creation Fails

Cannot Delete Group

Resource Quota Not Applied

Next Steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally