UnifiedPush Operator

Project health

Table of Contents

• Overview
• Prerequisites
• Getting Started
  • Cloning the repository
  • Minishift installation and setup
  • Installing
  • Uninstalling
• Configuration
  • UnifiedPushServer Options
  • Defaults for resource sizes, limits and requests
  • Container Names
  • Monitoring Service (Metrics)
• Development
  • Running the operator
• Testing
  • Run unit tests
  • Run e2e tests
• Publishing images
• Tag Releases
• Architecture
  • CI/CD
• Makefile command reference
  • Application
  • Local Development
  • Jenkins
  • Tests / CI
• Supportability
• Security Response
• Legal
• Contributing
• Questions

Overview

The UnifiedPush Operator for Kubernetes provides an easy way to install and manage an AeroGear UnifiedPush Server on OpenShift.

Prerequisites

Install Go

Ensure the $GOPATH environment variable is set

Install the dep package manager

Install Operator-SDK

Install kubectl

Getting Started

Cloning the repository

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

$ git clone [email protected]:aerogear/unifiedpush-operator.git $GOPATH/src/github.com/aerogear/unifiedpush-operator

Minishift installation and setup

Install Minishift then install Operators on it by running the following commands.

# 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

ℹ️	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:

$ make install

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

ℹ️	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.

$ make cluster/clean

ℹ️	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.

ℹ️	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.	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.	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.	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

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 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 integr8ly/Grafana and Prometheus operators are installed. For further detail see 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.

ℹ️	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

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

make code/run

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

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

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

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

1. When finished, clean up:

make cluster/clean

Testing

Run unit tests

make test/unit

Run e2e tests

1. 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"

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

oc login <url> --token <token>

1. Prepare a new OpenShift project for testing

make NAMESPACE=$NAMESPACE cluster/prepare

1. 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 yq installed, just simply edit the image name in deploy/operator.yaml

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

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

1. Run the test

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

Publishing images

Images are automatically built and pushed to our 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

1. Create a new version tag following the semver, for example 0.1.0

2. Bump the version in the version.go file.

3. Update the the CHANGELOG.MD with the new release.

4. Update any tag references in all SOP files (e.g https://github.com/aerogear/unifiedpush-operator/blob/0.1.0/SOP/SOP-operator.adoc)

5. Create a git tag with the version value, for example:

   $ git tag -a 0.1.0 -m "version 0.1.0"

6. Push the new tag to the upstream repository, this will trigger an automated release by the Jenkins, for example:

   $ git push upstream 0.1.0

   ℹ️	The image with the tag will be created and pushed to the unifiedpush-operator image hosting repository by the Jenkins.

7. 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 Operator Scope section in the Operator Framework documentation. Also, check its roles in Deploy directory.

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

CI/CD

CircleCI

• Coveralls

• Unit Tests

ℹ️	See the config.yml.

Jenkins

• Integration Tests

• Build of images

ℹ️	See the 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 vet.
make code/fix	Formats code using 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

ℹ️	The 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 v1.Route to expose the service and 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 Red Hat Product Security team.

Legal

The UnifiedPush Operator is licensed under the Apache License, Version 2.0 License, and is subject to the AeroGear Export Policy.

Contributing

All contributions are hugely appreciated. Please see our Contributing Guide for guidelines on how to open issues and pull requests. Please check out our Code of Conduct too.

Questions

There are a number of ways you can get in in touch with us, please see the AeroGear community.