Skip to content

Upgrading the Traceable Operator

This guide covers how to upgrade the Traceable Operator (also known as Traceable Installer).

Overview

The Traceable Operator manages the installation and configuration of the Traceable Platform. Upgrading the operator ensures you have the latest features and bug fixes for managing your platform.

Prerequisites

Before upgrading the operator:

  • Ensure the platform is stable and healthy
  • Complete a backup of the installer state (see below)
  • Have the target operator version number ready

Backup Installer State

Highly Recommended: Always backup the traceable installer state before upgrading the operator.

Steps to Backup

  1. Login to the Traceable Operator UI
  2. Click on the Backup State menu in the sidebar
  3. Click on the Download Zip button
  4. Save the zip file to a secure location

Important: This backup contains all your configuration and state information. Keep it safe for recovery purposes.

Upgrade Methods

You can upgrade the operator using two methods:

  1. UI Method - Visual interface
  2. ClusterMgr Method - Command-line interface

UI Method

Steps

  1. Click on Upgrade Cluster in the sidebar menu
  2. Click on the Upgrade Operator button
  3. Enter the version of the Operator to upgrade to (e.g., 2.5.0)
  4. Leave the Additional Args field blank (unless instructed by Traceable support)
  5. Click Trigger Upgrade

Expected Behavior

  • The Operator will restart with the new version
  • The UI will be unavailable for a few seconds during the restart
  • The page will automatically reconnect once the operator is back online

Verification

After the upgrade:

  1. Wait for the UI to become available again (usually 30-60 seconds)
  2. Login to the Operator UI
  3. Verify the version number in the UI footer or about page
  4. Confirm all configurations are intact

ClusterMgr Method

1. Download Latest ClusterMgr

Download the latest clustermgr from the downloads portal:

https://downloads.traceable.ai/#platform/installer/clustermgr/linux-amd64/

2. Run the Upgrade Command

Execute the following command:

./clustermgr upgrade --ti-set cluster.triggerUpgrade=false \
  --skip-workflow-exec

Parameters:

  • cluster.triggerUpgrade=false: Prevents automatic platform upgrade
  • --skip-workflow-exec: Only upgrades the operator, not the platform

3. Wait for Completion

The upgrade process will:

  1. Update the operator deployment
  2. Restart the operator pod
  3. Wait for the operator to become healthy

Monitor the upgrade:

# Watch operator pod status
kubectl get pods -n <traceable-namespace> -l app=traceable-operator -w

# Check operator logs
kubectl logs -n <traceable-namespace> -l app=traceable-operator -f

4. Verify Upgrade

After the upgrade completes:

  1. Wait for the operator pod to be in Running state
  2. Login to the Operator UI
  3. Verify the version number
  4. Confirm all configurations are intact

Post-Upgrade Verification

1. Check Operator Status

kubectl get pods -n <traceable-namespace> -l app=traceable-operator

Expected output:

NAME                                  READY   STATUS    RESTARTS   AGE
traceable-operator-xxxxxxxxxx-xxxxx   1/1     Running   0          2m

2. Check Operator Logs

kubectl logs -n <traceable-namespace> -l app=traceable-operator --tail=50

Look for:

  • Successful startup messages
  • No error messages
  • Version information

3. Access Operator UI

  1. Navigate to the Operator URL
  2. Login with your credentials
  3. Verify you can access all pages
  4. Check that the version is displayed correctly

4. Verify Platform Management

  1. Navigate to Install Workflow page
  2. Verify you can see all services
  3. Check that Upgrade Cluster functionality is accessible
  4. Confirm Backup State is working

Troubleshooting

Operator Pod Not Starting

If the operator pod fails to start:

  1. Check pod status:
kubectl describe pod -n <traceable-namespace> -l app=traceable-operator
  1. Check for image pull errors:
kubectl get events -n <traceable-namespace> --sort-by='.lastTimestamp'
  1. Verify image availability:
    • Ensure the operator image for the target version is available
    • Check image pull secrets are configured correctly

UI Not Accessible After Upgrade

If the UI is not accessible:

  1. Check operator pod logs:
kubectl logs -n <traceable-namespace> -l app=traceable-operator
  1. Check service and ingress:
kubectl get svc,ingress -n <traceable-namespace>
  1. Verify DNS resolution:
    • Ensure the operator URL resolves correctly
    • Check ingress controller is working

Configuration Lost After Upgrade

If configurations appear to be lost:

  1. Check persistent volume:
kubectl get pvc -n <traceable-namespace>
  1. Restore from backup:
    • Use the backup zip file created before upgrade
    • Contact Traceable support for restoration assistance

Rollback Operator Upgrade

If you need to rollback the operator:

  1. Using ClusterMgr:
./clustermgr upgrade --ti-set cluster.version=<previous-version> \
  --ti-set cluster.triggerUpgrade=false \
  --skip-workflow-exec

  1. Using UI:

    • Follow the same upgrade process but specify the previous version

  2. Restore from backup:

    • If needed, restore the installer state from the backup zip file
    • Contact Traceable support for assistance

Best Practices

Before Upgrade

  • Backup installer state
  • Document current operator version
  • Verify platform is healthy
  • Schedule maintenance window
  • Notify stakeholders

During Upgrade

  • Monitor operator pod status
  • Watch for errors in logs
  • Keep backup accessible
  • Do not make configuration changes

After Upgrade

  • Verify operator version
  • Test UI accessibility
  • Confirm all configurations intact
  • Document upgrade completion
  • Update runbooks with new version

Operator vs Platform Upgrade

Important Distinction:

  • Operator Upgrade: Updates the management/installer component only
  • Platform Upgrade: Updates the actual Traceable services (API, UI, processors, etc.)

You can upgrade the operator independently of the platform. However, ensure operator version compatibility with your platform version.

Version Compatibility

Consult with Traceable support to ensure:

  • Operator version is compatible with your platform version
  • No breaking changes in the operator upgrade
  • Any special upgrade instructions for your version path

Support

For operator upgrade assistance or issues, contact: support@harness.io