Skip to content

Commit c68121c

Browse files
csviricsviri
authoredDec 12, 2024··
docs: migration guide as blogpost refactor (#2632)
Signed-off-by: Attila Mészáros <[email protected]>
·
v5.0.4v5.0.0-RC1
1 parent f79ec63 commit c68121c

File tree

2 files changed

+52
-110
lines changed

2 files changed

+52
-110
lines changed
 

Diff for: ‎docs/content/en/blog/releases/v5-release.md

+51
Original file line numberDiff line numberDiff line change
@@ -315,6 +315,57 @@ purpose, it will check if the CRD of a target resource type of a dependent resou
315315
See usage in integration
316316
test [here](https://github.com/operator-framework/java-operator-sdk/blob/refs/heads/next/operator-framework/src/test/java/io/javaoperatorsdk/operator/workflow/crdpresentactivation).
317317

318+
## Fabric8 client updated to 7.0
319+
320+
The Fabric8 client has been updated to version 7.0.0. This is a new major version which implies that some API might have
321+
changed. Please take a look at the [Fabric8 client 7.0.0 migration guide](https://github.com/fabric8io/kubernetes-client/blob/main/doc/MIGRATION-v7.md).
322+
323+
### CRD generator changes
324+
325+
Starting with v5.0 (in accordance with changes made to the Fabric8 client in version 7.0.0), the CRD generator will use the maven plugin instead of the annotation processor as was previously the case.
326+
In many instances, you can simply configure the plugin by adding the following stanza to your project's POM build configuration:
327+
328+
```xml
329+
<plugin>
330+
<groupId>io.fabric8</groupId>
331+
<artifactId>crd-generator-maven-plugin</artifactId>
332+
<version>${fabric8-client.version}</version>
333+
<executions>
334+
<execution>
335+
<goals>
336+
<goal>generate</goal>
337+
</goals>
338+
</execution>
339+
</executions>
340+
</plugin>
341+
342+
```
343+
*NOTE*: If you use the SDK's JUnit extension for your tests, you might also need to configure the CRD generator plugin to access your test `CustomResource` implementations as follows:
344+
```xml
345+
346+
<plugin>
347+
<groupId>io.fabric8</groupId>
348+
<artifactId>crd-generator-maven-plugin</artifactId>
349+
<version>${fabric8-client.version}</version>
350+
<executions>
351+
<execution>
352+
<goals>
353+
<goal>generate</goal>
354+
</goals>
355+
<phase>process-test-classes</phase>
356+
<configuration>
357+
<classesToScan>${project.build.testOutputDirectory}</classesToScan>
358+
<classpath>WITH_ALL_DEPENDENCIES_AND_TESTS</classpath>
359+
</configuration>
360+
</execution>
361+
</executions>
362+
</plugin>
363+
364+
```
365+
366+
Please refer to the [CRD generator documentation](https://github.com/fabric8io/kubernetes-client/blob/main/doc/CRD-generator.md) for more details.
367+
368+
318369
## Experimental
319370

320371
### Check if the following reconciliation is imminent

Diff for: ‎docs/content/en/docs/migration/v5-0-migration.md

+1-110
Original file line numberDiff line numberDiff line change
@@ -3,113 +3,4 @@ title: Migrating from v4.7 to v5.0
33
description: Migrating from v4.7 to v5.0
44
---
55

6-
# Migrating from v4.7 to v5.0
7-
8-
## Fabric8 client updated to 7.0
9-
10-
The Fabric8 client has been updated to version 7.0.0. This is a new major version which implies that some API might have
11-
changed. Please take a look at the [Fabric8 client 7.0.0 migration guide](https://github.com/fabric8io/kubernetes-client/blob/main/doc/MIGRATION-v7.md).
12-
13-
### CRD generator changes
14-
15-
Starting with v5.0 (in accordance with changes made to the Fabric8 client in version 7.0.0), the CRD generator will use the maven plugin instead of the annotation processor as was previously the case.
16-
In many instances, you can simply configure the plugin by adding the following stanza to your project's POM build configuration:
17-
18-
```xml
19-
<plugin>
20-
<groupId>io.fabric8</groupId>
21-
<artifactId>crd-generator-maven-plugin</artifactId>
22-
<version>${fabric8-client.version}</version>
23-
<executions>
24-
<execution>
25-
<goals>
26-
<goal>generate</goal>
27-
</goals>
28-
</execution>
29-
</executions>
30-
</plugin>
31-
32-
```
33-
*NOTE*: If you use the SDK's JUnit extension for your tests, you might also need to configure the CRD generator plugin to access your test `CustomResource` implementations as follows:
34-
```xml
35-
36-
<plugin>
37-
<groupId>io.fabric8</groupId>
38-
<artifactId>crd-generator-maven-plugin</artifactId>
39-
<version>${fabric8-client.version}</version>
40-
<executions>
41-
<execution>
42-
<goals>
43-
<goal>generate</goal>
44-
</goals>
45-
<phase>process-test-classes</phase>
46-
<configuration>
47-
<classesToScan>${project.build.testOutputDirectory}</classesToScan>
48-
<classpath>WITH_ALL_DEPENDENCIES_AND_TESTS</classpath>
49-
</configuration>
50-
</execution>
51-
</executions>
52-
</plugin>
53-
54-
```
55-
56-
Please refer to the [CRD generator documentation](https://github.com/fabric8io/kubernetes-client/blob/main/doc/CRD-generator.md) for more details.
57-
58-
59-
## API tweaks
60-
61-
1. [Result of managed dependent resources](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/dependent/managed/ManagedDependentResourceContext.java#L55-L57)
62-
is not `Optional` anymore. In case you use this result, simply use the result
63-
objects directly.
64-
2. `EventSourceInitializer` is not a separate interface anymore. It is part of the `Reconciler` interface with a
65-
default implementation. You can simply remove this interface from your reconciler. The
66-
[`EventSourceUtils`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/EventSourceUtils.java#L11-L11)
67-
now contains all the utility methods used for event sources naming that were previously defined in
68-
the `EventSourceInitializer` interface.
69-
3. Similarly, the `EventSourceProvider` interface has been remove, replaced by explicit initialization of the associated
70-
event source on `DependentResource` via the `
71-
Optional<? extends EventSource<R, P>> eventSource(EventSourceContext<P> eventSourceContext)` method.
72-
4. Event sources are now explicitly named (via the `name` method of the `EventSource` interface). Built-in event sources
73-
implementation have been updated to allow you to specify a name when instantiating them. If you don't provide a name
74-
for your `EventSource` implementation (for example, by using its default, no-arg constructor), one will be
75-
automatically generated. This simplifies the API to define event source to
76-
`List<EventSource> prepareEventSources(EventSourceContext<P> context)`.
77-
!!! IMPORTANT !!!
78-
If you use dynamic registration of event sources, be sure to name your event sources explicitly as letting JOSDK name
79-
them automatically might result in duplicated event sources being registered as JOSDK relies on the name to identify
80-
event sources and concurrent, dynamic registration might lead to identical event sources having different generated
81-
names, thus leading JOSDK to consider them as different and hence, register them multiple times.
82-
5. Updates through `UpdateControl` now
83-
use [Server Side Apply (SSA)](https://kubernetes.io/docs/reference/using-api/server-side-apply/) by default to add
84-
the finalizer and for all
85-
the patch operations in `UpdateControl`. The update operations were removed. If you do not wish to use SSA, you can
86-
deactivate the feature using `ConfigurationService.useSSAToPatchPrimaryResource` and
87-
related `ConfigurationServiceOverrider.withUseSSAToPatchPrimaryResource`.
88-
89-
!!! IMPORTANT !!!
90-
91-
See known issues with migration from non-SSA to SSA based status updates here:
92-
[integration test](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/StatusPatchSSAMigrationIT.java#L71-L82)
93-
where it is demonstrated. Also, the related part of
94-
a [workaround](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/StatusPatchSSAMigrationIT.java#L110-L116).
95-
96-
6. `ManagedDependentResourceContext` has been renamed to `ManagedWorkflowAndDependentResourceContext` and is accessed
97-
via the accordingly renamed `managedWorkflowAndDependentResourceContext` method.
98-
7. `ResourceDiscriminator` was removed. In most of the cases you can just delete the discriminator, everything should
99-
work without it by default. To optimize and handle special cases see the relevant section
100-
in [Dependent Resource documentation](/docs/dependent-resources#multiple-dependent-resources-of-same-type).
101-
8. `ConfigurationService.getTerminationTimeoutSeconds` and associated overriding mechanism have been removed,
102-
use `Operator.stop(Duration)` instead.
103-
9. `Operator.installShutdownHook()` has been removed, use `Operator.installShutdownHook(Duration)` instead
104-
10. Automated observed generation handling feature was removed (`ObservedGenerationAware` interface
105-
and `ObservedGenerationAwareStatus` class were deleted). Manually handling observed generation is fairly easy to do
106-
in your reconciler, however, it cannot be done automatically when using SSA. We therefore removed the feature since
107-
it would have been confusing to have a different behavior for SSA and non-SSA cases. For an example of how to do
108-
observed generation handling manually in your reconciler, see
109-
[this sample](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/manualobservedgeneration/ManualObservedGenerationReconciler.java).
110-
11. `BulkDependentResource` now supports [read-only mode](https://github.com/operator-framework/java-operator-sdk/issues/2233).
111-
This also means, that `BulkDependentResource` now does not automatically implement `Creator` and `Deleter` as before.
112-
Make sure to implement those interfaces in your bulk dependent resources. You can use also the new helper interface, the
113-
[`CRUDBulkDependentResource`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/CRUDBulkDependentResource.java)
114-
what also implement `BulkUpdater` interface.
115-
12. `ErrorStatusHandler` is deleted. Just delete the interface from your impl.
6+
For migration to v5 see [this blogpost](../../blog/releases/v5-release.md).

0 commit comments

Comments
 (0)
Please sign in to comment.