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

# Helm Releases

> View and manage Helm releases deployed in your Kubernetes clusters

Helm releases represent deployed instances of Helm charts in your cluster. You can view release status, chart information, deployed resources, revision history, and related events.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Helm Release" icon="package">
    A deployed instance of a Helm chart with a specific configuration.
  </Card>

  <Card title="Chart" icon="file-code">
    A Helm package containing Kubernetes resource templates and default values.
  </Card>

  <Card title="Revision" icon="history">
    A version of the release. Each upgrade or rollback creates a new revision.
  </Card>

  <Card title="Values" icon="sliders">
    Configuration values used to customize the chart deployment.
  </Card>
</CardGroup>

## Required Permissions

| Action         | Permission                                     |
| -------------- | ---------------------------------------------- |
| View releases  | `iam:project:infrastructure:kubernetes:read`   |
| Delete release | `iam:project:infrastructure:kubernetes:delete` |

<Info>
  Helm releases are managed externally via Helm CLI or CD tools. The platform provides read-only visibility and the ability to delete releases.
</Info>

## Release Status Values

| Status               | Description                                  |
| -------------------- | -------------------------------------------- |
| **deployed**         | Release is successfully deployed and running |
| **failed**           | Release deployment or upgrade failed         |
| **pending-install**  | Initial installation in progress             |
| **pending-upgrade**  | Upgrade operation in progress                |
| **pending-rollback** | Rollback operation in progress               |
| **superseded**       | Previous revision, replaced by a newer one   |
| **uninstalling**     | Uninstall operation in progress              |

## How to View Helm Releases

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

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

  <Step title="Filter and Search">
    Use the search box to find releases by name, chart, or namespace. Filter by status (Deployed, Failed, Pending, Superseded).
  </Step>
</Steps>

## How to View Release Details

<Steps>
  <Step title="Find the Release">
    Locate the release in the list.
  </Step>

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

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

    * **Overview**: Name, namespace, revision, age, deployment timestamps
    * **Chart Info**: Chart name, chart version, app version, description
    * **Resources**: Deployments, StatefulSets, DaemonSets, Services, and Pods created by the release
    * **Revision History**: All revisions with status, chart version, and timestamps
    * **Events**: Kubernetes events related to the release resources
  </Step>
</Steps>

## How to Delete a Helm Release

<Steps>
  <Step title="Find the Release">
    Locate the release in the list.
  </Step>

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

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

  <Step title="Confirm">
    Review the warning and confirm the deletion.
  </Step>
</Steps>

<Warning>
  Deleting a Helm release only removes the release metadata (Helm secrets). The actual resources deployed by the chart (Deployments, Services, ConfigMaps, etc.) will remain in the cluster unless they were created with owner references to the release. Delete resources separately if needed.
</Warning>

## Understanding Release Resources

When viewing a release's details, the Resources section shows Kubernetes objects created by the chart:

| Resource Type    | What It Shows                       |
| ---------------- | ----------------------------------- |
| **Deployments**  | Name, replica count, ready replicas |
| **StatefulSets** | Name, replica count, ready replicas |
| **DaemonSets**   | Name, desired nodes, ready nodes    |
| **Services**     | Name, type, cluster IP, ports       |
| **Pods**         | Name, phase, ready status           |

<Tip>
  Resources are identified by common Helm labels: `app.kubernetes.io/instance`, `release`, or `app` matching the release name.
</Tip>

## Understanding Revision History

Each Helm operation creates a new revision:

* **Install**: Creates revision 1
* **Upgrade**: Creates a new revision (2, 3, 4...)
* **Rollback**: Creates a new revision with the old configuration

The history shows:

* Revision number
* Status at that revision
* Chart version used
* Timestamp
* Description (upgrade notes)

<Info>
  Helm keeps release history as Kubernetes secrets with the `owner=helm` label. By default, Helm retains the last 10 revisions.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Release shows 'failed' status">
    * Check the Events section for error details
    * Review pod logs for application errors
    * Verify ConfigMaps and Secrets exist
    * Check resource quota limits in the namespace
    * Use `helm history <release>` CLI command for more details
  </Accordion>

  <Accordion title="Release stuck in pending state">
    * Check if pods are starting successfully
    * Review events for scheduling issues
    * Verify node resources are available
    * Check for PVC binding issues if using persistent storage
  </Accordion>

  <Accordion title="Resources not showing in release details">
    * Ensure resources have standard Helm labels
    * Check `app.kubernetes.io/instance=<release-name>` label
    * Some charts use custom labeling schemes
  </Accordion>

  <Accordion title="Cannot find a release">
    * Verify the correct namespace is selected
    * Check if the release was installed in a different namespace
    * Helm secrets may have been manually deleted
  </Accordion>

  <Accordion title="Deleted release but resources remain">
    * Platform deletion only removes Helm metadata
    * Use `kubectl delete` to remove remaining resources
    * Or reinstall and use `helm uninstall` for clean removal
  </Accordion>

  <Accordion title="Release history missing">
    * Helm secrets may have been deleted
    * Check `helm.sh/release-max-history` setting
    * Old revisions are automatically pruned based on history limit
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can I upgrade or rollback releases from the platform?">
    Currently, the platform provides read-only access to Helm releases. Use the Helm CLI or your CD pipeline to perform upgrades and rollbacks.
  </Accordion>

  <Accordion title="How does Helm store release information?">
    Helm stores release information as Kubernetes secrets with the `owner=helm` label. Each revision is stored as a separate secret containing the release manifest, values, and chart metadata.
  </Accordion>

  <Accordion title="What's the difference between deleting here vs 'helm uninstall'?">
    Platform deletion removes only the Helm secrets (metadata). `helm uninstall` removes both the metadata AND all resources deployed by the chart. Use `helm uninstall` for a complete cleanup.
  </Accordion>

  <Accordion title="Why do I see multiple revisions with 'superseded' status?">
    Each upgrade creates a new revision and marks the previous one as superseded. This is normal and allows rollbacks to previous configurations.
  </Accordion>

  <Accordion title="How many revisions are kept?">
    By default, Helm keeps the last 10 revisions. This can be configured with `--history-max` flag during install/upgrade or the `HELM_MAX_HISTORY` environment variable.
  </Accordion>

  <Accordion title="Can I see the values used for a release?">
    The current view shows chart and version information. For detailed values, use `helm get values <release>` CLI command.
  </Accordion>

  <Accordion title="Why are some resources not associated with a release?">
    Resources need Helm-standard labels to be associated with a release. If a chart uses custom labels or creates resources without proper labeling, they won't appear in the resources list.
  </Accordion>

  <Accordion title="What happens if I delete a release with running workloads?">
    The workloads continue running. Deleting the release only removes Helm's tracking metadata. The Deployments, Services, and Pods remain active until manually deleted.
  </Accordion>
</AccordionGroup>