wildfly-operator

README

image:https://github.com/wildfly/wildfly-operator/actions/workflows/go.yml/badge.svg?branch=master["Go",link="https://github.com/wildfly/wildfly-operator/actions/workflows/go.yml"]
image:https://quay.io/repository/wildfly/wildfly-operator/status?token=c568da69-fcdb-4b58-8821-5e98f6522290["Docker Repository on Quay", link="https://quay.io/repository/wildfly/wildfly-operator"]
image:https://goreportcard.com/badge/github.com/wildfly/wildfly-operator["Go Report Card", link="https://goreportcard.com/report/github.com/wildfly/wildfly-operator"]
image:https://img.shields.io/badge/zulip-join_chat-brightgreen.svg["Join Chat", link="https://wildfly.zulipchat.com/"]

# WildFly Operator for Kubernetes/OpenShift

The WildFly Operator for Kubernetes provides easy monitoring and configuration for Java applications deployed on http://wildfly.org[WildFly application server] using the https://github.com/wildfly/wildfly-s2i[Source-to-Image (S2I) template for WildFly].

Once installed, the WildFly Operator provides the following features:

* Create/Destroy: Easily launch an application deployed on WildFly

* Simple Configuration: Configure the fundamentals of WildFly-based application including number of nodes, application image, etc.

## Custom Resource Definitions

The operator acts on the following Custom Resource Definitions (CRDs):

* `WildFlyServer`, which defines a WildFly deployment. The `Spec` and `Status` of this resources are defined in the https://github.com/wildfly/wildfly-operator/blob/master/doc/apis.adoc[API documentation].

## Quickstart

### Install the Operator and associate resources:

The examples require that https://kubernetes.io/docs/setup/minikube/[Minikube] is installed and running.

[source,shell]
----
# install WildFlyServer CRD
$ kubectl apply -f deploy/crds/wildfly.org_wildflyservers_crd.yaml
# Install all resources for the WildFly Operator
$ kubectl apply -f deploy/operator.yaml
----

### Install a custom resource

An example of a custom resource of `WildFlyServer` is described in https://github.com/wildfly/wildfly-operator/blob/master/deploy/crds/quickstart-cr.yaml[quickstart-cr.yaml]:

[source,yaml]
----
apiVersion: wildfly.org/v1alpha1
kind: WildFlyServer
metadata:
  name: quickstart
spec:
  applicationImage: "quay.io/wildfly-quickstarts/wildfly-operator-quickstart:18.0"
  replicas: 2
  storage:
    volumeClaimTemplate:
      spec:
        resources:
          requests:
            storage: 3Gi
----

[NOTE]
=====
It is based on the S2I application image https://quay.io/repository/wildfly-quickstarts/wildfly-operator-quickstart[jmesnil/wildfly-operator-quickstart:18.0] that provides a simple Java Web application https://github.com/jmesnil/wildfly-operator-quickstart[wildfly-operator-quickstart] on top of WildFly 18.0.0.Final which returns the IP address of its host:

[source,shell]
----
$ curl http://localhost:8080/
{"ip":"172.17.0.3"}
----

This simple application illustrates that successive calls will be load balanced across the various pods that runs the application.
=====

[source,shell]
----
$ kubectl create -f deploy/crds/quickstart-cr.yaml
wildflyserver.wildfly.org/quickstart created
----

Once the application is deployed, it can be accessed through a load balancer:

[source,shell]
----
$ curl $(minikube service quickstart-loadbalancer --url)
{"ip":"172.17.0.7"}
$ curl $(minikube service quickstart-loadbalancer --url)
{"ip":"172.17.0.8"}
$ curl $(minikube service quickstart-loadbalancer --url)
{"ip":"172.17.0.7"}
----

As illustrated above, calls to the application are load balanced across the pods that runs the application image (as we can see from the different IP addresses).

The WildFly operator describes the deployed application with `$ kubectl describe wildflyserver quickstart`:

[source,yaml]
----
Name:         quickstart
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  wildfly.org/v1alpha1
Kind:         WildFlyServer
Metadata:
  Creation Timestamp:  2019-04-09T08:49:24Z
  Generation:          1
  Resource Version:    7954
  Self Link:           /apis/wildfly.org/v1alpha1/namespaces/default/wildflyservers/quickstart
  UID:                 5feb0fd3-5aa4-11e9-af00-7a65e1e4ff53
Spec:
  Application Image:  quay.io/wildfly-quickstarts/wildfly-operator-quickstart:18.0
  Bootable Jar:       false
  Replicas:           2
  Storage:
    Volume Claim Template:
      Spec:
        Resources:
          Requests:
            Storage:  3Gi
Status:
  Pods:
    Name:    quickstart-0
    Pod IP:  172.17.0.7
    Name:    quickstart-1
    Pod IP:  172.17.0.8
Events:      <none>
----

The `Status` section is updated with the 2 pods names containing the application image.

You can modify this custom resource spec to scale up its replicas from `2` to `3`:

[source,shell]
----
$ kubectl edit wildflyserver quickstart
# Change the `replicas: 2` spec to `replicas: 3` and save

wildflyserver.wildfly.org/quickstart edited
----

The deployment will be updated to scale up to 3 Pods and the resource `Status` will be updated accordingly:

[source,shell]
----
$ kubectl describe wildflyserver quickstart
----

[source,yaml]
----
Name:         quickstart
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  wildfly.org/v1alpha1
Kind:         WildFlyServer
Metadata:
  Creation Timestamp:  2019-04-09T08:49:24Z
  Generation:          2
  Resource Version:    8137
  Self Link:           /apis/wildfly.org/v1alpha1/namespaces/default/wildflyservers/quickstart
  UID:                 5feb0fd3-5aa4-11e9-af00-7a65e1e4ff53
Spec:
  Application Image:  quay.io/wildfly-quickstarts/wildfly-operator-quickstart:18.0
  Bootable Jar:       false
  Replicas:           3
  Storage:
    Volume Claim Template:
      Spec:
        Resources:
          Requests:
            Storage:  3Gi
Status:
  Pods:
    Name:    quickstart-0
    Pod IP:  172.17.0.7
    Name:    quickstart-1
    Pod IP:  172.17.0.8
    Name:    quickstart-2
    Pod IP:  172.17.0.9
Events:      <none>
----

You can then remove this custom resource and its assocated resources:

[source,shell]
----
$ kubectl delete wildflyserver quickstart

wildflyserver.wildfly.org "quickstart" deleted
----

#### OpenShift

The examples can also be installed in OpenShift and requires a few additional steps.

The instructions requires that https://github.com/minishift/minishift[Minishift] is installed and running.

Deploying the operator and its resources by executing the following commands:

[source,shell]
----
$ oc login -u system:admin
$ oc adm policy add-cluster-role-to-user cluster-admin developer
$ oc apply -f deploy/crds/wildfly_v1alpha1_wildflyserver_crd.yaml
$ oc apply -f deploy/operator.yaml

$ oc login -u developer
----

After installing the `WildFlyServer` resource from `deploy/crds/quickstart-cr.yaml`, you have to create a route to expose it from OpenShift:

[source,shell]
----
$ oc expose svc/quickstart-loadbalancer

route.route.openshift.io/quickstart-loadbalancer exposed
----

This will expose the service from OpenShift. To know the URL of the exposed service, run:

[source,shell]
----
$ oc get route quickstart-loadbalancer --template='{{ .spec.host }}'
----

This will display the host of the route (on my local machine, it displays `quickstart-loadbalancer-myproject.192.168.64.16.nip.io`).

The application can then be accessed by running:

[source,shell]
----
$ curl "http://$(oc get route quickstart-loadbalancer --template='{{ .spec.host }}')"
{"ip":"172.17.0.9"}
----

# Developer Instructions

## System Requirements

* https://github.com/golang/go[go] with `$GOPATH` set to `$HOME/go`
* https://github.com/golang/dep#installation[dep]
* Docker
* Either https://github.com/minishift/minishift[Minishift] or https://kubernetes.io/docs/setup/minikube/[Minikube]    

### Building the WildFly Operator

1. Add the source under `$GOPATH`:
+  
```
$ git clone https://github.com/wildfly/wildfly-operator.git $GOPATH/src/github.com/wildfly/wildfly-operator
```
2. Change to the source directory.
+
```
$ cd $GOPATH/src/github.com/wildfly/wildfly-operator
```
3. Review the available build targets.
+
```
$ make
```
4. Run any build target. For example, compile and build the WildFly Operator with:
+
```
$ make build
```

### Run end-to-end (e2e) tests

The tests relies on Minikube as the container platform

````
$ eval $(minikube -p minikube docker-env) && make test-e2e-minikube
````