|
| 1 | +# CockroachDB Operator API Version Migration (v1alpha1 → v1beta1) |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +CockroachDB Operator is transitioning from `v1alpha1` to `v1beta1` API version. This document provides essential upgrade instructions. |
| 6 | + |
| 7 | +**Current Version**: `25.4.3-preview+1` (Multi-version support) |
| 8 | + |
| 9 | +--- |
| 10 | + |
| 11 | +## Before You Upgrade |
| 12 | + |
| 13 | +### 🚨 Critical Warning |
| 14 | + |
| 15 | +**NEVER DELETE THE CRD** |
| 16 | +- **DO NOT delete CRDs** if you encounter upgrade issues |
| 17 | +- Deleting CRDs will **permanently delete all your CockroachDB clusters and data** |
| 18 | +- If you have upgrade issues, check logs and contact support – do not delete CRDs |
| 19 | + |
| 20 | +--- |
| 21 | + |
| 22 | +## User Scenarios |
| 23 | + |
| 24 | +### New Users (Fresh Installation) |
| 25 | +If you're installing for the first time: |
| 26 | +- ✅ Install normally - no special steps needed |
| 27 | +- ✅ Pre-upgrade validation will automatically detect new installation and skip unnecessary checks |
| 28 | + |
| 29 | +### Existing Users (Upgrading from v1alpha1) |
| 30 | +If you have existing CockroachDB clusters: |
| 31 | +- ✅ Follow the two-step upgrade process below |
| 32 | +- ✅ Pre-upgrade validation will automatically: |
| 33 | + - Verify CRD supports v1beta1 |
| 34 | + - Rewrite resources to v1beta1 storage format |
| 35 | + - Validate API access |
| 36 | +- ✅ Zero downtime - your cluster continues running during the upgrade |
| 37 | + |
| 38 | +--- |
| 39 | + |
| 40 | +## Upgrade Instructions |
| 41 | + |
| 42 | +### ⚠️ Required Upgrade Order |
| 43 | + |
| 44 | +**The operator MUST be upgraded before the CockroachDB chart.** |
| 45 | + |
| 46 | +Why? The CockroachDB chart now uses `v1beta1` templates, which requires the operator to enable `v1beta1` support in the CRD first. |
| 47 | + |
| 48 | +### Step-by-Step Upgrade |
| 49 | + |
| 50 | +```bash |
| 51 | +# Step 1: Upgrade operator first |
| 52 | +helm upgrade <operator-release> ./cockroachdb-parent/charts/operator -n <namespace> |
| 53 | + |
| 54 | +# Step 2: Then upgrade CockroachDB chart |
| 55 | +helm upgrade <cockroachdb-release> ./cockroachdb-parent/charts/cockroachdb -n <namespace> |
| 56 | +``` |
| 57 | + |
| 58 | +**Important**: Both steps are required. Even if you don't have CockroachDB chart value changes, you must upgrade it to update Helm's stored manifest to v1beta1. |
| 59 | + |
| 60 | +### Post-Upgrade |
| 61 | + |
| 62 | +Clear your kubectl cache: |
| 63 | +```bash |
| 64 | +rm -rf ~/.kube/cache |
| 65 | +``` |
| 66 | + |
| 67 | +--- |
| 68 | + |
| 69 | +## What Happens During Upgrade |
| 70 | + |
| 71 | +1. **Operator Upgrade**: Adds v1beta1 support to CRD (both v1alpha1 and v1beta1 are served, v1beta1 is storage version) |
| 72 | +2. **CockroachDB Chart Upgrade**: Updates templates to v1beta1, pre-upgrade hook validates and rewrites resources |
| 73 | +3. **Automatic Validation**: Pre-upgrade hook ensures everything is ready before proceeding |
| 74 | + |
| 75 | +--- |
| 76 | + |
| 77 | +## Common Issues |
| 78 | + |
| 79 | +### "UPGRADE BLOCKED - CRD does not support v1beta1" |
| 80 | + |
| 81 | +**Cause**: Trying to upgrade CockroachDB chart before operator |
| 82 | + |
| 83 | +**Solution**: Upgrade operator first (Step 1 above), then retry CockroachDB chart upgrade |
| 84 | + |
| 85 | +--- |
| 86 | + |
| 87 | +### "Cannot access CrdbCluster via v1beta1 API" |
| 88 | + |
| 89 | +**Cause**: Operator not running or CRD configuration issue |
| 90 | + |
| 91 | +**Solution**: |
| 92 | +1. Check operator status: `kubectl get pods -n <namespace> -l app.kubernetes.io/name=cockroach-operator` |
| 93 | +2. Check operator logs: `kubectl logs -n <namespace> -l app.kubernetes.io/name=cockroach-operator` |
| 94 | +3. Verify CRD: `kubectl get crd crdbclusters.crdb.cockroachlabs.com -o yaml` |
| 95 | + |
| 96 | +--- |
| 97 | + |
| 98 | +## Verification |
| 99 | + |
| 100 | +After upgrade, verify everything is working: |
| 101 | + |
| 102 | +```bash |
| 103 | +# Check CRD configuration |
| 104 | +kubectl get crd crdbclusters.crdb.cockroachlabs.com \ |
| 105 | + -o jsonpath='{.spec.versions[?(@.storage==true)].name}' |
| 106 | +# Expected output: v1beta1 |
| 107 | + |
| 108 | +# Check your clusters |
| 109 | +kubectl get crdbcluster -n <namespace> |
| 110 | + |
| 111 | +# Verify Helm manifest uses v1beta1 |
| 112 | +helm get manifest <release> -n <namespace> | grep "apiVersion: crdb.cockroachlabs.com" |
| 113 | +# Expected: v1beta1 |
| 114 | +``` |
| 115 | + |
| 116 | +--- |
| 117 | + |
| 118 | +## FAQ |
| 119 | + |
| 120 | +**Q: Will this cause downtime?** |
| 121 | +A: No. The migration is zero-downtime. Resources remain accessible during upgrade. |
| 122 | + |
| 123 | +**Q: Do I need to do anything manually?** |
| 124 | +A: No. Just follow the two-step upgrade order. Pre-upgrade hooks handle everything else automatically. |
| 125 | + |
| 126 | +**Q: What if I only upgrade the operator?** |
| 127 | +A: You must also upgrade the CockroachDB chart (Step 2). This updates Helm's manifest to v1beta1, which is required for future upgrades. |
| 128 | + |
| 129 | +--- |
| 130 | + |
| 131 | +## Support |
| 132 | + |
| 133 | +If you encounter issues: |
| 134 | + |
| 135 | +**🚨 IMPORTANT: Never delete CRDs to "fix" upgrade issues - this will destroy all your data!** |
| 136 | + |
| 137 | +**Check pre-upgrade job logs:** |
| 138 | +```bash |
| 139 | +kubectl logs job/<release>-pre-upgrade-validation -n <namespace> |
| 140 | +``` |
| 141 | + |
| 142 | +**Check operator logs:** |
| 143 | +```bash |
| 144 | +kubectl logs -n <namespace> -l app.kubernetes.io/name=cockroach-operator --tail=50 |
| 145 | +``` |
| 146 | + |
| 147 | +**Check for events:** |
| 148 | +```bash |
| 149 | +kubectl get events -n <namespace> --sort-by='.lastTimestamp' |
| 150 | +``` |
| 151 | + |
| 152 | +--- |
| 153 | + |
| 154 | +## Quick Reference |
| 155 | + |
| 156 | +**Before upgrade:** |
| 157 | +- ⚠️ Never delete CRDs (will delete all data) |
| 158 | +- ⚠️ Upgrade operator first, then CockroachDB chart |
| 159 | + |
| 160 | +**Upgrade commands:** |
| 161 | +```bash |
| 162 | +# Step 1 |
| 163 | +helm upgrade <operator-release> ./cockroachdb-parent/charts/operator -n <namespace> |
| 164 | + |
| 165 | +# Step 2 |
| 166 | +helm upgrade <cockroachdb-release> ./cockroachdb-parent/charts/cockroachdb -n <namespace> |
| 167 | +``` |
| 168 | + |
| 169 | +**After upgrade:** |
| 170 | +```bash |
| 171 | +# Clear kubectl cache |
| 172 | +rm -rf ~/.kube/cache |
| 173 | + |
| 174 | +# Verify |
| 175 | +kubectl get crdbcluster -n <namespace> |
| 176 | +``` |
| 177 | + |
| 178 | +**If issues occur:** |
| 179 | +- Check job logs: `kubectl logs job/<release>-pre-upgrade-validation` |
| 180 | +- Check operator logs |
| 181 | +- DO NOT delete CRDs |
0 commit comments