Helm:Debug

---
name: helm:debug
description: Debug Helm chart issues - template rendering, value overrides, hook failures
---

# Debug Helm Charts

## Context-Safe Execution (MANDATORY)

**Helm template output can be hundreds of lines.** Always redirect to files:

```bash
export LOG_DIR="${LOG_DIR:-${WORKSPACE_DIR:-/tmp}/rossoctl-helm}"
mkdir -p "$LOG_DIR"

# Redirect helm template output
helm template rossoctl charts/rossoctl -n rossoctl-system > $LOG_DIR/rendered.yaml 2>&1 && echo "OK" || echo "FAIL"
# Analyze in subagent: Task(subagent_type='Explore') with Grep to find specific templates/values
```

## When to Use

- Helm install/upgrade fails
- Template rendering produces unexpected output
- Values not applied correctly
- Hook jobs failing

## Template Debugging

Render templates locally without installing:

```bash
helm template rossoctl charts/rossoctl -n rossoctl-system -f charts/rossoctl/.secrets.yaml
```

Render a specific template:

```bash
helm template rossoctl charts/rossoctl -n rossoctl-system -s templates/ui-oauth-secret-job.yaml
```

Compare rendered output with what's deployed:

```bash
helm get manifest rossoctl -n rossoctl-system
```

## Value Debugging

Show computed values:

```bash
helm get values rossoctl -n rossoctl-system
```

Show all values (including defaults):

```bash
helm get values rossoctl -n rossoctl-system -a
```

Show chart default values:

```bash
helm show values charts/rossoctl
```

## Release Debugging

Check release status:

```bash
helm status rossoctl -n rossoctl-system
```

Check release history:

```bash
helm history rossoctl -n rossoctl-system
```

## Hook Debugging

Hooks run as Jobs. Check their status:

```bash
kubectl get jobs -n rossoctl-system
```

Check hook job logs:

```bash
kubectl logs -n rossoctl-system job/<hook-job-name>
```

## Dependency Issues

Update chart dependencies:

```bash
helm dependency update charts/rossoctl
```

List dependencies:

```bash
helm dependency list charts/rossoctl
```

## Common Issues

| Issue | Cause | Fix |
|-------|-------|-----|
| `UPGRADE FAILED: another operation in progress` | Stale lock | `kubectl delete secret -n rossoctl-system -l status=pending-upgrade` |
| Template render error | Bad YAML indent | Use `helm template` to see exact error |
| Values not applied | Wrong `-f` order | Later files override earlier ones |
| Hook timeout | Job takes too long | Check job logs, increase timeout |

## Related Skills

- `rossoctl:deploy` - Platform deployment
- `rossoctl:operator` - Operator management
- `k8s:pods` - Debug pod issues from hook jobs
- `rca:hypershift` - RCA when Helm issues cause test failures
- `rca:kind` - RCA on local Kind cluster
- `tdd:hypershift` - TDD loop that includes Helm reinstall iterations
- `tdd:kind` - TDD loop on Kind cluster