Merge pull request #9563 from geoand/k8s-doc-minikube

Add documentation about the Minikube extension

Author: gsmet

docs/src/main/asciidoc/deploying-to-kubernetes.adoc

@@ -388,12 +388,53 @@ To access the API server from within a Kubernetes cluster, some RBAC related res
 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.
 
+=== Deploying to Minikube
+
+https://github.com/kubernetes/minikube[Minikube] is quite popular when a Kubernetes cluster is needed for development purposes. To make the deployment to Minikube
+experience as frictionless as possible, Quarkus provides the `quarkus-minikube` extension. This extension can be added to a project like so:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-minikube</artifactId>
+</dependency>
+----
+
+The purpose of this extension is to generate Kubernetes manifests (`minikube.yaml` and `minikube.json`) that are tailored to Minikube.
+This extension assumes a couple things:
+
+* Users won't be using an image registry and will instead make their container image accessible to the Kubernetes cluster by building it directly
+into Minikube's Docker daemon. To use Minikube's Docker daemon you must first execute:
++
+[source]
+----
+eval $(minikube -p minikube docker-env)
+----
+
+* Applications deployed to Kubernetes won't be accessed via a Kubernetes `Ingress`, but rather as a `NodePort` `Service`.
+The advantage of doing this is that the URL of an application can be retrieved trivially by executing:
++
+[source]
+----
+minikube service list
+----
+
+To control the https://kubernetes.io/docs/concepts/services-networking/service/#nodeport[nodePort] that is used in this case, users can set `quarkus.kubernetes.node-port`.
+Note however that this configuration is entirely optional because Quarkus will automatically use a proper (and non-changing) value if none is set.
+
+WARNING: It is highly discouraged to use the manifests generated by the Minikube extension when deploying to production as these manifests are intended for development purposes
+only. When deploying to production, consider using the vanilla Kubernetes manifests (or the OpenShift ones when targeting OpenShift).
+
+NOTE: If the assumptions the Minikube extension makes don't fit your workflow, nothing prevents you from using the regular Kubernetes extension to generate Kubernetes manifests
+and apply those to your Minikube cluster.
+
 == Tuning the generated resources using application.properties
 
 The Kubernetes extension allows tuning the generated manifest, using the `application.properties` file.
 Here are some examples:
 
-== Configuration options
+=== Configuration options
 
 The table below describe all the available configuration options.
 
@@ -445,7 +486,7 @@ In this example `initial-delay` and `period` are fields of the type `Probe`.
 Below you will find tables describing all available types.
 
 
-=== Basic Types
+==== Basic Types
 
 .ServiceType
 Allowed values: `cluster-ip`, `node-port`, `load-balancer`, `external-name`
@@ -495,7 +536,7 @@ Allowed values: `cluster-ip`, `node-port`, `load-balancer`, `external-name`
 |====
 
 
-=== Mounts and Volumes
+==== Mounts and Volumes
 
 .Mount
 |====
@@ -566,7 +607,7 @@ Allowed values: `cluster-ip`, `node-port`, `load-balancer`, `external-name`
 |====
 
 [#openshift]
-== OpenShift
+=== OpenShift
 
 To enable the generation of OpenShift resources, you need to include OpenShift in the target platforms:
 
@@ -641,7 +682,7 @@ The OpenShift resources can be customized in a similar approach with Kubernetes.
 |====
 
 [#knative]
-== Knative
+=== Knative
 
 To enable the generation of Knative resources, you need to include Knative in the target platforms:
 
@@ -734,6 +775,19 @@ The generated service can be customized using the following properties:
 | quarkus.knative.sidecars                        | Map<String, Container>                    |             |
 |====
 
+=== Deployment targets
+
+Mentioned in the previous sections was the concept of `deployment-target`. This concept allows users to control which Kubernetes manifests will be generated
+and deployed to a cluster (if `quarkus.kubernetes.deploy` has been set to `true`).
+
+By default, when no `deployment-target` is set, then only vanilla Kubernetes resources are generated and deployed. When multiple values are set (for example
+`quarkus.kubernetes.deployment-target=kubernetes,openshift`) then the resources for all targets are generated, but only the resources
+that correspond to the *first* target are applied to the cluster (if deployment is enabled).
+
+In the case of wrapper extensions like OpenShift and Minikube, when these extensions have been explicitly added to the project, the default `deployment-target`
+is set by those extensions. For example if `quarkus-minikube` has been added to a project, then `minikube` becomes the default deployment target and its
+resources will be applied to the Kubernetes cluster when deployment via `quarkus.kubernetes.deploy` has been set.
+Users can still override the deployment-targets manually using `quarkus.kubernetes.deployment-target`.
 
 === Deprecated configuration
 
@@ -818,7 +872,7 @@ The name of the resource is determined by the application name and may be overri
 For example, in the `kubernetes-quickstart` application, we can add a `kubernetes.yml` file in the `src/main/kubernetes` that looks like:
 
 [source,yaml]
----
+----
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -843,12 +897,12 @@ spec:
         env:
         - name: FOO
           value: BAR
----
+----
 
 The generated `kubernetes.yml` will look like:
 
 [source,yaml]
----
+----
 apiVersion: "apps/v1"
 kind: "Deployment"
 metadata:
@@ -882,7 +936,7 @@ spec:
           name: "http"
           protocol: "TCP"
       serviceAccount: "kubernetes-quickstart"
----
+----
 
 The provided replicas <1>, labels <2> and environment variables <3>  were retained. However, the image <4> and container port <5> were modified. Moreover, the default annotations have been added.