helm-release-management

---
name: helm-release-management
description: Manage Helm releases — install, upgrade, uninstall, list, inspect, history. Use when the user mentions deploying Helm charts, upgrading releases, or managing Kubernetes deployments.
license: MIT
---

# Helm Release Management

Comprehensive guidance for day-to-day Helm release operations including installation, upgrades, uninstallation, and release tracking.

## When to Use This Skill

| Use this skill when... | Use <sibling> instead when... |
|---|---|
| Running `helm install`, `helm upgrade`, `helm uninstall`, or listing releases | Use helm-release-recovery when an upgrade has failed and needs rollback or stuck-state recovery |
| Checking release status, history, or rolling out a new chart version | Use helm-values-management when the focus is configuring values across environments |
| Promoting an existing chart from staging to production | Use helm-chart-development when authoring the chart that will be installed |

## When to Use

Use this skill automatically when:
- User requests deploying or installing Helm charts
- User mentions upgrading or updating Helm releases
- User wants to list or manage releases across namespaces
- User needs to check release history or status
- User requests uninstalling or removing releases

## Core Release Operations

### Install New Release

```bash
# Basic install
helm install <release-name> <chart> --namespace <namespace> --create-namespace

# Install with custom values
helm install myapp bitnami/nginx \
  --namespace production \
  --create-namespace \
  --values values.yaml \
  --set replicaCount=3

# Install with atomic rollback on failure
helm install myapp ./mychart \
  --namespace staging \
  --atomic \
  --timeout 5m \
  --wait

# Install from repository with specific version
helm install mydb bitnami/postgresql \
  --namespace database \
  --version 12.1.9 \
  --values db-values.yaml

# Dry-run before actual install
helm install myapp ./chart \
  --namespace prod \
  --dry-run \
  --debug
```

**Key Flags:**
- `--namespace` - Target namespace (ALWAYS specify explicitly)
- `--create-namespace` - Create namespace if it doesn't exist
- `--values` / `-f` - Specify values file(s)
- `--set` - Override individual values
- `--atomic` - Rollback automatically on failure (RECOMMENDED)
- `--wait` - Wait for resources to be ready
- `--timeout` - Maximum time to wait (default 5m)
- `--dry-run --debug` - Preview without installing

### Upgrade Existing Release

```bash
# Basic upgrade with new values
helm upgrade myapp ./mychart \
  --namespace production \
  --values values.yaml

# Upgrade with value overrides
helm upgrade myapp bitnami/nginx \
  --namespace prod \
  --reuse-values \
  --set image.tag=1.21.0

# Upgrade with new chart version
helm upgrade mydb bitnami/postgresql \
  --namespace database \
  --version 12.2.0 \
  --atomic \
  --wait

# Install if not exists, upgrade if exists
helm upgrade --install myapp ./chart \
  --namespace staging \
  --create-namespace \
  --values values.yaml

# Force upgrade (recreate resources)
helm upgrade myapp ./chart \
  --namespace prod \
  --force \
  --recreate-pods
```

**Key Flags:**
- `--reuse-values` - Reuse existing values, merge with new
- `--reset-values` - Reset to chart defaults, ignore existing
- `--install` - Install if release doesn't exist
- `--force` - Force resource updates (use cautiously)
- `--recreate-pods` - Recreate pods even if no changes
- `--cleanup-on-fail` - Delete new resources on failed upgrade

**Value Override Precedence** (lowest to highest):
1. Chart default values (`values.yaml` in chart)
2. Previous release values (with `--reuse-values`)
3. Parent chart values
4. User-specified values files (`-f values.yaml`)
5. Individual value overrides (`--set key=value`)

### Uninstall Release

```bash
# Basic uninstall
helm uninstall myapp --namespace production

# Uninstall but keep history (allows rollback)
helm uninstall myapp \
  --namespace staging \
  --keep-history

# Uninstall with timeout
helm uninstall myapp \
  --namespace prod \
  --timeout 10m \
  --wait
```

### List Releases

```bash
# List releases in namespace
helm list --namespace production

# List all releases across all namespaces
helm list --all-namespaces

# List with additional details
helm list \
  --all-namespaces \
  --output yaml \
  --max 50

# List including uninstalled releases
helm list --namespace staging --uninstalled

# Filter releases by name pattern
helm list --filter '^my.*' --namespace prod
```

**Key Flags:**
- `--all-namespaces` / `-A` - List releases across all namespaces
- `--all` - Show all releases including failed
- `--uninstalled` - Show uninstalled releases
- `--failed` - Show only failed releases
- `--pending` - Show pending releases
- `--filter` - Filter by release name (regex)

## Release Information & History

### Check Release Status

```bash
# Get release status
helm status myapp --namespace production

# Show deployed resources
helm status myapp \
  --namespace prod \
  --show-resources
```

### View Release History

```bash
# View revision history
helm history myapp --namespace production

# View detailed history
helm history myapp \
  --namespace prod \
  --output yaml \
  --max 10
```

### Inspect Release

```bash
# Get deployed manifest
helm get manifest myapp --namespace production

# Get deployed values
helm get values myapp --namespace production

# Get all values (including defaults)
helm get values myapp --namespace prod --all

# Get release metadata
helm get metadata myapp --namespace production

# Get release notes
helm get notes myapp --namespace production

# Get everything
helm get all myapp --namespace production
```

For common workflows (deploy new application, update configuration, upgrade chart version, multi-environment deployment), best practices, troubleshooting, and integration with other tools, see [REFERENCE.md](REFERENCE.md).

## Agentic Optimizations

| Context | Command |
|---------|---------|
| List releases (structured) | `helm list -n <ns> -o json` |
| Release history (structured) | `helm history <release> -n <ns> --output json` |
| Release status (structured) | `helm status <release> -n <ns> -o json` |
| Values (structured) | `helm get values <release> -n <ns> -o json` |
| Failed releases | `helm list -n <ns> --failed -o json` |

## Related Skills

- **Helm Debugging** - Troubleshooting failed deployments
- **Helm Values Management** - Advanced values configuration
- **Helm Release Recovery** - Rollback and recovery strategies
- **ArgoCD CLI Login** - GitOps integration with ArgoCD
- **Kubernetes Operations** - Managing deployed resources

## References

- [Helm Install Documentation](https://helm.sh/docs/helm/helm_install/)
- [Helm Upgrade Documentation](https://helm.sh/docs/helm/helm_upgrade/)
- [Helm Best Practices](https://helm.sh/docs/chart_best_practices/)
- [Helm Values Documentation](https://helm.sh/docs/chart_template_guide/values_files/)