improve: integration test to showcase external resource state in status

operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/externalstateinstatus/ExternalStateInStatusCustomResource.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright Java Operator SDK Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.javaoperatorsdk.operator.baseapi.externalstateinstatus;
+
+import io.fabric8.kubernetes.api.model.Namespaced;
+import io.fabric8.kubernetes.client.CustomResource;
+import io.fabric8.kubernetes.model.annotation.Group;
+import io.fabric8.kubernetes.model.annotation.ShortNames;
+import io.fabric8.kubernetes.model.annotation.Version;
+
+@Group("sample.javaoperatorsdk")
+@Version("v1")
+@ShortNames("essis")
+public class ExternalStateInStatusCustomResource
+    extends CustomResource<ExternalStateInStatusSpec, ExternalStateInStatusStatus>
+    implements Namespaced {}

operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/externalstateinstatus/ExternalStateInStatusIT.java

@@ -0,0 +1,106 @@
+/*
+ * Copyright Java Operator SDK Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.javaoperatorsdk.operator.baseapi.externalstateinstatus;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import io.fabric8.kubernetes.api.model.ObjectMetaBuilder;
+import io.javaoperatorsdk.annotation.Sample;
+import io.javaoperatorsdk.operator.junit.LocallyRunOperatorExtension;
+import io.javaoperatorsdk.operator.support.ExternalIDGenServiceMock;
+import io.javaoperatorsdk.operator.support.ExternalServiceResetExtension;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.awaitility.Awaitility.await;
+
+/**
+ * Manages an external resource while storing its state (the external resource ID) directly in the
+ * <b>status</b> of the custom resource, rather than in a separate resource like a ConfigMap. This
+ * is only reliable because of the stronger read-after-write consistency for updates: after the
+ * external resource is created the reconciler patches the status with the ID, and that patched
+ * resource is placed into the cache so the next reconciliation observes the ID and does not create
+ * a duplicate external resource.
+ */
+@Sample(
+    tldr = "Managing an External Resource with State Stored in the Status",
+    description =
+        """
+        Demonstrates how to manage an external resource (outside of Kubernetes) while storing its \
+        state - the generated external ID - in the status of the custom resource. The reconciler \
+        persists the ID with a status patch and relies on the stronger read-after-write \
+        consistency for updates so that the next reconciliation observes the stored ID and never \
+        creates a duplicate external resource. A fake external service stands in for the managed \
+        external system.
+        """)
+@ExtendWith(ExternalServiceResetExtension.class)
+class ExternalStateInStatusIT {
+
+  private static final String TEST_RESOURCE_NAME = "test1";
+
+  public static final String INITIAL_TEST_DATA = "initialTestData";
+  public static final String UPDATED_DATA = "updatedData";
+
+  private final ExternalIDGenServiceMock externalService = ExternalIDGenServiceMock.getInstance();
+
+  @RegisterExtension
+  LocallyRunOperatorExtension operator =
+      LocallyRunOperatorExtension.builder()
+          .withReconciler(ExternalStateInStatusReconciler.class)
+          .build();
+
+  @Test
+  void reconcilesResourceWithStateStoredInStatus() {
+    var resource = operator.create(testResource());
+    assertResourceCreated(INITIAL_TEST_DATA);
+
+    resource.getSpec().setData(UPDATED_DATA);
+    operator.replace(resource);
+    assertResourceCreated(UPDATED_DATA);
+
+    operator.delete(resource);
+    assertResourceDeleted();
+  }
+
+  private void assertResourceCreated(String expectedData) {
+    await()
+        .untilAsserted(
+            () -> {
+              var resources = externalService.listResources();
+              // exactly one external resource is created, no duplicates
+              assertThat(resources).hasSize(1);
+              var extRes = resources.get(0);
+              assertThat(extRes.getData()).isEqualTo(expectedData);
+
+              var cr = operator.get(ExternalStateInStatusCustomResource.class, TEST_RESOURCE_NAME);
+              assertThat(cr.getStatus()).isNotNull();
+              // the external resource state (its ID) is stored in the status
+              assertThat(cr.getStatus().getId()).isEqualTo(extRes.getId());
+            });
+  }
+
+  private void assertResourceDeleted() {
+    await().untilAsserted(() -> assertThat(externalService.listResources()).isEmpty());
+  }
+
+  private ExternalStateInStatusCustomResource testResource() {
+    var res = new ExternalStateInStatusCustomResource();
+    res.setMetadata(new ObjectMetaBuilder().withName(TEST_RESOURCE_NAME).build());
+    res.setSpec(new ExternalStateInStatusSpec().setData(INITIAL_TEST_DATA));
+    return res;
+  }
+}

operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/externalstateinstatus/ExternalStateInStatusReconciler.java

@@ -0,0 +1,156 @@
+/*
+ * Copyright Java Operator SDK Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.javaoperatorsdk.operator.baseapi.externalstateinstatus;
+
+import java.time.Duration;
+import java.util.Collections;
+import java.util.List;
+import java.util.Set;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import io.javaoperatorsdk.operator.api.reconciler.Cleaner;
+import io.javaoperatorsdk.operator.api.reconciler.Context;
+import io.javaoperatorsdk.operator.api.reconciler.ControllerConfiguration;
+import io.javaoperatorsdk.operator.api.reconciler.DeleteControl;
+import io.javaoperatorsdk.operator.api.reconciler.EventSourceContext;
+import io.javaoperatorsdk.operator.api.reconciler.Reconciler;
+import io.javaoperatorsdk.operator.api.reconciler.UpdateControl;
+import io.javaoperatorsdk.operator.processing.event.ResourceID;
+import io.javaoperatorsdk.operator.processing.event.source.EventSource;
+import io.javaoperatorsdk.operator.processing.event.source.polling.PerResourcePollingConfigurationBuilder;
+import io.javaoperatorsdk.operator.processing.event.source.polling.PerResourcePollingEventSource;
+import io.javaoperatorsdk.operator.support.ExternalIDGenServiceMock;
+import io.javaoperatorsdk.operator.support.ExternalResource;
+import io.javaoperatorsdk.operator.support.TestExecutionInfoProvider;
+
+/**
+ * Manages an external resource (living in the {@link ExternalIDGenServiceMock fake external
+ * service}) while storing the external resource's state - here just its generated ID - directly in
+ * the <b>status</b> of the custom resource.
+ *
+ * <p>This pattern only works reliably thanks to the stronger read-after-write consistency for
+ * updates: after the external resource is created, its ID is persisted through {@link
+ * UpdateControl#patchStatus(io.fabric8.kubernetes.api.model.HasMetadata)}. The patched resource
+ * (holding the ID) is placed into the controller's cache, so the very next reconciliation observes
+ * the ID and does not create a duplicate external resource - even before the informer delivers the
+ * update event.
+ */
+@ControllerConfiguration
+public class ExternalStateInStatusReconciler
+    implements Reconciler<ExternalStateInStatusCustomResource>,
+        Cleaner<ExternalStateInStatusCustomResource>,
+        TestExecutionInfoProvider {
+
+  private final AtomicInteger numberOfExecutions = new AtomicInteger(0);
+
+  private final ExternalIDGenServiceMock externalService = ExternalIDGenServiceMock.getInstance();
+
+  PerResourcePollingEventSource<ExternalResource, ExternalStateInStatusCustomResource, String>
+      externalResourceEventSource;
+
+  @Override
+  public UpdateControl<ExternalStateInStatusCustomResource> reconcile(
+      ExternalStateInStatusCustomResource resource,
+      Context<ExternalStateInStatusCustomResource> context) {
+    numberOfExecutions.addAndGet(1);
+
+    var externalResource = context.getSecondaryResource(ExternalResource.class);
+    if (externalResource.isEmpty()) {
+      // No external resource is associated with this primary yet. If we already stored an ID we
+      // are just waiting for the poll to catch up (do nothing), otherwise we create the external
+      // resource and persist its ID into the status. Relying on read-after-write consistency the
+      // stored ID is visible on the next reconciliation, so no duplicate is created.
+      if (idFromStatus(resource) == null) {
+        return createExternalResource(resource);
+      }
+      return UpdateControl.noUpdate();
+    }
+
+    var currentExternalResource = externalResource.orElseThrow();
+    if (!currentExternalResource.getData().equals(resource.getSpec().getData())) {
+      updateExternalResource(resource, currentExternalResource);
+    }
+    return UpdateControl.noUpdate();
+  }
+
+  private UpdateControl<ExternalStateInStatusCustomResource> createExternalResource(
+      ExternalStateInStatusCustomResource resource) {
+    var createdResource =
+        externalService.create(new ExternalResource(resource.getSpec().getData()));
+
+    // Make sure the freshly created external resource is available in the poll cache for the next
+    // reconciliation, so it is not created again.
+    externalResourceEventSource.handleRecentResourceCreate(
+        ResourceID.fromResource(resource), createdResource);
+
+    resource.setStatus(new ExternalStateInStatusStatus().setId(createdResource.getId()));
+    return UpdateControl.patchStatus(resource);
+  }
+
+  private void updateExternalResource(
+      ExternalStateInStatusCustomResource resource, ExternalResource externalResource) {
+    var newResource = new ExternalResource(externalResource.getId(), resource.getSpec().getData());
+    externalService.update(newResource);
+    externalResourceEventSource.handleRecentResourceUpdate(
+        ResourceID.fromResource(resource), newResource, externalResource);
+  }
+
+  @Override
+  public DeleteControl cleanup(
+      ExternalStateInStatusCustomResource resource,
+      Context<ExternalStateInStatusCustomResource> context) {
+    var id = idFromStatus(resource);
+    if (id != null) {
+      externalService.delete(id);
+    }
+    return DeleteControl.defaultDelete();
+  }
+
+  @Override
+  public int getNumberOfExecutions() {
+    return numberOfExecutions.get();
+  }
+
+  @Override
+  public List<EventSource<?, ExternalStateInStatusCustomResource>> prepareEventSources(
+      EventSourceContext<ExternalStateInStatusCustomResource> context) {
+
+    final PerResourcePollingEventSource.ResourceFetcher<
+            ExternalResource, ExternalStateInStatusCustomResource>
+        fetcher =
+            (ExternalStateInStatusCustomResource primaryResource) -> {
+              var id = idFromStatus(primaryResource);
+              if (id == null) {
+                return Collections.emptySet();
+              }
+              return externalService.read(id).map(Set::of).orElseGet(Collections::emptySet);
+            };
+    externalResourceEventSource =
+        new PerResourcePollingEventSource<>(
+            ExternalResource.class,
+            context,
+            new PerResourcePollingConfigurationBuilder<
+                    ExternalResource, ExternalStateInStatusCustomResource, String>(
+                    fetcher, Duration.ofMillis(300L))
+                .build());
+
+    return List.of(externalResourceEventSource);
+  }
+
+  private static String idFromStatus(ExternalStateInStatusCustomResource resource) {
+    return resource.getStatus() == null ? null : resource.getStatus().getId();
+  }
+}

operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/externalstateinstatus/ExternalStateInStatusSpec.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright Java Operator SDK Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.javaoperatorsdk.operator.baseapi.externalstateinstatus;
+
+public class ExternalStateInStatusSpec {
+
+  private String data;
+
+  public String getData() {
+    return data;
+  }
+
+  public ExternalStateInStatusSpec setData(String data) {
+    this.data = data;
+    return this;
+  }
+}

operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/externalstateinstatus/ExternalStateInStatusStatus.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright Java Operator SDK Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.javaoperatorsdk.operator.baseapi.externalstateinstatus;
+
+/** Holds the identifier of the managed external resource. This is the external resource state. */
+public class ExternalStateInStatusStatus {
+
+  private String id;
+
+  public String getId() {
+    return id;
+  }
+
+  public ExternalStateInStatusStatus setId(String id) {
+    this.id = id;
+    return this;
+  }
+}