Organization

Organization custom resource definition for resource hierarchy

Overview

The Organization custom resource represents a top-level container for projects and resources. Organizations provide isolation, quota management, and access control boundaries.

Organization resources are part of the Milo resource manager API group (resourcemanager.miloapis.com/v1alpha1).

Resource Definition

apiVersion: resourcemanager.miloapis.com/v1alpha1
kind: Organization
metadata:
  name: my-org
spec:
  type: Standard

API Group

apiVersion · string · required

resourcemanager.miloapis.com/v1alpha1

kind · string · required

Organization

Organization Types

Organizations can be one of two types:

Personal

Automatically created for each user. Cannot be deleted or modified. Used for individual user workspaces.

Standard

Created by users for teams and companies. Can have multiple members with different roles.

Metadata

metadata.name · string · required

The name of the organization. Must be globally unique.

Personal organizations: Named personal-org-<hash> (automatically generated)

Standard organizations: User-chosen name

metadata.annotations · object

Annotations for organization metadata.

Standard annotations:

• kubernetes.io/display-name: Display name for UIs
• kubernetes.io/description: Organization description

Example:

annotations:
  kubernetes.io/display-name: "Acme Corporation"
  kubernetes.io/description: "Engineering organization for Acme Corp"

metadata.ownerReferences · array

Owner references (used for personal organizations).

Personal organizations have a controller reference to the User resource, ensuring the organization is deleted when the user is deleted.

Spec Fields

spec.type · string · required

The type of organization.

Values:

• Personal: Personal organization (one per user)
• Standard: Team/company organization

Personal organizations cannot change their type or display name. This is enforced by a ValidatingAdmissionPolicy.

Status Fields

The Organization status reflects the current state:

status.phase · string

The current phase of the organization.

Values:

• Active: Organization is active and ready
• Pending: Organization is being set up
• Deleting: Organization is being deleted

status.namespace · string

The namespace created for this organization: organization-<name>

All organization-scoped resources are created in this namespace.

status.conditions · array

Detailed conditions about the organization state.

Each condition includes:

• type: Condition type (e.g., “Ready”)
• status: True, False, or Unknown
• reason: Machine-readable reason code
• message: Human-readable message
• lastTransitionTime: When the condition last changed

Quota Management

Organizations act as quota consumers. Quotas are granted to organizations and claimed by projects within the organization.

Project Quota

Organizations have a quota for the number of projects they can create:

apiVersion: quota.miloapis.com/v1alpha1
kind: ResourceRegistration
metadata:
  name: projects-per-organization
spec:
  consumerType:
    apiGroup: resourcemanager.miloapis.com
    kind: Organization
  type: Entity
  resourceType: resourcemanager.miloapis.com/projects
  baseUnit: project
  displayUnit: projects

Default quotas:

• Personal organizations: Limited project quota
• Standard organizations: Higher default quota, can be increased

Organization Membership

Users are granted access to organizations via OrganizationMembership resources:

apiVersion: resourcemanager.miloapis.com/v1alpha1
kind: OrganizationMembership
metadata:
  name: membership-john
  namespace: organization-my-org
spec:
  organizationRef:
    name: my-org
  userRef:
    name: john-user-id
  roles:
  - name: datum-cloud-owner
    namespace: datum-assignable-organization-roles

Standard Roles

datum-cloud-owner · role

Full control over the organization and all its resources.

Permissions:

• Create/delete projects
• Manage organization members
• View/edit all resources
• Manage quotas

datum-cloud-editor · role

Can create and manage resources but cannot manage organization settings.

Permissions:

• Create/edit resources
• View organization details
• Cannot manage members or quotas

datum-cloud-viewer · role

Read-only access to organization resources.

Permissions:

• View all resources
• Cannot create/edit/delete

Validation Policies

Personal Organization Protection

Personal organizations have special validation rules:

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
  name: disallow-personal-org-name-change
spec:
  validations:
  - expression: "object.spec.type != 'Personal' || oldObject.metadata.annotations['kubernetes.io/display-name'] == object.metadata.annotations['kubernetes.io/display-name']"
    message: "The display name of a personal organization cannot be changed."

Protected fields for Personal organizations:

• metadata.annotations['kubernetes.io/display-name']
• spec.type

Examples

Standard Organization

apiVersion: resourcemanager.miloapis.com/v1alpha1
kind: Organization
metadata:
  name: acme-corp
  annotations:
    kubernetes.io/display-name: "Acme Corporation"
    kubernetes.io/description: "Main engineering organization"
spec:
  type: Standard

Personal Organization (Auto-created)

apiVersion: resourcemanager.miloapis.com/v1alpha1
kind: Organization
metadata:
  name: personal-org-a1b2c3d4
  annotations:
    kubernetes.io/display-name: "John Doe's Personal Org"
    kubernetes.io/description: "John Doe's Personal Org"
  ownerReferences:
  - apiVersion: iam.miloapis.com/v1alpha1
    kind: User
    name: user-12345
    uid: 12345-67890
    controller: true
spec:
  type: Personal

Organization with Membership

Create an organization and add a member:

apiVersion: resourcemanager.miloapis.com/v1alpha1
kind: Organization
metadata:
  name: my-team
  annotations:
    kubernetes.io/display-name: "My Team"
spec:
  type: Standard
---
apiVersion: resourcemanager.miloapis.com/v1alpha1
kind: OrganizationMembership
metadata:
  name: membership-alice
  namespace: organization-my-team
spec:
  organizationRef:
    name: my-team
  userRef:
    name: alice-user-id
  roles:
  - name: datum-cloud-owner
    namespace: datum-assignable-organization-roles

kubectl Commands

List Organizations

# List all organizations
kubectl get organizations

# List personal organizations
kubectl get organizations -l type=Personal

# List standard organizations
kubectl get organizations -l type=Standard

# Custom columns
kubectl get organizations \
  -o custom-columns=NAME:.metadata.name,TYPE:.spec.type,DISPLAY:.metadata.annotations['kubernetes\.io/display-name']

Get Organization Details

# Get full specification
kubectl get organization my-org -o yaml

# Get organization status
kubectl get organization my-org -o jsonpath='{.status}'

# Describe with events
kubectl describe organization my-org

Create Standard Organization

kubectl apply -f organization.yaml

View Organization Members

# List memberships in an organization
kubectl get organizationmemberships -n organization-my-org

# Get membership details
kubectl describe organizationmembership membership-alice -n organization-my-org

Delete Organization

# Delete standard organization
kubectl delete organization my-org

# Personal organizations cannot be deleted directly
# They are deleted when the user is deleted

Related Resources

• Project - Projects are created within organizations
• PersonalOrganizationController - Manages personal organization lifecycle

Troubleshooting

Cannot create organization

Check:

1. Verify you have permission to create organizations
2. Check if the name is already taken: kubectl get organization <name>
3. Ensure the name follows Kubernetes naming conventions (lowercase, alphanumeric, hyphens)
4. Check quota limits

Personal organization missing

Check:

1. Verify the PersonalOrganizationController is running
2. Check user status: kubectl get user <name> -o yaml
3. View controller logs: kubectl logs -n datum-system deployment/datum-controller-manager
4. Ensure user registration is approved

Cannot modify personal organization

Personal organizations have restrictions:

• Display name cannot be changed
• Type cannot be changed
• Organization cannot be deleted (deleted with user)

This is enforced by ValidatingAdmissionPolicy and is by design.

Member cannot access organization resources

Check:

1. Verify membership exists: kubectl get organizationmemberships -n organization-<name>
2. Check assigned roles in the membership spec
3. Verify the role exists: kubectl get role <role-name> -n <role-namespace>
4. Check PolicyBindings: kubectl get policybindings -n organization-<name>

Source Reference

Source: internal/controller/resourcemanager/personal_organization_controller.go:80-100