Skip to content

Commit f51d2fd

Browse files
ArnobKumarSahaArnobKumarSaha
authored
Add cluster upgrade (#122)
Signed-off-by: Arnob Kumar Saha <arnob@appscode.com>
1 parent 88e520d commit f51d2fd

1 file changed

Lines changed: 211 additions & 0 deletions

File tree

‎docs/platform/guides/cluster-management/cluster-upgrade.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
---
2+
layout: docs
3+
menu:
4+
docsplatform_{{.version}}:
5+
identifier: cluster-upgrade
6+
name: Upgrade Cluster
7+
parent: cluster-management
8+
weight: 80
9+
menu_name: docsplatform_{{.version}}
10+
section_menu_id: guides
11+
---
12+
13+
14+
# Upgrading Your ACE Platform: Management, Imported, and Spoke Clusters
15+
16+
## Overview
17+
18+
This guide walks through upgrading an **AppsCode Container Engine (ACE)** deployment
19+
across all cluster tiers — the base management cluster, the AC cluster, general imported
20+
clusters, and spoke clusters. The example below upgrades from release `2025.5.16` to
21+
`2025.6.x`.
22+
23+
---
24+
25+
## Architecture
26+
27+
```
28+
┌─────────────────────────┐
29+
│ Management Cluster │
30+
│ (ACE control plane) │
31+
└────────────┬────────────┘
32+
│
33+
┌──────────────────┼──────────────────┐
34+
│ │ │
35+
┌──────────▼──────┐ ┌────────▼────────┐ ┌─────▼──────────┐
36+
│ ACE Cluster │ │ Imported Cluster │ │ Spoke Cluster │
37+
│ (management) │ │ (generic import) │ │ (generic import│
38+
└─────────────────┘ └─────────────────┘ └────────────────┘
39+
```
40+
41+
Each tier is upgraded separately; the order matters.
42+
43+
---
44+
45+
## Pre-checks
46+
47+
Before starting, verify your current installer version and target release.
48+
49+
1. Log in to [appscode.com](https://appscode.com) and switch to your organization.
50+
2. Navigate to your installer and click **View Details**.
51+
3. Note the **current version** (e.g., `2025.5.16`) and confirm the **target version**
52+
(e.g., `2025.6.x`).
53+
54+
```bash
55+
# Confirm current Helm release versions on the management cluster
56+
helm list -A | grep opscenter-features
57+
58+
# Watch releases during upgrade
59+
kubectl get helmreleases -A -w
60+
```
61+
62+
---
63+
64+
## Upgrade Flow
65+
66+
### Step 1 — Download the new installer archive
67+
68+
1. On the installer page, click **Upgrade to <x.y.z>**.
69+
2. Click **Download** to get the updated `.values` (val) file.
70+
3. The downloaded archive lands in your local archive folder (e.g., `archive2/`).
71+
72+
```bash
73+
# Optional: inspect the downloaded values file before applying
74+
cat ~/Downloads/<release>.values.yaml
75+
```
76+
77+
---
78+
79+
### Step 2 — Apply the upgrade via Platform UI
80+
81+
1. Switch from the **Console UI** to the **Platform UI**.
82+
2. Go to **User Settings → Upgrade**.
83+
3. Select the val file downloaded in Step 1.
84+
4. Click **Update Version**.
85+
86+
The platform creates a background job that updates Helm releases one by one.
87+
88+
```bash
89+
# Monitor the upgrade job on the management cluster
90+
kubectl get jobs -n ace -w
91+
92+
# Watch Helm releases roll forward
93+
kubectl get helmreleases -A -w
94+
```
95+
96+
> **Expected state:** `current version: 5.16 → update in progress: 6.16`
97+
98+
Once the job completes, verify the op-center feature set reflects the new version.
99+
100+
---
101+
102+
### Step 3 — Upgrade spoke clusters
103+
104+
Spoke clusters are imported as **generic DBaaS** generally. Update them individually before
105+
updating the cluster set.
106+
107+
1. In the Console, go to **Your Organization → Hub Cluster → ACE**.
108+
2. Select the correct **Cluster set** (how you imported). For example, Generic DBaaS.
109+
3. Select your spoke cluster.
110+
4. Click **Update ACE Resources → Update Version → Yes**.
111+
112+
![Upgrade](images/upgrade/upgrade_1.png)
113+
114+
```bash
115+
# After triggering, watch the QB operator start the upgrade on the spoke
116+
kubectl get helmreleases -A -w --context <spoke-cluster-context>
117+
118+
# Wait for all pods to return to Running
119+
kubectl get pods -A --context <spoke-cluster-context>
120+
```
121+
122+
The cluster set manifest (which holds metadata about all spoke clusters) updates
123+
almost instantly. The underlying Helm releases take longer — wait for them to
124+
reconcile before moving on.
125+
126+
---
127+
128+
### Step 4 — Upgrade general imported clusters
129+
130+
1. In the Console, select the **General Imported Cluster**.
131+
2. Open its **Settings** page and click **Update Version**.
132+
133+
```bash
134+
# Verify on the imported cluster
135+
kubectl get helmreleases -A --context <imported-cluster-context>
136+
```
137+
138+
This path updates Helm releases directly (not via a cluster set), so progress is
139+
visible immediately.
140+
141+
---
142+
143+
### Step 5 — Update the cluster set
144+
145+
After **all** individual clusters are on the new version:
146+
147+
1. In the Console, go to **Your Organization → Hub Cluster → ACE**.
148+
2. Select the correct **Cluster set** (how you imported). For example, Generic DBaaS.
149+
3. Click **Update Cluster Set**.
150+
151+
```bash
152+
# Confirm cluster set version
153+
kubectl get clusterset -A
154+
```
155+
156+
> Before clicking **Update Cluster Set**, you will see the cluster set still shows the old version (e.g., `5.6`).
157+
> After the update it will be marked as **unaligned** briefly, then reconcile.
158+
159+
---
160+
161+
### Step 6 — Verify
162+
163+
```bash
164+
# Check every Helm release is at the new version across all clusters
165+
for ctx in management spoke imported; do
166+
echo "=== $ctx ==="
167+
helm list -A --kube-context $ctx | grep -v DEPLOYED
168+
done
169+
170+
# Spot-check the search manager (may self-update from the cluster side)
171+
kubectl get deployment search-manager -n ace -o jsonpath='{.spec.template.spec.containers[0].image}'
172+
```
173+
174+
All clusters should report version `6.6.16` (or your target release).
175+
176+
---
177+
178+
## Lessons Learned
179+
180+
| Observation | Takeaway |
181+
|---|---|
182+
| One Helm release failed to update via the job | It had already reconciled from the cluster side — not always an error |
183+
| Cluster set update is near-instant | It only patches a manifest, not the releases themselves — releases follow async |
184+
| Search manager self-updated | Some components pull their version from the cluster operator, not the installer job |
185+
| Upgrade order matters | Always update individual clusters **before** the cluster set |
186+
| Ports need time after upgrade | Wait for all pods to reach `Running` before declaring success |
187+
188+
---
189+
190+
## Quick Reference
191+
192+
```
193+
appscode.com → Download val file
194+
↓
195+
Platform UI → Update Version (Management / Platform cluster)
196+
↓
197+
Console → Generic DBaaS → Update AC Resources (each spoke)
198+
↓
199+
Console → Generic DBaaS → Update Cluster Set
200+
↓
201+
Console → Imported Cluster → Settings → Update Version
202+
↓
203+
Verify: helm list -A across all contexts
204+
```
205+
206+
No downtime during upgrade procedure — the platform performs rolling Helm release updates and
207+
most workloads stay running throughout.
208+
209+
---
210+
Here is a sample video on how you can setup the full platform:
211+
<iframe width="1900" height="869" src="https://www.youtube.com/embed/99_8acxcr-s" title="6. Upgrade procedure" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

0 commit comments

Comments
 (0)