Cloud agent upgrade fails with dependency error in distribution center

SCM Blue Yonder Luminate
, , , , , , ,
1

Attempting to upgrade the cloud agent for our distribution center from version 2022.2.1 to 2022.2.5 and hitting a dependency error that’s blocking the upgrade. The agent manages sync between our on-prem WMS and Blue Yonder Luminate cloud services. After running the upgrade script, the agent fails to start with Python module dependency conflicts.

The error log shows something about incompatible versions of the ‘requests’ library and SSL certificate validation modules. We’re running Python 3.8.10 on Ubuntu 20.04 LTS. I’m not sure if the issue is with the Python version itself, or if there are specific dependencies that need to be cleaned up before the upgrade.


ERROR: Cannot install cloud-agent-2022.2.5
ERROR: Dependency conflict: requests>=2.28.0
ERROR: Current: requests==2.25.1
Agent startup validation failed

The upgrade documentation mentions Python 3.9+ is recommended but doesn’t explicitly say 3.8 is unsupported. Has anyone successfully upgraded the cloud agent on Python 3.8, or do we need to upgrade Python first?

2

We had this exact error during our upgrade. The issue is that the agent installer doesn’t clean up old dependencies properly. You need to manually uninstall the old agent version first, including all its Python packages, before installing the new version. Don’t just run the upgrade script directly. Use pip uninstall cloud-agent and then install fresh. This forces all dependencies to be resolved against the new requirements.

3

The agent startup validation that’s failing is actually a good safety check - it prevents the agent from running with incompatible dependencies that could cause data sync issues. Before you fix the dependency problem, back up your current agent configuration files. The upgrade process sometimes overwrites custom settings. Also verify that your agent’s SSL certificates are still valid - expired certs can cause similar startup failures that look like dependency errors.

4

Python 3.8 is technically still supported for 2022.2.5, but it’s at end-of-life as of October 2024, so Blue Yonder is moving away from it. The dependency conflict you’re seeing is because the newer agent version requires requests 2.28.0 or higher for security patches, but your system has an older version pinned by other packages. Try upgrading the requests library separately first: pip install --upgrade requests before running the agent upgrade.

5

I’d recommend using a Python virtual environment for the cloud agent instead of installing it system-wide. This isolates the agent’s dependencies from other Python applications on your server. Create a new venv, install the agent there, and you won’t have these conflicts. We do this for all our cloud agents and upgrades are much smoother. The agent’s systemd service file can be configured to use the venv Python interpreter.

6

I’ll walk you through a complete solution covering Python version requirements, dependency cleanup, and agent startup validation.

Agent Python Version Requirements:

Blue Yonder cloud agent 2022.2.5 officially supports Python 3.8 through 3.11, but there are important caveats:

  • Python 3.8: Supported but deprecated. Will be dropped in 2023.x versions
  • Python 3.9: Recommended minimum for 2022.2.5
  • Python 3.10: Fully supported and recommended
  • Python 3.11: Supported with 2022.2.4+

Your Python 3.8.10 installation will technically work, but you’re encountering dependency conflicts because newer Python packages (like requests 2.28.0+) have dropped some backward compatibility with Python 3.8.

Recommended approach: Upgrade to Python 3.10 before upgrading the agent. Here’s how on Ubuntu 20.04:

sudo apt update
sudo apt install python3.10 python3.10-venv
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1

This installs Python 3.10 alongside your existing 3.8 installation without breaking system tools that depend on 3.8.

Dependency Cleanup Process:

The core issue is that your current agent installation has pinned old dependency versions that conflict with the new agent’s requirements. Here’s the proper cleanup sequence:

1. Stop the current agent:

sudo systemctl stop blue-yonder-cloud-agent
sudo systemctl disable blue-yonder-cloud-agent

2. Back up current configuration:

sudo cp -r /etc/blue-yonder/cloud-agent /etc/blue-yonder/cloud-agent.backup
sudo cp -r /var/log/blue-yonder/cloud-agent /var/log/blue-yonder/cloud-agent.backup

3. Completely remove old agent and dependencies:

sudo pip3 uninstall -y cloud-agent
sudo pip3 uninstall -y requests urllib3 certifi
sudo pip3 uninstall -y cryptography pyopenssl

These are the core dependencies that commonly conflict. Remove them completely so the new installation can install compatible versions.

4. Clean pip cache:

sudo pip3 cache purge

This ensures the new installation pulls fresh packages rather than using cached incompatible versions.

5. Create isolated virtual environment (STRONGLY RECOMMENDED):

sudo python3.10 -m venv /opt/blue-yonder/agent-venv
source /opt/blue-yonder/agent-venv/bin/activate

Using a virtual environment isolates the agent’s dependencies from system Python packages, preventing future conflicts.

6. Install new agent in the virtual environment:

pip install --upgrade pip setuptools wheel
pip install cloud-agent==2022.2.5

The agent installer will now resolve all dependencies against Python 3.10 without conflicts.

7. Restore configuration:

sudo cp -r /etc/blue-yonder/cloud-agent.backup/* /etc/blue-yonder/cloud-agent/

8. Update systemd service to use virtual environment:

Edit /etc/systemd/system/blue-yonder-cloud-agent.service:

[Service]
ExecStart=/opt/blue-yonder/agent-venv/bin/python3 -m cloud_agent.main
Environment="PYTHONPATH=/opt/blue-yonder/agent-venv/lib/python3.10/site-packages"

This ensures the systemd service uses the virtual environment’s Python interpreter.

Agent Startup Validation:

The agent 2022.2.5 includes enhanced startup validation that checks:

  1. Dependency versions: All required packages meet minimum versions
  2. SSL/TLS configuration: Certificate validation libraries are properly installed
  3. Network connectivity: Can reach Blue Yonder cloud endpoints
  4. Configuration validity: All required config parameters are present
  5. Permissions: Agent has necessary file system and network permissions

To manually run startup validation before enabling the service:

source /opt/blue-yonder/agent-venv/bin/activate
python3 -m cloud_agent.validate --config /etc/blue-yonder/cloud-agent/config.yaml

This runs the validation checks and reports any issues before you start the actual service.

Common Validation Failures and Fixes:

1. SSL Certificate Validation: If you see SSL-related errors:

pip install --upgrade certifi
python3 -c "import certifi; print(certifi.where())"

Verify the certificate bundle path matches what’s in your agent config.

2. Network Connectivity: Test connectivity to cloud endpoints:

curl -v https://api.blueyonder.com/health
curl -v https://{your-tenant}.luminate.blueyonder.com/api/health

If these fail, check firewall rules and proxy settings.

3. Configuration Parameters: Validate your config file structure:

Pseudocode for validation:


// Pseudocode - Config validation steps:
1. Load config YAML and verify syntax
2. Check required fields: tenant_id, api_key, sync_endpoints
3. Validate API credentials against cloud service
4. Test write permissions to log directory
5. Verify sync schedule cron expressions are valid
// Agent won't start if any validation fails

Complete Upgrade Procedure:

Putting it all together:

# 1. Stop and backup
sudo systemctl stop blue-yonder-cloud-agent
sudo cp -r /etc/blue-yonder/cloud-agent /etc/blue-yonder/cloud-agent.backup

# 2. Install Python 3.10
sudo apt install python3.10 python3.10-venv

# 3. Create virtual environment
sudo python3.10 -m venv /opt/blue-yonder/agent-venv
source /opt/blue-yonder/agent-venv/bin/activate

# 4. Install new agent
pip install --upgrade pip
pip install cloud-agent==2022.2.5

# 5. Restore config
sudo cp -r /etc/blue-yonder/cloud-agent.backup/* /etc/blue-yonder/cloud-agent/

# 6. Run validation
python3 -m cloud_agent.validate --config /etc/blue-yonder/cloud-agent/config.yaml

# 7. Update systemd service (edit as shown above)
sudo nano /etc/systemd/system/blue-yonder-cloud-agent.service

# 8. Reload and start
sudo systemctl daemon-reload
sudo systemctl enable blue-yonder-cloud-agent
sudo systemctl start blue-yonder-cloud-agent

# 9. Verify startup
sudo systemctl status blue-yonder-cloud-agent
sudo tail -f /var/log/blue-yonder/cloud-agent/agent.log

Post-Upgrade Verification:

After the agent starts successfully:

  1. Check sync job status in the Luminate cloud console
  2. Verify recent data syncs completed successfully
  3. Monitor agent logs for any warnings or errors
  4. Test a manual sync to confirm bidirectional communication
  5. Update your documentation with the new Python version and virtual environment setup

Alternative: If You Must Stay on Python 3.8:

If upgrading Python isn’t immediately feasible, you can work around the dependency conflicts:

pip install "requests>=2.25.1,<2.28.0"
pip install cloud-agent==2022.2.5 --no-deps
pip install -r /opt/blue-yonder/agent-requirements-py38.txt

This pins the requests library to a 3.8-compatible version and manually installs dependencies. However, this is NOT recommended as you’ll miss security updates and will be forced to upgrade Python for future agent versions.

The proper solution is upgrading to Python 3.10 with a virtual environment, which future-proofs your installation and eliminates dependency conflicts permanently.