Upgrading with Ansible (3.7 -> 3.7.1)

1 1. Overview
2 2. Prerequisites
3 3. Upgrade Procedure
4 4. Verification

1. Overview

This guide provides step-by-step instructions for upgrading an existing Syndeia Cloud installation to version 3.7.1 using the Ansible playbook. For fresh installations, see Ansible Deployment

Supported upgrade paths:

Syndeia Cloud 3.6 SP2 (scripted install) → 3.7.1 (Ansible)
Syndeia Cloud 3.7.x (scripted install) → 3.7.1 (Ansible)
Syndeia Cloud 3.7.x (Ansible install) → 3.7.1 (Ansible)

The upgrade is automatic — the playbook detects the existing installation via the syndeia-cloud-current symlink and switches to upgrade mode. No special flags are needed. The same ansible-playbook command is used for both fresh installs and upgrades.

The playbook handles:

Automatic Detection: Identifies the existing version and installation method (scripted or Ansible).
Secret Recovery: Preserves JWT and Play Framework secrets so active sessions survive the upgrade.
Configuration Migration: Carries forward your customizations while incorporating new defaults (see Section 5).
Dependency Upgrades: Side-by-side installation of Java, Cassandra, Kafka, and JanusGraph with symlink cutover.
Kafka ZooKeeper→KRaft Migration: Automatic migration from ZooKeeper to KRaft mode when upgrading from 3.6 SP2, with data-loss safety checks.
Artifact Porting: HTTPS configuration, keystore, vendor libraries, and Java CA certificates copied from the old installation.
Data Preservation: All Cassandra keyspaces, Kafka topics, and JanusGraph data are preserved.

2. Prerequisites

2.1 Before You Begin

Know your passwords. The playbook verifies credentials against the running system before making any changes. You will need:
- The syndeia_admin Cassandra password (set during original installation)
- The super.user Syndeia Cloud password (default: syn45ia)
Collect pre-upgrade statistics. Before starting the upgrade, collect baseline statistics from your running SC 3.7 instance. These metrics will be compared after the upgrade to verify successful data migration.
Stage 1 - Collect statistics from Source Syndeia Cloud 3.6 Server
Read the Fresh Installation Guide first [here] if you have not previously worked with the Ansible deployment. This guide assumes familiarity with the playbook structure, customer_config.yml, and inventory setup.
Back up your data. While the upgrade preserves all databases, taking a snapshot is strongly recommended:
sudo tar czf ~/syndeia-backup-$(date +%Y%m%d).tar.gz \ /opt/icx/syndeia-cloud-current/ \ /var/lib/cassandra/data/
Verify system resources. The playbook checks these automatically, but confirming them in advance avoids surprises:
- See Software and Hardware Requirements
- 16 CPU cores, 32 GB RAM
- 40 GB free on the Cassandra data partition, 10 GB on /opt, 10 GB on /tmp
  
  Note: These values are based on our standard deployment guidelines. If your environment has different resource constraints, you can adjust the thresholds in the customer_config.yml file.

2.2 Software Packages

Download the following from the Intercax secure file share (see your license email):

syndeia-cloud-3.7.1.zip (The application package)
syndeia-cloud-3.7.1-ansible.zip (The deployment automation package)

3. Upgrade Procedure

Stage 1: Preparation

Note: All steps in this procedure (Stages 1 through 3 ) must be performed on the Ansible controller node. The Ansible control node may either be

The same machine where Syndeia Cloud is being installed /upgraded or
A separate dedicated machine

Step 1: Transfer Files

Transfer the downloaded packages to your home directory of Ansible control node

From a Linux/macOS workstation:

scp syndeia-cloud-3.7.1.zip syndeia-cloud-3.7.1-ansible.zip <user>@<server-ip>:~/

From a Windows workstation, use WinSCP, FileZilla, or a similar SFTP client. Connect to the target server with your SSH credentials and upload both zip files to your home directory (/home/<user>/).

Step 2: Stage the New Application Package

SSH into the Ansible control server and move the application zip to the software directory:

ssh <user>@<server-ip>
mkdir -p ~/syndeia-software
mv ~/syndeia-cloud-3.7.1.zip ~/syndeia-software/

If older zip files exist in that directory, either remove them or specify the exact filename later in customer_config.yml:

ls ~/syndeia-software/syndeia-cloud-*.zip

If multiple zips are present, remove the old one to avoid ambiguity:

rm ~/syndeia-software/syndeia-cloud-3.7.zip

Or specify the exact filename in Step 4:

customer_syndeia_zip_filename: "syndeia-cloud-3.7.1.zip"

Step 3: Update the Ansible Package

Extract the new Ansible package:

unzip ~/syndeia-cloud-3.7.1-ansible.zip -d ~/syndeia-cloud-3.7.1-ansible
cd ~/syndeia-cloud-3.7.1-ansible

Stage 2: Configuration

Step 4: Set Up Configuration

First, determine whether you have a previous Ansible deployment directory on the Ansible control node:

# Check if a previous Ansible directory exists
ls ~/syndeia-cloud-*-ansible/ 2>/dev/null || echo "No previous Ansible directory found"

Case 1: Previous Ansible deployment exists (upgrading from a previous Ansible-based install):

# Find your previous Ansible directory
ls -d ~/syndeia-cloud-*-ansible/


#Copy configuration files from the previous directory
# Replace <old-version> with your actual previous version (e.g., 3.7)
cp ~/syndeia-cloud-<old-version>-ansible/customer_config.yml ~/syndeia-cloud-3.7.1-ansible/
cp ~/syndeia-cloud-<old-version>-ansible/inventory.ini ~/syndeia-cloud-3.7.1-ansible/

Note: The destination ~/syndeia-cloud-3.7.1-ansible/ is the directory you extracted in Step 3. Make sure you are copying into this new directory, not the old one.

Case 2: No previous Ansible deployment (upgrading from a scripted install or first-time Ansible use), or if you are unable to locate a previous Ansible deployment directory.

Create new configuration files from the provided templates:

# Make sure you are in the new Ansible directory first
cd ~/syndeia-cloud-3.7.1-ansible

# Create configuration files from templates
cp customer_config.yml.template customer_config.yml
cp inventory.ini.template inventory.ini

Important: These template files already exist in the extracted Ansible package directory. Do not look for them elsewhere.

Then configure inventory.ini as described in the Fresh Installation Guide, Stage 2.

Local Installation:

If you are installing Syndeia Cloud on the same server from which you are running Ansible, replace your-syndeia-server.example.com with localhost ansible_connection=local:

[syndeia_cloud_servers]
localhost ansible_connection=local

Note: The inventory.ini file includes a property referencing your personal SSH private key (~/.ssh/id_rsa). This file may not exist on the server unless you have previously used it as a bastion or jump host.

To check if it already exists:

ls ~/.ssh/id_rsa

If it does not exist, generate a new SSH key pair using the following command:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Replace your_email@example.com with your email address or any text that helps you identify the key. When prompted for a passphrase, press Enter to skip — no passphrase is recommended for Ansible use.

The command will produce output similar to the following:

Generating public/private rsa key pair.
Enter file in which to save the key (/home/test/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/test/.ssh/id_rsa.
Your public key has been saved in /home/test/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:qyHf/jKOl75hLTGMVk64UYL+zL/SSKqMccDF056hHRQd2FEDCftY your_email@example.com
The key's randomart image is:
+---[RSA 4096]----+
|  ..o*+=.        |
|   .o.o          |
|  . . .          |
|   + o E         |
|  o + . S        |
| o ..+   .       |
|..oo+oo +.       |
|= o+o*oB=.       |
|o=  =+BBB=.      |
+----[SHA256]-----+

Step 5: Verify Configuration:

Open customer_config.yml and ensure the following are set correctly:

vim customer_config.yml

Required — Cassandra password (must match the password set during the original installation):

customer_cassandra_syndeia_admin_password: "<your-original-cassandra-password>"

Required if changed — Superuser password (add this, only needed if you changed the default syn45ia):

customer_syndeia_superuser_password: "<your-current-superuser-password>"

Note: If you are unsure whether the default password has been changed, please contact your system administrator to obtain the current superuser password and Cassandra password before proceeding.

The playbook tests both passwords against the running system before stopping any services. If either is wrong, it fails immediately with clear instructions — no changes are made.

To summarize the changes that have been introduced in configuration files for this release, you may choose to compare the files with “diff”

diff customer_config.yml customer_config.yml.template | less

The output will be similar to this:

$ diff customer_config.yml   customer_config.yml.template
1,147c1,147
< ## customer_config.yml.template
< ##
< ## Syndeia Cloud Installation Configuration Template
< ##
< ## INSTRUCTIONS:
< ## 1. Copy this file to 'customer_config.yml'.
< ## 2. Edit 'customer_config.yml' with your environment-specific values.
< ## 3. Run the playbook with: ansible-playbook install_syndeia.ansible.yml --extra-vars "@customer_config.yml"
< ##
< ## Any variable you define in your 'customer_config.yml' will override the default setting.
< ## Variables that are commented out here will use their default values from the playbook.
< ##
<
< ## ==============================================================================
< ## SECTION 1: ESSENTIAL CONFIGURATION (MUST BE REVIEWED)
< ## ==============================================================================
<
< ## --- Passwords & Secrets ---
<
< ## The password for the 'syndeia_admin' user that will be created in Cassandra.
< customer_cassandra_syndeia_admin_password: "syn45ia"
<
< customer_syndeia_play_secret: "4v5t6n+ly7VibeVbx9DDTEHLt8subg4fMxuvAhQ8FcPg0UTla75NES8uLIFO1q2C"
< customer_syndeia_jwt_secret: "JSOctzW8KMtj/avFiYNdI4laU9QHG0yhKHEBfHBxzcT/rGX46aVDiDT5lHwV/bbm"
<
< ## --- License Configuration (Choose ONE option) ---
<
< ## OPTION 1: File-based license.
< ## Provide the absolute path to your 'syndeia.lic' file on the Ansible control node.
< # customer_syndeia_license_file_path: "/path/to/your/syndeia.lic"
<
< ## OPTION 2: Floating license server.
< ## Provide the hostname or IP address of your Reprise License Manager (RLM) server.
< ## Ensure 'customer_syndeia_license_file_path' is commented out or empty if you use this.
< customer_syndeia_license_server_host: "myLS.domain.tld"
< customer_syndeia_license_server_rlm_port: 5053
< customer_syndeia_license_server_isv_port: 5055
<
< ## --- Networking ---
< ## The primary IP address or FQDN that all backend services (Cassandra, Kafka, JanusGraph)
< ## should listen on. For a standard single-node installation, '127.0.0.1' is sufficient.
< ## For multi-node deployments or if you need to access services from other machines,
< ## set this to the server's network-accessible IP.
< customer_listen_address_services: "127.0.0.1"
<
< ## The hostname or IP address that Kafka will advertise to clients. In most single-node
< ## cases, this can be the same as 'listen_address_services'. In complex network
< ## environments (like Docker or cloud platforms), this might need to be a different,
< ## externally-reachable address.
< customer_kafka_advertised_host: "127.0.0.1"
<
< ## ==============================================================================
< ## SECTION 2: ADVANCED & OPTIONAL CONFIGURATION
< ## ==============================================================================
<
< ## --- Security & Secrets ---
< ## For production, it is STRONGLY recommended to set these to persistent, randomly-generated strings.
< ## If left as 'auto' (the default), new secrets will be generated on every playbook run,
< ## which can invalidate active user sessions.
< # customer_syndeia_play_secret: "your-super-long-random-and-unguessable-play-secret"
< # customer_syndeia_jwt_secret: "another-equally-long-and-random-jwt-signing-secret"
<
< ## --- Installation Flags ---
< ## Set to false to disable the automatic configuration of firewalld (if it is running).
< # customer_syndeia_configure_firewalld: true
<
< ## Set to false to prevent the playbook from running the final DevOps setup (superuser creation, etc.).
< # customer_syndeia_devops_run_setup: true
<
< ## Set to true to DROP ALL existing syndeia_cloud keyspaces. WARNING: DESTRUCTIVE OPERATION.
< # customer_syndeia_wipe_keyspaces: false
<
< ## Set to true to skip the post-install DevOps steps (e.g., creating superuser).
< # customer_syndeia_cloud_skip_devops: false
<
< ## --- Path to Syndeia Cloud Software Package ---
< ## The local path on the Ansible control node where the syndeia-cloud-*.zip is located.
< ## This defaults to $HOME/syndeia-software
< # customer_syndeia_software_dir: "/path/to/syndeia-packages"
<
< ## --- Component-Specific Settings ---
<
< ## Cassandra
< ## A comma-separated list of seed node IP addresses for the Cassandra cluster.
< ## For a single node, this should be the same as 'listen_address_services'.
< # customer_cassandra_seeds: "127.0.0.1"
<
< ## The name for your Cassandra cluster.
< # customer_cassandra_cluster_name: "SC Cluster"
<
< ## The user that Syndeia Cloud will use to connect to Cassandra.
< # customer_cassandra_syndeia_admin_user: "syndeia_admin"
<
< ## The number of tokens for the Cassandra node.
< # customer_cassandra_num_tokens: 256
<
< ## The port for the CQL native transport.
< # customer_cassandra_native_port: 9042
<
< ## Paths for Cassandra data directories.
< # customer_cassandra_data_dir: "/var/lib/cassandra/data"
< # customer_cassandra_commitlog_dir: "/var/lib/cassandra/commitlog"
< # customer_cassandra_saved_caches_dir: "/var/lib/cassandra/saved_caches"
< # customer_cassandra_hints_dir: "/var/lib/cassandra/hints"
<
< ## Advanced Cassandra performance tuning.
< # customer_cassandra_write_request_timeout_in_ms: 20000
< # customer_cassandra_batch_size_fail_threshold_in_kb: 300
<
< ## Kafka
< ## The base directory for Kafka's log data.
< # customer_kafka_log_dirs: "/var/lib/kafka/kraft-logs"
<
< ## The unique ID for this Kafka node.
< # customer_kafka_node_id: 1
<
< ## A unique ID for the Kafka cluster. Set to 'generate' to create a new one on first run.
< # customer_kafka_cluster_id: "generate"
<
< ## The port for the main Kafka broker listener.
< # customer_kafka_broker_listener_port: 9092
<
< ## The port for the Kafka KRaft controller listener.
< # customer_kafka_controller_listener_port: 9093
<
< ## JanusGraph
< ## Replication factor for JanusGraph keyspaces in Cassandra.
< # customer_janusgraph_replication_factor: 1
<
< ## The port for the JanusGraph Gremlin server.
< # customer_janusgraph_port: 8182
<
< ## JMX Monitoring
< ## Set to true to enable JMX remote monitoring for Java services.
< # customer_java_enable_jmx: true
< # customer_jmx_monitor_password: "CHANGEME_MonitorJMXPassword"
< # customer_jmx_control_password: "CHANGEME_ControlJMXPassword"
<
< ## --- LDAP Integration ---
< ## To enable LDAP, set this to true and provide the details for your LDAP server.
< # customer_syndeia_setup_ldap: false
< # ldap_host: "ldap.example.com"
< # ldap_base_dn: "dc=example,dc=com"
< # ldap_admin_user_dn: "cn=admin,dc=example,dc=com"
< # ldap_admin_password: "CHANGEME_LdapAdminPassword"
< # ldap_user_bind_attribute: "uid"
< # ldap_mail_attribute: "mail"

Stage 3: Execution

Step 6: Run the Playbook

ansible-playbook install_syndeia.ansible.yml --extra-vars "@customer_config.yml" -bK

The -bK flag tells Ansible to run with elevated privileges (-b = become sudo) and prompt for your sudo password (-K). When prompted for the BECOME password, enter your user account password.

If your server is configured for passwordless sudo, the -bK flag is not required. You can the shorter options instead (but the -bK flag is harmless):

ansible-playbook install_syndeia.ansible.yml --extra-vars "@customer_config.yml"

The playbook detects any existing installation automatically.

The upgrade typically takes 5–10 minutes, depending on the number of integration services and whether dependency versions have changed.

Step 7: Observe

This Ansible deployment of Syndeia typically takes 5–10 minutes and it depends on the number of integration services and whether dependency versions have changed.

Monitor the screen for status, but the process runs from here to the end without further prompting.4

4. Verification

After the upgrade completes, collect post-upgrade statistics and compare them against the pre-upgrade baseline to verify successful data migration : Stage 7 - Collect statistics from the upgraded SC 3.7

Then run the following checks:

4.1 Check Version

readlink -f /opt/icx/syndeia-cloud-current

This points to the new 3.7.1 installation directory (e.g., /opt/icx/syndeia-cloud-3.7.1). If the wrong version is linked, review your earlier steps.

4.2 Check Services

systemctl list-units "sc-*.service" --no-pager

All services should show active (running).

Pipeline Service (New in 3.7.1):

Syndeia Cloud 3.7.1 introduces a new pipeline service (pipeline-impl). If you are upgrading from 3.7, this service will be deployed with a fresh default configuration.

If you are intending to use this, you will need either an existing Apache Airflow external environment or set one up (see https://intercax.atlassian.net/wiki/x/bYErPwE for more information on how to do this).
If you do not intend to use Pipelines: No action is required. The service will be deployed but does not need to be configured. You can proceed to the Verification section.

4.3 Check Infrastructure

systemctl is-active cassandra kafka janusgraph

All three should return active.

4.4 Check Core Ports

for port in 9000 56110 56120 56180 56135 56132; do
  ss -tlnp | grep -q ":${port} " && echo "Port ${port} OK" || echo "Port ${port} MISSING"
done

Note: Port 9000 (HTTP) may show as MISSING if you have intentionally disabled HTTP in favor of HTTPS. If HTTPS is enabled on your deployment, check port 9443 instead of 9000 (or your configured HTTPS port):

for port in 9443 56110 56120 56180 56135 56132; do
  ss -tlnp | grep -q ":${port} " && echo "Port ${port} OK" || echo "Port ${port} MISSING"
done

4.5 Verify Secrets Were Preserved

grep 'authenticator.sharedSecret' /opt/icx/syndeia-cloud-current/web-gateway-*/conf/silhouette.conf
grep 'play.http.secret.key' /opt/icx/syndeia-cloud-current/auth-impl-*/conf/application.conf

These should match the values from your previous installation.

4.6 Verify Configuration Migration

Spot-check a service config to confirm your customizations were carried forward:

grep '<your-custom-setting>' /opt/icx/syndeia-cloud-current/auth-impl-*/conf/application.conf

4.7 Verify Ported Artifacts

ls -la /opt/icx/syndeia-cloud-current/web-gateway-*/conf/HTTPS.conf 2>/dev/null
ls -la /opt/icx/syndeia-cloud-current/teamcenter-impl-*/lib/TC/ 2>/dev/null
ls -la /opt/icx/syndeia-cloud-current/dscr-impl-*/lib/dscr/ 2>/dev/null
ls -la /opt/icx/syndeia-cloud-current/dse3-impl-*/lib/dse3/ 2>/dev/null

4.8 Login Test

Command line:

# HTTP (default)
curl -s -X POST 'http://127.0.0.1:9000/signIn' \
  -H 'Content-Type: application/json' \
  -d '{"username":"super.user","password":"<your-superuser-password>","rememberMe":true}' \
  | grep -q '"statusCode":201' && echo "Login OK" || echo "Login FAILED"


# HTTPS (if enabled)
curl -s -k -X POST 'https://127.0.0.1:9443/signIn' \
  -H 'Content-Type: application/json' \
  -d '{"username":"super.user","password":"<your-superuser-password>","rememberMe":true}' \
  | grep -q '"statusCode":201' && echo "Login OK" || echo "Login FAILED"

Note: If HTTPS is enabled on your deployment, use https:// with port 9443 instead of http:// with port 9000. The -k flag is required if using a self-signed certificate.

Replace <your-superuser-password> with your actual password.

Browser:

Open your browser and navigate to:

#HTTP
ssh -L 9000:127.0.0.1:9000 <user>@<server-ip>

#HTTPS
ssh -L 9443:127.0.0.1:9443 <user>@<server-ip>

Log in with your existing credentials. Active sessions from before the upgrade should still be valid (secrets are preserved).

Note: If you are unable to reach the server from your browser, verify that:

The server's firewall allows traffic on port 9000 (HTTP) or 9443 (HTTPS)
You are using the correct server IP or hostname
Your network allows access to the server

Once all verification checks have passed and you have confirmed the upgrade is successful, it is strongly recommended to take a full backup of the server before returning it to production. This gives you a clean restore point if any issues arise after go-live.

sudo tar czf ~/syndeia-backup-post-upgrade-$(date +%Y%m%d).tar.gz \
  /opt/icx/syndeia-cloud-current/ \
  /var/lib/cassandra/data/

✅ After the backup is complete, the server is ready to be returned to production.

Additional Reference: For advanced configuration options, migration strategies, and ported artifacts, see References for Ansible Upgrades

Troubleshooting: If you encounter any issues during the upgrade, refer toTroubleshooting Ansible Upgrades