> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Namespaces

> Create and manage Kubernetes namespaces for workload isolation

Namespaces provide logical isolation for resources within a Kubernetes cluster. Use them to separate environments, teams, or applications.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Namespace" icon="folder-tree">
    A logical boundary that isolates resources within a cluster.
  </Card>

  <Card title="Resource Quota" icon="scale-balanced">
    Limits on total resource consumption within a namespace.
  </Card>

  <Card title="Limit Range" icon="gauge">
    Default and maximum resource constraints for containers.
  </Card>

  <Card title="System Namespace" icon="gear">
    Protected namespaces used by Kubernetes components.
  </Card>
</CardGroup>

## Required Permissions

| Action                 | Permission                                     |
| ---------------------- | ---------------------------------------------- |
| View namespaces        | `iam:project:infrastructure:kubernetes:read`   |
| Create/Edit namespaces | `iam:project:infrastructure:kubernetes:write`  |
| Delete namespaces      | `iam:project:infrastructure:kubernetes:delete` |

## How to Create a Namespace

<Steps>
  <Step title="Select Cluster">
    Choose a cluster from the dropdown.
  </Step>

  <Step title="Click Create Namespace">
    Click the **Create Namespace** button.
  </Step>

  <Step title="Choose a Template">
    Select a template based on your needs:

    * **Basic Namespace** - Simple namespace with labels
    * **With Resource Quota** - Includes CPU, memory, and object count limits
    * **With Limit Range** - Includes default container resource constraints
  </Step>

  <Step title="Configure YAML">
    Edit the namespace name and any additional settings in the YAML editor.
  </Step>

  <Step title="Create">
    Click **Create** to apply.
  </Step>
</Steps>

<Info>
  Namespace names must be valid DNS labels: lowercase letters, numbers, and hyphens only. Maximum 63 characters.
</Info>

## How to Edit a Namespace

<Steps>
  <Step title="Select the Namespace">
    Click on the namespace row to open details, then click **Edit YAML**.
  </Step>

  <Step title="Modify YAML">
    Edit labels, annotations, or other mutable fields.
  </Step>

  <Step title="Save">
    Click **Update** to apply changes.
  </Step>
</Steps>

<Warning>
  Namespace names cannot be changed after creation. Only labels and annotations can be modified.
</Warning>

## How to Delete a Namespace

<Steps>
  <Step title="Select the Namespace">
    Click the actions menu on the namespace row.
  </Step>

  <Step title="Click Delete">
    Select **Delete** from the menu.
  </Step>

  <Step title="Confirm">
    Confirm the deletion.
  </Step>
</Steps>

<Warning>
  Deleting a namespace removes ALL resources within it including pods, deployments, services, configmaps, secrets, and PVCs. This action cannot be undone.
</Warning>

## System Namespaces

The following namespaces are protected and cannot be deleted:

| Namespace         | Purpose                          |
| ----------------- | -------------------------------- |
| `kube-system`     | Kubernetes system components     |
| `kube-public`     | Publicly accessible cluster data |
| `kube-node-lease` | Node heartbeat leases            |
| `default`         | Default namespace for resources  |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Namespace stuck in Terminating status">
    This usually indicates resources with finalizers that cannot complete:

    * Check for stuck persistent volume claims
    * Look for resources with deletion finalizers
    * Consider manually removing finalizers as a last resort
  </Accordion>

  <Accordion title="Cannot create namespace">
    * Verify you have write permission
    * Check namespace name follows DNS label rules (lowercase, numbers, hyphens only)
    * Ensure name is not already taken
  </Accordion>

  <Accordion title="Cannot delete namespace">
    * System namespaces (`kube-system`, `kube-public`, `kube-node-lease`, `default`) cannot be deleted
    * Verify you have delete permission
  </Accordion>

  <Accordion title="Resource quota preventing deployments">
    * Check current usage against quota limits
    * Either increase quota or reduce resource requests
    * Use `kubectl describe resourcequota -n <namespace>` to see usage
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What are resource quotas for?">
    Resource quotas limit total namespace consumption (CPU, memory, object counts). They prevent a single namespace from consuming all cluster resources.
  </Accordion>

  <Accordion title="What are limit ranges for?">
    Limit ranges set default resource requests/limits for containers that don't specify them. They also enforce minimum and maximum constraints.
  </Accordion>

  <Accordion title="Can pods in different namespaces communicate?">
    Yes, by default. Use the DNS name `<service>.<namespace>.svc.cluster.local`. Apply NetworkPolicies to restrict cross-namespace traffic.
  </Accordion>

  <Accordion title="How do I organize namespaces?">
    Common patterns:

    * By environment: `dev`, `staging`, `prod`
    * By team: `team-a`, `team-b`
    * By application: `app-frontend`, `app-backend`
  </Accordion>
</AccordionGroup>