Mobile Developer Console Operator

Project health

The Mobile Developer Console Operator for Kubernetes provides an easy way to install and manage an AeroGear Mobile Developer Console on Kubernetes.

Table of Contents

• Limitations
• Cloning the repository
• Minishift Pre-requisites
• Remote cluster Prerequisities
• Installing the Operator
• Provisioning a Mobile Developer Console instance
• Configuration
  • OpenShift Host
  • Image Streams
  • Container Names
• Custom Resources (aka How to get value from this operator)
  • MobileDeveloperConsole
• Monitoring Service (Metrics)
• Getting help
• Development
  • Prerequisites
  • Running the operator
• Security Response
• Legal

Limitations

ℹ️	This operator currently only works on OpenShift. This is because it provisions `Route`s and also relies on the fact that OpenShift provides an OAuth server. In future we aim to make it work on vanilla Kubernetes also.

Cloning the repository

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

$ git clone git@github.com:aerogear/mobile-developer-console-operator.git $GOPATH/src/github.com/aerogear/mobile-developer-console-operator

Minishift Pre-requisites

1. Enable CORS addon on Minishift

Follow these steps in order to enable CORS on Minishift.

if minishift addons list | grep cors ; then
    minishift addons apply cors
else
    MINISHIFT_ADDONS_PATH=/tmp/minishift-addons
    rm -rf $MINISHIFT_ADDONS_PATH && git clone https://github.com/minishift/minishift-addons.git $MINISHIFT_ADDONS_PATH
    # Not needed after https://github.com/minishift/minishift-addons/pull/187 is merged
    cd $MINISHIFT_ADDONS_PATH
    git fetch origin pull/187/head:cors-fix && git checkout cors-fix
    minishift addons install /tmp/minishift-addons/add-ons/cors
    minishift addons apply cors
fi

1. Export required OPENSHIFT_HOST variable

export OPENSHIFT_HOST=$(minishift ip):8443

Remote cluster Prerequisities

If you are using a remote cluster, you should check OpenShift configuration guide on how to update the CORS configurations.

Installing the Operator

As a user with admin permissions, you can install the mobile-developer-console-operator in your OpenShift cluster as follows:

make cluster/prepare install-operator

Provisioning a Mobile Developer Console instance

make install-mdc

Once the mobiledeveloperconsole CR is created with the make install-mdc above, the operator will provision a Mobile Developer Console instance.

However, an OAuthClient needs to be created with the Mobile Developer Console URL.

OAUTH_CLIENT_ID=$(oc get -n mobile-developer-console -f deploy/crds/mdc_v1alpha1_mobiledeveloperconsole_cr.yaml --template "{{.spec.oAuthClientId}}")
OAUTH_CLIENT_SECRET=$(oc get -n mobile-developer-console -f deploy/crds/mdc_v1alpha1_mobiledeveloperconsole_cr.yaml --template "{{.spec.oAuthClientSecret}}")
MDC_ROUTE=$(oc -n mobile-developer-console get route example-mdc-mdc-proxy --template "{{.spec.host}}")

cat <<EOF | oc apply -f -
apiVersion: v1
grantMethod: auto
kind: OAuthClient
metadata:
  name: ${OAUTH_CLIENT_ID}
secret: ${OAUTH_CLIENT_SECRET}
redirectURIs: ["https://${MDC_ROUTE}"]
EOF

oc rollout latest example-mdc

Configuration

OpenShift Host

Although it is clear for the person managing/deploying the Mobile Developer Console operator, it is not clear for the operator itself to get the public hostname of the OpenShift cluster. This hostname is required by the operator. It will then be passed to provisioned Mobile Developer Console instances. Mobile Developer Console uses this public hostname in its web UI to make calls to OpenShift REST API. Thus the value given in the environment variable must be public and accessible by potential users' browsers. Instructions at the top of the document for enabling CORS in OpenShift is also because of the same reasons.

Table 1. Environment Variables

Name	Default	Purpose
OPENSHIFT_HOST	None - it is required	Public hostname of the OpenShift cluster
UPS_DOCUMENTATION_URL	https://docs.aerogear.org/limited-availability/upstream/ups.html	Link to documentation for Unified Push service.
IDM_DOCUMENTATION_URL	https://docs.aerogear.org/limited-availability/upstream/idm.html	Link to documentation for Identity Management service.
SYNC_DOCUMENTATION_URL	https://docs.aerogear.org/limited-availability/upstream/sync.html	Link to documentation for Data Sync service.
MSS_DOCUMENTATION_URL	https://docs.aerogear.org/limited-availability/upstream/mss.html	Link to documentation for Mobile Security Service.

Image Streams

The operator uses 2 image streams and what image streams to use are configurable with environment variables.

Mobile Developer Console and OAuth proxy image stream are created within the same namespace by the operator.

The following table shows the available environment variable names, along with their default values:

Table 2. Environment Variables

Name	Default	Purpose
MDC_IMAGE_STREAM_NAME	mdc-imagestream	Name of the Mobile Developer Console image stream that will be created by the operator.
MDC_IMAGE_STREAM_TAG	latest	Tag of the Mobile Developer Console image stream that will be created by the operator.
MDC_IMAGE_STREAM_INITIAL_IMAGE	quay.io/aerogear/mobile-developer-console:latest	Initial image for the Mobile Developer Console image stream that will be created by the operator.
OAUTH_PROXY_IMAGE_STREAM_NAME	mdc-oauth-proxy-imagestream	Name of the OAuth proxy image stream that will be created by the operator.
OAUTH_PROXY_IMAGE_STREAM_TAG	latest	Tag of the OAuth proxy image stream that will be created by the operator.
OAUTH_PROXY_IMAGE_STREAM_INITIAL_IMAGE	docker.io/openshift/oauth-proxy:v1.1.0	Initial image for the OAuth proxy image stream that will be created by the operator.

🔥	Re-deploying this operator with customized images will cause all instances owned by the operator to be updated.

Container Names

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

Table 3. Environment Variables

Name	Default
MDC_CONTAINER_NAME	mdc
OAUTH_PROXY_CONTAINER_NAME	mdc-oauth-proxy

Custom Resources (aka How to get value from this operator)

MobileDeveloperConsole

This is the main installation resource kind. Creation of a valid MobileDeveloperConsole CR will result in a functional Mobile Developer Console deployed to your namespace.

Here are all of the configurable fields in a MobileDeveloperConsole:

Table 4. MobileDeveloperConsole fields

Field Name	Description
oAuthClientId	Id of the OAuthClient to use when protecting the Mobile Developer Console instance with OpenShift OAuth Proxy.
oAuthClientSecret	Password of the OAuthClient to use when protecting the Mobile Developer Console instance with OpenShift OAuth Proxy.

An example MobileDeveloperConsole resource is available at ./deploy/crds/mdc_v1alpha1_mobiledeveloperconsole_cr.yaml:

mdc_v1alpha1_mobiledeveloperconsole_cr.yaml

apiVersion: mdc.aerogear.org/v1alpha1
kind: MobileDeveloperConsole
metadata:
  name: example-mdc
spec:
  oAuthClientId: mobile-developer-console
  oAuthClientSecret: foobar

To create this, you can run:

kubectl apply -n mobile-developer-console -f ./deploy/crds/mdc_v1alpha1_mobiledeveloperconsole_cr.yaml

To see the created instance then, you can run:

kubectl get mdc example-mdc -n mobile-developer-console -o yaml

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 mobile developer console. These metrics can be used to generate alerts in AlertManager and a dashboard in Grafana.

It is required that the grafana-operator and {prometheus_operator are installed. For further details see application-monitoring-operator.

The following commands will add the monitoring resources to the mobile-developer-console where the operator has been installed:

make monitoring/install

❗	The namespace name is hard-coded in the prometheus_rule.yaml and grafana-dashboard.yaml. The following is an example from the prometheus_rule.yaml. You should replace them if the operator is not installed in the mobile-developer-console namespace.

  expr: |
          (1-absent(kube_pod_status_ready{condition="true", namespace="mobile-developer-console"})) or sum(kube_pod_status_ready{condition="true", namespace="mobile-developer-console"}) != 3

[source,shell]

ℹ️	The command make monitoring/uninstall will remove the monitoring resources.

Getting help

All AeroGear projects use the same communication channels.

Issue tracker

Our main issue tracker is AeroGear on JBoss Jira. Issues may also be created here on GitHub for individual projects.

Chat

For synchronous real-time chat, we use Matrix/IRC. These are bridged together, so you can choose which is more convenient for you: #aerogear:matrix.org on Matrix or #aerogear on FreeNode IRC.

Discussion list

For important conversations, we discuss asynchronously on this Google Groups Mailing List. This is great for discussions that should involve many people in different time zones, and allows us to easily link back to conversations in future.

Development

Prerequisites

• Access to an OpenShift cluster with admin privileges to be able to create Roles. Minishift is suggested.

• Go, Make, dep, operator-sdk, kubectl (kubectl can just be a symlink to oc)

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 Mobile Developer Console instance (in another terminal):

make install-mdc

1. Watch the status of your Mobile Developer Console instance provisioning (optional):

watch -n1 "kubectl get po -n mobile-developer-console && echo '' && kubectl get mdc -o yaml -n mobile-developer-console"

1. 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 MDC 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:

2. When finished, clean up:

make cluster/clean

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 Mobile Developer Console Operator is licensed under the Apache License, Version 2.0 License, and is subject to the AeroGear Export Policy.