Step-by-Step: Upgrading Segura® Platform Online in Cluster Mode with an Arbitrator

PAM Core
,
1

Disclaimer: This guide is based on my personal experience upgrading a Segura® Platform cluster after studying the official documentation, combining different procedures, and successfully performing the upgrade myself. It is not an official Segura® guide. Always review the official documentation before performing upgrades in a production environment.

Step 1 – Remove the Arbitrator

Before starting the upgrade, remove the arbitrator from the cluster.

On the arbitrator host:

cd /opt/manifests/docker-compose
docker compose down
# or
docker-compose down

Step 2 – Take VM Snapshots

Before upgrading, create snapshots of all Segura® Platform instances.

Important

  • In clustered environments, always take snapshots in reverse order , starting from the last member and ending with the primary member .
  • Take snapshots of each VM individually .
  • Shut down one instance at a time, create its snapshot, power it back on, and verify that it has fully synchronized before proceeding to the next instance.
  • Snapshots should only be taken while the Segura® Platform instances are offline. This guarantees you can roll back if necessary.

On the Secondary Instance

Shut down the appliance:

orbit shutdown

Wait until the VM is completely powered off.

Create a snapshot from your hypervisor.

Power the VM back on and wait until it is fully synchronized.

On the Primary Instance

Repeat the same procedure:

orbit shutdown

Once the VM is completely powered off, create a snapshot in your hypervisor.

Power it back on and verify that the cluster is synchronized.

At this point, your recovery snapshots are ready.

Step 3 – Verify Cluster Health

Before upgrading, ensure replication is healthy.

Navigate to:

Orbit Server Manager → Replication → Status

Verify that all cluster members are:

  • ON
  • Synchronized

Only continue if the cluster is healthy.

Step 4 – Upgrade the Primary Instance

Update package information:

apt-get update

Install or update Orbit CLI:

apt-get install orbit-cli

Start the upgrade:

orbit update

During the Upgrade

In some versions, after running orbit update , the system requests a reboot and then an orbit upgrade .

If prompted:

orbit shutdown --reboot

After the appliance comes back online:

orbit upgrade

Finally, reboot once more:

orbit shutdown -r

Note: In my experience, repeating the update cycle (orbit update ) around three times was sufficient to ensure the appliance reached the latest available version. This may vary depending on your current version and available updates.

Step 5 – Upgrade the Secondary Instance

Repeat exactly the same upgrade procedure on the secondary node:

  • apt-get update
  • apt-get install orbit-cli
  • orbit update
  • Reboot if requested
  • orbit upgrade
  • Final reboot

Wait until the node rejoins the cluster and synchronization is complete before moving to the next step.

Step 6 – Recreate the Arbitrator

Generate new arbitrator configuration files.

Older versions

orbit cluster arbiter create-config

Newer versions

orbit cluster galera arbiter create-config

Transfer the generated archive to the Docker host:

scp /var/tmp/senhasegura-cluster-arbiter/manifests.tar.gz \
user@ARBITRATOR_IP:/tmp/

On the arbitrator machine:

Go to /opt :

cd /opt

Remove the old manifests:

rm -rf manifests

Extract the new manifests:

tar -xzvf /tmp/manifests.tar.gz

Go to the Docker Compose directory:

cd manifests/docker-compose

Start the containers:

docker compose up -d
# or
docker-compose up -d

Step 7 – Verify Arbitrator Status

Older versions

orbit cluster arbiter status

Newer versions

orbit cluster galera arbiter status

Expected output:

senhasegura cluster arbiter

Status: ENABLED
Arbiter IP address: xxx.xxx.xxx.xxx

Galera Cluster arbiter (garbd) status:
Connected, OK

Elasticsearch arbiter status:
Connected, OK

Final Verification

Once the upgrade is complete:

  • Verify that all cluster members are synchronized.
  • Confirm replication is healthy.
  • Validate that all services are running.
  • Confirm the arbitrator reports Connected, OK .
  • Test user authentication and privileged sessions.

References

This guide was prepared after reviewing and combining information from the official Segura® documentation together with practical upgrade experience.

Note: This article is an independent community guide and is not an official Segura® publication . Always refer to the latest official documentation before performing upgrades in production environments, as procedures may vary between versions.

2 Likes
2

Awesome guide Hassan!

I follow most of the same process. I also have some additional experiences which may be of use for some:

Sometimes in- and outbound SCP traffic seems blocked by an AppArmor profile. SCP transfer can be enabled by:

orbit support scp allow

I do think, that the orbit update and orbit upgrade commands are exactly the same and can be used interchangeably.

I always preload the updates with orbit update --download-only on all nodes. This way, you can minimise downtime, and the actual update process is much quicker.

If a multi tenancy license is available but not actually needed, multi tenancy still gets enabled after every upgrade. It needs to be disabled with orbit multi-tenancy disable (need to double check the command).

I’m always updating in a screen session, especially when connected through SSH. This means that if the connection drops, I can still reconnect to the running update session using the commands screen -ls and screen -r.

Segura seems to have a maintenance mode (orbit application maintenance), but I’m not sure if this is needed in V4.0+ anymore. I don’t think it does anything anyway. Do you know anything more about it, by chance?

1 Like
3

Thank you for the interesting tip!

As far as I know, Maintenance Mode is used to pause asynchronous tasks handled by NATS. In a clustered environment, these asynchronous tasks are executed by the primary instance.

During an upgrade, it’s possible that an asynchronous task (such as a password rotation or another scheduled operation) is running. Enabling Maintenance Mode helps prevent these tasks from starting or continuing during the upgrade, ensuring they are not interrupted and protecting the consistency of ongoing operations.

1 Like