# Dev Services for Kubernetes

Dev Services for Kubernetes automatically starts a Kubernetes API server (plus the required etcd) in dev mode and when running tests. So you don’t have to start it manually. The application is configured automatically.

The following testcontainers are supported: kind, k3s or api only(default)

## Enabling / Disabling Dev Services for Kubernetes

Dev Services for Kubernetes is automatically enabled unless:

- `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

| 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 KubernetesClientBuildConfig class.

## 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.

| Dev Services for Kubernetes starts the container with the `quarkus-dev-service-kubernetes` label which is used to identify the container.

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`.

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

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 cheat sheet.

Simple Bean Example

    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. You can configure the flavor and version using the `quarkus.kubernetes-client.devservices.flavor` and `quarkus.kubernetes-client.devservices.api-version` properties:

    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.

If `api-version` is not set, the latest version for the given flavor will be used. Otherwise, the version must match a version supported by the given flavor.

## Configuration reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property | Type | Default
--- | --- | ---
`quarkus.kubernetes-client.devservices.enabled` If Dev Services for Kubernetes should be used. (default to true) If this is true and kubernetes client is not configured then a kubernetes cluster will be started and will be used. Environment variable: `QUARKUS_KUBERNETES_CLIENT_DEVSERVICES_ENABLED` | boolean | `true`
`quarkus.kubernetes-client.devservices.api-version` 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 Environment variable: `QUARKUS_KUBERNETES_CLIENT_DEVSERVICES_API_VERSION` | string |
`quarkus.kubernetes-client.devservices.flavor` The flavor to use (kind, k3s or api-only). If not set, Dev Services for Kubernetes will set it to: api-only. Environment variable: `QUARKUS_KUBERNETES_CLIENT_DEVSERVICES_FLAVOR` | `kind`, `k3s`, `api-only` |
`quarkus.kubernetes-client.devservices.override-kubeconfig` By default, if a kubeconfig is found, Dev Services for Kubernetes will not start. Set this to true to override the kubeconfig config. Environment variable: `QUARKUS_KUBERNETES_CLIENT_DEVSERVICES_OVERRIDE_KUBECONFIG` | boolean | `false`
`quarkus.kubernetes-client.devservices.shared` Indicates if the Kubernetes cluster managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Kubernetes starts a new container. The discovery uses the `quarkus-dev-service-kubernetes` label. The value is configured using the `service-name` property. Container sharing is only used in dev mode. Environment variable: `QUARKUS_KUBERNETES_CLIENT_DEVSERVICES_SHARED` | boolean | `true`
`quarkus.kubernetes-client.devservices.service-name` The value of the `quarkus-dev-service-kubernetes` label attached to the started container. This property is used when `shared` is set to `true`. In this case, before starting a container, Dev Services for Kubernetes looks for a container with the `quarkus-dev-service-kubernetes` label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it starts a new container with the `quarkus-dev-service-kubernetes` label set to the specified value. This property is used when you need multiple shared Kubernetes clusters. Environment variable: `QUARKUS_KUBERNETES_CLIENT_DEVSERVICES_SERVICE_NAME` | string | `kubernetes`
`quarkus.kubernetes-client.devservices.container-env."environment-variable-name"` Environment variables that are passed to the container. Environment variable: `QUARKUS_KUBERNETES_CLIENT_DEVSERVICES_CONTAINER_ENV__ENVIRONMENT_VARIABLE_NAME_` | Map<String,String> |