app-metrics-operator

README

:toc:
:toc-placement!:

// gEmoji for admonitions, see
// https://gist.github.com/dcode/0cfbf2699a1fe9b46ff04c41721dda74#admonitions
ifdef::env-github[]
:status:
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:table-caption!:
:warning-caption: :warning:
endif::[]

// Links (alphabetical order)
:apache_license: http://www.apache.org/licenses/LICENSE-2.0[Apache License, Version 2.0]
:application_monitoring_operator: https://github.com/integr8ly/application-monitoring-operator[application-monitoring-operator]
:export_policy: https://aerogear.org/legal/export.html[AeroGear Export Policy]
:aerogear_freenode: irc://irc.freenode.net/aerogear[#aerogear on FreeNode IRC]
:aerogear_jira: https://issues.jboss.org/projects/AEROGEAR/issues[AeroGear on JBoss Jira]
:aerogear_matrix: https://matrix.to/#/!IipcvbGVqkiTUQauSC:matrix.org[#aerogear:matrix.org on Matrix]
:mailing_list: https://groups.google.com/forum/#!forum/aerogear[Google Groups Mailing List]
:minishift: https://github.com/minishift/minishift[Minishift]
:rh_product_security: https://access.redhat.com/security/team/contact[Red Hat Product Security team]

= App Metrics Operator

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

== Overview

The App Metrics Operator for Kubernetes provides an easy way to
install and manage AeroGear App Metrics Service on Kubernetes.

toc::[]

== Prerequisites

|===
|https://golang.org/doc/install[Install Go]
|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/app-metrics-operator.git $GOPATH/src/github.com/aerogear/app-metrics-operator
----

=== Minishift installation and setup

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

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

NOTE: The above steps are not required in OCP > 4 since the OLM and Operators came installed by default.

=== Installation

As a user with admin permissions, you can install the
app-metrics-operator and a sample CR in your OpenShift cluster as follows:

[source,shell]
----
make cluster/prepare
make install
----

== Configuration

=== Image Streams

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

App Metrics image stream is 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:


.Environment Variables
|===
|Name |Default |Purpose

|`APP_METRICS_IMAGE_STREAM_NAME`
|`app-metrics-imagestream`
| Name of the App Metrics image stream that will be created by the operator.

|`APP_METRICS_IMAGE_STREAM_TAG`
|`latest`
| Tag of the App Metrics image stream that will be created by the operator.

|`APP_METRICS_IMAGE_STREAM_INITIAL_IMAGE`
|`docker.io/aerogear/aerogear-app-metrics:0.0.13`
| Initial image for the App Metrics image stream that will be created by the operator.

|`POSTGRES_IMAGE_STREAM_NAMESPACE`
|`openshift`
| Namespace to look for the Postgres image stream.

|`POSTGRES_IMAGE_STREAM_NAME`
|`postgresql`
| Name of the Postgres image stream to look for.

|`POSTGRES_IMAGE_STREAM_TAG`
|`10`
| Tag of the Postgres image stream.

|===

CAUTION: 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.

.Environment Variables
|===
|Name |Default

|`APP_METRICS_CONTAINER_NAME`
|`appmetrics`

|`POSTGRES_CONTAINER_NAME`
|`postgresql`

|===


=== Backups

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

=== Monitoring Service (Metrics)

The application-monitoring stack provisioned by the
{application_monitoring_operator} on https://github.com/integr8ly[Integr8ly]
can be used to gather metrics from this operator and the AppMetrics 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 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 command enables the monitoring service in the operator namespace:

[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="app-metrics"})) or sum(kube_pod_status_ready{condition="true", namespace="app-metrics"}) < 3

[source,shell]
----

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

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

=== AppMetricsService

This is the main installation resource kind. Creation of a valid
AppMetricsService CR will result in a functional App Metrics Service
deployed to your namespace.

`AppMetricsService` has no fields that are configurable.

An example AppMetricsService resource is available at
`./deploy/crds/metrics_v1alpha1_appmetricsservice_cr.yaml`:

.metrics_v1alpha1_appmetricsservice_cr.yaml
[source,yaml]
----
apiVersion: metrics.aerogear.org/v1alpha1
kind: AppMetricsService
metadata:
  name: example-appmetricsservice
----

To create this, you can run:

[source,shell]
----
kubectl apply -n app-metrics -f ./deploy/crds/metrics_v1alpha1_appmetricsservice_cr.yaml
----

To see the created instance then, you can run:

----
kubectl get appmetricsservice example-appmetricsservice -n app-metrics -o yaml
----

=== AppMetricsConfig

This is the service consumption resource kind. Creation of a valid
AppMetricsConfig CR will write the client config to
a config map in the CR namespace.

`AppMetricsConfig` has no fields that are configurable.

An example AppMetricsConfig resource is available at
`./deploy/crds/metrics_v1alpha1_appmetricsconfig_cr.yaml`:

.metrics_v1alpha1_appmetricsconfig_cr.yaml
[source,yaml]
----
apiVersion: metrics.aerogear.org/v1alpha1
kind: AppMetricsConfig
metadata:
  name: example-app
----

To create this, you can run:

[source,shell]
----
kubectl apply -n app-metrics -f ./deploy/crds/metrics_v1alpha1_appmetricsconfig_cr.yaml
----


To see the created instance then, you can run:

[source,shell]
----
kubectl get appmetricsconfig example-app -n app-metrics -o yaml
----


The config map created will have the name pattern `<cr-app-name>-metrics`. For the example above,
you can run the following command to get the config map.

[source,shell]
----
kubectl get configmap example-app-metrics -n app-metrics -o yaml
----

It will have content similar to this:

[source,shell]
----
apiVersion: v1
data:
  SDKConfig: >-
    {"url":
    "https://example-appmetricsservice-appmetrics-app-metrics.openshift.cluster.hostname"}
kind: ConfigMap
----

== 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:

[source,shell]
----
make cluster/prepare
----

2. Run the operator (locally, not in OpenShift):

[source,shell]
----
make code/run
----

3. Create an App Metrics Service instance (in another terminal):

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

4. Watch the status of your App Metrics Service instance provisioning (optional):

[source,shell]
----
watch -n1 "kubectl get po -n app-metrics && echo '' && kubectl get appmetricsservice -o yaml -n app-metrics"
----

5. 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 App Metrics 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:

6. Create an App Metrics Config instance:

----
make example-app/apply
----

7. Watch the status of your App Metrics Config (optional):

[source,shell]
----
watch -n1 "kubectl get po -n app-metrics && echo '' && kubectl get appmetricsconfig -o yaml -n app-metrics"
----

8. Check the config map created:

[source,shell]
----
kubectl get configmap -n app-metrics example-app-metrics -o yaml
----

9. When finished, clean up:

[source,shell]
----
make cluster/clean
----

== Publishing images

Images are automatically built and pushed to our https://quay.io/repository/aerogear/app-metrics-operator[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.

== 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.
. Update any tag references in all SOP files (e.g `https://github.com/aerogear/app-metrics-operator/blob/0.1.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 Jenkins, 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/app-metrics-operator[unifiedpush-operator image hosting repository] by the Jenkins.

== 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 which will be created by this project.

=== CI/CD

==== CircleCI

* Coveralls
* Unit Tests

NOTE: See the link:./circleci/config.yml[config.yml].

==== Jenkins

* Integration Tests
* Build of images

NOTE: See the link:./Jenkinsfile[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 example-app/apply`  | Create an Example App Metrics Config instance
| `make cluster/prepare`                | It will apply all less the operator.yaml.
| `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`
|===

=== 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 https://golang.org/cmd/vet/[vet].
| `make code/fix`                       | Formats code using https://golang.org/cmd/gofmt/[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
|===

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

== Supportability
// https://issues.jboss.org/browse/AEROGEAR-9162
This operator was developed using the Kubernetes and Openshift APIs.

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.
Also, it is using https://docs.openshift.com/enterprise/3.0/architecture/core_concepts/builds_and_image_streams.html[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.

== Security Response

If you've found a security issue that you'd like to disclose confidentially please contact the {rh_product_security}.

== Legal

The UnifiedPush Operator is licensed under the {apache_license}
License, and is subject to the {export_policy}.

== 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].