---
title: Upgrade Management
slug: upgrade-management
createdAt: 2026-02-24T04:09:16.268Z
---

# Overview

Kubegrade Upgrade Management helps teams reduce manual effort and upgrade risk by turning Kubernetes upgrades into a guided, auditable workflow.

### Core outcomes

- Faster upgrade planning
- Preflight validation before changes
- Safer execution with approvals
- PR-based, GitOps-compatible remediation where config changes are required
- Better auditability and rollback readiness



# Supported Kubernetes versions/providers

## Providers

- Amazon / AWS / EKS
- GoogleCloud / GKE
- Microsoft Azure / AKS
- OpenShift
- DigitalOcean
- AlibabaCloud
- Rancher/RKE (if supported)
- Self-managed upstream Kubernetes



## Version support format (recommended)

### Provide

- Minimum supported version per provider
- Tested upgrade paths (N → N+1, etc.)
- Unsupported/skipped paths
- Provider-specific notes (managed add-ons, control plane sequencing, nodegroup specifics)



# Preflight checks (API deprecations, add-ons, constraints)

Preflight checks are run before upgrade execution to identify blockers and risk.



## Typical checks

- Kubernetes API deprecations in manifests
- Add-on compatibility (CNI, CSI, ingress controllers, metrics stack)
- Version skew constraints
- Pod disruption budget / capacity constraints
- Node image/runtime prerequisites
- Admission controller and policy conflicts
- Deprecated Helm chart APIs / CRD compatibility
- Cluster health baseline (unhealthy nodes, failing workloads)



## Output

### Preflight results should be categorized as

- Blockers (must fix)
- Warnings (recommended fixes)
- Informational notes



# Upgrade plans (single / multi-cluster)

## Single-cluster upgrade plan

### Includes

- Cluster target version
- Preflight status
- Required remediations
- Maintenance window
- Rollback strategy
- Approval requirements



## Multi-cluster upgrade plan

### Adds

- Sequencing (development -> canary → staging → production)
- Cluster grouping by environment/provider/team
- Parallelism constraints
- Success gates between waves
- Standardized runbook application



## Recommended pattern

1. Development cluster
2. Canary cluster
3. Staging cluster(s)
4. Limited production wave
5. Broad production rollout



# Scheduling + maintenance windows

Kubegrade supports scheduling upgrades and workflows within controlled windows via the agents.



## Scheduling capabilities

- One-time scheduled execution
- Recurring maintenance windows
- Timezone-aware windows
- Environment-specific restrictions
- Freeze windows / blackout periods



## Operational controls

- Preflight refresh before execution
- Re-approval if conditions changed
- Auto-cancel on critical health regressions (if configured)



# What gets written where (PR contents, provenance)



## Typical PR contents

- Manifest or values updates
- Version pin changes
- Compatibility fixes
- Config changes required by target version
- Explanatory summary of why changes are required
- References to preflight findings



## Provenance metadata (recommended)

- Workflow run ID
- Cluster / environment
- Policy checks passed/failed
- Agent/version used
- Timestamp
- Approver(s) (linked in audit trail)



# Runbooks: common upgrade failure modes

## 1) Node upgrade stalls

### Possible causes

- Pod disruption budgets too strict
- Capacity shortage
- DaemonSet rollout blocking drain
- Misconfigured eviction settings

### Response

- Review draining events
- Temporarily scale capacity / relax constraints (approved)
- Retry wave



## 2) Workloads fail after upgrade

### Possible causes

- API deprecations missed
- Admission/policy incompatibility
- Ingress/controller changes
- CRD/version mismatch

### Response

- Review failing workloads and dependency graph impact
- Generate remediation PR
- Roll back workload config or cluster wave if needed



## 3) Add-on incompatibility

### Possible causes

- Unsupported add-on version for target K8s version
- CSI/CNI version skew
- Metrics/monitoring stack incompatibility

### Response

- Pin compatible add-on version
- Upgrade add-ons in required order
- Re-run preflight



## 4) Control plane/node version skew issues

### Possible causes

- Validate provider sequencing rules
- Reconcile managed nodegroups
- Apply supported path only

### Response

- Validate provider sequencing rules
- Reconcile managed nodegroups
- Apply supported path only