# Upgrade: 2025.1 (Epoxy) → 2025.2

This is a **sequential (non-SLURP) upgrade**. 2025.2 is not a SLURP release, so operators on 2025.2 cannot skip to 2026.1 — they must upgrade to 2026.1 sequentially. If your goal is to reach 2026.1 with fewer steps, use the SLURP path: 2025.1 → 2026.1 (see `2025.1-to-2026.1.md`).

---

## Pre-Upgrade Steps

### 1. Complete Online Data Migrations on 2025.1

Before installing any 2025.2 packages, drain all pending online data migrations on the current version. Skipping this step can cause failures during the 2025.2 database migration.

```bash
# Nova
nova-manage db online_data_migrations
# Repeat until output shows: "0 rows were migrated in the last batch"

# Cinder
cinder-manage db online_data_migrations
# Repeat until: "0 rows were migrated in the last batch"

# Ironic (if deployed)
ironic-dbsync online_data_migrations
```

### 2. Address Deprecations

Check the 2025.1 service logs for deprecation warnings. These indicate configuration or API usage that will be removed in 2025.2 or later.

```bash
journalctl -u nova-api --since "30 days ago" | grep -i deprecat
journalctl -u neutron-server --since "30 days ago" | grep -i deprecat
journalctl -u cinder-api --since "30 days ago" | grep -i deprecat
journalctl -u keystone --since "30 days ago" | grep -i deprecat
journalctl -u glance-api --since "30 days ago" | grep -i deprecat
```

Check the 2025.2 release notes for each service for the specific deprecations removed in this cycle:
- Nova: https://docs.openstack.org/releasenotes/nova/2025.2.html
- Neutron: https://docs.openstack.org/releasenotes/neutron/2025.2.html
- Cinder: https://docs.openstack.org/releasenotes/cinder/2025.2.html
- Keystone: https://docs.openstack.org/releasenotes/keystone/2025.2.html
- Glance: https://docs.openstack.org/releasenotes/glance/2025.2.html

### 3. Back Up Databases

```bash
# Back up all service databases before touching packages
for db in keystone nova nova_api nova_cell0 neutron cinder glance heat barbican designate ironic magnum octavia manila; do
  mysqldump --single-transaction --routines --triggers "$db" > "/backup/${db}-2025.1-pre-upgrade.sql"
  echo "Backed up $db"
done
```

### 4. Back Up Configuration

```bash
tar czf /backup/openstack-config-2025.1-pre-upgrade.tar.gz \
  /etc/keystone \
  /etc/nova \
  /etc/neutron \
  /etc/cinder \
  /etc/glance \
  /etc/heat \
  /etc/horizon \
  /etc/octavia \
  /etc/designate \
  /etc/barbican \
  /etc/ironic \
  /etc/magnum \
  /etc/manila
```

### 5. Verify Current Health

```bash
openstack compute service list
openstack network agent list
openstack volume service list
openstack token issue
```

All services must be `up` before proceeding. Resolve any `down` services first.

---

## Breaking Changes

Check the official 2025.2 upgrade notes for each service for the full list. General patterns to watch for:

### Configuration Changes

- Options deprecated in 2025.1 may be **removed** in 2025.2. Removed options cause the service to fail to start.
- Review `/etc/<service>/<service>.conf` against the 2025.2 sample config: `<service>-manage config --help` or compare against the new package's sample.
- For renamed options, the service will log a clear error identifying the old name and the replacement.

### API Changes

- Check release notes for any API microversion bumps that remove or change behavior at older microversions.
- Verify client versions: `openstack --version` and update `python-openstackclient` to a version compatible with 2025.2 APIs.

### Nova-Specific

- Verify no live migrations are in progress before upgrading nova-compute nodes.
- Check for any instances in `migrating` or `resize` state: `openstack server list --all-projects --status MIGRATING`

### Neutron-Specific

- If using ML2/OVN, verify OVN version compatibility with the new Neutron release.
- Check for any ports in `DOWN` state that may indicate pre-existing issues: `openstack port list --status DOWN`

---

## Upgrade Execution

Follow the service upgrade order from `README.md`. Below are the database migration commands for each service.

### Infrastructure (RabbitMQ, MariaDB, Memcached)

Upgrade infrastructure packages according to your distribution's procedures. RabbitMQ and MariaDB upgrades are outside OpenStack's scope — follow their respective upgrade guides.

After upgrading MariaDB, verify Galera cluster health:

```bash
mysql -u root -p -e "SHOW STATUS LIKE 'wsrep_cluster_size';"
mysql -u root -p -e "SHOW STATUS LIKE 'wsrep_local_state_comment';"
```

### Keystone

```bash
# Stop Keystone (or stop the WSGI server hosting it)
systemctl stop apache2  # or nginx, depending on your setup

# Upgrade packages
apt-get install --only-upgrade keystone python3-keystone
# or: dnf upgrade openstack-keystone python3-keystone

# Review and merge any .dpkg-new or .rpmnew config files
diff /etc/keystone/keystone.conf /etc/keystone/keystone.conf.dpkg-new || true

# Run database migration
keystone-manage db_sync

# Start Keystone
systemctl start apache2

# Verify
openstack token issue
openstack endpoint list
```

### Glance

```bash
systemctl stop glance-api

apt-get install --only-upgrade glance python3-glance

glance-manage db_sync

systemctl start glance-api
openstack image list
```

### Cinder

```bash
systemctl stop cinder-api cinder-scheduler cinder-volume cinder-backup

apt-get install --only-upgrade cinder-api cinder-volume cinder-scheduler cinder-backup python3-cinder

cinder-manage db sync

systemctl start cinder-api cinder-scheduler cinder-volume cinder-backup

# Run online data migrations after startup
cinder-manage db online_data_migrations
```

### Neutron

```bash
systemctl stop neutron-server

# On network nodes and compute nodes:
# systemctl stop neutron-openvswitch-agent neutron-l3-agent neutron-dhcp-agent neutron-metadata-agent

apt-get install --only-upgrade neutron-server neutron-plugin-ml2 python3-neutron
# Upgrade agent packages on all network and compute nodes as well

neutron-db-manage upgrade heads

systemctl start neutron-server
# Start agents on network/compute nodes after server is healthy
```

### Nova

```bash
# Phase 1: Pin RPC to allow rolling upgrade
# Add to /etc/nova/nova.conf:
# [upgrade_levels]
# compute = auto
systemctl restart nova-conductor nova-scheduler

# Phase 2: Upgrade control plane
systemctl stop nova-api nova-conductor nova-scheduler nova-novncproxy

apt-get install --only-upgrade nova-api nova-conductor nova-scheduler nova-novncproxy python3-nova

nova-manage api_db sync
nova-manage db sync

systemctl start nova-api nova-conductor nova-scheduler nova-novncproxy

# Phase 3: Upgrade compute nodes (one at a time)
# On each compute node:
systemctl stop nova-compute
apt-get install --only-upgrade nova-compute python3-nova
systemctl start nova-compute
# Verify: openstack compute service list | grep <this-node>

# Phase 4: Online data migrations (after all compute nodes upgraded)
nova-manage db online_data_migrations
# Repeat until: 0 rows migrated

# Phase 5: Remove RPC pin from nova.conf, restart conductor/scheduler
```

### Remaining Services

Upgrade Heat, Octavia, Designate, Barbican, Ironic, Magnum, Manila using their respective db sync commands (see `README.md`).

---

## Post-Upgrade Verification

```bash
# Verify all services are up
openstack compute service list
openstack network agent list
openstack volume service list

# Verify authentication works
openstack token issue

# Verify image service
openstack image list

# Verify a test instance can launch
openstack server create \
  --flavor m1.tiny \
  --image cirros \
  --network shared \
  --wait \
  upgrade-verify-test
openstack server show upgrade-verify-test -f value -c status
openstack server delete upgrade-verify-test --wait

# Check logs for deprecation warnings relevant to 2025.2 → 2026.1 path
journalctl -u nova-api | grep -i deprecat | tail -20
journalctl -u neutron-server | grep -i deprecat | tail -20
```

## Configuration Cleanup

After confirming the upgrade is stable:

```bash
# Remove backup .dpkg-old or .rpmsave config files
find /etc/keystone /etc/nova /etc/neutron /etc/cinder /etc/glance -name "*.dpkg-old" -o -name "*.rpmsave"
# Review each before deleting
```

Remove any `[upgrade_levels]` sections from service config files — these should not remain after all nodes are at the new version.