Skip to content
This repository has been archived by the owner on Apr 17, 2023. It is now read-only.

Latest commit

 

History

History
502 lines (351 loc) · 15.3 KB

README.adoc

File metadata and controls

502 lines (351 loc) · 15.3 KB

UnifiedPush Operator

Overview

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

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.

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.