{"id":69142,"plugin_id":"plugin_asdk_app_6ae160c3d9e48191aaeffd03cc5ef09d","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-28T18:07:04.063Z","digest":"2693577f03b8d12657ddc2981bd3c7e73cc61aa91cf5d84ba78a1c751e0d4f4b","against":null,"payload":{"description":"Guides CockroachDB version upgrades with tier-appropriate procedures. Self-Hosted covers manual rolling binary replacement with finalization control. Advanced/BYOC covers Console-initiated major upgrades, maintenance windows for patches, and release channel selection. Standard and Basic upgrades are fully automatic with no customer action required. Use when planning, executing, or monitoring a version upgrade.","included_files":[],"name":"upgrading-cluster-version","skill_md_contents":"---\nname: upgrading-cluster-version\ndescription: Guides CockroachDB version upgrades with tier-appropriate procedures. Self-Hosted covers manual rolling binary replacement with finalization control. Advanced/BYOC covers Console-initiated major upgrades, maintenance windows for patches, and release channel selection. Standard and Basic upgrades are fully automatic with no customer action required. Use when planning, executing, or monitoring a version upgrade.\ncompatibility: Self-Hosted requires CLI and SQL access with admin role. Advanced/BYOC requires Cloud Console with Cluster Admin role. Standard/Basic upgrades are automatic — SQL access needed only for post-upgrade verification.\n---\n\n# Upgrading Cluster Version\n\nGuides CockroachDB version upgrades end-to-end. Before providing procedures, this skill gathers deployment context to deliver only the steps relevant to the operator's tier.\n\n## When to Use This Skill\n\n- Planning or executing a version upgrade (Self-Hosted)\n- Initiating a major version upgrade via Cloud Console (Advanced, BYOC)\n- Configuring how patches are applied (Advanced, BYOC)\n- Verifying upgrade completion (all tiers)\n- Deciding whether to finalize or roll back (Self-Hosted)\n\n**For pre-upgrade health check:** Use [reviewing-cluster-health](../reviewing-cluster-health/SKILL.md).\n**For node drain during Self-Hosted upgrade:** Use [performing-cluster-maintenance](../perform-cluster-maintenance/SKILL.md).\n**For maintenance window configuration:** Use [performing-cluster-maintenance](../perform-cluster-maintenance/SKILL.md).\n\n---\n\n## Step 1: Gather Context\n\n### Required Context\n\n| Question | Options | Why It Matters |\n|----------|---------|----------------|\n| **Deployment tier?** | Self-Hosted, Advanced, BYOC, Standard, Basic | Completely different upgrade procedures per tier |\n| **Current version?** | e.g., v24.2.5 | Validates upgrade path and compatibility |\n\n### Additional Context (by tier)\n\n**If Self-Hosted:**\n\n| Question | Options | Why It Matters |\n|----------|---------|----------------|\n| **Upgrade type?** | Major (e.g., 24.2→24.3), Patch (e.g., 24.2.5→24.2.8) | Major requires finalization; patches do not |\n| **Target version?** | e.g., v24.3.1 | Confirms version is available and sequential |\n| **Deployment platform?** | Bare metal, VMs, Kubernetes (Operator/Helm/manual) | Changes binary replacement and restart procedure |\n| **Process manager?** | systemd, manual, container orchestrator | Changes stop/start commands |\n| **Node count?** | Number | Affects upgrade sequencing |\n\n**If Advanced or BYOC:**\n\n| Question | Options | Why It Matters |\n|----------|---------|----------------|\n| **Upgrade type?** | Major version, Patch | Major requires Console initiation; patches use maintenance windows |\n| **Cloud provider?** (BYOC only) | AWS, GCP, Azure | For infrastructure-level monitoring during upgrade |\n| **Release channel?** | Regular, Innovation | Innovation gives latest features, shorter support window |\n\n**If Standard or Basic:** No additional context needed — upgrades are fully automatic.\n\n### Context-Driven Routing\n\n| Tier | Go To |\n|------|-------|\n| Self-Hosted | [Self-Hosted Upgrade](#self-hosted-upgrade) |\n| Advanced | [Advanced Upgrade](#advanced-upgrade) |\n| BYOC | [BYOC Upgrade](#byoc-upgrade) |\n| Standard | [Standard Upgrade](#standard-upgrade) |\n| Basic | [Basic Upgrade](#basic-upgrade) |\n\n---\n\n## Self-Hosted Upgrade\n\n**Applies when:** Tier = Self-Hosted\n\n### Major vs Patch\n\n| Aspect | Major (e.g., 24.2→24.3) | Patch (e.g., 24.2.5→24.2.8) |\n|--------|--------------------------|------------------------------|\n| Finalization required | Yes | No |\n| Rollback possible | Before finalization | Always (binary swap) |\n| Auto-finalization | Enabled by default (disable recommended) | N/A |\n\n### Pre-Upgrade Validation\n\n```bash\n# All nodes live, version-consistent, fully replicated\ncockroach node status --decommission --certs-dir=<certs-dir> --host=<any-live-node>\n```\n\nIn the output: every node should show `is_live = true`, the `build` column should be a single value, and `ranges_underreplicated` should be `0` everywhere.\n\n```sql\n-- No bulk operations running\nWITH j AS (SHOW JOBS)\nSELECT job_id, job_type, status, now() - created AS running_for FROM j\nWHERE status IN ('running', 'paused')\n  AND job_type IN ('SCHEMA CHANGE', 'BACKUP', 'RESTORE', 'IMPORT', 'NEW SCHEMA CHANGE');\n\n-- No pending finalization from a previous upgrade\nSHOW CLUSTER SETTING cluster.preserve_downgrade_option;\n```\n\n### Disable Auto-Finalization (Major Version — Recommended)\n\n```sql\nSET CLUSTER SETTING cluster.preserve_downgrade_option = '<current_version>';\n-- Example: SET CLUSTER SETTING cluster.preserve_downgrade_option = '24.2';\n```\n\n### Rolling Node Upgrade (repeat for each node)\n\n**If process manager = systemd:**\n```bash\ncockroach node drain --self --certs-dir=<certs-dir> --host=<node-address>\nsudo systemctl stop cockroachdb\ncp /path/to/new/cockroach /usr/local/bin/cockroach\ncockroach version  # verify new binary\nsudo systemctl start cockroachdb\n```\n\n**If Kubernetes (Operator):**\n```bash\nkubectl patch crdbcluster <name> --type merge -p '{\"spec\":{\"cockroachDBVersion\":\"<new-version>\"}}'\n# Operator handles rolling restart automatically\n```\n\n**If Kubernetes (Helm):**\n```bash\nhelm upgrade cockroachdb cockroachdb/cockroachdb --set image.tag=<new-version>\n```\n\n**If Kubernetes (manual StatefulSet):**\n```bash\nkubectl set image statefulset/cockroachdb cockroachdb=cockroachdb/cockroach:<new-version>\n```\n\n**Verify each node before proceeding to the next:**\n```bash\ncockroach node status --certs-dir=<certs-dir> --host=<any-live-node> <upgraded-node-id>\n```\nThe targeted node should show `is_live = true` on the new `build`.\n\n### Monitor Progress\n\n```bash\ncockroach node status --certs-dir=<certs-dir> --host=<any-live-node>\n```\nCompare the `build` column across all rows. Nodes still on the old version are pending; rolling upgrade is complete when every row shows the new version.\n\n### Finalize (Major Version Only — Irreversible)\n\nConfirm via `cockroach node status` that the `build` column has a single value (every node upgraded). Then:\n\n```sql\nRESET CLUSTER SETTING cluster.preserve_downgrade_option;\nSHOW CLUSTER SETTING version;  -- Monitor until updated\n```\n\n### Roll Back (Before Finalization Only)\n\nVerify `cluster.preserve_downgrade_option` still returns the old version, then replace each node's binary with the previous version and restart. After all nodes are back:\n```sql\nRESET CLUSTER SETTING cluster.preserve_downgrade_option;\n```\n\n---\n\n## Advanced Upgrade\n\n**Applies when:** Tier = Advanced\n\nAdvanced clusters are managed by Cockroach Labs. You initiate major upgrades; patches are applied automatically.\n\n### Major Version Upgrade\n\n1. **Cloud Console → Cluster → Settings → Upgrade**\n2. Select target version\n3. CRL performs rolling upgrade across nodes automatically\n4. Monitor progress in Cloud Console\n5. Finalize via Cloud Console when testing is complete\n\n**Verification during upgrade:**\n```bash\ncockroach node status --certs-dir=<certs-dir> --host=<any-live-node>\n```\nTally the `build` column to see how many nodes are on the new version vs the old.\n\n### Patch Upgrades\n\nPatches are applied automatically during the configured maintenance window. See [performing-cluster-maintenance](../perform-cluster-maintenance/SKILL.md) for maintenance window configuration and patch deferral.\n\n### Release Channel\n\n- **Regular:** Stability-focused, longer support windows\n- **Innovation:** Latest features, shorter support, can be skipped\n\nConfigure via Cloud Console → Cluster → Settings → Upgrades.\n\n### Upgrade Before End of Support\n\nYou are responsible for initiating major upgrades before the current version reaches End of Support (EOS). Failure to upgrade before EOS may affect SLA guarantees.\n\n### Cloud API\n\n```bash\n# Check current version\ncurl -s -H \"Authorization: Bearer $COCKROACH_API_KEY\" \\\n  \"https://cockroachlabs.cloud/api/v1/clusters/<cluster-id>\" | jq '.cockroach_version'\n```\n\n---\n\n## BYOC Upgrade\n\n**Applies when:** Tier = BYOC\n\nBYOC upgrade procedures are the same as Advanced. Follow all [Advanced Upgrade](#advanced-upgrade) steps.\n\n### Cloud Provider Monitoring During Upgrade\n\nSince BYOC clusters run in your cloud account, you can observe the rolling upgrade in your infrastructure:\n\n**If AWS:** EC2 console shows instance restarts; CloudWatch metrics show brief dips during node cycling.\n\n**If GCP:** Compute Engine console shows VM restarts; Cloud Monitoring shows instance-level events.\n\n**If Azure:** Azure portal shows VM restarts; Azure Monitor captures instance events.\n\n### Additional BYOC Considerations\n\n- Verify PrivateLink/PSC/VPC Peering connections remain healthy during the upgrade\n- Reserved instances and committed use discounts are unaffected (instance types don't change)\n\n---\n\n## Standard Upgrade\n\n**Applies when:** Tier = Standard\n\nStandard is a multi-tenant managed service. There are no nodes or infrastructure for you to manage. All upgrades — both major versions and patches — are applied automatically by Cockroach Labs.\n\n- Only Regular releases (no Innovation channel)\n- No maintenance window configuration\n- No deferral capability\n- No downtime during upgrades\n\n### After an Upgrade\n\n1. Monitor Cloud Console for upgrade notifications\n2. Review release notes for behavior changes\n3. Verify application compatibility:\n   ```sql\n   SELECT version();\n   ```\n\n---\n\n## Basic Upgrade\n\n**Applies when:** Tier = Basic\n\nBasic is a serverless offering. All upgrades are fully managed and transparent. The serverless architecture is designed for zero-downtime upgrades with no customer action required.\n\n### After an Upgrade\n\n1. Review release notes for behavior changes\n2. Verify version if needed: `SELECT version();`\n\n---\n\n## Safety Considerations\n\n| Operation | Tier | Reversible? |\n|-----------|------|-------------|\n| Set preserve_downgrade_option | SH | Yes |\n| Replace node binary | SH | Yes (swap back before finalization) |\n| Finalize upgrade | SH | **No — irreversible** |\n| Initiate Cloud Console upgrade | ADV/BYOC | Contact support to discuss |\n| Automatic upgrade | STD/BAS | N/A (managed by CRL) |\n\n**Critical:**\n- Never skip major versions (SH) — upgrades must be sequential\n- Never finalize before testing (SH) — finalization is irreversible\n- Never change cluster settings during an upgrade (SH, ADV, BYOC)\n\n## Troubleshooting\n\n| Issue | Tier | Fix |\n|-------|------|-----|\n| Cannot set preserve_downgrade_option | SH | Value must match output of `SHOW CLUSTER SETTING version` |\n| Finalization stuck | SH | Decommission dead nodes; ensure all live nodes are upgraded |\n| Auto-finalization triggered early | SH | Cannot undo; test application on new version |\n| Upgrade not available in Console | ADV/BYOC | Check release schedule; contact support |\n| Behavior change after automatic upgrade | STD/BAS | Review release notes; contact support |\n\n## References\n\n**Related skills:**\n- [reviewing-cluster-health](../reviewing-cluster-health/SKILL.md) — Pre/post-upgrade health\n- [performing-cluster-maintenance](../perform-cluster-maintenance/SKILL.md) — Node drain (SH) and maintenance windows (ADV/BYOC)\n- [managing-cluster-settings](../managing-cluster-settings/SKILL.md) — preserve_downgrade_option\n\n**Official CockroachDB Documentation:**\n- [Upgrade Self-Hosted](https://www.cockroachlabs.com/docs/stable/upgrade-cockroach-version)\n- [Upgrade Cloud Cluster](https://www.cockroachlabs.com/docs/cockroachcloud/upgrade-cockroach-version)\n- [Cloud Upgrade Policy](https://www.cockroachlabs.com/docs/cockroachcloud/upgrade-policy)\n- [Upgrade on Kubernetes](https://www.cockroachlabs.com/docs/stable/upgrade-cockroachdb-kubernetes)\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}