> ## 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.

# Pods

> View and manage Kubernetes pods with logs, exec, and lifecycle controls

Pods are the smallest deployable units in Kubernetes. Each pod contains one or more containers that share storage and network resources. Monitor pod health, view logs, execute commands, and manage pod lifecycle.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Pod" icon="box">
    A group of one or more containers with shared storage and network.
  </Card>

  <Card title="Container" icon="cube">
    A running instance of a container image within a pod.
  </Card>

  <Card title="Init Container" icon="play">
    Containers that run to completion before app containers start.
  </Card>

  <Card title="Pod Status" icon="circle-check">
    Current state of the pod (Running, Pending, Failed, etc.).
  </Card>
</CardGroup>

## Required Permissions

| Action              | Permission                                     |
| ------------------- | ---------------------------------------------- |
| View pods           | `iam:project:infrastructure:kubernetes:read`   |
| View logs           | `iam:project:infrastructure:kubernetes:logs`   |
| Exec into container | `iam:project:infrastructure:kubernetes:logs`   |
| Create pod          | `iam:project:infrastructure:kubernetes:write`  |
| Edit pod            | `iam:project:infrastructure:kubernetes:write`  |
| Delete pod          | `iam:project:infrastructure:kubernetes:delete` |

## Pod Status Values

| Status               | Description                                          |
| -------------------- | ---------------------------------------------------- |
| **Running**          | All containers started and at least one is running   |
| **Pending**          | Pod accepted but containers not yet running          |
| **Succeeded**        | All containers terminated successfully (exit code 0) |
| **Failed**           | All containers terminated, at least one failed       |
| **CrashLoopBackOff** | Container repeatedly crashing after restart          |
| **ImagePullBackOff** | Failed to pull container image                       |
| **Init:N/M**         | Init containers running (N of M completed)           |
| **Init:Error**       | Init container failed                                |
| **Terminating**      | Pod is being deleted                                 |
| **Unknown**          | Pod state cannot be determined                       |

## How to View Pods

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

  <Step title="Select Namespace">
    Choose a namespace or select "all" to view pods across all namespaces.
  </Step>

  <Step title="Filter and Search">
    Use the search box to find pods by name, or filter by status.
  </Step>
</Steps>

## How to View Pod Details

<Steps>
  <Step title="Find the Pod">
    Locate the pod in the list.
  </Step>

  <Step title="Click Pod Name">
    Click on the pod name to open the detail drawer.
  </Step>

  <Step title="Review Details">
    View pod information including:

    * Container status and resource usage
    * Node placement
    * Labels and annotations
    * Conditions and events
    * Volume mounts
  </Step>
</Steps>

## How to View Container Logs

<Steps>
  <Step title="Find the Pod">
    Locate the pod in the list.
  </Step>

  <Step title="Open Actions Menu">
    Click the actions menu (three dots) on the pod row.
  </Step>

  <Step title="Select Container">
    Choose **View Logs** and select the specific container.
  </Step>

  <Step title="View Logs">
    Logs open in the bottom panel with real-time streaming.
  </Step>
</Steps>

<Tip>
  For pods with multiple containers, select the specific container from the submenu. Init containers are listed separately.
</Tip>

## How to Exec into a Container

<Steps>
  <Step title="Find the Pod">
    Locate the running pod.
  </Step>

  <Step title="Open Actions Menu">
    Click the actions menu on the pod row.
  </Step>

  <Step title="Select Container">
    Choose **Exec** and select the target container.
  </Step>

  <Step title="Use Terminal">
    A terminal opens in the bottom panel connected to the container.
  </Step>
</Steps>

<Warning>
  Exec requires the pod to be in Running state. Use with caution in production environments.
</Warning>

## How to Create a Pod

<Steps>
  <Step title="Click Create Pod">
    Click the **Create Pod** button in the page header.
  </Step>

  <Step title="Write YAML">
    Enter the pod manifest in YAML format. A template is provided.
  </Step>

  <Step title="Select Namespace">
    Choose the target namespace for the pod.
  </Step>

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

<Info>
  Pods are typically created by controllers (Deployments, StatefulSets, Jobs). Direct pod creation is mainly for testing or one-off tasks.
</Info>

## How to Edit a Pod

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu on the pod row.
  </Step>

  <Step title="Click Edit YAML">
    Select **Edit YAML** to open the editor.
  </Step>

  <Step title="Modify Fields">
    Edit the allowed fields and save.
  </Step>
</Steps>

**Editable pod fields:**

* `spec.containers[*].image` - Container image
* `spec.activeDeadlineSeconds` - Maximum pod lifetime
* `spec.tolerations` - Node tolerations (limited)
* `metadata.labels` - Pod labels
* `metadata.annotations` - Pod annotations

<Warning>
  Most pod fields are immutable after creation. To change other fields, delete and recreate the pod (or update the parent controller).
</Warning>

## How to Delete a Pod

<Steps>
  <Step title="Open Actions Menu">
    Click the actions menu on the pod row.
  </Step>

  <Step title="Select Delete Option">
    Choose **Delete** for graceful termination or **Force Delete** for immediate termination.
  </Step>

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

**Delete options:**

| Option           | Behavior                                                            |
| ---------------- | ------------------------------------------------------------------- |
| **Delete**       | Graceful termination with default grace period (usually 30 seconds) |
| **Force Delete** | Immediate termination (grace\_period=0)                             |

<Warning>
  If the pod is managed by a controller (Deployment, ReplicaSet, etc.), a replacement pod will be created automatically.
</Warning>

## Understanding Restarts

High restart counts indicate problems:

| Restart Count | Indication                                       |
| ------------- | ------------------------------------------------ |
| 0             | Normal - pod stable                              |
| 1-5           | May be normal or recovering from transient issue |
| >5            | Investigation needed - likely crash loop         |

Common restart causes:

* Application crashes (check logs)
* Out of memory (OOMKilled)
* Liveness probe failures
* Failed startup commands

## Troubleshooting

<AccordionGroup>
  <Accordion title="Pod stuck in Pending">
    * **Insufficient resources**: Node doesn't have enough CPU/memory
    * **Node selector mismatch**: No node matches the selector
    * **Taints and tolerations**: Pod lacks required tolerations
    * **PVC pending**: Persistent volume claim not bound
    * **Image pull issues**: Check image name and pull secrets
  </Accordion>

  <Accordion title="Pod in CrashLoopBackOff">
    * Application is crashing repeatedly
    * Check container logs for error messages
    * Verify command and arguments are correct
    * Check if required environment variables are set
    * Ensure mounted secrets/configmaps exist
  </Accordion>

  <Accordion title="Pod in ImagePullBackOff">
    * Image name or tag is incorrect
    * Image doesn't exist in registry
    * Registry authentication failed (check imagePullSecrets)
    * Network connectivity to registry blocked
  </Accordion>

  <Accordion title="Cannot view logs">
    * Pod must have started at least once
    * Container must exist (check init containers for init phase)
    * Use "previous" option for crashed container logs
    * Verify you have logs permission
  </Accordion>

  <Accordion title="Exec connection fails">
    * Pod must be in Running state
    * Container must be running (not init phase)
    * Network connectivity to node required
    * Verify you have logs permission
  </Accordion>

  <Accordion title="Pod evicted">
    * Node under resource pressure (memory, disk, PID)
    * Check node conditions for pressure status
    * Review pod resource requests and limits
    * Consider adding pod priority class
  </Accordion>

  <Accordion title="OOMKilled container">
    * Container exceeded memory limit
    * Increase memory limit in pod spec
    * Profile application memory usage
    * Check for memory leaks
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between pod phase and status?">
    **Phase** is the high-level lifecycle state (Pending, Running, Succeeded, Failed, Unknown). **Status** provides more detail including container-specific states like CrashLoopBackOff or ImagePullBackOff.
  </Accordion>

  <Accordion title="Why can't I edit most pod fields?">
    Pods are designed to be immutable for reliability. To change configuration, update the parent controller (Deployment, StatefulSet) which will create new pods with the updated spec.
  </Accordion>

  <Accordion title="How do I get logs from a crashed container?">
    Use the "previous" option when viewing logs to see output from the previous container instance before it crashed.
  </Accordion>

  <Accordion title="What happens when I delete a pod managed by a Deployment?">
    The Deployment's ReplicaSet will automatically create a replacement pod to maintain the desired replica count.
  </Accordion>

  <Accordion title="Why is my pod restarting repeatedly?">
    Common causes include application crashes, OOM kills, and liveness probe failures. Check container logs and events for specific error messages.
  </Accordion>

  <Accordion title="How do I find which node a pod is running on?">
    The node name is displayed in the pod list and detail view. You can also filter or sort by node.
  </Accordion>

  <Accordion title="What is QoS class?">
    Quality of Service class determines pod eviction priority: **Guaranteed** (highest), **Burstable**, **BestEffort** (lowest). Set resource requests and limits to control QoS.
  </Accordion>

  <Accordion title="Can I exec into an init container?">
    Yes, but only while the init container is running. Once it completes, you can only view its logs (using previous container option if needed).
  </Accordion>
</AccordionGroup>