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.

Removal of `YangModelDependencyInfo`¶

The YangModelDependencyInfo construct has been removed. It has been replaced with SourceDependency a dedicated model that clarifies dependencies on YANG sources. The extraction logic has been retained within YangIRSourceInfoExtractor. This change allows the DependencyResolver to work directly on SourceInfo. See YANGTOOLS-1150 for details.

Renaming of `YangIRSource` method ¶

YangIRSchemaSource has been renamed to YangIRSource. Method getRootStatement() has been renamed to statement().

`YangTextSchemaSource` is now a `CharSource`¶

YangTextSchemaSource has been updated to operate as a CharSource instead of ByteSource. The default encoding is now UTF-8. See YANGTOOLS-1508 for details.

Promotion of SchemaSourceRepresentation SchemaSourceRepresentation has been promoted as an extensible framework for identifying and working with sources of YANG schema. This framework allows for easy transformation into YANG model constructs. SchemaSourceRepresentation and its specializations are now located in yang.model.api.source As part of this promotion, YangTextSchemaSource has been removed and replaced by SourceIdentifier. See YANGTOOLS-1150 for details.

Exposing of DelegatedYangTextSource DelegatedYangTextSource was introduced to replace static factory methods in YangTextSource. This change simplifies the handling of YANG schema sources by reducing the complexity of conversions and streamlining how CharSource and ByteSource are managed. Users are now encouraged to use DelegatedYangTextSource for handling YANG schema text sources. See YANGTOOLS-1561 for details.

Disconnected `NormalizedNode` from `Identifiable`¶

NormalizedNode has been disconnected from the Identifiable interface. The method name() now replaces getIdentifier() for fetching node identifiers. While getIdentifier() is still available, it has been deprecated and is expected to be removed in future versions. Update your implementation to use the new name() method for node identification. See YANGTOOLS-1472 for details.

Removal of `EffectiveModelContextListener` and `EffectiveModelContextProvider`¶

EffectiveModelContextListener and EffectiveModelContextProvider were removed. The handling of EffectiveModelContext now directly involves methods that provide the context where needed, simplifying the overall design:

EffectiveModelContext modelContext()

See Commit for details.

MD-SAL Impacts ¶

Removed `(DOM)TransactionChainListener`¶

The DOMTransactionChainListener and TransactionChainListener have been removed. Error reporting is now handled by attaching listeners to a separately exposed ListenableFuture, simplifying transaction chain management. See MDSAL-850 for details.

Renaming of `Singleton Service Components`¶

The mdsal-singleton-dom-impl has been renamed to mdsal-singleton-impl and the mdsal-singleton-common-api has been renamed to mdsal-singleton-api.

List of Changes exposed in `DOMDataTreeChangeListener`¶

DOMDataTreeChangeListener was updated to expose a list of changes instead of a collection.

onDataTreeChanged(final List<DataTreeModification<T>> changes)

instead of

onDataTreeChanged(final Collection<DataTreeModification<T>> changes)

See Github for details.

Exposed 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. See MDSAL-61 for details.

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. See MDSAL-772 for details.

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. See MDSAL-815 for details.

Reduction of `ObjectRegistration` Usage ¶

Usage of ObjectRegistration has been reduced in favor of the simpler Registration interface. This change impacts several services, such as ActionProviderService and DataTreeCommitCohortRegistry, where the adaptation of ObjectRegistration is no longer necessary. Ensure that any code relying on ObjectRegistration is updated to use the new Registration interface. See MDSAL-843 for details.

Removal of `DOMRpcRouterServices`¶

DOMRpcRouterServices has been removed to simplify the RPC routing mechanism. The DOMRpcRouter is now directly exposed as the endpoint without an intermediate interface. Notably, the method names in DOMRpcRouter differ from those in DOMRpcRouterServices. DOMNotificationRouter#create was removed as it has been deprecated. Use operator new() instead for creating instance of DOMNotificationRouter. See MDSAL-842 for details.

Renaming of `$Yang*` Classes and Package ¶

the $Yang* generation classes were renamed to avoid the use of the dollar sign ($) in class names. Additionally, the root package for these classes was changed from org.opendaylight.yang.gen.v1 to org.opendaylight.yang.svc.v1. See MDSAL-836 for details.

Refactor of `DOMNotificationSubscriptionListener`¶

The DOMNotificationSubscriptionListener and DOMNotificationSubscriptionListenerRegistry were refactored and replaced by DOMNotificationPublishDemandExtension. This new structure is now integrated into DOMNotificationRouter. Ensure your code is updated to use DOMNotificationRouter for managing notification subscriptions. See MDSAL-481 for details.

Removal of `DOMYangTextSourceProvider`¶

DOMYangTextSourceProvider was replaced with DOMSchemaService.YangTextSourceExtension. Make sure to update your implementation to reflect these changes. See Commit for details.

Netconf Impacts ¶

Moving XmlElement methods ¶

XmlElement had a number of methods which are hosted in XmlUtil now: XmlUtil#hasNamespace, XmlUtil#namespace, XmlUtil#namespaceAttribute.

Enforce base64 encoding for `netconf-keystore`¶

This change switch type to binary for all leafs that are claiming their type as base64. See NETCONF-1186 for details.

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. See NETCONF-1115 for details.

`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. See NETCONF-1186 for details.

`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. See NETCONF-1102 for details.

`odl-netconf-callhome-server` model has a new revision ¶

The ssh-host-key field outside of the transport choice has been marked as obsolete. The transport choice is now mandatory. The key is now managed via the ssh-client-params container within the transport choice. See NETCONF-1243 for details.

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>

See NETCONF-668 for details.

`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. See NETCONF-1193 for details.