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

# Events

> Monitor real-time Kubernetes cluster events for troubleshooting and observability

Kubernetes Events provide a record of what is happening inside the cluster. They report state changes, errors, and other significant occurrences across all resources, making them essential for troubleshooting and monitoring cluster health.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Event" icon="bell">
    A record of a state change or occurrence in the cluster, such as pod scheduling, image pulling, or container failures.
  </Card>

  <Card title="Event Type" icon="tag">
    Events are classified as **Normal** (informational) or **Warning** (potential issues).
  </Card>

  <Card title="Reason" icon="file-text">
    A short, machine-readable code indicating what happened (e.g., `Scheduled`, `Pulled`, `Failed`).
  </Card>

  <Card title="Involved Object" icon="box">
    The Kubernetes resource (Pod, Deployment, Node, etc.) that the event relates to.
  </Card>
</CardGroup>

<Info>
  Events are automatically collected from all namespaces in the cluster. They provide real-time visibility into cluster activity without requiring namespace selection.
</Info>

## Required Permissions

| Action      | Permission                                   |
| ----------- | -------------------------------------------- |
| View Events | `iam:project:infrastructure:kubernetes:read` |

<Info>
  Events are **read-only** in Kubernetes. They are generated automatically by the system and cannot be created, edited, or deleted through the API.
</Info>

## Event Types

| Type        | Description                                                                                             |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| **Normal**  | Informational events indicating successful operations (scheduling, pulling images, starting containers) |
| **Warning** | Events indicating potential problems that may require attention (failures, errors, resource issues)     |

## Event Fields

| Field         | Description                                        |
| ------------- | -------------------------------------------------- |
| **Namespace** | The namespace where the event occurred             |
| **Last Seen** | When the event was last observed                   |
| **Type**      | Event severity: Normal or Warning                  |
| **Reason**    | Machine-readable code for the event cause          |
| **Object**    | The resource (Kind/Name) that the event relates to |
| **Message**   | Human-readable description of what happened        |

## How to View Events

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

  <Step title="View Events">
    Events from all namespaces are displayed automatically with real-time updates.
  </Step>

  <Step title="Filter and Search">
    Use the search box to find events by message content. Filter by event reason to focus on specific event types.
  </Step>

  <Step title="Review Statistics">
    Check the summary cards for:

    * **Total Events**: All events in the cluster
    * **Warnings**: Events that may indicate problems
    * **Normal**: Informational events
    * **Namespaces**: Number of namespaces with events
  </Step>
</Steps>

## Common Event Reasons

### Pod Events

| Reason             | Type    | Description                         |
| ------------------ | ------- | ----------------------------------- |
| `Scheduled`        | Normal  | Pod assigned to a node              |
| `Pulled`           | Normal  | Container image pulled successfully |
| `Created`          | Normal  | Container created                   |
| `Started`          | Normal  | Container started                   |
| `Killing`          | Normal  | Container being terminated          |
| `Failed`           | Warning | Container failed to start           |
| `BackOff`          | Warning | Container restarting after failure  |
| `FailedScheduling` | Warning | Pod could not be scheduled          |
| `Unhealthy`        | Warning | Liveness/readiness probe failed     |
| `FailedMount`      | Warning | Volume mount failed                 |

### Node Events

| Reason                    | Type    | Description              |
| ------------------------- | ------- | ------------------------ |
| `NodeReady`               | Normal  | Node became ready        |
| `NodeNotReady`            | Warning | Node is not ready        |
| `NodeHasDiskPressure`     | Warning | Node has disk pressure   |
| `NodeHasMemoryPressure`   | Warning | Node has memory pressure |
| `NodeHasNoDiskPressure`   | Normal  | Disk pressure resolved   |
| `NodeHasNoMemoryPressure` | Normal  | Memory pressure resolved |

### Deployment Events

| Reason               | Type   | Description                 |
| -------------------- | ------ | --------------------------- |
| `ScalingReplicaSet`  | Normal | Deployment scaling replicas |
| `SuccessfulCreate`   | Normal | ReplicaSet created          |
| `SuccessfulDelete`   | Normal | ReplicaSet deleted          |
| `DeploymentRollback` | Normal | Deployment rolled back      |

### Other Common Events

| Reason                  | Type    | Description                  |
| ----------------------- | ------- | ---------------------------- |
| `ProvisioningSucceeded` | Normal  | PVC provisioning completed   |
| `ProvisioningFailed`    | Warning | PVC provisioning failed      |
| `FailedBinding`         | Warning | PVC binding failed           |
| `ExternalProvisioning`  | Normal  | External provisioner working |
| `LeaderElection`        | Normal  | Leader election occurred     |

## Troubleshooting with Events

<AccordionGroup>
  <Accordion title="Pod stuck in Pending">
    Look for events with reason:

    * `FailedScheduling` - Check for resource constraints or node selectors
    * `FailedMount` - Check PVC and volume configuration
    * `NodeNotReady` - Check node health

    Events will show the specific reason for scheduling failure.
  </Accordion>

  <Accordion title="Container keeps restarting">
    Look for events with reason:

    * `BackOff` - Container crashing, check logs
    * `Unhealthy` - Probe failures, check probe configuration
    * `Failed` - Container start failure, check image and command

    Check the event message for specific error details.
  </Accordion>

  <Accordion title="Image pull failures">
    Look for events with reason:

    * `Failed` - With message about image pull
    * `BackOff` - ImagePullBackOff state

    Common causes: wrong image name, missing credentials, network issues.
  </Accordion>

  <Accordion title="Volume mount issues">
    Look for events with reason:

    * `FailedMount` - Volume could not be mounted
    * `FailedAttachVolume` - Volume attachment failed
    * `ProvisioningFailed` - Dynamic provisioning failed

    Check StorageClass and PVC configuration.
  </Accordion>

  <Accordion title="Node issues">
    Look for events with reason:

    * `NodeNotReady` - Node health problems
    * `NodeHasDiskPressure` - Disk space issues
    * `NodeHasMemoryPressure` - Memory issues
    * `Rebooted` - Node was rebooted

    Events show when conditions changed.
  </Accordion>

  <Accordion title="No events showing">
    * Verify the cluster is ready and accessible
    * Check if you have read permission for the cluster
    * Events expire after a default retention period (1 hour by default in Kubernetes)
    * Try refreshing the page
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="How long are events retained?">
    By default, Kubernetes retains events for 1 hour. After this time, events are automatically garbage collected. This retention period is configurable at the cluster level via the `--event-ttl` flag on the API server.
  </Accordion>

  <Accordion title="Why do I see duplicate events?">
    Events can be deduplicated by Kubernetes. The "count" field shows how many times an event occurred. In the UI, you see the most recent occurrence with its timestamp.
  </Accordion>

  <Accordion title="Can I create or delete events?">
    Events are generated automatically by Kubernetes components and controllers. They cannot be manually created, edited, or deleted through normal means. They are purely informational records.
  </Accordion>

  <Accordion title="What does 'Last Seen' mean?">
    Last Seen indicates when the event was most recently observed. For recurring events (like repeated failures), this shows the latest occurrence, not when the problem first started.
  </Accordion>

  <Accordion title="Why are Warning events important?">
    Warning events indicate potential problems that may need attention:

    * Failed operations (scheduling, volume mounting, image pulling)
    * Resource constraints (disk/memory pressure)
    * Health check failures

    Monitoring Warning events helps identify issues before they become critical.
  </Accordion>

  <Accordion title="How do I filter events for a specific pod?">
    Use the search box to search for the pod name. Events related to that pod will be shown. You can also search by namespace, event message, or any other field content.
  </Accordion>

  <Accordion title="What is the difference between events and logs?">
    **Events** are cluster-level records of significant occurrences (state changes, errors). They are short-lived and structured.

    **Logs** are continuous output from containers. They provide detailed application-level information and are typically retained longer.

    Use events for quick troubleshooting of Kubernetes issues; use logs for application debugging.
  </Accordion>

  <Accordion title="Why do events show from all namespaces?">
    Events are displayed cluster-wide to provide complete visibility into cluster activity. This helps identify cross-namespace issues and understand the overall cluster state. Use search and filters to focus on specific namespaces.
  </Accordion>
</AccordionGroup>

## Best Practices

<Tip>
  **Monitor Warning Events**: Set up alerts for Warning events, especially `FailedScheduling`, `Unhealthy`, and `Failed` events. These often indicate problems that need attention.
</Tip>

<Tip>
  **Use Events for Initial Troubleshooting**: When a workload has issues, events are the first place to look. They provide immediate context about what Kubernetes is doing with your resources.
</Tip>

<Tip>
  **Correlate Events with Resource Status**: Events explain *why* a resource is in a certain state. If a Pod is Pending, events will show the scheduling failure reason.
</Tip>