Migrations on Java Operator SDK

Migrating from v1 to v2

Mon, 01 Jan 0001 00:00:00 +0000

Version 2 of the framework introduces improvements, features and breaking changes for the APIs both internal and user facing ones. The migration should be however trivial in most of the cases. For detailed overview of all major issues until the release of v2.0.0 see milestone on GitHub . For a summary and reasoning behind some naming changes see this issue

User Facing API Changes

The following items are renamed and slightly changed:

Migrating from v2 to v3

Mon, 01 Jan 0001 00:00:00 +0000

Version 3 introduces some breaking changes to APIs, however the migration to these changes should be trivial.

Reconciler

Reconciler can throw checked exception (not just runtime exception), and that also can be handled by ErrorStatusHandler.
cleanup method is extracted from the Reconciler interface to a separate Cleaner interface. Finalizers only makes sense that the Cleanup is implemented, from now finalizer is only added if the Reconciler implements this interface (or has managed dependent resources implementing Deleter interface, see dependent resource docs).
Context object of Reconciler now takes the Primary resource as parametrized type: Context<MyCustomResource>.
ErrorStatusHandler result changed, it functionally has been extended to now prevent Exception to be retried and handles checked exceptions as mentioned above.

Event Sources

Event Sources are now registered with a name. But utility method is available to make it easy to migrate to a default name.
InformerEventSource constructor changed to reflect additional functionality in a non backwards compatible way. All the configuration options from the constructor where moved to InformerConfiguration . See sample usage in WebPageReconciler .
PrimaryResourcesRetriever was renamed to SecondaryToPrimaryMapper
AssociatedSecondaryResourceIdentifier was renamed to PrimaryToSecondaryMapper
getAssociatedResource is now renamed to get getSecondaryResource in multiple places

Migrating from v3 to v3.1

Mon, 01 Jan 0001 00:00:00 +0000

ReconciliationMaxInterval Annotation has been renamed to MaxReconciliationInterval

Associated methods on both the ControllerConfiguration class and annotation have also been renamed accordingly.

Workflows Impact on Managed Dependent Resources Behavior

Version 3.1 comes with a workflow engine that replaces the previous behavior of managed dependent resources. See Workflows documentation for further details. The primary impact after upgrade is a change of the order in which managed dependent resources are reconciled. They are now reconciled in parallel with optional ordering defined using the ‘depends_on’ relation to define order between resources if needed. In v3, managed dependent resources were implicitly reconciled in the order they were defined in.

Migrating from v4.2 to v4.3

Mon, 01 Jan 0001 00:00:00 +0000

Condition API Change

In Workflows the target of the condition was the managed resource itself, not the target dependent resource. This changed, now the API contains the dependent resource.

New API:

public interface Condition<R, P extends HasMetadata> {

 boolean isMet(DependentResource<R, P> dependentResource, P primary, Context<P> context);

}

Former API:

public interface Condition<R, P extends HasMetadata> {

 boolean isMet(P primary, R secondary, Context<P> context);

}

Migration is trivial. Since the secondary resource can be accessed from the dependent resource. So to access the secondary resource just use dependentResource.getSecondaryResource(primary,context).

Migrating from v4.3 to v4.4

Mon, 01 Jan 0001 00:00:00 +0000

API changes

ConfigurationService

We have simplified how to deal with the Kubernetes client. Previous versions provided direct access to underlying aspects of the client’s configuration or serialization mechanism. However, the link between these aspects wasn’t as explicit as it should have been. Moreover, the Fabric8 client framework has also revised their serialization architecture in the 6.7 version (see this fabric8 pull request for a discussion of that change), moving from statically configured serialization to a per-client configuration (though it’s still possible to share serialization mechanism between client instances). As a consequence, we made the following changes to the ConfigurationService API:

Migrating from v4.4 to v4.5

Mon, 01 Jan 0001 00:00:00 +0000

Version 4.5 introduces improvements related to event handling for Dependent Resources, more precisely the caching and event handling features. As a result the Kubernetes resources managed using KubernetesDependentResource or its subclasses, will add an annotation recording the resource’s version whenever JOSDK updates or creates such resources. This can be turned off using a feature flag if causes some issues in your use case.

Using this feature, JOSDK now tracks versions of cached resources. It also uses, by default, that information to prevent unneeded reconciliations that could occur when, depending on the timing of operations, an outdated resource would happen to be in the cache. This relies on the fact that versions (as recorded by the metadata.resourceVersion field) are currently implemented as monotonically increasing integers (though they should be considered as opaque and their interpretation discouraged). Note that, while this helps preventing unneeded reconciliations, things would eventually reach consistency even in the absence of this feature. Also, if this interpreting of the resource versions causes issues, you can turn the feature off using the following feature flag.

Migrating from v4.7 to v5.0

Mon, 01 Jan 0001 00:00:00 +0000

For migration to v5 see this blogpost.