unifiedpush-operator

:toc:
:toc-placement!:

// gEmoji for admonitions, see
// https://gist.github.com/dcode/0cfbf2699a1fe9b46ff04c41721dda74#admonitions
ifdef::env-github[]
:status:
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:table-caption!:
:warning-caption: :warning:
endif::[]

// Links (alphabetical order)
:apache_license: http://www.apache.org/licenses/LICENSE-2.0[Apache License, Version 2.0]
:application_monitoring_operator: https://github.com/integr8ly/application-monitoring-operator[application-monitoring-operator]
:code_of_conduct: link:CODE_OF_CONDUCT.md[Contributor Code of Conduct]
:export_policy: https://aerogear.org/legal/export.html[AeroGear Export Policy]
:aerogear_freenode: irc://irc.freenode.net/aerogear[#aerogear on FreeNode IRC]
:aerogear_jira: https://issues.jboss.org/projects/AEROGEAR/issues[AeroGear on JBoss Jira]
:aerogear_matrix: https://matrix.to/#/!IipcvbGVqkiTUQauSC:matrix.org[#aerogear:matrix.org on Matrix]
:mailing_list: https://groups.google.com/forum/#!forum/aerogear[Google Groups Mailing List]
:minishift: https://github.com/minishift/minishift[Minishift]
:rh_product_security: https://access.redhat.com/security/team/contact[Red Hat Product Security team]

= UnifiedPush Operator

ifdef::status[]
.*Project health*
image:https://circleci.com/gh/aerogear/unifiedpush-operator.svg?style=svg[Build Status (CircleCI), link=https://circleci.com/gh/aerogear/unifiedpush-operator]
image:https://img.shields.io/:license-Apache2-blue.svg[License (License), link=http://www.apache.org/licenses/LICENSE-2.0]
image:https://coveralls.io/repos/github/aerogear/unifiedpush-operator/badge.svg?branch=master[Coverage Status (Coveralls), link=https://coveralls.io/github/aerogear/unifiedpush-operator?branch=master]
image:https://goreportcard.com/badge/github.com/aerogear/unifiedpush-operator[Go Report Card (Go Report Card), link=https://goreportcard.com/report/github.com/aerogear/unifiedpush-operator]
endif::[]

toc::[]

== Overview

The UnifiedPush Operator for Kubernetes provides an easy way to install and manage an https://aerogear.org/docs/unifiedpush/[AeroGear UnifiedPush] Server on OpenShift.

== Prerequisites

|===
|https://golang.org/doc/install[Install Go]
|https://github.com/golang/go/wiki/SettingGOPATH[Ensure the $GOPATH environment variable is set]
|https://golang.github.io/dep/docs/installation.html[Install the dep package manager]
|https://github.com/operator-framework/operator-sdk#quick-start[Install Operator-SDK]
|https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl[Install kubectl]
|===

== Getting Started

=== Cloning the repository

By the following commands you will create a local directory and clone this project.

[source,shell]
----
$ git clone git@github.com:aerogear/unifiedpush-operator.git $GOPATH/src/github.com/aerogear/unifiedpush-operator
----

=== Minishift installation and setup

https://docs.okd.io/latest/minishift/getting-started/installing.html[Install Minishift] then install Operators on it by running the following commands.

[source,shell]
----
# create a new profile to test the operator
$ minishift profile set unifiedpush-operator

# enable the admin-user add-on
$ minishift addon enable admin-user

# add insecure registry to download the images from docker
$ minishift config set insecure-registry 172.30.0.0/16

# start the instance
$ minishift start
----

NOTE: The above steps are not required in OCP > 4 since the OLM and Operators came installed by default.

=== Installing

Use the following command to install the UnifiedPush Operator and Service in your OpenShift cluster as follows:

[source,shell]
----
$ make install
----

IMPORTANT: It will install an example configuration setup for your Push Server. To know how to configure it see <<UnifiedPushServer Options>>

NOTE: To install you need be logged in as a user with cluster privileges like the `system:admin` user. E.g. By using: `oc login -u system:admin`.

=== Uninstalling

Use the following command to delete all related configuration applied by the `make install` of this project.

[source,shell]
----
$ make cluster/clean
----

NOTE: To uninstall you need be logged in as a user with cluster privileges like the `system:admin` user. E.g. By using: `oc login -u system:admin`.

== Configuration

=== UnifiedPushServer Options

This is the main installation resource kind. Creation of a valid
UnifiedPushServer CR will result in a functional AeroGear
UnifiedPushServer deployed to your namespace.

[NOTE]
====
This operator currently only supports one UnifiedPushServer CR to be
created.
====

Here are all of the configurable fields in a UnifiedPushServer:

.UnifiedPushServer fields
|===
|Field Name |Description |Default

|backups
|A list of backup entries that CronJobs will be created from. See
 `./deploy/crds/push_v1alpha1_unifiedpushserver_cr_with_backup.yaml`
 for an annotated example. Note that a ServiceAccount called
 "backupjob" must already exist before the operator will create any
 backup CronJobs. See
 https://github.com/integr8ly/backup-container-image/tree/master/templates/openshift/rbac
 for an example.
| No backups

|useMessageBroker
|Can be set to true to use managed queues, if you are using enmasse.
|false

|unifiedPushResourceRequirements
|Unified Push Service container resource requirements.
a|
[source,yaml]
----
limits:
    memory: "<value of UPS_MEMORY_LIMIT passed to operator>"
    cpu: "<value of UPS_CPU_LIMIT passed to operator>"
requests:
    memory: "<value of UPS_MEMORY_REQUEST passed to operator>"
    cpu: "<value of UPS_CPU_REQUEST passed to operator>"
----

|oAuthResourceRequirements
|OAuth Proxy container resource requirements.
a|
[source,yaml]
----
limits:
    memory: "<value of OAUTH_MEMORY_LIMIT passed to operator>"
    cpu: "<value of OAUTH_CPU_LIMIT passed to operator>"
requests:
    memory: "<value of OAUTH_MEMORY_REQUEST passed to operator>"
    cpu: "<value of OAUTH_CPU_REQUEST passed to operator>"
----

|postgresResourceRequirements
|Postgres container resource requirements.
a|
[source,yaml]
----
limits:
    memory: "<value of POSTGRES_MEMORY_LIMIT passed to operator>"
    cpu: "<value of POSTGRES_CPU_LIMIT passed to operator>"
requests:
    memory: "<value of POSTGRES_MEMORY_REQUEST passed to operator>"
    cpu: "<value of POSTGRES_CPU_REQUEST passed to operator>"
----


|postgresPVCSize
|PVC size for Postgres service
|Value of `POSTGRES_PVC_SIZE` environment variable passed to operator

|===

The most basic UnifiedPushServer CR doesn't specify anything in the
Spec section, so the example in
`./deploy/crds/push_v1alpha1_unifiedpushserver_cr.yaml` is a good
template:

.push_v1alpha1_unifiedpushserver_cr.yaml
[source,yaml]
----
apiVersion: push.aerogear.org/v1alpha1
kind: UnifiedPushServer
metadata:
  name: example-unifiedpushserver
----

To create this, you can run:

....
kubectl apply -n unifiedpush -f ./deploy/crds/push_v1alpha1_unifiedpushserver_cr.yaml
....

To see the created instance then, you can run:

....
kubectl get ups example-unifiedpushserver -n unifiedpush -o yaml
....

=== Defaults for resource sizes, limits and requests

As described in the section above, it is possible to define memory, cpu and volume limits and requests in the UnifiedPushServer CR.

However, operator will use some defaults that are passed to operator as environment variables, if no value is specified in the CR.
If no environment variable is also passed to operator, operator will use some hardcoded values.

Here are these variables:

.Defaults for resource sizes, limits and requests
|===
|Variable |Default value


|`UPS_MEMORY_LIMIT`
|`2Gi`

|`UPS_MEMORY_REQUEST`
|`512Mi`

|`UPS_CPU_LIMIT`
|`1`

|`UPS_CPU_REQUEST`
|`500m`


|`OAUTH_MEMORY_LIMIT`
|`64Mi`

|`OAUTH_MEMORY_REQUEST`
|`32Mi`

|`OAUTH_CPU_LIMIT`
|`20m`

|`OAUTH_CPU_REQUEST`
|`10m`


|`POSTGRES_MEMORY_LIMIT`
|`512Mi`

|`POSTGRES_MEMORY_REQUEST`
|`256Mi`

|`POSTGRES_CPU_LIMIT`
|`1`

|`POSTGRES_CPU_REQUEST`
|`250m`

|`POSTGRES_PVC_SIZE`
|`5Gi`

|===

=== Container Names

If you would like to modify the container names, you can use the following environment variables.

.Environment Variables
|===
|Name |Default

|`UPS_CONTAINER_NAME`
|`ups`

|`OAUTH_PROXY_CONTAINER_NAME`
|`ups-oauth-proxy`

|`POSTGRES_CONTAINER_NAME`
|`postgresql`

|===

=== Monitoring Service (Metrics)

The application-monitoring stack provisioned by the
{application_monitoring_operator} on https://github.com/integr8ly[Integr8ly]
can be used to gather metrics from this operator and the UnifiedPush Server. These metrics can be used by Integr8ly's application monitoring to generate Prometheus metrics, AlertManager alerts and a dashboard in Grafana.

It is required that the https://github.com/integr8ly/grafana-operator[integr8ly/Grafana] and https://github.com/coreos/prometheus-operator[Prometheus] operators are installed. For further detail see https://github.com/integr8ly/application-monitoring-operator[integr8ly/application-monitoring-operator].

The operator will install it's own monitoring resrouces required by Grafana and Prometheus on startup and will install the Resources required for monitoring the UnifiedPush Server on creation of the UnifiedPushServer CR.

NOTE: These will be ignored if the required CRDs are not installed on the cluster. Restart the operator to install the resources if the application-monitoring stack is deployed afterwards.

== Development

=== Running the operator

1. Prepare the operator project:

....
make cluster/prepare
....

2. Run the operator (locally, not in OpenShift):

....
make code/run
....

3. Create a UPS instance (in another terminal):

....
kubectl apply -f deploy/crds/push_v1alpha1_unifiedpushserver_cr.yaml -n unifiedpush
....

4. Watch the status of your UPS instance provisioning (optional):

....
watch -n1 "kubectl get po -n unifiedpush && echo '' && kubectl get ups -o yaml -n unifiedpush"
....

6. When finished, clean up:

....
make cluster/clean
....

== Testing

=== Run unit tests

....
make test/unit
....

=== Run e2e tests

. Export env vars used in commands below

....
export NAMESPACE="<name-of-your-openshift-project-used-for-testing>"
export IMAGE="quay.io/<your-account-name>/unifiedpush-operator"
....

. Login to OpenShift cluster as a user with cluster-admin role

....
oc login <url> --token <token>
....

. Prepare a new OpenShift project for testing

....
make NAMESPACE=$NAMESPACE cluster/prepare
....

. Modify the operator image name in manifest file

....
yq w -i deploy/operator.yaml spec.template.spec.containers[0].image $IMAGE
....

Note: If you do not have link:https://mikefarah.github.io/yq/[yq] installed, just simply edit the image name in link:deploy/operator.yaml[deploy/operator.yaml]

. Build & push the operator container image to your Dockerhub/Quay image repository, e.g.

....
operator-sdk build $IMAGE --enable-tests && docker push $IMAGE
....

. Run the test

....
operator-sdk test cluster $IMAGE --namespace $NAMESPACE --service-account unifiedpush-operator
....

== Publishing images

Images are automatically built and pushed to our https://quay.io/repository/aerogear/unifiedpush-operator[image repository] by the Jenkins in the following cases:

- For every change merged to master a new image with the `master` tag is published.
- For every change merged that has a git tag a new image with the `<operator-version>` and `latest` tags are published.

== Tag Releases

Following the steps

. Create a new version tag following the http://semver.org/spec/v2.0.0.html[semver], for example `0.1.0`
. Bump the version in the link:./version/version.go[version.go] file.
. Update the the link:./CHANGELOG.MD[CHANGELOG.MD] with the new release.
. Update any tag references in all SOP files (e.g `https://github.com/aerogear/unifiedpush-operator/blob/0.1.0/SOP/SOP-operator.adoc`)
. Create a git tag with the version value, for example:
+
[source,shell]
----
$ git tag -a 0.1.0 -m "version 0.1.0"
----
+
. Push the new tag to the upstream repository, this will trigger an automated release by the Jenkins, for example:
+
[source,shell]
----
$ git push upstream 0.1.0
----
+
NOTE: The image with the tag will be created and pushed to the https://quay.io/repository/aerogear/unifiedpush-operator[unifiedpush-operator image hosting repository] by the Jenkins.

. Create a release in Github so that it is picked up by some internal processes

== Architecture

This operator is `cluster-scoped`. For further information see the https://github.com/operator-framework/operator-sdk/blob/master/doc/user-guide.md#operator-scope[Operator Scope] section in the Operator Framework documentation. Also, check its roles in link:./deploy/[Deploy] directory.

NOTE: The operator, application and database will be installed in the namespace which will be created by this project.

=== CI/CD

==== CircleCI

* Coveralls
* Unit Tests

NOTE: See the link:./circleci/config.yml[config.yml].

==== Jenkins

* Integration Tests
* Build of images

NOTE: See the link:./Jenkinsfile[Jenkinsfile].

== Makefile command reference

=== Application

|===
| *Command*                        | *Description*
| `make install`                   | Creates the `{namespace}` namespace, application CRDS, cluster role and service account.
| `make cluster/clean`                  | It will delete what was performed in the `make cluster/prepare` .
| `make cluster/prepare`                | It will apply all less the operator.yaml.
|===


=== Local Development

|===
| `make code/run`                       | Runs the operator locally for development purposes.
| `make code/gen`                       | Sets up environment for debugging proposes.
| `make code/vet`                       | Examines source code and reports suspicious constructs using https://golang.org/cmd/vet/[vet].
| `make code/fix`                       | Formats code using https://golang.org/cmd/gofmt/[gofmt].
|===

=== Jenkins

|===
| `make test/compile`                      | Compile image to be used in the e2e tests
| `make code/compile`                      | Compile image to be used by Jenkins
|===

===  Tests / CI

|===
| `make test/integration-cover`          | It will run the coveralls.
| `make test/unit`                       | Runs unit tests
| `make code/build/linux`                | Build image with the parameters required for CircleCI
|===

NOTE: The link:./Makefile[Makefile] is implemented with tasks which you should use to work with.

== Supportability

This operator was developed using the Kubernetes and Openshift APIs.

Currently this project requires the usage of the https://docs.openshift.com/container-platform/3.11/rest_api/apis-route.openshift.io/v1.Route.html[v1.Route] to expose the service and https://github.com/openshift/oauth-proxy[OAuth-proxy] for authentication which make it unsupportable for Kubernetes.
In this way, this project is not compatible with Kubernetes, however, in future we aim to make it work on vanilla Kubernetes also.

== Security Response

If you've found a security issue that you'd like to disclose confidentially please contact the {rh_product_security}.

== Legal

The UnifiedPush Operator is licensed under the {apache_license}
License, and is subject to the {export_policy}.

== Contributing

All contributions are hugely appreciated. Please see our https://aerogear.org/community/#guides[Contributing Guide] for guidelines on how to open issues and pull requests. Please check out our link:./.github/CODE_OF_CONDUCT.md[Code of Conduct] too.

== Questions

There are a number of ways you can get in in touch with us, please see the https://aerogear.org/community/#contact[AeroGear community].