2024.03 Calcium Platform Upgrade

This document describes the steps to help users upgrade from Potassium to Calcium platform. Refer to Managed Snapshot Integrated (MSI) project upgrade patches for more information and hints for solutions to common problems not explicitly listed here.

Preparation

JDK 17 Version

2024.03 Calcium, requires Java 17, both during compile-time and run-time. Make sure to install JDK 17 corresponding to at least openjdk-17.0.7, and that the JAVA_HOME environment variable points to the JDK directory.

Version Bump

Before performing platform upgrade, do the following to bump the odlparent versions (for example, bump-odl-version):

  1. Update the odlparent version from 13.0.4. to 13.0.11. There should not be any reference to org.opendaylight.odlparent, except for 13.0.11. This includes custom feature.xml templates (src/main/feature/feature.xml), the version range should be “[13,14)”.

bump-odl-version odlparent 13.0.4 13.0.11
  1. Update the direct yangtools version references from 11.0.1 to 13.0.2, There should not be any reference to org.opendaylight.yangtools, except for 11.0.1. This includes custom feature.xml templates (src/main/feature/feature.xml), the version range should be “[12,13)” instead of “[11,12)”.

bump-odl-version yangtools 11.0.1 13.0.2
  1. Update the MD-SAL version from 12.0.1. to 13.0.1. There should not be any reference to org.opendaylight.mdsal, except for 13.0.1.

bump-odl-version mdsal 12.0.1 13.0.1
  1. Update the Controller version from 8.0.1. to 9.0.2. There should not be any reference to org.opendaylight.controller, except for 9.0.2.

bump-odl-version controller 8.0.1. 9.0.2.
  1. Update the InfraUtils version from 6.0.2. to 6.0.6. There should not be any reference to org.opendaylight.infrautils, except for 6.0.6.

bump-odl-version infrautils 6.0.2. 6.0.6.
  1. Update the AAA version from 0.18.1. to 0.19.3 There should not be any reference to org.opendaylight.aaa, except for 0.19.3

bump-odl-version aaa 0.18.1. 0.19.3
  1. Update the NETCONF version from 6.0.3 to 7.0.4 There should not be any reference to org.opendaylight.netconf, except for 7.0.4

bump-odl-version netconf 6.0.3 7.0.4

Install Dependent Projects

Before performing platform upgrade, users must also install any dependent project. To locally install a dependent project, pull and install the respective calcium-mri changes for any dependent project.

Perform the following steps to save time when locally installing any dependent project:

  • For quick install:

mvn -Pq clean install
  • If previously installed, go offline and/or use the no-snapshot-update option.

mvn -Pq -o -nsu clean install

Upgrade the ODL Parent

The following sub-section describes how to upgrade to the ODL Parent version 13. Refer to the ODL Parent Release Notes for more information.

Features

Any version range referencing version of ODL Parent must be “[13,14)” for ODL Parent 13.

<feature name="odl-infrautils-caches">
    <feature version="[13,14)">odl-guava</feature>
</feature>

ODL Parent Impacts

YANG Tools Impacts

QNameModule now uses RevisionUnion

QNameModule has been updated to use RevisionUnion instead of holding an optional Revision. This change simplifies handling of revisions within YANG models. Additionally, new of() and ofRevision() convenience methods have been introduced, while the create() methods have been deprecated.

Exposed FileYangTextSource

FileYangTextSource has been introduced as a replacement for numerous static factory methods (e.g. YangTextSource#forPath) previously used for file-backed YANG text sources. See YANGTOOLS-1561 for details.

MD-SAL Impacts

mdsal-singleton-dom-impl renamed to mdsal-singleton-impl

The mdsal-singleton-dom-impl has been renamed to mdsal-singleton-impl.

BindingMapping moved

Expose Completion Future from WriteOperations

WriteOperations now exposes a FluentFuture<?> which completes when a transaction is committed or aborted. This improvement allows code to react to when changes are actually committed, which is essential for tasks like chaining cache updates.

Removal of yang.binding.RpcService

The yang.binding.RpcService interface has been removed. This interface, which served as a base marker for generated interfaces representing YANG rpc statements, has been deprecated due to outdated design assumptions from Java 7. In its place, use yang.binding.Rpc and related lambda-compatible interfaces for a more modern, streamlined approach.

PathArgument refactored to DataObjectStep

InstanceIdentifier.PathArgument has been refactored to DataObjectStep, a top-level construct that simplifies expressing paths of DataObject type references. This change streamlines method signatures and imports while keeping the older AbstractPathArgument for serialization compatibility.

Netconf Impacts

Clean up XmlElement methods

XmlElement has a number of methods which are better hosted in XmlUtil, without the need for encapsulation.

Enforce base64 encoding for netconf-keystore

This change Changed type to binary for all leafs that are claiming their type as base64.

Base64 Encoding for Netconf Device Passwords

The Netconf device passwords are now encoded using Base64. This is enforced for encrypted authentication, ensuring compatibility with RFC 7950. The RPC logic continues to handle password encoding when creating devices.

netconf-keystore model has a new revision

This revision introduces changes where several elements, including private keys and certificates, are now being Base64-encoded for enhanced security and conformance with standard practices.

sal-remote-augment model has a new revision

The sal-remote-augment.yang model has been updated to revision 2023-11-03. See NETCONF-1102 for details.

odl-device-notification model has a new revision

odl-device-notification output has been corrected to ensure that the stream subscription results in a stream name. Previously, it returned a stream-path, but this has been changed to a stream-name

Standalone YANG Library Data Writer

A new standalone YANG library data writer was introduced to replace previous implementations that could cause data inconsistency. This new dedicated module ensures that YANG library data is written from a single source to prevent potential data corruption.

<dependency>
  <groupId>org.opendaylight.netconf</groupId>
  <artifactId>yanglib-mdsal-writer</artifactId>
</dependency>

odl-netconf-device model has a new revision

Several leaf names have been simplified, including changes like renaming between-attempts-timeout-millis to min-backoff-millis, max-timeout-between-attempts-millis to max-backoff-millis, and sleep-factor to backoff-multiplier.

Controller Impacts

Removal of RpcService from sal-cluster-admin-impl

This change removes the usage of RpcService from sal-cluster-admin-impl to improve modularity and reduce dependencies. If your application interacts with sal-cluster-admin-impl, ensure you adapt to this change by removing any reliance on RpcService within this implementation.

AAA Impacts

Exception Handling for Encryption/Decryption Failures

Error handling in the AAA module was improved to throw a GeneralSecurityException if encryption or decryption fails. Previously, the system would log the error and return the inserted string, which could cause confusion.