Skip to content

Commit f362c6a

Browse files
csvirimetacosm
csviri
authored and
metacosm
committed
docs: migrate v5 changes to docsy (#2397)
Signed-off-by: Attila Mészáros <[email protected]>
1 parent 1226c89 commit f362c6a

File tree

4 files changed

+248
-271
lines changed

4 files changed

+248
-271
lines changed

‎docsy/content/en/docs/dependent-resources/_index.md

+84-167
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ title: Dependent Resources
33
weight: 60
44
---
55

6+
# Dependent Resources
7+
68
## Motivations and Goals
79

810
Most operators need to deal with secondary resources when trying to realize the desired state
@@ -96,13 +98,13 @@ and labels, which are ignored by default:
9698

9799
```java
98100
public class MyDependentResource extends KubernetesDependentResource<MyDependent, MyPrimary>
99-
implements Matcher<MyDependent, MyPrimary> {
100-
// your implementation
101+
implements Matcher<MyDependent, MyPrimary> {
102+
// your implementation
101103

102-
public Result<MyDependent> match(MyDependent actualResource, MyPrimary primary,
103-
Context<MyPrimary> context) {
104-
return GenericKubernetesResourceMatcher.match(this, actualResource, primary, context, true);
105-
}
104+
public Result<MyDependent> match(MyDependent actualResource, MyPrimary primary,
105+
Context<MyPrimary> context) {
106+
return GenericKubernetesResourceMatcher.match(this, actualResource, primary, context, true);
107+
}
106108
}
107109
```
108110

@@ -136,24 +138,24 @@ Deleted (or set to be garbage collected). The following example shows how to cre
136138
@KubernetesDependent(labelSelector = WebPageManagedDependentsReconciler.SELECTOR)
137139
class DeploymentDependentResource extends CRUDKubernetesDependentResource<Deployment, WebPage> {
138140

139-
public DeploymentDependentResource() {
140-
super(Deployment.class);
141-
}
142-
143-
@Override
144-
protected Deployment desired(WebPage webPage, Context<WebPage> context) {
145-
var deploymentName = deploymentName(webPage);
146-
Deployment deployment = loadYaml(Deployment.class, getClass(), "deployment.yaml");
147-
deployment.getMetadata().setName(deploymentName);
148-
deployment.getMetadata().setNamespace(webPage.getMetadata().getNamespace());
149-
deployment.getSpec().getSelector().getMatchLabels().put("app", deploymentName);
150-
151-
deployment.getSpec().getTemplate().getMetadata().getLabels()
152-
.put("app", deploymentName);
153-
deployment.getSpec().getTemplate().getSpec().getVolumes().get(0)
154-
.setConfigMap(new ConfigMapVolumeSourceBuilder().withName(configMapName(webPage)).build());
155-
return deployment;
156-
}
141+
public DeploymentDependentResource() {
142+
super(Deployment.class);
143+
}
144+
145+
@Override
146+
protected Deployment desired(WebPage webPage, Context<WebPage> context) {
147+
var deploymentName = deploymentName(webPage);
148+
Deployment deployment = loadYaml(Deployment.class, getClass(), "deployment.yaml");
149+
deployment.getMetadata().setName(deploymentName);
150+
deployment.getMetadata().setNamespace(webPage.getMetadata().getNamespace());
151+
deployment.getSpec().getSelector().getMatchLabels().put("app", deploymentName);
152+
153+
deployment.getSpec().getTemplate().getMetadata().getLabels()
154+
.put("app", deploymentName);
155+
deployment.getSpec().getTemplate().getSpec().getVolumes().get(0)
156+
.setConfigMap(new ConfigMapVolumeSourceBuilder().withName(configMapName(webPage)).build());
157+
return deployment;
158+
}
157159
}
158160
```
159161

@@ -189,25 +191,25 @@ instances are managed by JOSDK, an example of which can be seen below:
189191
```java
190192

191193
@ControllerConfiguration(
192-
labelSelector = SELECTOR,
193-
dependents = {
194-
@Dependent(type = ConfigMapDependentResource.class),
195-
@Dependent(type = DeploymentDependentResource.class),
196-
@Dependent(type = ServiceDependentResource.class)
197-
})
194+
labelSelector = SELECTOR,
195+
dependents = {
196+
@Dependent(type = ConfigMapDependentResource.class),
197+
@Dependent(type = DeploymentDependentResource.class),
198+
@Dependent(type = ServiceDependentResource.class)
199+
})
198200
public class WebPageManagedDependentsReconciler
199-
implements Reconciler<WebPage>, ErrorStatusHandler<WebPage> {
201+
implements Reconciler<WebPage>, ErrorStatusHandler<WebPage> {
200202

201-
// omitted code
203+
// omitted code
202204

203-
@Override
204-
public UpdateControl<WebPage> reconcile(WebPage webPage, Context<WebPage> context) {
205+
@Override
206+
public UpdateControl<WebPage> reconcile(WebPage webPage, Context<WebPage> context) {
205207

206-
final var name = context.getSecondaryResource(ConfigMap.class).orElseThrow()
207-
.getMetadata().getName();
208-
webPage.setStatus(createStatus(name));
209-
return UpdateControl.patchStatus(webPage);
210-
}
208+
final var name = context.getSecondaryResource(ConfigMap.class).orElseThrow()
209+
.getMetadata().getName();
210+
webPage.setStatus(createStatus(name));
211+
return UpdateControl.patchStatus(webPage);
212+
}
211213

212214
}
213215
```
@@ -222,104 +224,11 @@ It is also possible to wire dependent resources programmatically. In practice th
222224
developer is responsible for initializing and managing the dependent resources as well as calling
223225
their `reconcile` method. However, this makes it possible for developers to fully customize the
224226
reconciliation process. Standalone dependent resources should be used in cases when the managed use
225-
case does not fit.
226-
227-
Note that [Workflows](https://javaoperatorsdk.io/docs/workflows) also can be invoked from standalone
228-
resources.
229-
230-
The following sample is similar to the one above, simply performing additional checks, and
231-
conditionally creating an `Ingress`:
232-
233-
```java
234-
235-
@ControllerConfiguration
236-
public class WebPageStandaloneDependentsReconciler
237-
implements Reconciler<WebPage>, ErrorStatusHandler<WebPage>,
238-
EventSourceInitializer<WebPage> {
239-
240-
private KubernetesDependentResource<ConfigMap, WebPage> configMapDR;
241-
private KubernetesDependentResource<Deployment, WebPage> deploymentDR;
242-
private KubernetesDependentResource<Service, WebPage> serviceDR;
243-
private KubernetesDependentResource<Service, WebPage> ingressDR;
244-
245-
public WebPageStandaloneDependentsReconciler(KubernetesClient kubernetesClient) {
246-
// 1.
247-
createDependentResources(kubernetesClient);
248-
}
249-
250-
@Override
251-
public List<EventSource> prepareEventSources(EventSourceContext<WebPage> context) {
252-
// 2.
253-
return List.of(
254-
configMapDR.initEventSource(context),
255-
deploymentDR.initEventSource(context),
256-
serviceDR.initEventSource(context));
257-
}
258-
259-
@Override
260-
public UpdateControl<WebPage> reconcile(WebPage webPage, Context<WebPage> context) {
261-
262-
// 3.
263-
if (!isValidHtml(webPage.getHtml())) {
264-
return UpdateControl.patchStatus(setInvalidHtmlErrorMessage(webPage));
265-
}
266-
267-
// 4.
268-
configMapDR.reconcile(webPage, context);
269-
deploymentDR.reconcile(webPage, context);
270-
serviceDR.reconcile(webPage, context);
271-
272-
// 5.
273-
if (Boolean.TRUE.equals(webPage.getSpec().getExposed())) {
274-
ingressDR.reconcile(webPage, context);
275-
} else {
276-
ingressDR.delete(webPage, context);
277-
}
227+
case does not fit. You can, of course, also use [Workflows](https://javaoperatorsdk.io/docs/workflows) when managing
228+
resources programmatically.
278229

279-
// 6.
280-
webPage.setStatus(
281-
createStatus(configMapDR.getResource(webPage).orElseThrow().getMetadata().getName()));
282-
return UpdateControl.patchStatus(webPage);
283-
}
284-
285-
private void createDependentResources(KubernetesClient client) {
286-
this.configMapDR = new ConfigMapDependentResource();
287-
this.deploymentDR = new DeploymentDependentResource();
288-
this.serviceDR = new ServiceDependentResource();
289-
this.ingressDR = new IngressDependentResource();
290-
291-
Arrays.asList(configMapDR, deploymentDR, serviceDR, ingressDR).forEach(dr -> {
292-
dr.setKubernetesClient(client);
293-
dr.configureWith(new KubernetesDependentResourceConfig()
294-
.setLabelSelector(DEPENDENT_RESOURCE_LABEL_SELECTOR));
295-
});
296-
}
297-
298-
// omitted code
299-
}
300-
```
301-
302-
There are multiple things happening here:
303-
304-
1. Dependent resources are explicitly created and can be access later by reference.
305-
2. Event sources are produced by the dependent resources, but needs to be explicitly registered in
306-
this case by implementing
307-
the [`EventSourceInitializer`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/EventSourceInitializer.java)
308-
interface.
309-
3. The input html is validated, and error message is set in case it is invalid.
310-
4. Reconciliation of dependent resources is called explicitly, but here the workflow
311-
customization is fully in the hand of the developer.
312-
5. An `Ingress` is created but only in case `exposed` flag set to true on custom resource. Tries to
313-
delete it if not.
314-
6. Status is set in a different way, this is just an alternative way to show, that the actual state
315-
can be read using the reference. This could be written in a same way as in the managed example.
316-
317-
See the full source code of
318-
sample [here](https://github.com/operator-framework/java-operator-sdk/blob/main/sample-operators/webpage/src/main/java/io/javaoperatorsdk/operator/sample/WebPageStandaloneDependentsReconciler.java)
319-
.
320-
321-
Note also the Workflows feature makes it possible to also support this conditional creation use
322-
case in managed dependent resources.
230+
You can see a commented example of how to do
231+
so [here](https://github.com/operator-framework/java-operator-sdk/blob/main/sample-operators/webpage/src/main/java/io/javaoperatorsdk/operator/sample/WebPageStandaloneDependentsReconciler.java).
323232

324233
## Creating/Updating Kubernetes Resources
325234

@@ -352,17 +261,17 @@ Since SSA is a complex feature, JOSDK implements a feature flag allowing users t
352261
these implementations. See
353262
in [ConfigurationService](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L332-L358).
354263

355-
It is, however, important to note that these implementations are default, generic
356-
implementations that the framework can provide expected behavior out of the box. In many
357-
situations, these will work just fine but it is also possible to provide matching algorithms
264+
It is, however, important to note that these implementations are default, generic
265+
implementations that the framework can provide expected behavior out of the box. In many
266+
situations, these will work just fine but it is also possible to provide matching algorithms
358267
optimized for specific use cases. This is easily done by simply overriding
359-
the `match(...)` [method](https://github.com/java-operator-sdk/java-operator-sdk/blob/e16559fd41bbb8bef6ce9d1f47bffa212a941b09/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/kubernetes/KubernetesDependentResource.java#L156-L156).
268+
the `match(...)` [method](https://github.com/java-operator-sdk/java-operator-sdk/blob/e16559fd41bbb8bef6ce9d1f47bffa212a941b09/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/kubernetes/KubernetesDependentResource.java#L156-L156).
360269

361-
It is also possible to bypass the matching logic altogether to simply rely on the server-side
270+
It is also possible to bypass the matching logic altogether to simply rely on the server-side
362271
apply mechanism if always sending potentially unchanged resources to the cluster is not an issue.
363272
JOSDK's matching mechanism allows to spare some potentially useless calls to the Kubernetes API
364-
server. To bypass the matching feature completely, simply override the `match` method to always
365-
return `false`, thus telling JOSDK that the actual state never matches the desired one, making
273+
server. To bypass the matching feature completely, simply override the `match` method to always
274+
return `false`, thus telling JOSDK that the actual state never matches the desired one, making
366275
it always update the resources using SSA.
367276

368277
WARNING: Older versions of Kubernetes before 1.25 would create an additional resource version for every SSA update
@@ -389,20 +298,25 @@ tests [here](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/op
389298

390299
When dealing with multiple dependent resources of same type, the dependent resource implementation
391300
needs to know which specific resource should be targeted when reconciling a given dependent
392-
resource, since there will be multiple instances of that type which could possibly be used, each
393-
associated with the same primary resource. In order to do this, JOSDK relies on the
394-
[resource discriminator](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ResourceDiscriminator.java)
395-
concept. Resource discriminators uniquely identify the target resource of a dependent resource.
396-
In the managed Kubernetes dependent resources case, the discriminator can be declaratively set
397-
using the `@KubernetesDependent` annotation:
398-
399-
```java
400-
401-
@KubernetesDependent(resourceDiscriminator = ConfigMap1Discriminator.class)
402-
public class MultipleManagedDependentResourceConfigMap1 {
403-
//...
404-
}
405-
```
301+
resource, since there could be multiple instances of that type which could possibly be used, each
302+
associated with the same primary resource. In this situation, JOSDK automatically selects the appropriate secondary
303+
resource matching the desired state associated with the primary resource. This makes sense because the desired
304+
state computation already needs to be able to discriminate among multiple related secondary resources to tell JOSDK how
305+
they should be reconciled.
306+
307+
There might be casees, though, where it might be problematic to call the `desired` method several times (for example, because it is costly to do so), it is always possible to override this automated discrimination using several means:
308+
309+
- Implement your own `getSecondaryResource` method on your `DependentResource` implementation from scratch.
310+
- Override the `selectManagedSecondaryResource` method, if your `DependentResource` extends `AbstractDependentResource`.
311+
This should be relatively simple to override this method to optimize the matching to your needs. You can see an
312+
example of such an implementation in
313+
the [`ExternalWithStateDependentResource`](https://github.com/operator-framework/java-operator-sdk/blob/6cd0f884a7c9b60c81bd2d52da54adbd64d6e118/operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/externalstate/ExternalWithStateDependentResource.java#L43-L49)
314+
class.
315+
- Override the `managedSecondaryResourceID` method, if your `DependentResource` extends `KubernetesDependentResource`,
316+
where it's very often possible to easily determine the `ResourceID` of the secondary resource. This would probably be
317+
the easiest solution if you're working with Kubernetes resources.
318+
319+
### Sharing an Event Source Between Dependent Resources
406320

407321
Dependent resources usually also provide event sources. When dealing with multiple dependents of
408322
the same type, one needs to decide whether these dependent resources should track the same
@@ -418,10 +332,10 @@ would look as follows:
418332
useEventSourceWithName = "configMapSource")
419333
```
420334

421-
A sample is provided as an integration test both
422-
for [managed](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/MultipleManagedDependentSameTypeIT.java)
423-
and
424-
for [standalone](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/MultipleDependentResourceIT.java)
335+
A sample is provided as an integration test both:
336+
for [managed](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/MultipleManagedDependentNoDiscriminatorIT.java)
337+
338+
For [standalone](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/MultipleDependentResourceIT.java)
425339
cases.
426340

427341
## Bulk Dependent Resources
@@ -484,15 +398,18 @@ also be created, one per dependent resource.
484398
See [integration test](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/ExternalStateBulkIT.java)
485399
as a sample.
486400

487-
488401
## GenericKubernetesResource based Dependent Resources
489402

490-
In rare circumstances resource handling where there is no class representation or just typeless handling might be needed.
491-
Fabric8 Client provides [GenericKubernetesResource](https://github.com/fabric8io/kubernetes-client/blob/main/doc/CHEATSHEET.md#resource-typeless-api)
492-
to support that.
403+
In rare circumstances resource handling where there is no class representation or just typeless handling might be
404+
needed.
405+
Fabric8 Client
406+
provides [GenericKubernetesResource](https://github.com/fabric8io/kubernetes-client/blob/main/doc/CHEATSHEET.md#resource-typeless-api)
407+
to support that.
493408

494-
For dependent resource this is supported by [GenericKubernetesDependentResource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/kubernetes/GenericKubernetesDependentResource.java#L8-L8)
495-
. See samples [here](https://github.com/java-operator-sdk/java-operator-sdk/tree/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/generickubernetesresource).
409+
For dependent resource this is supported
410+
by [GenericKubernetesDependentResource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/kubernetes/GenericKubernetesDependentResource.java#L8-L8)
411+
. See
412+
samples [here](https://github.com/java-operator-sdk/java-operator-sdk/tree/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/generickubernetesresource).
496413

497414
## Other Dependent Resource Features
498415

0 commit comments

Comments
 (0)