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):

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

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

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

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.

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.

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

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.