mobile-security-service-operator

README

ifdef::env-github[]
:status:
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
:table-caption!:
:namespace: mobile-security-service
endif::[]

:toc:
:toc-placement!:

= Mobile Security Service Operator

ifdef::status[]
.*Project health*
image:https://circleci.com/gh/aerogear/mobile-security-service-operator.svg?style=svg[Build Status (CircleCI), link=https://circleci.com/gh/aerogear/mobile-security-service-operator]
image:https://img.shields.io/:license-Apache2-blue.svg[License (License), link=http://www.apache.org/licenses/LICENSE-2.0]
image:https://coveralls.io/repos/github/aerogear/mobile-security-service-operator/badge.svg?branch=master[Coverage Status (Coveralls), link=https://coveralls.io/github/aerogear/mobile-security-service-operator?branch=master]
image:https://goreportcard.com/badge/github.com/aerogear/mobile-security-service-operator[Go Report Card (Go Report Card), link=https://goreportcard.com/report/github.com/aerogear/mobile-security-service-operator]
endif::[]

:toc:
toc::[]

== Overview

An https://commons.openshift.org/sig/OpenshiftOperators.html[Operator] based on the https://github.com/operator-framework/operator-sdk[Operator SDK] to run the https://github.com/aerogear/mobile-security-service[Mobile Security Service] protected by https://github.com/openshift/oauth-proxy[OAuth] on a OpenShift cluster.

image::https://user-images.githubusercontent.com/7708031/55628052-9ad02d00-57a7-11e9-8a53-f1d5c845358a.png[Create Server,align="center"]

== Prerequisites

|===
|https://golang.org/doc/install[Install Golang]
|https://github.com/golang/go/wiki/SettingGOPATH[Ensure the $GOPATH environment variable is set]
|https://golang.github.io/dep/docs/installation.html[Install the dep package manager]
|https://github.com/operator-framework/operator-sdk#quick-start[Install Operator-SDK]
|https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl[Install kubectl]
|===

== Getting Started

=== Cloning the repository

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

[source,shell]
----
$ git clone git@github.com:aerogear/mobile-security-service-operator.git $GOPATH/src/github.com/aerogear/mobile-security-service-operator
----

=== Minishift installation and setup

https://docs.okd.io/latest/minishift/getting-started/installing.html[Install Minishift] then enable Operators on it by running the following commands.

[source,shell]
----
# create a new profile to test the operator
$ minishift profile set mss-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
----

=== Installing

Use the following command to install the Operator, Service and its Database.

NOTE: 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`.

[source,shell]
----
$ make install
----

To verify that the pods has been successful created you can run the following command.

[source,shell]
----
# Go to the project namespace. E.g mobile-security-service
$ oc project mobile-security-service

# Check the pods which are deployed
$ oc get pods
NAME                                                READY     STATUS    RESTARTS   AGE
mobile-security-service-569d4f8d86-vp5hq            1/1       Running   2          1h
mobile-security-service-db-ccb5856f6-8qnvc          1/1       Running   0          1h
mobile-security-service-operator-785cbdbf46-wq2lf   1/1       Running   0          1h

----

To verify that the installation was successful completed you can check the `AppStatus=` status field of link:./deploy/crds/mobile-security-service_v1alpha1_mobilesecurityservice_cr.yaml[Service CR] and the `DatabaseStatus=OK` status field of link:./deploy/crds/mobile-security-service_v1alpha1_mobilesecurityservicedb_cr.yaml[Database CR] in the cluster. For both are expected this status fields be added with the value "OK" when all installation process is finished and are all created successfully as the following example.

[source,shell]
----
# To check the Service CR
$ oc describe mobilesecurityservices
...
  Route Name:                        route
  Size:                              1
Status:
  App Status:       OK
  Config Map Name:  mobile-security-service-config
  Deployment Name:  mobile-security-service
...

# To check the Database CR
$ oc describe mobilesecurityservicedbs
...
  Size:                      1
Status:
  Database Status:  OK
  Deployment Name:  mobile-security-service-db
  Deployment Status:
...
----

NOTE: To troubleshooting the installation if it does not complete successfully check the status of its CRs. Note that all objects which are managed by them has an respective status field on it. E.g `Deployment Status`

=== Creating/Binding an app

* Create a link:./deploy/crds/examples/mobile-security-service_v1alpha1_mobilesecurityserviceapp_cr.yaml[MobileSecurityServiceApp CR] as this example.
+
* The app name and appId need to be specified into the link:./deploy/crds/examples/mobile-security-service_v1alpha1_mobilesecurityserviceapp_cr.yaml[MobileSecurityServiceApp CR] as follows.
+
[source,shell]
----
  # The appName spec defines the name of the app used to bind the service
  appName: "app"
  # The appId spec defines the appId of the app used to bind the service
  appId: "appid"
----
+
* Run the following command to bind the app to the Mobile Security Service
+
[source,shell]
----
$ make example-app/apply
----

NOTE: This command will execute `kubectl apply -f deploy/crds/examples/mobile-security-service_v1alpha1_mobilesecurityserviceapp_cr.yaml` and apply the link:./deploy/crds/examples/mobile-security-service_v1alpha1_mobilesecurityserviceapp_cr.yaml[MobileSecurityServiceApp CR] example.

=== Deleting/Unbinding an app

* Run the following command to delete/unbind the app from the service.
+
[source,shell]
----
$ make example-app/delete
----

IMPORTANT: This command will execute `kubectl delete -f deploy/crds/examples/mobile-security-service_v1alpha1_mobilesecurityserviceapp_cr.yaml` and delete the link:./deploy/crds/examples/mobile-security-service_v1alpha1_mobilesecurityserviceapp_cr.yaml[MobileSecurityServiceApp CR] example.

NOTE: The Rest Service endpoint to delete it is called in the finalizer of the link:./deploy/crds/examples/mobile-security-service_v1alpha1_mobilesecurityserviceapp_cr.yaml[MobileSecurityServiceApp CR] and the CR will be just allowed to be removed when the app is no longer available in its Service.

=== Uninstalling

Use the following command to delete the Operator, the Service and its Database and all related configuration applied by the `install` of this project.

[source,shell]
----
$ make uninstall
----

NOTE: 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 and Options

=== Customizing the Service

The Mobile Security Service image and its parameters are configurable and specified by the link:./deploy/crds/mobile-security-service_v1alpha1_mobilesecurityservice_cr.yaml[MobileSecurityService CR].

NOTE: Default values are applied by the operator in link:./mobile-security-service-operator/pkg/controller/mobilesecurityservice/mandatory_specs.go[mandatory_specs.go] are applied for the mandatory specifications which are not made in the link:./deploy/crds/mobile-security-service_v1alpha1_mobilesecurityservice_cr.yaml[MobileSecurityService CR].

=== Customizing the Database

The database image and its parameters are configurable and specified by the link:./deploy/crds/mobile-security-service_v1alpha1_mobilesecurityservicedb_cr.yaml[MobileSecurityServiceDB CR].

NOTE: Default values are applied by the operator in link:./mobile-security-service-operator/pkg/controller/mobilesecurityservicedb/mandatory_specs.go[mandatory_specs.go] are applied for the mandatory specifications which are not made in the link:./deploy/crds/mobile-security-service_v1alpha1_mobilesecurityserviceddb_cr.yaml[MobileSecurityServiceDB CR].

=== Changing the operator namespace

By using the command `make install` the default namespace `mobile-security-service`,  defined in the link:./Makefile[Makefile] will be created and the operator will be installed in this namespace. You are able to install the operator in another namespace if you wish, however, you need to set up its roles (RBAC) in order to apply them on the namespace where the operator will be installed. The namespace name needs to be changed in the link:./deploy/cluster_role_binding.yaml[Cluster Role Binding] file. Note, that you also need to change the namespace in the link:./Makefile[Makefile] in order to use the command `make install` for another namespace. 

[source,yaml]
----
  # Replace this with the namespace where the operator will be deployed.
  namespace: mobile-security-service
----

=== Managing valid namespaces to apply the MobileSecurityServiceApp

Only namespaces specified in the environment variable `APP_NAMESPACES` can be used to apply Apps. If the link:./deploy/crds/examples/mobile-security-service_v1alpha1_mobilesecurityserviceapp_cr.yaml[MobileSecurityServiceApp CR] is applied to a namespace that is not specified in `APP_NAMESPACES` it will be ignored. Refer to configuration in the link:./deploy/operator.yaml[operator.yaml] file.

IMPORTANT: The values should be split by `;`. E.g `mobile-security-service-apps;example-namespace-apps`

NOTE: To run the project locally export the ENV VAR. E.g. `export APP_NAMESPACES=mobile-security-service-apps`

=== Changing the Environment Variables values

Environment Variables are used to configure the https://github.com/aerogear/mobile-security-service[Mobile Security Service] Application and Database. For further information on configuration see the https://github.com/aerogear/mobile-security-service#setup-and-configurations[Setup and Configuration] section.

=== Monitoring Service (Metrics)

The application-monitoring stack provisioned by the
https://github.com/integr8ly/application-monitoring-operator[application-monitoring-operator] on https://github.com/integr8ly[Integr8ly]
can be used to gather metrics from this operator and the mobile security service. 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 https://github.com/integr8ly/grafana-operator[integr8ly/Grafana] and https://github.com/coreos/prometheus-operator[Prometheus] operators are installed. For further detail see https://github.com/integr8ly/application-monitoring-operator[integr8ly/application-monitoring-operator].

The following commands will enable the monitoring service where the operator has been installed in the default namespace with the make commands.

[source,shell]
----
make monitoring/install
----

IMPORTANT: The namespaces are setup manually in the files link:./deploy/monitor/service_monitor.yaml[ServiceMonitor], link:./deploy/monitor/prometheus_rule.yaml[Prometheus Rules], link:./deploy/monitor/operator-service.yaml[Operator Service], and link:./deploy/monitor/grafana-dashboard[Grafana Dashboard]. Following an example from the link:./deploy/monitor/prometheus_rule.yaml[Prometheus Rules]. You should replace them if the operator is not installed in the default namespace.

[source,yaml]
----
  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]
----

NOTE: The command `make monitoring/uninstall` will uninstall the Monitor Service.

=== Configuring the Backup Service

==== Backup

===== Install
The backup service is implemented by using  https://github.com/integr8ly/backup-container-image[integr8ly/backup-container-image]. It will do the backup of the database and the APP CRs which are data required to be restore in the case of failures. Following the steps to enable it.

. Setup the AWS in order to store the backup outside of the cluster. You need to add your AWS details to link:./mobile-security-service-operator/deploy/crds/mobile-security-service_v1alpha1_mobilesecurityservicebackup_cr.yaml[MobileSecurityServiceBackup] as follows or add the name of the secret which has already this data in the cluster.
+
[source,yaml]
----
  # ---------------------------------
  # Stored Host - AWS
  # ----------------------------

  awsS3BucketName: "example-awsS3BucketName"
  awsAccessKeyId: "example-awsAccessKeyId"
  awsSecretAccessKey: "example-awsSecretAccessKey"
----
+
IMPORTANT: Also, you can add the name of the secret which is created already in the cluster.
+
. Run the command `make backup/install` in the same namespace where the MobileSecurityService Database is installed in order to apply the CronJob which will do this process.
+
. Add the label `integreatly-middleware-service=true` in all namespaces defined in the ENV VAR APP_NAMESPACES in the link:./deploy/operator.yaml[operator.yaml]. (E.g  oc label ns/mobile-security-service-apps integreatly-middleware-service=true`). It will backup all link:./deploy/crds/examples/mobile-security-service_v1alpha1_mobilesecurityserviceapp_cr.yaml[MobileSecurityServiceApp CR] applied on them.

NOTE: 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`.

===== Verifying

To verify that the backup has been successful created you can run the following command in the namespace where the operator is installed.

[source,shell]
----
$ oc get cronjob.batch/mobile-security-service-backup
NAME                             SCHEDULE      SUSPEND   ACTIVE    LAST SCHEDULE   AGE
mobile-security-service-backup   0 * * * *   False     0         13s             12m
----

To check the jobs executed you can run the command `oc get jobs` in the namespace where the operator is installed as the following example.

[source,shell]
----
$ oc get jobs
NAME                                        DESIRED   SUCCESSFUL   AGE
mobile-security-service-backup-1561588320   1         0            6m
mobile-security-service-backup-1561588380   1         0            5m
mobile-security-service-backup-1561588440   1         0            4m
mobile-security-service-backup-1561588500   1         0            3m
mobile-security-service-backup-1561588560   1         0            2m
mobile-security-service-backup-1561588620   1         0            1m
mobile-security-service-backup-1561588680   1         0            43s
----

NOTE: In the above example the schedule was made to run this job each minute (`*/1 * * * *`)

To check the logs and troubleshooting you can run the command `oc logs $podName -f` in the namespace where the operator is installed as the following example.

[source,shell]
----
 $ oc logs job.batch/mobile-security-service-backup-1561589040 -f
dumping mobile_security_service
dumping postgres
==> Component data dump completed
/tmp/intly/archives/mobile-security-service.mobile_security_service-22_46_06.pg_dump.gz
WARNING: mobile-security-service.mobile_security_service-22_46_06.pg_dump.gz: Owner username not known. Storing UID=1001 instead.
upload: '/tmp/intly/archives/mobile-security-service.mobile_security_service-22_46_06.pg_dump.gz' -> 's3://camilabkp/backups/mss/postgres/2019/06/26/mobile-security-service.mobile_security_service-22_46_06.pg_dump.gz'  [1 of 1]
 1213 of 1213   100% in    1s   955.54 B/s  done
ERROR: S3 error: 403 (RequestTimeTooSkewed): The difference between the request time and the current time is too large.
----

==== Restore

Following the steps required to be performed in case of be required do the restore based in the backup service.

. Install the Mobile Security Service by following the steps in <<Installing>>.
. Restore the database with the dump which was stored in the AWS S3 bucket.
+
NOTE: To restore we should run `gunzip -c filename.gz | psql dbname`
+
. It is required re-apply all APP CRs which has an backup in the AWS bucket as well.

== Architecture

This operator is `cluster-scoped`. For further information see the https://github.com/operator-framework/operator-sdk/blob/master/doc/user-guide.md#operator-scope[Operator Scope] section in the Operator Framework documentation. Also, check its roles in link:./deploy/[Deploy] directory.

NOTE: The operator, application and database will be installed in the namespace `{namespace}` which will be created by this project.

=== CRD Definitions

|===
| *CustomResourceDefinition*    | *Description*
| link:./deploy/crds/mobile-security-service_v1alpha1_mobilesecurityservice_crd.yaml[MobileSecurityService]             | Packages, manages, installs and configures the https://github.com/aerogear/mobile-security-service[Mobile Security Service] on the cluster.
| link:./deploy/crds/mobile-security-service_v1alpha1_mobilesecurityservicedb_crd.yaml[MobileSecurityServiceDB]             | Packages, manages, installs and configures the https://github.com/aerogear/mobile-security-service[Mobile Security Service] Database on the cluster.
| link:./deploy/crds/mobile-security-service_v1alpha1_mobilesecurityserviceapp_crd.yaml[MobileSecurityServiceApp]             | Creates and update the app in the REST API.
| link:./deploy/crds/mobile-security-service_v1alpha1_mobilesecurityservicebackup_crd.yaml[MobileSecurityServiceBackup]             | Packages, manages, installs and configures the CronJob to do the backup using the image https://github.com/integr8ly/backup-container-image[backup-container-image]
|===

=== Resources managed by each CRD Controller

* *link:./pkg/controller/mobilesecurityservice/controller.go[Mobile Security Service]*
+
|===
| *Resource*    | *Description*
| link:./pkg/controller/mobilesecurityservice/configmaps.go[configmaps.go]             | Define the ConfigMap resources required for the Mobile Security Service Application and its Database. It will create the `mobile-security-service-app` which map the values used in the Environment Variables of both.
| link:./pkg/controller/mobilesecurityservice/deployments.go[deployments.go]           | Define the Deployment resource of Mobile Security Service Application, e.g. container and resources definitions.
| link:./pkg/controller/mobilesecurityservice/route.go[route.go]                       | Define the route resource required to expose the Mobile Security Service (REST Service and UI).
| link:./pkg/controller/mobilesecurityservice/services.go[services.go]                 | Define the Service resource of Mobile Security Service Application.
|===

* *link:./pkg/controller/mobilesecurityservicedb/controller.go[Mobile Security Service Database]*
+
|===
| *Resource*    | *Description*
| link:./pkg/controller/mobilesecurityservicedb/deployments.go[deployments.go]           | Define the Deployment resource of Mobile Security Service Database. (E.g container and resources definitions)
| link:./pkg/controller/mobilesecurityservicedb/pvs.go[pvs.go]                           | Define the PersistentVolumeClaim resource used by its Database.
| link:./pkg/controller/mobilesecurityservice/services.go[services.go]                   | Define the Service resource of Mobile Security Service Database.
|===

* *link:./pkg/controller/mobilesecurityservicebackup/controller.go[Mobile Security Service Backup]*
+
|===
| *Resource*    | *Description*
| link:./pkg/controller/mobilesecurityservicebackup/cronjobs.go[cronjobs.go]           | Define the CronJob resources in order to do the Backup.
| link:./pkg/controller/mobilesecurityservicebackup/secrets.go[secrets.go]           | Define the database and AWS secrets resources created.
|===

=== Oauth Authentication

An Oauth Proxy container and the required configuration will be setup by default by the operator to provide authentication to the Mobile Security Service.

=== Design Pattern

The Design Pattern adopted to build the objects in its controllers is http://tmrts.com/go-patterns/creational/factory.html[Factory Method Pattern].

== Administration

=== Status Definition per Types

* link:./pkg/apis/mobilesecurityservice/v1alpha1/mobilesecurityservice_types.go[MobileSecurityService]
+
|===
| *Status*    | *Description*
| `appStatus` | For this status is expected the value `OK` which means that all required Kubernetes/OCP objects are created.
| `configMapName` | Name of the configMap created with the Environment Variables.
| `deploymentName` | Name of the deployment object created for the App.
| `deploymentStatus` | Deployment Status from ks8 API (https://kubernetes.io/docs/reference/federation/extensions/v1beta1/definitions/#_v1beta1_deploymentstatus[v1beta1.DeploymentStatus]).
| `serviceName` | Name of the service object created for the App.
| `serviceStatus` | Deployment Status from ks8 API (https://kubernetes.io/docs/reference/federation/v1/definitions/#_v1_servicestatus[v1.ServiceStatus]).
| `routeName` | Name of the route object created for the App.
| `routeStatus` | Route Status from OCP API (https://docs.openshift.com/container-platform/3.7/rest_api/apis-route.openshift.io/v1.Route.html#object-schema[v1.Route]).
|===

* link:./pkg/apis/mobilesecurityservice/v1alpha1/mobilesecurityservicedb_types.go[MobileSecurityServiceDB]
+
|===
| *Status*    | *Description*
| `databaseStatus` | For this status is expected the value `OK` which means that all required Kubernetes/OCP objects are created.
| `deploymentName` | Name of the deployment object created for the Database.
| `deploymentStatus` | Deployment Status from ks8 API (https://kubernetes.io/docs/reference/federation/extensions/v1beta1/definitions/#_v1beta1_deploymentstatus[v1beta1.DeploymentStatus]).
| `serviceName` | Name of the service object created for the Database.
| `serviceStatus` | Deployment Status from ks8 API (https://kubernetes.io/docs/reference/federation/v1/definitions/#_v1_servicestatus[v1.ServiceStatus]).
| `PersistentVolumeClaimName` | Name of the PersistentVolumeClaimName object created for the Database.
|===

* link:./pkg/apis/mobilesecurityservice/v1alpha1/mobilesecurityserviceapp_types.go[MobileSecurityServiceApp]
+
|===
| *Status*    | *Description*
| `bindStatus` | For this status is expected the value `OK` which means that the app was created in the API Service.
|===

* link:./pkg/apis/mobilesecurityservice/v1alpha1/mobilesecurityservicebackup_types.go[MobileSecurityServiceBackup]
+
|===
| *Status*    | *Description*
| `backupStatus` | Should show `OK` when everything is created successfully.
| `cronJobName` | Name of cronJob resource  created by it.
| `cronJobStatus` | CronJob Status from ks8 API (https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.10/#cronjobstatus-v1beta1-batch[k8s.io/api/batch/v1beta1/CronJobStatus]).
| `dbSecretName` | Name of database secret resource created in order to allow the https://github.com/integr8ly/backup-container-image[integr8ly/backup-container-image] connect to the database .
| `dbSecretData` | Data used into the secret to connect to the database .
| `awsSecretName` | Name of AWS S3 bucket secret resource used in order to allow the https://github.com/integr8ly/backup-container-image[integr8ly/backup-container-image] connect to AWS to send the backup .
| `awsSecretData` | Data used to in the secret to send the backup files to the AWS S3.
| `awsSecretDataNamespace` | Namespace where the backup image will looking for the of the Aws Secret  used.
| `encryptionKeySecretName` | Name of the EncryptionKey used.
| `encryptionKeySecretNamespace` | Namespace where the backup image will looking for the of the EncryptionKey used.
| `encryptionKeySecretData` | Data used into the EncryptionKey.
| `hasEncryptionKey` | Expected true when it was configured to use an EncryptionKey secret
| `databasePodFound` | The value expected here is true which shows that the database pod was found.
| `servicePodFound` | The value expected here is true which shows that the database service was found.
|===

== Development

=== Local Setup

Run the following command to setup this project locally.

[source,yaml]
----
$ make setup
----

=== Running the operator locally

The following command will install the operator in the cluster and run the changes performed locally without the need to publish a `dev` tag. In this way, you can verify your code in the development environment.

[source,yaml]
----
$ make code/run/local
----

IMPORTANT: The local changes are applied when the command `operator-sdk up local --namespace={namespace}` is executed then it is not a hot deploy and to get the latest changes you need re-run the command.

=== Checking Database

By the following commands you are able to connect in the Mobile Security Service Database. You can check it by OpenShift UI in the Database's pod terminal.

[source,shell]
----
# Login into the the Postgres
psql -U postgres

# To connect into the default database
\c mobile_security_service

# To list the tables
\dt

# To select all data from the app table
SELECT * FROM app;
----

=== Debugging

Follow the below steps to debug the project in some IDEs.

NOTE: The code needs to be compiled/built first.

==== IntelliJ IDEA / GoLand

[source,shell]
----
$ make setup/debug
$ cd cmd/manager/
$ dlv debug --headless --listen=:2345 --api-version=2
----

Then, debug the project from the IDE by using the default setup of `Go Remote` option.

==== Visual Code

[source,shell]
----
$ make setup/debug
$ dlv --listen=:2345 --headless=true --api-version=2 exec ./build/_output/bin/mobile-security-service-operator-local  --
----

debug the project using the following Visual Code launch config.

[source,yaml]
----
{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "test",
            "type": "go",
            "request": "launch",
            "mode": "remote",
            "remotePath": "${workspaceFolder}/cmd/manager/main.go",
            "port": 2345,
            "host": "127.0.0.1",
            "program": "${workspaceFolder}",
            "env": {},
            "args": []
        }
    ]
}
----

NOTE: The image/tag used from https://github.com/aerogear/mobile-security-service[Mobile Security Service] is defined in link:./deploy/crds/mobile-security-service_v1alpha1_mobilesecurityservice_cr.yaml[mobile-security-service_v1alpha1_mobilesecurityservice_cr.yaml] file.

== Makefile command reference

=== Application Commands

|===
| *Command*                        | *Description*
| `make install`                   | Creates the `{namespace}` namespace, application CRDS, cluster role and service account. Installs the operator and the Service and DB
| `make uninstall`                 | Uninstalls the operator and the Service and DB. Deletes the `{namespace}`` namespace, application CRDS, cluster role and service account and the app namespace. i.e. all configuration applied by `make install`
| `make example-app/apply`         | Applies the Example App CR (Create/Update app in the cluster and Service.).
| `make example-app/delete`        | Deletes the Example App CR (Delete app from the Service).
| `make refresh-operator-image`    | Deletes and applies the operator in order to refresh the image when a tag is not changed (development use)
| `make monitoring/install`        | Installs Monitoring Service in order to provide metrics
| `make monitoring/uninstall`      | Uninstalls Monitoring Service in order to provide metrics, i.e. all configuration applied by `make monitoring/install`
| `make backup/install`            | Installs the backup Service in the operator's namespace
| `make backup/uninstall`          | Uninstalls the backup Service from the operator's namespace.
|===

=== Local Development

|===
| `make code/run-local`                 | Runs the operator locally for development purposes.
| `make setup/debug`                    | Sets up environment for debugging proposes.
| `make code/vet`                       | Examines source code and reports suspicious constructs using https://golang.org/cmd/vet/[vet].
| `make code/fmt`                       | Formats code using https://golang.org/cmd/gofmt/[gofmt].
| `make code/gen`                       | It will automatically generated/update the files by using the operator-sdk based on the CR status and spec definitions.
|===

=== CI

|===
| `make test/run`                        | Runs test suite
| `make test/integration-cover`          | Run coverage check
| `make image/build/master`              | Used by CI to build operator image from `master` branch and add `:master` tag.
| `make image/push/master`               | Used by CI to push the `master` image to https://quay.io/repository/aerogear/mobile-security-service-operator[quay.io registry].
| `make image/build/release`             | Used by CI to build operator image from a tagged commit and add `:<version>` and `latest` tag.
| `make image/push/release`              | Used by CI to push the `release` and `latest` image to https://quay.io/repository/aerogear/mobile-security-service-operator[quay.io registry].
|===

=== Tests

|===
| `make test/run`                      | Runs test suite
| `make test/integration-cover`        | Run coverage check
|===

NOTE: The link:./Makefile[Makefile] is implemented with tasks which you should use to work with.

== Publishing images

Images are automatically built and pushed to our https://quay.io/repository/aerogear/mobile-security-service-operator[image repository] 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.

If the image does not get built and pushed automatically the job may be re-run manually via the https://circleci.com/gh/aerogear/mobile-security-service-operator[CI dashboard].

== Tags Release

Following the steps

* Create a new version tag following the http://semver.org/spec/v2.0.0.html[semver], for example `0.1.0`
* Bump the version in the link:./version/version.go[version.go] file.
* Update the the link:./CHANGELOG.md[CHANGELOG.md] with the new release.
* Looking for the SOPs and update the tag for the them in all files (e.g `https://github.com/aerogear/mobile-security-service-operator/blob/0.2.0/SOP/SOP-operator.adoc`)
* Create a git tag with the version value, for example:

[source,shell]
----
$ 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 CI, for example:

[source,shell]
----
$ git push upstream 0.1.0
----

NOTE: The image with the tag will be created and pushed to the https://quay.io/repository/aerogear/mobile-security-service[mobile-security-service image hosting repository] by the CI.

WARNING: Do not use letters in the tag such as `v`. It will not work.

== Supportability

This operator was developed using mainly the Kubernetes APIs in order to be compatible with both, however, currently this project requires the usage of the https://docs.openshift.com/container-platform/3.11/rest_api/apis-route.openshift.io/v1.Route.html[v1.Route] to expose the service and https://github.com/openshift/oauth-proxy[OAuth-proxy] for authentication which make it unsupportable for Kubernetes.

== Contributing

All contributions are hugely appreciated. Please see our https://aerogear.org/community/#guides[Contributing Guide] for guidelines on how to open issues and pull requests. Please check out our link:./.github/CODE_OF_CONDUCT.md[Code of Conduct] too.

== Questions

There are a number of ways you can get in in touch with us, please see the https://aerogear.org/community/#contact[AeroGear community].