The UnifiedPush Operator for Kubernetes provides an easy way to install and manage an AeroGear UnifiedPush Server on OpenShift.
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-operatorInstall 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. |
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.
|
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:
| Field Name | Description | Default |
|---|---|---|
backups |
A list of backup entries that CronJobs will be created from. See
|
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 |
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:
apiVersion: push.aerogear.org/v1alpha1
kind: UnifiedPushServer
metadata:
name: example-unifiedpushserverTo 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
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:
| Variable | Default value |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If you would like to modify the container names, you can use the following environment variables.
| Name | Default |
|---|---|
|
|
|
|
|
|
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. |
-
Prepare the operator project:
make cluster/prepare
-
Run the operator (locally, not in OpenShift):
make code/run
-
Create a UPS instance (in another terminal):
kubectl apply -f deploy/crds/push_v1alpha1_unifiedpushserver_cr.yaml -n unifiedpush
-
Watch the status of your UPS instance provisioning (optional):
watch -n1 "kubectl get po -n unifiedpush && echo '' && kubectl get ups -o yaml -n unifiedpush"
-
When finished, clean up:
make cluster/clean
-
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 yq installed, just simply edit the image name in 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
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
mastertag is published. -
For every change merged that has a git tag a new image with the
<operator-version>andlatesttags are published.
Following the steps
-
Create a new version tag following the semver, for example
0.1.0 -
Bump the version in the version.go file.
-
Update the the 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:
$ 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:
$ 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. -
Create a release in Github so that it is picked up by some internal processes
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. |
Command |
Description |
|
Creates the |
|
It will delete what was performed in the |
|
It will apply all less the operator.yaml. |
|
Runs the operator locally for development purposes. |
|
Sets up environment for debugging proposes. |
|
Examines source code and reports suspicious constructs using vet. |
|
Formats code using gofmt. |
|
Compile image to be used in the e2e tests |
|
Compile image to be used by Jenkins |
|
It will run the coveralls. |
|
Runs unit tests |
|
Build image with the parameters required for CircleCI |
|
ℹ️
|
The Makefile is implemented with tasks which you should use to work with. |
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.
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.
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.
There are a number of ways you can get in in touch with us, please see the AeroGear community.