Skip to main content

Standard Upgrade Guide

📘 Overview​

This guide explains how to safely upgrade CSGHUB in a production environment. The upgrade process ensures data security, service continuity, and minimal downtime.

💡 Scope: Applicable for CSGHUB clusters deployed via Helm Chart.

⚙️ Prerequisites​

✅ Environment Requirements​

ItemRequirement
Kubernetes Clusterv1.33+, cluster in healthy state (kubectl get nodes all Ready)
Helmv3.12.0+, with administrator privileges
CSGHUB DeploymentRunning instance successfully deployed via Helm

⚠️ Note: Always backup data and save configuration before upgrading to prevent data loss.

💾 Pre-Upgrade Preparation​

1️⃣ Backup Current Configuration​

Export current Helm values:

helm get values csghub -n csghub -o yaml > csghub-values-backup.yaml

2️⃣ Backup Critical Data​

At minimum, backup the following:

ComponentBackup Method
Database (PostgreSQL)Follow database backup and restore guide
Helm ValuesAlready exported as csghub-values-backup.yaml

💡 Recommended: Use snapshot-based backups (e.g., Ceph Snapshot / RDS Snapshot) for consistency.

🧩 Upgrade Steps​

1️⃣ Update Helm Repository​

helm repo update

Check available versions:

helm search repo csghub/csghub --versions

Example output:

NAME              	CHART VERSION	APP VERSION	DESCRIPTION
csghub/csghub     	1.16.0        v1.16.0     CSGHub charts with CE and EE.
......

2️⃣ Version Notes​

v1.16.0​

Starting with v1.16.0, the system deprecates ingress-nginx by default and uses envoyGateway instead.

Because Helm upgrades do not automatically create the CRDs (CustomResourceDefinitions) required by dependent components, if the current cluster version is lower than v1.16.0, the relevant CRDs need to be manually installed before upgrading.

Execute the following script:

curl -sSL https://charts.opencsg.com/repository/scripts/crds_install.sh | bash

This script is used to:

  • Install envoyGateway related CRDs

  • Ensure related components function correctly after upgrading to v1.16.0

v1.17.0​

Starting from v1.17.0, the resources of the following components will be centrally managed by CSGHub Helm Chart:

  • Knative Serving

  • Argo Workflow

  • LeaderWorkSet

To allow Helm to take over these components, existing resources need to be patched during the upgrade to add Helm management-related metadata.

Execute the following script:

curl -sSL https://charts.opencsg.com/repository/scripts/crds_takeover.sh | bash

This script is used to:

  • Add Helm management information to existing Knative Serving / Argo Workflow / LeaderWorkSet resources

  • Enable these resources to be taken over and integrated into unified management by CSGHub Helm Chart

Note: If the target version for the upgrade is v1.17.0 or higher, the above scripts must be executed sequentially.

3️⃣ Execute Upgrade Command​

Execute upgrade command:

helm upgrade --install csghub csghub/csghub \
  --namespace csghub \
  -f csghub-values-backup.yaml

To upgrade to a specific version:

helm upgrade csghub csghub/csghub \
  --namespace csghub \
  -f csghub-values-backup.yaml \
  --version 1.17.0

⚠️ If you modified the domain or enabled HTTPS, ensure the following parameters remain consistent:

--set global.ingress.domain="<your-domain>" \
--set global.ingress.tls.enabled=true \
--set global.ingress.tls.secretName="csghub-tls-certs"

4️⃣ Verify Upgrade Status​

helm status csghub -n csghub

Check if all Pods are running:

kubectl get pods -n csghub

Normally, all components should be in Running or Completed state.

🔄 Rollback (If Needed)​

To roll back if issues occur:

Check revision history:

helm history csghub -n csghub

Rollback to a previous revision:

helm rollback csghub <revision> -n csghub

⚠️ Rollback does not automatically restore external database or storage data. Use backups if needed.

🔍 Post-Upgrade Validation​

Verify services:

ServiceValidation Command / Action
CSGHUB PortalAccess http://csghub.example.com
Casdoor ConsoleAccess http://casdoor.example.com
Temporal ConsoleAccess http://csghub.example.com/-/temporal
MinIO ConsoleAccess http://minio.example.com:30080/console
RegistryExecute docker login csghub.example.com to verify availability

To retrieve credentials:

kubectl get secret -n csghub csghub-casdoor-init \
  -o jsonpath='{.data.INIT_ADMIN_USER}' | base64 -d && echo -n " / " && \
kubectl get secret -n csghub csghub-casdoor-init \
  -o jsonpath='{.data.INIT_ADMIN_PASSWORD}' | base64 -d

⚡ Common Issues​

🔒 Safe Upgrade Recommendations​

  • ✅ Test version compatibility in a staging environment before production.
  • ✅ Retain at least 2 historical versions for quick rollback.

📚 References​