Merge pull request #48554 from metacosm/kube-dev-service

Clean up Kubernetes Dev Service doc and code

Author: geoand

core/deployment/src/main/java/io/quarkus/deployment/builditem/ContainerRuntimeStatusBuildItem.java

@@ -5,7 +5,7 @@
 
 public abstract class ContainerRuntimeStatusBuildItem extends SimpleBuildItem {
     private final IsContainerRuntimeWorking isContainerRuntimeWorking;
-    private Boolean cachedStatus;
+    private volatile Boolean cachedStatus;
 
     protected ContainerRuntimeStatusBuildItem(IsContainerRuntimeWorking isContainerRuntimeWorking) {
         this.isContainerRuntimeWorking = isContainerRuntimeWorking;

docs/src/main/asciidoc/kubernetes-dev-services.adoc

@@ -17,76 +17,33 @@ The following https://github.com/dajudge/kindcontainer?tab=readme-ov-file#contai
 
 == Enabling / Disabling Dev Services for Kubernetes
 
-Dev Services for Kubernetes is automatically enabled unless:
+To use the Kubernetes Dev Service, you simply need to add the `quarkus-kubernetes-client` extension to your project:
 
-- `quarkus.kubernetes-client.devservices.enabled` is set to `false`
-- the `api-server-url` is configured
-- a valid Kube config file is found and `quarkus.kubernetes-client.devservices.override-kubeconfig` is not set to `true`
-- you include the `quarkus-test-kubernetes-client` dependency
+:add-extension-extensions: kubernetes-client
+include::{includes}/devtools/extension-add.adoc[]
 
-NOTE: Dev Services for Kubernetes relies on a container engine: Docker or Podman to start the server.
+A Kubernetes API server is automatically started in dev or test modes whenever the `quarkus-kubernetes-client` extension is configured for a project. However, the dev service is disabled in some cases to prevent potential confusing situations:
+
+- if the dev service is explicitly disabled by setting `quarkus.kubernetes-client.devservices.enabled` to `false`
+- if the client is explicitly configured to access a given API server via `quarkus.kubernetes-client.api-server-url`
+- if a valid Kube config file is found, in which case that configuration will be used by the client. It is, however, possible to force the dev service to start anyway by setting `quarkus.kubernetes-client.devservices.override-kubeconfig` to `true` to disregard the existing configuration
+- if you include the `quarkus-test-kubernetes-client` dependency as, presumably, in that case, you have tests that rely on the Fabric8 mock server and don't need to start a cluster
+
+NOTE: Dev Services for Kubernetes relies on a container engine (Docker or Podman) to start the server.
 If your environment does not support such a container engine, you will have to start a Kubernetes cluster running in a VM, in the cloud, etc.
-In this case, you can configure the Kubernetes cluster access using either a Kube config file or the various properties available in the https://github.com/quarkusio/quarkus/blob/main/extensions/kubernetes-client/runtime-internal/src/main/java/io/quarkus/kubernetes/client/runtime/KubernetesClientBuildConfig.java[KubernetesClientBuildConfig] class.
+In this case, you can configure the Kubernetes cluster access using either a Kube config file or the various properties available as specified in the xref:kubernetes-client.adoc[Kubernetes client configuration guide].
 
 == Shared cluster
 
-Most of the time you need to share the cluster between applications.
-Dev Services for Kubernetes implements a _service discovery_ mechanism for your multiple Quarkus applications running in dev mode to share a single cluster.
+Applications often need to share access to the same cluster. For that purpose, Dev Services for Kubernetes implements a _service discovery_ mechanism for multiple Quarkus applications running in dev mode to share a single cluster.
 
-NOTE: Dev Services for Kubernetes starts the container with the `quarkus-dev-service-kubernetes` label which is used to identify the container.
+NOTE: Dev Services for Kubernetes starts the api server container with the `quarkus-dev-service-kubernetes` label which is used to identify it.
 
-If you need multiple (shared) clusters, you can configure the `quarkus.kubernetes-client.devservices.service-name` configuration property and indicate the cluster name.
-It looks for a container with the name defined, or starts a new one if none can be found.
-The default service name is `kubernetes`.
+If you need multiple (shared) clusters, you can provide a value for the `quarkus.kubernetes-client.devservices.service-name` configuration property to specify the name of the cluster that will be shared among the selected applications. The dev service support will look for an already existing container with that specified name or starts a new one if none can be found.The default service name is `kubernetes`.
 
 Sharing is enabled by default in dev mode, but disabled in test mode.
 You can disable the sharing with `quarkus.kubernetes-client.devservices.shared=false`.
 
-== What else for the developers
-
-If you would like to develop test cases running top of the kubernetes cluster (launched as test container by the Dev Service), then add the following dependencies to your pom file
-
-[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
-.pom.xml
-----
-<dependency>
-    <groupId>io.quarkus</groupId>
-    <artifactId>quarkus-kubernetes-client</artifactId>
-</dependency>
-----
-
-and set the Quarkus properties to select the flavor, or kube version.
-
-Then you will be able to create a Fabric8 Kubernetes Client object able to perform many kube tasks as detailed part of this https://github.com/fabric8io/kubernetes-client/blob/main/doc/CHEATSHEET.md[cheat sheet].
-
-.Simple Bean Example
-[source,java]
-----
-package org.acme;
-
-import org.junit.jupiter.api.Test;
-
-import io.fabric8.kubernetes.api.model.*;
-import io.fabric8.kubernetes.client.KubernetesClient;
-import io.quarkus.test.junit.QuarkusTest;
-
-@QuarkusTest
-public class ArgocdExtensionDevModeTest {
-
-    @Inject
-    private KubernetesClient client;
-
-    @Test
-    public void testCreatePod() {
-        client.resource(new PodBuilder()
-           .withMetadata(<METADATA_OBJECT>)
-           .withSpec(<SPEC_OBJECT>)
-           .build())
-           .inNamespace(<USER_NAMESPACE>)
-           .create();
-    }
-----
-
 == Configuring the cluster
 
 Dev Services for Kubernetes provides three different flavors of Kubernetes cluster. Each flavor supports different Kubernetes API versions.
@@ -98,10 +55,12 @@ quarkus.kubernetes-client.devservices.flavor=api-only # k3s or kind
 quarkus.kubernetes-client.devservices.api-version=1.22
 ----
 
-`api-only` only starts a Kubernetes API Server (plus the required etcd). If you need a fully-featured Kubernetes cluster that can spin up Pods, you can use `k3s` or `kind`. `k3s` requires to start the container with `privileged mode`. The `kind` test container supports now to use podman rootless or rootfull.
+`api-only` only starts a Kubernetes API Server (plus the required etcd). If you need a fully-featured Kubernetes cluster that can spin up Pods, you can use `k3s` or `kind`. `k3s` requires to start the container with `privileged mode`. The `kind` test container now also supports using podman's rootless mode.
 
 If `api-version` is not set, the latest version for the given flavor will be used. Otherwise, the version must match a https://github.com/dajudge/kindcontainer/blob/master/k8s-versions.json[version supported by the given flavor].
 
+Once the cluster is configured, you can access it easily as you normally would, for example, by injecting a client instance in your test.
+
 == Configuration reference
 
 include::{generated-dir}/config/quarkus-kubernetes-client_quarkus.kubernetes-client.devservices.adoc[opts=optional, leveloffset=+1]

extensions/kubernetes-client/deployment/src/main/java/io/quarkus/kubernetes/client/deployment/DevServicesKubernetesProcessor.java

@@ -30,7 +30,6 @@
 import com.dajudge.kindcontainer.K3sContainerVersion;
 import com.dajudge.kindcontainer.KindContainer;
 import com.dajudge.kindcontainer.KindContainerVersion;
-import com.dajudge.kindcontainer.KubernetesContainer;
 import com.dajudge.kindcontainer.KubernetesVersionEnum;
 import com.dajudge.kindcontainer.client.KubeConfigUtils;
 import com.dajudge.kindcontainer.client.config.Cluster;
@@ -77,7 +76,6 @@ public class DevServicesKubernetesProcessor {
     private static final String KUBERNETES_CLIENT_DEVSERVICES_OVERRIDE_KUBECONFIG = "quarkus.kubernetes-client.devservices.override-kubeconfig";
     private static final Logger log = Logger.getLogger(DevServicesKubernetesProcessor.class);
     private static final String KUBERNETES_CLIENT_MASTER_URL = "quarkus.kubernetes-client.api-server-url";
-    private static final String KUBERNETES_CLIENT_DEVSERVICES_FLAVOR = "quarkus.kubernetes-client.devservices.flavor";
     private static final String DEFAULT_MASTER_URL_ENDING_WITH_SLASH = Config.DEFAULT_MASTER_URL + "/";
 
     static final String DEV_SERVICE_LABEL = "quarkus-dev-service-kubernetes";
@@ -88,6 +86,7 @@ public class DevServicesKubernetesProcessor {
     static volatile KubernetesDevServiceCfg cfg;
     static volatile boolean first = true;
 
+    @SuppressWarnings("OptionalUsedAsFieldOrParameterType")
     @BuildStep
     public DevServicesResultBuildItem setupKubernetesDevService(
             DockerStatusBuildItem dockerStatusBuildItem,
@@ -172,7 +171,7 @@ private void shutdownCluster() {
         }
     }
 
-    @SuppressWarnings("unchecked")
+    @SuppressWarnings({ "unchecked", "OptionalUsedAsFieldOrParameterType" })
     private RunningDevService startKubernetes(DockerStatusBuildItem dockerStatusBuildItem,
             DevServicesComposeProjectBuildItem composeProjectBuildItem,
             KubernetesDevServiceCfg config,
@@ -187,29 +186,27 @@ private RunningDevService startKubernetes(DockerStatusBuildItem dockerStatusBuil
 
         // Check if kubernetes-client.api-server-url is set
         if (ConfigUtils.isPropertyNonEmpty(KUBERNETES_CLIENT_MASTER_URL)) {
-            log.debug("Not starting Dev Services for Kubernetes, the " + KUBERNETES_CLIENT_MASTER_URL + " is configured.");
+            log.debug("Not starting Dev Services for Kubernetes as the client has been explicitly configured via "
+                    + KUBERNETES_CLIENT_MASTER_URL);
             return null;
         }
 
-        // Check if we should create a kind test container and launch it
-        // based on the Dev services config or the KubernetesRequest of the producer
-        boolean shouldStart = config.overrideKubeconfig
-                || devServiceKubeRequest.isPresent();
-
+        // If we have an explicit request coming from extensions, start even if there's a non-explicitly overridden kube config
+        final boolean shouldStart = config.overrideKubeconfig || devServiceKubeRequest.isPresent();
         if (!shouldStart) {
             var autoConfigMasterUrl = Config.autoConfigure(null).getMasterUrl();
             if (!DEFAULT_MASTER_URL_ENDING_WITH_SLASH.equals(autoConfigMasterUrl)) {
                 log.debug(
-                        "Not starting Dev Services for Kubernetes, the Kubernetes client is auto-configured. Set "
+                        "Not starting Dev Services for Kubernetes as a kube config file has been found. Set "
                                 + KUBERNETES_CLIENT_DEVSERVICES_OVERRIDE_KUBECONFIG
-                                + " to true to use Dev Services for Kubernetes.");
+                                + " to true to disregard the config and start Dev Services for Kubernetes.");
                 return null;
             }
         }
 
         if (!dockerStatusBuildItem.isContainerRuntimeAvailable()) {
             log.warn(
-                    "Docker isn't working, please configure the Kubernetes client.");
+                    "A running container runtime is required for Dev Services to work. Please check if your container runtime is running.");
             return null;
         }
 
@@ -221,35 +218,26 @@ private RunningDevService startKubernetes(DockerStatusBuildItem dockerStatusBuil
                         KUBERNETES_PORT, launchMode.getLaunchMode(), useSharedNetwork));
 
         final Supplier<RunningDevService> defaultKubernetesClusterSupplier = () -> {
-            KubernetesContainer container;
-
             Flavor clusterType = config.flavor
                     .or(() -> devServiceKubeRequest
                             .map(KubernetesDevServiceRequestBuildItem::getFlavor)
                             .map(Flavor::valueOf))
                     .orElse(api_only);
 
-            switch (clusterType) {
-                case api_only:
-                    container = new ApiServerContainer(
-                            config.apiVersion
-                                    .map(version -> findOrElseThrow(clusterType, version, ApiServerContainerVersion.class))
-                                    .orElseGet(() -> latest(ApiServerContainerVersion.class)));
-                    break;
-                case k3s:
-                    container = new K3sContainer(
-                            config.apiVersion.map(version -> findOrElseThrow(clusterType, version, K3sContainerVersion.class))
-                                    .orElseGet(() -> latest(K3sContainerVersion.class)));
-                    break;
-                case kind:
-                    container = new KindContainer(
-                            config.apiVersion
-                                    .map(version -> findOrElseThrow(clusterType, version, KindContainerVersion.class))
-                                    .orElseGet(() -> latest(KindContainerVersion.class)));
-                    break;
-                default:
-                    throw new RuntimeException(KUBERNETES_CLIENT_DEVSERVICES_FLAVOR + " must be a valid Flavor enum value.");
-            }
+            @SuppressWarnings("rawtypes")
+            final var container = switch (clusterType) {
+                case api_only -> new ApiServerContainer(
+                        config.apiVersion
+                                .map(version -> findOrElseThrow(clusterType, version, ApiServerContainerVersion.class))
+                                .orElseGet(() -> latest(ApiServerContainerVersion.class)));
+                case k3s -> new K3sContainer(
+                        config.apiVersion.map(version -> findOrElseThrow(clusterType, version, K3sContainerVersion.class))
+                                .orElseGet(() -> latest(K3sContainerVersion.class)));
+                case kind -> new KindContainer(
+                        config.apiVersion
+                                .map(version -> findOrElseThrow(clusterType, version, KindContainerVersion.class))
+                                .orElseGet(() -> latest(KindContainerVersion.class)));
+            };
 
             if (useSharedNetwork) {
                 ConfigureUtil.configureSharedNetwork(container, "quarkus-kubernetes-client");
@@ -323,6 +311,7 @@ private KubernetesDevServiceCfg getConfiguration(KubernetesClientBuildConfig cfg
         return new KubernetesDevServiceCfg(devServicesConfig);
     }
 
+    @SuppressWarnings("OptionalUsedAsFieldOrParameterType")
     private static final class KubernetesDevServiceCfg {
 
         public boolean devServicesEnabled;
@@ -352,9 +341,8 @@ public int hashCode() {
         public boolean equals(Object obj) {
             if (this == obj)
                 return true;
-            if (!(obj instanceof KubernetesDevServiceCfg))
+            if (!(obj instanceof KubernetesDevServiceCfg other))
                 return false;
-            KubernetesDevServiceCfg other = (KubernetesDevServiceCfg) obj;
             return devServicesEnabled == other.devServicesEnabled && flavor == other.flavor
                     && Objects.equals(apiVersion, other.apiVersion) && overrideKubeconfig == other.overrideKubeconfig
                     && shared == other.shared && Objects.equals(serviceName, other.serviceName)

extensions/kubernetes-client/deployment/src/main/java/io/quarkus/kubernetes/client/deployment/NoQuarkusTestKubernetesClient.java

@@ -6,20 +6,20 @@
 /**
  * Boolean supplier that returns true if quarkus-test-kubernetes-client is not
  * present in the application pom.xml.
- *
+ * <p>
  * quarkus-test-kubernetes-client provide a Kubernetes client configuration to connect
  * to a Kubernetes mock server and will have precedence over the configuration provided by
  * Dev Services for Kubernetes. DevServicesKubernetesProcessor uses this BooleanSupplier
  * to avoid starting a Kubernetes test container in such a case.
  */
 class NoQuarkusTestKubernetesClient implements BooleanSupplier {
     static final String IO_QUARKUS_TEST_KUBERNETES_CLIENT_PACKAGE = "io.quarkus.test.kubernetes.client";
-    static final Boolean IO_QUARKUS_TEST_KUBERNETES_CLIENT_AVAILABLE = Arrays.asList(Package.getPackages())
-            .stream()
-            .map(p -> p.getName()).anyMatch(p -> p.startsWith(IO_QUARKUS_TEST_KUBERNETES_CLIENT_PACKAGE));
+    static final Boolean IO_QUARKUS_TEST_KUBERNETES_CLIENT_AVAILABLE = Arrays.stream(Package.getPackages())
+            .map(Package::getName)
+            .anyMatch(p -> p.startsWith(IO_QUARKUS_TEST_KUBERNETES_CLIENT_PACKAGE));
 
     @Override
     public boolean getAsBoolean() {
         return !IO_QUARKUS_TEST_KUBERNETES_CLIENT_AVAILABLE;
     }
-}
+}

extensions/kubernetes-client/runtime-internal/src/main/java/io/quarkus/kubernetes/client/runtime/internal/KubernetesDevServicesBuildTimeConfig.java

@@ -10,7 +10,7 @@ public interface KubernetesDevServicesBuildTimeConfig {
 
     /**
      * If Dev Services for Kubernetes should be used. (default to true)
-     *
+     * <p>
      * If this is true and kubernetes client is not configured then a kubernetes cluster
      * will be started and will be used.
      */
@@ -19,15 +19,16 @@ public interface KubernetesDevServicesBuildTimeConfig {
 
     /**
      * The kubernetes api server version to use.
-     *
-     * If not set, Dev Services for Kubernetes will use the latest supported version of the given flavor.
-     * see https://github.com/dajudge/kindcontainer/blob/master/k8s-versions.json
+     * <p>
+     * If not set, Dev Services for Kubernetes will use the
+     * <a href="https://github.com/dajudge/kindcontainer/blob/master/k8s-versions.json">latest supported version</a> of the
+     * given flavor.
      */
     Optional<String> apiVersion();
 
     /**
      * The flavor to use (kind, k3s or api-only).
-     *
+     * <p>
      * If not set, Dev Services for Kubernetes will set it to: api-only.
      */
     Optional<Flavor> flavor();
@@ -74,16 +75,16 @@ public interface KubernetesDevServicesBuildTimeConfig {
 
     enum Flavor {
         /**
-         * kind (needs priviledge docker)
+         * kind (needs privileged docker)
          */
         kind,
         /**
-         * k3s (needs priviledge docker)
+         * k3s (needs privileged docker)
          */
         k3s,
         /**
          * api only
          */
-        api_only;
+        api_only
     }
 }

extensions/kubernetes-client/spi/src/main/java/io/quarkus/kubernetes/client/spi/KubernetesDevServiceRequestBuildItem.java

@@ -6,7 +6,7 @@
  * BuildItem managing the Kubernetes DevService Request information for the extension consuming it
  */
 public final class KubernetesDevServiceRequestBuildItem extends SimpleBuildItem {
-    private String flavor;
+    private final String flavor;
 
     public KubernetesDevServiceRequestBuildItem(String flavor) {
         this.flavor = flavor;