<commit_before>////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc
////
= Quarkus - Generating Kubernetes resources

include::./attributes.adoc[]

This guide covers generating and deploying Kubernetes resources based on sane defaults and user supplied configuration.
In detail, it supports generating resources for <<Kubernetes>>, <<Openshift>> and <<Quarkus.Knative.>. Also it supports automatically <<deploying, Deployment>> these resources to the target platform.

== Prerequisites

To complete this guide, you need:

* roughly 10 minutes
* an IDE
* JDK 1.8+ installed with `JAVA_HOME` configured appropriately
* Apache Maven 3.5.3+
* access to a Kubernetes or cluster (Minikube is a viable options)

== Creating the Maven project

First, we need a new project that contains the Kubernetes extension. This can be done using the following command:

[source, subs=attributes+]
----
mvn io.quarkus:quarkus-maven-plugin:{quarkus-version}:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=kubernetes-quickstart \
    -DclassName="org.acme.rest.GreetingResource" \
    -Dpath="/greeting" \
    -Dextensions="kubernetes"
cd kubernetes-quickstart
----

=== Kubernetes

Quarkus offers the ability to automatically generate Kubernetes resources based on sane defaults and user supplied configuration. The implementation that takes care
of generating the actual Kubernetes resources is provided by https://github.com/dekorateio/dekorate/[dekorate]. Currently it supports the generation of resources for
vanilla Kubernetes and OpenShift.

When we added the `kubernetes` extension to the command line invocation above, the following dependency was added to the `pom.xml`

[source,xml]
----
    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-kubernetes</artifactId>
    </dependency>
----

By adding this dependency, we now have the ability to configure the Kubernetes resource generation and application using the usual `application.properties` approach that Quarkus provides.
The configuration items that are available can be found in: `io.quarkus.kubernetes.deployment.KubernetesConfig` class.
Furthermore, the items provided by `io.quarkus.deployment.ApplicationConfig` affect the Kubernetes resources.

By using the following configuration for example:

[source]
----
quarkus.kubernetes.group=yourDockerUsername # this is optional and defaults to your username if not set.
quarkus.application.name=test-quarkus-app # this is also optional and defaults to the project name if not set
----

and following the execution of `./mvnw package` you will notice amongst the other files that are created, two files named
`kubernetes.json` and `kubernetes.yml` in the `target/kubernetes/` directory.

If you look at either file you will see that it contains both a Kubernetes `Deployment` and a `Service`.

The full source of the `kubernetes.json` file looks something like this:

[source,json]
----
{
  "apiVersion" : "v1",
  "kind" : "List",
  "items" : [ {
    "apiVersion" : "apps/v1",
    "kind" : "Deployment",
    "metadata" : {
      "labels" : {
        "app" : "test-quarkus-app",
        "version" : "1.0-SNAPSHOT",
        "group" : "yourDockerUsername"
      },
      "name" : "test-quarkus-app"
    },
    "spec" : {
      "replicas" : 1,
      "selector" : {
        "matchLabels" : {
          "app" : "test-quarkus-app",
          "version" : "1.0-SNAPSHOT",
          "group" : "yourDockerUsername"
        }
      },
      "template" : {
        "metadata" : {
          "labels" : {
            "app" : "test-quarkus-app",
            "version" : "1.0-SNAPSHOT",
            "group" : "yourDockerUsername"
          }
        },
        "spec" : {
          "containers" : [ {
            "env" : [ {
              "name" : "KUBERNETES_NAMESPACE",
              "valueFrom" : {
                "fieldRef" : {
                  "fieldPath" : "metadata.namespace"
                }
              }
            } ],
            "image" : "yourDockerUsername/test-quarkus-app:1.0-SNAPSHOT",
            "imagePullPolicy" : "IfNotPresent",
            "name" : "test-quarkus-app"
          } ]
        }
      }
    }
  } ]
}
----

An important thing to note about the `Deployment` is that is uses `yourDockerUsername/test-quarkus-app:1.0-SNAPSHOT` as the Docker image of the `Pod`.

Also the `Service` is configured to use container port `8080` (which is automatically picked up by the standard Quarkus configuration).

=== Add readiness and liveness probes

By default the Kubernetes resources do not contain readiness and liveness probes in the generated `Deployment`. Adding them however is just a matter of adding the Smallrye Health extension like so:

[source,xml]
----
    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-smallrye-health</artifactId>
    </dependency>
----

The values of the generated probes will be determined by the configured health properties: `quarkus.smallrye-health.root-path`, `quarkus.smallrye-health.liveness-path` and `quarkus.smallrye-health.readiness-path`.
More information about the health extension can be found in the relevant link:microprofile-health[guide].

=== Using the Kubernetes client

Applications that are deployed to Kubernetes and need to access the API server, will usually make use of the `kubernetes-client` extension:

[source,xml]
----
    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-kubernetes-client</artifactId>
    </dependency>
----

To access the API server from within a Kubernetes cluster, some RBAC related resources are required (e.g. a ServiceAccount, a RoleBinding etc.).
So, when the `kubernetes-client` extension is present, the `kubernetes` extension is going to create those resources automatically, so that application will be granted the `view` role.
If more roles are required, they will have to be added manually.

== Tuning the generated resources using application.properties

The Kubernetes extension allows tuning the generated manifest, using the `application.properties` file.
Here are some examples:

=== Changing the number of replicas:
To change the number of replicas from 1 to  3:

[source]
----
quarkus.kubernetes.replicas=3
----

=== Defining a docker registry and repository

The docker registry and the user of the docker image can be specified, with the following properties:

[source]
----
quarkus.kubernetes.group=myUser
quarkus.docker.registry=http://my.docker-registry.net
----

Note: These options used to be `quarkus.kubernetes.docker.registry` and `quarkus.kubernetes.group` respectively.

=== Adding labels:
To add a new label to all generated resources, say `foo=bar`:

[source]
----
quarkus.kubernetes.labels.foo=bar
----

=== Customizing the readiness probe:
To set the initial delay of the probe to 20 seconds and the period to 45:

[source]
----
quarkus.kubernetes.readiness-probe.initial-delay-seconds=20
quarkus.kubernetes.readiness-probe.period-seconds=45
----

Here you can find a complete reference to all the available configuration options:

==== Configuration options

The table below describe all the available configuration options.

.Kubernetes
|====
| Property                                           | Type                                      | Description | Default Value
| quarkus.kubernetes.group                           | String                                    |             |
| quarkus.kubernetes.name                            | String                                    |             |
| quarkus.kubernetes.version                         | String                                    |             |
| quarkus.kubernetes.init-containers                 | Map<String, Container>                    |             |
| quarkus.kubernetes.labels                          | Map                                       |             |
| quarkus.kubernetes.annotations                     | Map                                       |             |
| quarkus.kubernetes.env-vars                        | Map<String, Env>                          |             |
| quarkus.kubernetes.working-dir                     | String                                    |             |
| quarkus.kubernetes.command                         | String[]                                  |             |
| quarkus.kubernetes.arguments                       | String[]                                  |             |
| quarkus.kubernetes.replicas                        | int                                       |             | 1
| quarkus.kubernetes.service-account                 | String                                    |             |
| quarkus.kubernetes.host                            | String                                    |             |
| quarkus.kubernetes.ports                           | Map<String, Port>                         |             |
| quarkus.kubernetes.service-type                    | ServiceType                               |             | ClusterIP
| quarkus.kubernetes.pvc-volumes                     | Map<String, PersistentVolumeClaimVolume>  |             |
| quarkus.kubernetes.secret-volumes                  | Map<String, SecretVolume>                 |             |
| quarkus.kubernetes.config-map-volumes              | Map<String, ConfigMapVolume>              |             |
| quarkus.kubernetes.git-repo-volumes                | Map<String, GitRepoVolume>                |             |
| quarkus.kubernetes.aws-elastic-block-store-volumes | Map<String, AwsElasticBlockStoreVolume>   |             |
| quarkus.kubernetes.azure-disk-volumes              | Map<String, AzureDiskVolume>              |             |
| quarkus.kubernetes.azure-file-volumes              | Map<String, AzureFileVolume>              |             |
| quarkus.kubernetes.mounts                          | Map<String, Mount>                        |             |
| quarkus.kubernetes.image-pull-policy               | ImagePullPolicy                           |             | IfNotPresent
| quarkus.kubernetes.image-pull-secrets              | String[]                                  |             |
| quarkus.kubernetes.liveness-probe                  | Probe                                     |             | ( see Probe )
| quarkus.kubernetes.readiness-probe                 | Probe                                     |             | ( see Probe )
| quarkus.kubernetes.sidecars                        | Map<String, Container>                    |             |
| quarkus.kubernetes.expose                          | boolean                                   |             | false
| quarkus.kubernetes.headless                        | boolean                                   |             | false
|====

Properties that use non standard types, can be referenced by expanding the property.
For example to define a `kubernetes-readiness-probe` which is of type `Probe`:

[source]
----
quarkus.kubernetes.readiness-probe.initial-delay-seconds=20
quarkus.kubernetes.readiness-probe.period-seconds=45
----

In this example `initial-delay` and `period-seconds` are fields of the type `Probe`.
Below you will find tables describing all available types.


===== Basic Types

.Env
|====
| Property  | Type   | Description | Default Value
| value     | String |             |
| secret    | String |             |              
| configmap | String |             |              
| field     | String |             |              
|====

.Probe
|====
| Property              | Type   | Description | Default Value
| http-action-path      | String |             |
| exec-action           | String |             |
| tcp-socket-action     | String |             |               
| initial-delay-seconds | int    |             |             0 
| period-seconds        | int    |             |            30
| timeout-seconds       | int    |             |            10
|====

.Port
|====
| Property        | Type     | Description | Default Value
| container-port  | int      |             |
| host-port       | int      |             | 0
| path            | String   |             | /
| protocol        | Protocol |             | TCP
|====

.Container
|====
| Property          | Type                                    | Description | Default Value
| image             | String                                  |             |
| env-vars          | Env[]                                   |             |
| working-dir       | String                                  |             |                                          
| command           | String[]                                |             |
| arguments         | String[]                                |             |
| ports             | Port[]                                  |             |
| mounts            | Mount[]                                 |             |
| image-pull-policy | ImagePullPolicy                         |             | IfNotPresent                             
| liveness-probe    | Probe                                   |             |                                          
| readiness-probe   | Probe                                   |             |                                          
|====


== Mounts and Volumes

.Mount
|====
| Property  | Type    | Description | Default Value
| path      | String  |             |
| sub-path  | String  |             |               
| read-only | boolean |             | false         
|====

.ConfigMapVolume
|====
| Property        | Type    | Description | Default Value
| config-map-name | String  |             |
| default-mode    | int     |             | 384
| optional        | boolean |             | false
|====

.SecretVolume
|====
| Property     | Type    | Description | Default Value
| secret-name  | String  |             |
| default-mode | int     |             | 384           
| optional     | boolean |             | false
|====


.AzureDiskVolume
|====
| Property     | Type    | Description | Default Value
| disk-name    | String  |             |
| disk-uri     | String  |             |               
| kind         | String  |             | Managed
| caching-mode | String  |             | ReadWrite     
| fs-type      | String  |             | ext4          
| read-only    | boolean |             | false         
|====

.AwsElasticBlockStoreVolume
|====
| Property    | Type    | Description | Default Value
| volume-id   | String  |             |
| partition   | int     |             |
| fs-type     | String  |             | ext4          
| read-only   | boolean |             | false         
|====

.GitRepoVolume
|====
| Property    | Type   | Description | Default Value
| repository  | String |             |
| directory   | String |             |
| revision    | String |             |
|====

.PersistentVolumeClaimVolume
|====
| Property    | Type    | Description | Default Value
| claim-name  | String  |             |
| read-only   | boolean |             | false        
|====
.AzureFileVolume
|====
| Property    | Type    | Description | Default Value
| share-name  | String  |             |
| secret-name | String  |             |              
| read-only   | boolean |             | false        
|====

=== OpenShift

To enable the generation of OpenShift resources, you need to include OpenShift in the target platforms:

[source]
----
quarkus.kubernetes.deployment-target=openshift
----

If you need to generate resources for both platforms (vanilla Kubernetes and OpenShift), then you need to include both (coma separated).

[source]
----
quarkus.kubernetes.deployment-target=kubernetes, openshift
----

The OpenShift resources can be customized in a similar approach with Kubernetes.

.Openshift
|====
| Property                                          | Type                                      | Description | Default Value
| quarkus.openshift.group                           | String                                    |             |
| quarkus.openshift.name                            | String                                    |             |
| quarkus.openshift.version                         | String                                    |             |
| quarkus.openshift.init-containers                 | Map<String, Container>                    |             |
| quarkus.openshift.labels                          | Map                                       |             |
| quarkus.openshift.annotations                     | Map                                       |             |
| quarkus.openshift.env-vars                        | Map<String, Env>                          |             |
| quarkus.openshift.working-dir                     | String                                    |             |
| quarkus.openshift.command                         | String[]                                  |             |
| quarkus.openshift.arguments                       | String[]                                  |             |
| quarkus.openshift.replicas                        | int                                       |             | 1
| quarkus.openshift.service-account                 | String                                    |             |
| quarkus.openshift.host                            | String                                    |             |
| quarkus.openshift.ports                           | Map<String, Port>                         |             |
| quarkus.openshift.service-type                    | ServiceType                               |             | ClusterIP
| quarkus.openshift.pvc-volumes                     | Map<String, PersistentVolumeClaimVolume>  |             |
| quarkus.openshift.secret-volumes                  | Map<String, SecretVolume>                 |             |
| quarkus.openshift.config-map-volumes              | Map<String, ConfigMapVolume>              |             |
| quarkus.openshift.git-repo-volumes                | Map<String, GitRepoVolume>                |             |
| quarkus.openshift.aws-elastic-block-store-volumes | Map<String, AwsElasticBlockStoreVolume>   |             |
| quarkus.openshift.azure-disk-volumes              | Map<String, AzureDiskVolume>              |             |
| quarkus.openshift.azure-file-volumes              | Map<String, AzureFileVolume>              |             |
| quarkus.openshift.mounts                          | Map<String, Mount>                        |             |
| quarkus.openshift.image-pull-policy               | ImagePullPolicy                           |             | IfNotPresent
| quarkus.openshift.image-pull-secrets              | String[]                                  |             |
| quarkus.openshift.liveness-probe                  | Probe                                     |             | ( see Probe )
| quarkus.openshift.readiness-probe                 | Probe                                     |             | ( see Probe )
| quarkus.openshift.sidecars                        | Map<String, Container>                    |             |
| quarkus.openshift.expose                          | boolean                                   |             | false
| quarkus.openshift.headless                        | boolean                                   |             | false
|====

=== Knative
    
To enable the generation of Quarkus.Knative.resources, you need to include Knative in the target platforms:

[source]
----
quarkus.kubernetes.deployment.target=knative
----

Following the execution of `./mvnw package` you will notice amongst the other files that are created, two files named
`quarkus.knative.json` and `knative.yml` in the `target/kubernetes/` directory.

If you look at either file you will see that it contains a Quarkus.Knative.`Service`.

The full source of the `quarkus.knative.json` file looks something like this:

[source,json]
----
{
  "apiVersion" : "v1",
  "kind" : "List",
  "items" : [ {
    "apiVersion" : "serving.quarkus.knative.dev/v1alpha1",
    "kind" : "Service",
    "metadata" : {
      "labels" : {
        "app" : "test-quarkus-app",
        "version" : "0.1-SNAPSHOT",
        "group" : "yourDockerUsername"
      },
      "name" : "quarkus.knative.
    },
    "spec" : {
      "runLatest" : {
        "configuration" : {
          "revisionTemplate" : {
            "spec" : {
              "container" : {
                "image" : "dev.local/yourDockerUsername/test-quarkus-app:1.0-SNAPSHOT",
                "imagePullPolicy" : "IfNotPresent"
              }
            }
          }
        }
      }
    }
  } ]
}
----

The generated service can be customized using the following properties:

.Knative
|====
| Property                                        | Type                                      | Description | Default Value
| quarkus.knative.group                           | String                                    |             |
| quarkus.knative.name                            | String                                    |             |
| quarkus.knative.version                         | String                                    |             |
| quarkus.knative.init-containers                 | Map<String, Container>                    |             |
| quarkus.knative.labels                          | Map                                       |             |
| quarkus.knative.annotations                     | Map                                       |             |
| quarkus.knative.env-vars                        | Map<String, Env>                          |             |
| quarkus.knative.working-dir                     | String                                    |             |
| quarkus.knative.command                         | String[]                                  |             |
| quarkus.knative.arguments                       | String[]                                  |             |
| quarkus.knative.replicas                        | int                                       |             | 1
| quarkus.knative.service-account                 | String                                    |             |
| quarkus.knative.host                            | String                                    |             |
| quarkus.knative.ports                           | Map<String, Port>                         |             |
| quarkus.knative.service-type                    | ServiceType                               |             | ClusterIP
| quarkus.knative.pvc-volumes                     | Map<String, PersistentVolumeClaimVolume>  |             |
| quarkus.knative.secret-volumes                  | Map<String, SecretVolume>                 |             |
| quarkus.knative.config-map-volumes              | Map<String, ConfigMapVolume>              |             |
| quarkus.knative.git-repo-volumes                | Map<String, GitRepoVolume>                |             |
| quarkus.knative.aws-elastic-block-store-volumes | Map<String, AwsElasticBlockStoreVolume>   |             |
| quarkus.knative.azure-disk-volumes              | Map<String, AzureDiskVolume>              |             |
| quarkus.knative.azure-file-volumes              | Map<String, AzureFileVolume>              |             |
| quarkus.knative.mounts                          | Map<String, Mount>                        |             |
| quarkus.knative.image-pull-policy               | ImagePullPolicy                           |             | IfNotPresent
| quarkus.knative.image-pull-secrets              | String[]                                  |             |
| quarkus.knative.liveness-probe                  | Probe                                     |             | ( see Probe )
| quarkus.knative.readiness-probe                 | Probe                                     |             | ( see Probe )
| quarkus.knative.sidecars                        | Map<String, Container>                    |             |
|====


=== Deprecated configuration

The following categories of configuration properties have been deprecated.

==== Properties without the quarkus prefix

In earlier versions of the extension, the `quarkus.` was missing from those properties. These properties are now deprecated.

==== Docker and S2i properties

The properties for configuring `docker` and `s2i` are also deprecated in favor of the new container-image extensions.

==== Config group arrays

Properties refering to config group arrays (e.g. kubernetes.labels[0], kubernetes.env-vars[0] etc) have been converted to maps, to align with the rest of the quarkus ecosystem.

The code below demonstrates the change in `labels` config:

[source]
----
# Old labels config:
kubernetes.labels[0].name=foo
kubernetes.labels[0].name=bar

# New labels
quarkus.kubernetes.labels.foo=bar
----

The code below demonstrates the change in `env-vars` config:

[source]
----
# Old env-vars config:
kubernetes.env-vars[0].name=foo
kubernetes.env-vars[0].configmap=my-configmap

# New env-vars
quarkus.kubernetes.env-vars.foo.configmap=myconfigmap
----


== Deployment

To trigger building and deploying a container image you need to enable the `quarkus.container.deploy` flag.
This can be easily done from the command line:

[source, subs=attributes+]
----
mvn clean package -Dquarkus.kubernetes.deploy=true
----

=== Building

Building is possible, using any of the 3 available `container-image` extensions:

- link:container-image#docker[Docker]
- link:container-image#jib[Jib]
- link:container-image#s2i[s2i]

Each time deployment is requested, a container build will be implicitly triggered (no additonal properties are required).

=== Deploying

When deployment is enabled, the kubernetes extension will selected the resources specified by `quarkus.kubernetes.deployment.target` and deploy them.
This assumes that a `.kube/config` is available in your user directory that points to a real kubernetes cluster.
In other words the extension will use whatever cluster `kubectl` uses. The same applies to credentials.

At the moment no additonal options are provided for further customization.
<commit_msg>docs: fix broken links in kubernetes.adoc guide<commit_after>////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc
////
= Quarkus - Generating Kubernetes resources

include::./attributes.adoc[]

This guide covers generating and deploying Kubernetes resources based on sane defaults and user supplied configuration.
In detail, it supports generating resources for <<Kubernetes>>, <<OpenShift>> and <<Knative>>. Also it supports automatically <<Deployment>> these resources to the target platform.

== Prerequisites

To complete this guide, you need:

* roughly 10 minutes
* an IDE
* JDK 1.8+ installed with `JAVA_HOME` configured appropriately
* Apache Maven 3.5.3+
* access to a Kubernetes or cluster (Minikube is a viable options)

== Creating the Maven project

First, we need a new project that contains the Kubernetes extension. This can be done using the following command:

[source, subs=attributes+]
----
mvn io.quarkus:quarkus-maven-plugin:{quarkus-version}:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=kubernetes-quickstart \
    -DclassName="org.acme.rest.GreetingResource" \
    -Dpath="/greeting" \
    -Dextensions="kubernetes"
cd kubernetes-quickstart
----

=== Kubernetes

Quarkus offers the ability to automatically generate Kubernetes resources based on sane defaults and user supplied configuration. The implementation that takes care
of generating the actual Kubernetes resources is provided by https://github.com/dekorateio/dekorate/[dekorate]. Currently it supports the generation of resources for
vanilla Kubernetes and OpenShift.

When we added the `kubernetes` extension to the command line invocation above, the following dependency was added to the `pom.xml`

[source,xml]
----
    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-kubernetes</artifactId>
    </dependency>
----

By adding this dependency, we now have the ability to configure the Kubernetes resource generation and application using the usual `application.properties` approach that Quarkus provides.
The configuration items that are available can be found in: `io.quarkus.kubernetes.deployment.KubernetesConfig` class.
Furthermore, the items provided by `io.quarkus.deployment.ApplicationConfig` affect the Kubernetes resources.

By using the following configuration for example:

[source]
----
quarkus.kubernetes.group=yourDockerUsername # this is optional and defaults to your username if not set.
quarkus.application.name=test-quarkus-app # this is also optional and defaults to the project name if not set
----

and following the execution of `./mvnw package` you will notice amongst the other files that are created, two files named
`kubernetes.json` and `kubernetes.yml` in the `target/kubernetes/` directory.

If you look at either file you will see that it contains both a Kubernetes `Deployment` and a `Service`.

The full source of the `kubernetes.json` file looks something like this:

[source,json]
----
{
  "apiVersion" : "v1",
  "kind" : "List",
  "items" : [ {
    "apiVersion" : "apps/v1",
    "kind" : "Deployment",
    "metadata" : {
      "labels" : {
        "app" : "test-quarkus-app",
        "version" : "1.0-SNAPSHOT",
        "group" : "yourDockerUsername"
      },
      "name" : "test-quarkus-app"
    },
    "spec" : {
      "replicas" : 1,
      "selector" : {
        "matchLabels" : {
          "app" : "test-quarkus-app",
          "version" : "1.0-SNAPSHOT",
          "group" : "yourDockerUsername"
        }
      },
      "template" : {
        "metadata" : {
          "labels" : {
            "app" : "test-quarkus-app",
            "version" : "1.0-SNAPSHOT",
            "group" : "yourDockerUsername"
          }
        },
        "spec" : {
          "containers" : [ {
            "env" : [ {
              "name" : "KUBERNETES_NAMESPACE",
              "valueFrom" : {
                "fieldRef" : {
                  "fieldPath" : "metadata.namespace"
                }
              }
            } ],
            "image" : "yourDockerUsername/test-quarkus-app:1.0-SNAPSHOT",
            "imagePullPolicy" : "IfNotPresent",
            "name" : "test-quarkus-app"
          } ]
        }
      }
    }
  } ]
}
----

An important thing to note about the `Deployment` is that is uses `yourDockerUsername/test-quarkus-app:1.0-SNAPSHOT` as the Docker image of the `Pod`.

Also the `Service` is configured to use container port `8080` (which is automatically picked up by the standard Quarkus configuration).

=== Add readiness and liveness probes

By default the Kubernetes resources do not contain readiness and liveness probes in the generated `Deployment`. Adding them however is just a matter of adding the Smallrye Health extension like so:

[source,xml]
----
    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-smallrye-health</artifactId>
    </dependency>
----

The values of the generated probes will be determined by the configured health properties: `quarkus.smallrye-health.root-path`, `quarkus.smallrye-health.liveness-path` and `quarkus.smallrye-health.readiness-path`.
More information about the health extension can be found in the relevant link:microprofile-health[guide].

=== Using the Kubernetes client

Applications that are deployed to Kubernetes and need to access the API server, will usually make use of the `kubernetes-client` extension:

[source,xml]
----
    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-kubernetes-client</artifactId>
    </dependency>
----

To access the API server from within a Kubernetes cluster, some RBAC related resources are required (e.g. a ServiceAccount, a RoleBinding etc.).
So, when the `kubernetes-client` extension is present, the `kubernetes` extension is going to create those resources automatically, so that application will be granted the `view` role.
If more roles are required, they will have to be added manually.

== Tuning the generated resources using application.properties

The Kubernetes extension allows tuning the generated manifest, using the `application.properties` file.
Here are some examples:

=== Changing the number of replicas:
To change the number of replicas from 1 to  3:

[source]
----
quarkus.kubernetes.replicas=3
----

=== Defining a docker registry and repository

The docker registry and the user of the docker image can be specified, with the following properties:

[source]
----
quarkus.kubernetes.group=myUser
quarkus.docker.registry=http://my.docker-registry.net
----

Note: These options used to be `quarkus.kubernetes.docker.registry` and `quarkus.kubernetes.group` respectively.

=== Adding labels:
To add a new label to all generated resources, say `foo=bar`:

[source]
----
quarkus.kubernetes.labels.foo=bar
----

=== Customizing the readiness probe:
To set the initial delay of the probe to 20 seconds and the period to 45:

[source]
----
quarkus.kubernetes.readiness-probe.initial-delay-seconds=20
quarkus.kubernetes.readiness-probe.period-seconds=45
----

Here you can find a complete reference to all the available configuration options:

==== Configuration options

The table below describe all the available configuration options.

.Kubernetes
|====
| Property                                           | Type                                      | Description | Default Value
| quarkus.kubernetes.group                           | String                                    |             |
| quarkus.kubernetes.name                            | String                                    |             |
| quarkus.kubernetes.version                         | String                                    |             |
| quarkus.kubernetes.init-containers                 | Map<String, Container>                    |             |
| quarkus.kubernetes.labels                          | Map                                       |             |
| quarkus.kubernetes.annotations                     | Map                                       |             |
| quarkus.kubernetes.env-vars                        | Map<String, Env>                          |             |
| quarkus.kubernetes.working-dir                     | String                                    |             |
| quarkus.kubernetes.command                         | String[]                                  |             |
| quarkus.kubernetes.arguments                       | String[]                                  |             |
| quarkus.kubernetes.replicas                        | int                                       |             | 1
| quarkus.kubernetes.service-account                 | String                                    |             |
| quarkus.kubernetes.host                            | String                                    |             |
| quarkus.kubernetes.ports                           | Map<String, Port>                         |             |
| quarkus.kubernetes.service-type                    | ServiceType                               |             | ClusterIP
| quarkus.kubernetes.pvc-volumes                     | Map<String, PersistentVolumeClaimVolume>  |             |
| quarkus.kubernetes.secret-volumes                  | Map<String, SecretVolume>                 |             |
| quarkus.kubernetes.config-map-volumes              | Map<String, ConfigMapVolume>              |             |
| quarkus.kubernetes.git-repo-volumes                | Map<String, GitRepoVolume>                |             |
| quarkus.kubernetes.aws-elastic-block-store-volumes | Map<String, AwsElasticBlockStoreVolume>   |             |
| quarkus.kubernetes.azure-disk-volumes              | Map<String, AzureDiskVolume>              |             |
| quarkus.kubernetes.azure-file-volumes              | Map<String, AzureFileVolume>              |             |
| quarkus.kubernetes.mounts                          | Map<String, Mount>                        |             |
| quarkus.kubernetes.image-pull-policy               | ImagePullPolicy                           |             | IfNotPresent
| quarkus.kubernetes.image-pull-secrets              | String[]                                  |             |
| quarkus.kubernetes.liveness-probe                  | Probe                                     |             | ( see Probe )
| quarkus.kubernetes.readiness-probe                 | Probe                                     |             | ( see Probe )
| quarkus.kubernetes.sidecars                        | Map<String, Container>                    |             |
| quarkus.kubernetes.expose                          | boolean                                   |             | false
| quarkus.kubernetes.headless                        | boolean                                   |             | false
|====

Properties that use non standard types, can be referenced by expanding the property.
For example to define a `kubernetes-readiness-probe` which is of type `Probe`:

[source]
----
quarkus.kubernetes.readiness-probe.initial-delay-seconds=20
quarkus.kubernetes.readiness-probe.period-seconds=45
----

In this example `initial-delay` and `period-seconds` are fields of the type `Probe`.
Below you will find tables describing all available types.


===== Basic Types

.Env
|====
| Property  | Type   | Description | Default Value
| value     | String |             |
| secret    | String |             |              
| configmap | String |             |              
| field     | String |             |              
|====

.Probe
|====
| Property              | Type   | Description | Default Value
| http-action-path      | String |             |
| exec-action           | String |             |
| tcp-socket-action     | String |             |               
| initial-delay-seconds | int    |             |             0 
| period-seconds        | int    |             |            30
| timeout-seconds       | int    |             |            10
|====

.Port
|====
| Property        | Type     | Description | Default Value
| container-port  | int      |             |
| host-port       | int      |             | 0
| path            | String   |             | /
| protocol        | Protocol |             | TCP
|====

.Container
|====
| Property          | Type                                    | Description | Default Value
| image             | String                                  |             |
| env-vars          | Env[]                                   |             |
| working-dir       | String                                  |             |                                          
| command           | String[]                                |             |
| arguments         | String[]                                |             |
| ports             | Port[]                                  |             |
| mounts            | Mount[]                                 |             |
| image-pull-policy | ImagePullPolicy                         |             | IfNotPresent                             
| liveness-probe    | Probe                                   |             |                                          
| readiness-probe   | Probe                                   |             |                                          
|====


== Mounts and Volumes

.Mount
|====
| Property  | Type    | Description | Default Value
| path      | String  |             |
| sub-path  | String  |             |               
| read-only | boolean |             | false         
|====

.ConfigMapVolume
|====
| Property        | Type    | Description | Default Value
| config-map-name | String  |             |
| default-mode    | int     |             | 384
| optional        | boolean |             | false
|====

.SecretVolume
|====
| Property     | Type    | Description | Default Value
| secret-name  | String  |             |
| default-mode | int     |             | 384           
| optional     | boolean |             | false
|====


.AzureDiskVolume
|====
| Property     | Type    | Description | Default Value
| disk-name    | String  |             |
| disk-uri     | String  |             |               
| kind         | String  |             | Managed
| caching-mode | String  |             | ReadWrite     
| fs-type      | String  |             | ext4          
| read-only    | boolean |             | false         
|====

.AwsElasticBlockStoreVolume
|====
| Property    | Type    | Description | Default Value
| volume-id   | String  |             |
| partition   | int     |             |
| fs-type     | String  |             | ext4          
| read-only   | boolean |             | false         
|====

.GitRepoVolume
|====
| Property    | Type   | Description | Default Value
| repository  | String |             |
| directory   | String |             |
| revision    | String |             |
|====

.PersistentVolumeClaimVolume
|====
| Property    | Type    | Description | Default Value
| claim-name  | String  |             |
| read-only   | boolean |             | false        
|====
.AzureFileVolume
|====
| Property    | Type    | Description | Default Value
| share-name  | String  |             |
| secret-name | String  |             |              
| read-only   | boolean |             | false        
|====

=== OpenShift

To enable the generation of OpenShift resources, you need to include OpenShift in the target platforms:

[source]
----
quarkus.kubernetes.deployment-target=openshift
----

If you need to generate resources for both platforms (vanilla Kubernetes and OpenShift), then you need to include both (coma separated).

[source]
----
quarkus.kubernetes.deployment-target=kubernetes, openshift
----

The OpenShift resources can be customized in a similar approach with Kubernetes.

.Openshift
|====
| Property                                          | Type                                      | Description | Default Value
| quarkus.openshift.group                           | String                                    |             |
| quarkus.openshift.name                            | String                                    |             |
| quarkus.openshift.version                         | String                                    |             |
| quarkus.openshift.init-containers                 | Map<String, Container>                    |             |
| quarkus.openshift.labels                          | Map                                       |             |
| quarkus.openshift.annotations                     | Map                                       |             |
| quarkus.openshift.env-vars                        | Map<String, Env>                          |             |
| quarkus.openshift.working-dir                     | String                                    |             |
| quarkus.openshift.command                         | String[]                                  |             |
| quarkus.openshift.arguments                       | String[]                                  |             |
| quarkus.openshift.replicas                        | int                                       |             | 1
| quarkus.openshift.service-account                 | String                                    |             |
| quarkus.openshift.host                            | String                                    |             |
| quarkus.openshift.ports                           | Map<String, Port>                         |             |
| quarkus.openshift.service-type                    | ServiceType                               |             | ClusterIP
| quarkus.openshift.pvc-volumes                     | Map<String, PersistentVolumeClaimVolume>  |             |
| quarkus.openshift.secret-volumes                  | Map<String, SecretVolume>                 |             |
| quarkus.openshift.config-map-volumes              | Map<String, ConfigMapVolume>              |             |
| quarkus.openshift.git-repo-volumes                | Map<String, GitRepoVolume>                |             |
| quarkus.openshift.aws-elastic-block-store-volumes | Map<String, AwsElasticBlockStoreVolume>   |             |
| quarkus.openshift.azure-disk-volumes              | Map<String, AzureDiskVolume>              |             |
| quarkus.openshift.azure-file-volumes              | Map<String, AzureFileVolume>              |             |
| quarkus.openshift.mounts                          | Map<String, Mount>                        |             |
| quarkus.openshift.image-pull-policy               | ImagePullPolicy                           |             | IfNotPresent
| quarkus.openshift.image-pull-secrets              | String[]                                  |             |
| quarkus.openshift.liveness-probe                  | Probe                                     |             | ( see Probe )
| quarkus.openshift.readiness-probe                 | Probe                                     |             | ( see Probe )
| quarkus.openshift.sidecars                        | Map<String, Container>                    |             |
| quarkus.openshift.expose                          | boolean                                   |             | false
| quarkus.openshift.headless                        | boolean                                   |             | false
|====

=== Knative
    
To enable the generation of Quarkus.Knative.resources, you need to include Knative in the target platforms:

[source]
----
quarkus.kubernetes.deployment.target=knative
----

Following the execution of `./mvnw package` you will notice amongst the other files that are created, two files named
`quarkus.knative.json` and `knative.yml` in the `target/kubernetes/` directory.

If you look at either file you will see that it contains a Quarkus.Knative.`Service`.

The full source of the `quarkus.knative.json` file looks something like this:

[source,json]
----
{
  "apiVersion" : "v1",
  "kind" : "List",
  "items" : [ {
    "apiVersion" : "serving.quarkus.knative.dev/v1alpha1",
    "kind" : "Service",
    "metadata" : {
      "labels" : {
        "app" : "test-quarkus-app",
        "version" : "0.1-SNAPSHOT",
        "group" : "yourDockerUsername"
      },
      "name" : "quarkus.knative.
    },
    "spec" : {
      "runLatest" : {
        "configuration" : {
          "revisionTemplate" : {
            "spec" : {
              "container" : {
                "image" : "dev.local/yourDockerUsername/test-quarkus-app:1.0-SNAPSHOT",
                "imagePullPolicy" : "IfNotPresent"
              }
            }
          }
        }
      }
    }
  } ]
}
----

The generated service can be customized using the following properties:

.Knative
|====
| Property                                        | Type                                      | Description | Default Value
| quarkus.knative.group                           | String                                    |             |
| quarkus.knative.name                            | String                                    |             |
| quarkus.knative.version                         | String                                    |             |
| quarkus.knative.init-containers                 | Map<String, Container>                    |             |
| quarkus.knative.labels                          | Map                                       |             |
| quarkus.knative.annotations                     | Map                                       |             |
| quarkus.knative.env-vars                        | Map<String, Env>                          |             |
| quarkus.knative.working-dir                     | String                                    |             |
| quarkus.knative.command                         | String[]                                  |             |
| quarkus.knative.arguments                       | String[]                                  |             |
| quarkus.knative.replicas                        | int                                       |             | 1
| quarkus.knative.service-account                 | String                                    |             |
| quarkus.knative.host                            | String                                    |             |
| quarkus.knative.ports                           | Map<String, Port>                         |             |
| quarkus.knative.service-type                    | ServiceType                               |             | ClusterIP
| quarkus.knative.pvc-volumes                     | Map<String, PersistentVolumeClaimVolume>  |             |
| quarkus.knative.secret-volumes                  | Map<String, SecretVolume>                 |             |
| quarkus.knative.config-map-volumes              | Map<String, ConfigMapVolume>              |             |
| quarkus.knative.git-repo-volumes                | Map<String, GitRepoVolume>                |             |
| quarkus.knative.aws-elastic-block-store-volumes | Map<String, AwsElasticBlockStoreVolume>   |             |
| quarkus.knative.azure-disk-volumes              | Map<String, AzureDiskVolume>              |             |
| quarkus.knative.azure-file-volumes              | Map<String, AzureFileVolume>              |             |
| quarkus.knative.mounts                          | Map<String, Mount>                        |             |
| quarkus.knative.image-pull-policy               | ImagePullPolicy                           |             | IfNotPresent
| quarkus.knative.image-pull-secrets              | String[]                                  |             |
| quarkus.knative.liveness-probe                  | Probe                                     |             | ( see Probe )
| quarkus.knative.readiness-probe                 | Probe                                     |             | ( see Probe )
| quarkus.knative.sidecars                        | Map<String, Container>                    |             |
|====


=== Deprecated configuration

The following categories of configuration properties have been deprecated.

==== Properties without the quarkus prefix

In earlier versions of the extension, the `quarkus.` was missing from those properties. These properties are now deprecated.

==== Docker and S2i properties

The properties for configuring `docker` and `s2i` are also deprecated in favor of the new container-image extensions.

==== Config group arrays

Properties refering to config group arrays (e.g. kubernetes.labels[0], kubernetes.env-vars[0] etc) have been converted to maps, to align with the rest of the quarkus ecosystem.

The code below demonstrates the change in `labels` config:

[source]
----
# Old labels config:
kubernetes.labels[0].name=foo
kubernetes.labels[0].name=bar

# New labels
quarkus.kubernetes.labels.foo=bar
----

The code below demonstrates the change in `env-vars` config:

[source]
----
# Old env-vars config:
kubernetes.env-vars[0].name=foo
kubernetes.env-vars[0].configmap=my-configmap

# New env-vars
quarkus.kubernetes.env-vars.foo.configmap=myconfigmap
----


== Deployment

To trigger building and deploying a container image you need to enable the `quarkus.container.deploy` flag.
This can be easily done from the command line:

[source, subs=attributes+]
----
mvn clean package -Dquarkus.kubernetes.deploy=true
----

=== Building

Building is possible, using any of the 3 available `container-image` extensions:

- link:container-image#docker[Docker]
- link:container-image#jib[Jib]
- link:container-image#s2i[s2i]

Each time deployment is requested, a container build will be implicitly triggered (no additonal properties are required).

=== Deploying

When deployment is enabled, the kubernetes extension will selected the resources specified by `quarkus.kubernetes.deployment.target` and deploy them.
This assumes that a `.kube/config` is available in your user directory that points to a real kubernetes cluster.
In other words the extension will use whatever cluster `kubectl` uses. The same applies to credentials.

At the moment no additonal options are provided for further customization.

{'fraction_non_alphanumeric': 0.09208945833095007, 'fraction_numerical': 0.0028217887852961926, 'mean_word_length': 1.3678389237506208, 'pattern_counts': {'":': 0, '<': 127, '<?xml version=': 0, '>': 126, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 8}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 324, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '115349', 'n_tokens_mistral': 13364, 'n_tokens_neox': 12334, 'n_words': 3285}