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 git@github.com: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.
|
-
Create a PushApplication CR as this example.
The app name and description need to be specified into the PushApplication CR as follows.
apiVersion: push.aerogear.org/v1alpha1 kind: PushApplication metadata: name: example-pushapplication spec: description: 'An example push application to demonstrate the unifiedpush-operator'
-
Run the following command to create the PushApplication into the Service
$ make example-pushapplication/apply
ℹ️You can delete it by running make example-pushapplication/delete
After creating the PushApplication above, you should be able to get
the pushApplicationId from the status, this will be needed to be
able to create Variants:
kubectl get pushApplication example-pushapplication -n unifiedpush-apps -o jsonpath='{.status.pushApplicationId}'Here are all of the configurable fields in an AndroidVariant:
| Field Name | Description |
|---|---|
pushApplicationId |
ID of the PushApplication that this variant corresponds to |
description |
Human friendly description for the variant |
senderId |
The "Google Project Number from the API Console |
serverKey |
The key from the Firebase Console of a project which has been enabled for FCM |
-
Apply an AndroidVariantCR based on the example a AndroidVariant CR as follows:
kubectl apply -n unifiedpush-apps -f ./deploy/crds/examples/push_v1alpha1_androidvariant_cr.yamlAfter creating the PushApplication above, you should be able to get the pushApplicationId from the status, this will be needed to be able to create Variants:
kubectl get PushApplication example-pushapplication -n unifiedpush-apps -o jsonpath='{.status.pushApplicationId}'Here are all of the configurable fields in an IOSVariant:
| Field Name | Description |
|---|---|
pushApplicationId |
ID of the PushApplication that this variant corresponds to |
description |
Human friendly description for the variant |
certificate |
The base64 encoded APNs certificate that is needed to establish a connection to Apple’s APNs Push Servers |
passphrase |
The APNs passphrase that is needed to establish a connection to Apple’s APNs Push Servers |
production |
If |
-
Apply an AndroidVariantCR based on the example a IOSVariant CR as follows:
kubectl apply -n unifiedpush-apps -f ./deploy/crds/examples/push_v1alpha1_iosvariant_cr.yaml
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 |
|---|---|
backups |
A list of backup entries that CronJobs will be created from. See
|
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
The operator uses 3 image streams and what image streams to use are configurable with environment variables.
Unified Push Server and Oauth proxy image stream are created within the same namespace by the operator.
However, for Postgres the image stream in openshift namespace is used.
The following table shows the available environment variable names, along with their default values:
| Name | Default | Purpose |
|---|---|---|
|
|
Name of the Unified Push image stream that will be created by the operator. |
|
|
Tag of the Unified Push image stream that will be created by the operator. |
|
|
Initial image for the Unified Push image stream that will be created by the operator. |
|
|
Name of the Oauth proxy image stream that will be created by the operator. |
|
|
Tag of the Oauth proxy image stream that will be created by the operator. |
|
|
Initial image for the Oauth proxy image stream that will be created by the operator. |
|
|
Namespace to look for the Postgres image stream. |
|
|
Name of the Postgres image stream to look for. |
|
|
Tag of the Postgres image stream. |
|
🔥
|
Re-deploying this operator with customized images will cause all instances owned by the operator to be updated. |
If you would like to modify the container names, you can use the following environment variables.
| Name | Default |
|---|---|
|
|
|
|
|
|
The BACKUP_IMAGE environment variable configures what image to use for backing up
the custom resources created by this operator. Default value is quay.io/integreatly/backup-container:1.0.8.
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 Grafana dashboard.
It is required that the integr8ly/Grafana and Prometheus operators are installed. For further detail see integr8ly/application-monitoring-operator.
The following command enables the monitoring service in the operator namespace:
make monitoring/install|
❗
|
The namespaces are setup manually in the files ServiceMonitor, Prometheus Rules, Operator Service, and Grafana Dashboard. Following an example from the Prometheus Rules. You should replace them if the operator is not installed in the default namespace. |
expr: |
(1-absent(kube_pod_status_ready{condition="true", namespace="mobile-security-service"})) or sum(kube_pod_status_ready{condition="true", namespace="mobile-security-service"}) != 3
[source,shell]|
ℹ️
|
The command make monitoring/uninstall will uninstall the Monitor Service.
|
-
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"
-
If you want to be able to work with resources that require the local instance of your operator to be able to talk to the UPS instance in the cluster, then you’ll need to make a corresponding domain name available locally. Something like the following should work, by adding an entry to /etc/hosts for the example Service that’s created, then forwarding the port from the relevant Pod in the cluster to the local machine. Run this in a separate terminal, and ctrl+c to clean it up when finished:
# su/sudo is needed to be able to: # - modify /etc/hosts # - bind to port :80 KUBECONFIG=$HOME/.kube/config su -c "echo '127.0.0.1 example-unifiedpushserver-unifiedpush' >> /etc/hosts && kubectl port-forward $(kubectl get po -l service=ups -o name) 80:8080 && sed -i -e 's/^127.0.0.1 example-unifiedpushserver-unifiedpush$//g' -e '/^[[:space:]]*$/d' /etc/hosts"
-
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.
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 |
|
Installs Monitoring Service in order to provide metrics |
|
Uninstalls Monitoring Service in order to provide metrics, i.e. all configuration applied by |
|
Applies the Example PushApplication CR ` |
|
Delete the Example PushApplication CR ` |
|
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. Also, it is using ImageStream which is from the OpenShift API specifically. 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.