Skip to main content

Upgrading Ice Flow

This guide covers how to upgrade Ice Flow to a new version. Upgrades replace the running binary, image, or chart and restart the service. Because all catalog, warehouse, scope, monitor, and replication state lives in Symphony's JetStream buckets—not on the Ice Flow host—upgrades are stateless from the extension's point of view. Active replications and monitors resume from their last bucket-tracked position on restart.

info

The commands below vary by deployment method. Ensure the required tools are installed for your environment.

Pre-Upgrade Checklist​

Before upgrading:

  1. Review the release notes for breaking changes or migration steps.
  2. Verify the extension is healthy. Confirm Ice Flow is connected and running: 
    cirata extension list
  3. Plan for downtime. Ice Flow stops accepting work while the new version starts. Active replications pause and resume after restart; expect 30–60 seconds of unavailability for the restart itself.
  4. Note custom configuration edits. The RPM marks iceflow.env, application.properties, and logback.xml as CONFIG | NOREPLACE, so admin edits survive upgrades. New defaults land in .rpmnew files for review.

RPM Upgrade​

sudo dnf upgrade cirata-iceflow-<new-version>.x86_64.rpm

On SLES:

sudo zypper update cirata-iceflow-<new-version>.x86_64.rpm

The package post-install scriptlet restarts the service automatically.

After the upgrade, review any .rpmnew files that appeared in /etc/cirata/symphony/extensions/iceflow/ and merge new defaults into your edited configuration as needed:

ls /etc/cirata/symphony/extensions/iceflow/*.rpmnew

Docker Upgrade​

# Pull or load the new image
docker pull cirata/iceflow:<new-version>

# Compose: update IMAGE_TAG and recreate
IMAGE_TAG=<new-version> SYMPHONY_TOKEN=<token> \
  docker compose up -d --force-recreate

For direct docker run workflows, stop and remove the old container, then start a new one against the new image tag:

docker stop cirata-iceflow && docker rm cirata-iceflow

docker run -d \
  --name cirata-iceflow \
  --restart unless-stopped \
  -e SYMPHONY_TOKEN=<token> \
  -v iceflow-logs:/var/log/cirata \
  cirata/iceflow:<new-version>

Kubernetes Upgrade​

helm upgrade my-iceflow iceflow-<new-version>.tgz \
  --reuse-values

kubectl rollout status deployment/my-iceflow

Pass --set image.tag=<new-version> if the chart version itself has not changed but you only want to roll a new image. Use --reset-values instead of --reuse-values to pick up new default values introduced by the chart.

Post-Upgrade Verification​

  1. Extension reconnects. Allow 30–60 seconds, then confirm: 
    cirata extension list
    Ice Flow should appear with the new version.
  2. Logs are clean. Review startup output for token, NATS, or Kerberos errors: 
    # RPM
    sudo journalctl -u cirata-iceflow --since "5 min ago"

    # Docker
    docker logs --tail 100 cirata-iceflow

    # Kubernetes
    kubectl logs -l app.kubernetes.io/instance=my-iceflow --tail 100
  3. Work resumes. Open at least one active monitor or replication in the Symphony UI and confirm a fresh event or operation timestamped after the restart.

Rollback​

If the upgrade causes issues, roll back to the previous version.

RPM​

sudo dnf downgrade cirata-iceflow-<previous-version>.x86_64.rpm

Docker​

IMAGE_TAG=<previous-version> SYMPHONY_TOKEN=<token> \
  docker compose up -d --force-recreate

Kubernetes​

helm rollback my-iceflow

Or roll back the underlying Deployment:

kubectl rollout undo deployment/my-iceflow
warning

Rollback is safe when no release between the two versions changed the schema of the JetStream buckets Ice Flow owns. Release notes call out any such change. When in doubt, take a backup of the Symphony configuration directory before upgrading so the bucket state can be restored alongside the binary.

Data Migration​

Ice Flow's persistent state lives in Symphony's iceflow_* JetStream buckets. The extension creates and migrates these on startup—new buckets introduced by a release are created automatically, and existing buckets are preserved across upgrades.

No host-local data migration is required.

Token Handling Across Upgrades​

If you installed Ice Flow with the registration-token flow, the permanent API key the SDK provisioned on first start lives in the OS credential store (or ~/.config/cirata/ as a fallback) under the cirata user. Upgrades leave this storage untouched, so no re-provisioning happens and you do not need to re-issue a registration token.

For Docker and Kubernetes installs that use a pre-provisioned SYMPHONY_TOKEN secret, the secret is independent of the image or chart version—upgrades pick up the same secret and reconnect immediately.

See Also​