2023.09 Potassium Platform Upgrade ¶

This document describes the steps to help users upgrade from Argon to Potassium 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 ¶

2023.09 Potassium, 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 12.0.3 to 13.0.4. There should not be any reference to org.opendaylight.odlparent, except for 13.0.4. This includes custom feature.xml templates (src/main/feature/feature.xml), the version range should be “[13,14)” instead of “[11,12)”, “[5.0.3,6)” or any other variation.

bump-odl-version odlparent 12.0.3 13.0.4

Update the direct yangtools version references from 10.0.4 to 11.0.1, 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 “[11,12)” instead of “[10,11)”.

bump-odl-version yangtools 10.0.4 11.0.1

Update the MD-SAL version from 11.0.7 to 12.0.1. There should not be any reference to org.opendaylight.mdsal, except for 12.0.1.

bump-odl-version mdsal 11.0.7 12.0.1

Update the Controller version from 7.0.4 to 8.0.1. There should not be any reference to org.opendaylight.controller, except for 8.0.1.

bump-odl-version controller 7.0.4 8.0.1

Update the InfraUtils version from 5.0.3 to 6.0.2. There should not be any reference to org.opendaylight.infrautils, except for 6.0.2.

bump-odl-version infrautils 5.0.3 6.0.2

Update the AAA version from 0.17.7 to 0.18.1. There should not be any reference to org.opendaylight.aaa, except for 0.18.1.

bump-odl-version aaa 0.17.7 0.18.1

Update the NETCONF version from 5.0.4 to 6.0.3. There should not be any reference to org.opendaylight.netconf, except for 6.0.3.

bump-odl-version netconf 5.0.4 6.0.3

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 potassium-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 11 of ODL Parent must be changed to “[13,14)” for ODL Parent 13.

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

ODL Parent Impacts ¶

Upstream declarations removed ¶

The declaration of commons-lang dependency has been removed.

Default annotation declarations removed ¶

odlparent no longer declares spotbugs-annotations, org.eclipse.jdt.annotation and modernizer-maven-annotations as <scope>provided</scope> dependencies. Downstreams will need to introduce these annotations as appropriate.

YANG Tools Impacts ¶

`AugmentationIdentifer` and `AugmentationNode` removed ¶

The class hierarchy of NormalizedNode has been updated to not contain augmented nodes in a separate AugmentationNode, but rather keep them directly in the node being augmented. This results in a flatter NormalizedNode structure and makes constructing structures involving augmentations and reconciling them with EffectiveModelContext much more straightforward.

See YANGTOOLS-568 for details.

RFC7952 and RFC8528 support integrated into `yang-data`¶

The interfaces supporting RFC7952 YANG annotations have been integrated into yang-data-api and yang-data-util artifacts. This rendered rfc7952-data-api and rfc7952-data-util artifacts empty and thus these have been removed. See YANGTOOLS-1489 for details.

The interfaces supporting RFC8528 YANG schema mounts have been integrated into yang-data-api and yang-data-util artifacts. This rendered rfc8528-data-api and rfc8528-data-util artifacts empty and thus these have been removed. See YANGTOOLS-1172 for details.

As part of these changes, following API changes have also been done in order to ease using these interfaces: * NormalizedNodeStreamWriterExtension has been renamed to NormalizedNodeStreamWriter.Extension * StreamWriterMetadataExtension has been renamed to NormalizedNodeStreamWriter.MetadataExtension * StreamWriterMountPointExtension has been renamed to NormalizedNodeStreamWriter.MountPointExtension * MountPointIdentifier has been removed with NormalizedMountPoint exposing its MountPointLabel directly

Finally, the result of NormalizedNodeStreamWriter is now a combined structure, NormalizationResult, which combines a mandatory NormalizedNode data tree, an optional NormalizedMetadata and an optional NormalizedMountPoints tree. For the purposes of receiving this the result, NormalizedNodeResult has been replaced with NormalizationResultHolder.

`DataSchemaContextNode` replaced with `DataSchemaContext`¶

yang.data.util.DataSchemaContextNode has been completely revamped and renamed to DataSchemaContext. It is now an interface implemented completely internally, with a proper interface hierarchy. Implementations of these interfaces are given out by DataSchemaContextTree. The resulting API is much easier to figure out and use, especially with proper documentation and naming not overlapping with other parts of YANG Tools. See YANGTOOLS-1413 for details.

`ExtensibleObject` has been reworked ¶

This interface no longer exposes a ClassToInstanceMap, but rather provides direct lookup and enumeration methods. Users need to be updated from performing

ExtensibleObject obj;
var extension = obj.getExtensions().getInstance(ExtensionType.class);

to instead doing

ExtensibleObject obj;
var extension = obj.extension(ExtensionType.class);

See YANGTOOLS-1509 for details.

`UsesNode.getRefines()` exposes only descendant paths ¶

The return type was changed to return Set<Descendant> instead of Map<Descendant, SchemaNode>. Users relying on accessing target nodes need to perform the resolution themselves. See YANGTOOLS-1518 for details.

`YangTextSchemaSources` is a `CharSource`¶

yang.model.api.repo.YangTextSchemaSource now operates on a stream of characters, not bytes. All users which instantiate sources from byte streams must specify the character set used. See YANGTOOLS-1508 for details.

MD-SAL Impacts ¶

`InstanceIdentifierBuilder` renamed to `InstanceIdentifier.Builder`¶

A long-standing bug, where a KeyedInstanceIdentifier could not be safely returned from InstanceIdentifierBuilder was fixed. As part of this fix, InstanceIdentifierBuilder was renamed to be an inner class, InstanceIdentifier.Builder. There is also a corresponding InstanceIdentifier.KeyedBuilder. See MDSAL-798 for details.

`BindingReflections.getModuleInfo()` has moved ¶

This reflection-based method was moved to BindingRuntimeHelpers class, as all its users already interact with mdsal-binding-runtime-spi. See MDSAL-803 for details.

Convenience model artifacts removed ¶

The aggregating multi-module RFCs have been removed. Users declaring a dependency on any of rfc6991, rfc8294, rfc8342, rfc8345, rfc8346, rfc8348, rfc8349, rfc8519, rfc8520, rfc8542, rfc8776 or rfc8795 need to now update these references to individual modules’ artifacts. See MDSAL-823 for details.

`BindingMapping` moved ¶

binding.spec.naming.BindingMapping has been renamed and moved to yang.binding.contract.Naming. See MDSAL-804 for details.

`IetfInetUtil.INSTANCE` and `IetfYangUtil.INSTANCE` removed ¶

IetfInetUtil and IetfYangUtil have been refactored so they now expose static utility methods not encapsulated in an object instance. All references to INSTANCE need to be removed:

byte[] bytes;
IetfYangUtil.INSTANCE.macAddressFor(bytes);

becomes

byte[] bytes;
IetfYangUtil.macAddressFor(bytes);

See MDSAL-804 for details.

Binding `Identifiable` and `Identifier` renamed ¶

yang.binding.Identifer has been renamed to yang.binding.Key and yang.binding.Identifiable has been renamed to yang.binding.KeyAware. This change prevents confusion with yangtools.concepts interfaces with the same name. See MDSAL-830 for details.

Controller Impacts ¶

None.