Skip to content

Commit

Permalink
Add documentation about the Minikube extension
Browse files Browse the repository at this point in the history
Follows up on quarkusio#8840
  • Loading branch information
geoand committed May 25, 2020
1 parent c02657d commit 89e2e25
Showing 1 changed file with 54 additions and 0 deletions.
54 changes: 54 additions & 0 deletions docs/src/main/asciidoc/deploying-to-kubernetes.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -388,6 +388,47 @@ 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.
Expand Down Expand Up @@ -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 extension 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

Expand Down

0 comments on commit 89e2e25

Please sign in to comment.