Add monitoring to OSDK

_topic_map.yml

@@ -119,6 +119,8 @@ Topics:
     File: osdk-ansible
   - Name: Creating Helm-based Operators
     File: osdk-helm
+  - Name: Configuring built-in monitoring with Prometheus
+    File: osdk-monitoring-prometheus
   - Name: Operator SDK CLI reference
     File: osdk-cli-reference
   - Name: Migrating to Operator SDK v0.1.0

applications/operator_sdk/osdk-getting-started.adoc

@@ -1,5 +1,5 @@
 :relfileprefix: ../
-[id='getting-started-osdk']
+[id='osdk-getting-started']
 = Getting started with the Operator SDK
 include::modules/common-attributes.adoc[]
 :context: osdk-getting-started
@@ -14,7 +14,9 @@ accomplished using two centerpieces of the Operator Framework: the Operator SDK
 (the `operator-sdk` CLI tool and `controller-runtime` library API) and the
 Operator Lifecycle Manager (OLM).
 
-include::modules/osdk-operator-sdk.adoc[leveloffset=+1]
+include::modules/osdk-architecture.adoc[leveloffset=+1]
+include::modules/osdk-monitoring-prometheus-operator-support.adoc[leveloffset=+2]
+
 include::modules/osdk-installing-cli.adoc[leveloffset=+1]
 include::modules/building-memcached-operator-using-osdk.adoc[leveloffset=+1]
 include::modules/managing-memcached-operator-using-olm.adoc[leveloffset=+1]

applications/operator_sdk/osdk-migrating-to-v0-1-0.adoc

@@ -18,7 +18,7 @@ The recommended method for migrating your project is to:
 . Modify the new project as described for v0.1.0.
 
 This guide uses the `memcached-operator`, the example project
-from xref:osdk-getting-started.adoc#getting-started-osdk[Getting started with the Operator SDK],
+from xref:osdk-getting-started.adoc#osdk-getting-started[Getting started with the Operator SDK],
 to illustrate the migration steps. See the
 link:https://github.com/operator-framework/operator-sdk-samples/tree/aa15bd278eec0959595e0a0a7282a26055d7f9d6/memcached-operator[v0.0.7 memcached-operator]
 and

applications/operator_sdk/osdk-monitoring-prometheus.adoc

@@ -0,0 +1,15 @@
+:relfileprefix: ../
+[id='osdk-monitoring-prometheus']
+= Configuring built-in monitoring with Prometheus
+include::modules/common-attributes.adoc[]
+:context: osdk-monitoring-prometheus
+
+toc::[]
+
+include::modules/osdk-monitoring-prometheus-operator-support.adoc[leveloffset=+1]
+
+include::modules/osdk-monitoring-prometheus-metrics-helper.adoc[leveloffset=+1]
+include::modules/osdk-monitoring-prometheus-metrics-helper-modifying-port.adoc[leveloffset=+2]
+
+include::modules/osdk-monitoring-prometheus-servicemonitor.adoc[leveloffset=+1]
+include::modules/osdk-monitoring-prometheus-servicemonitor-creating.adoc[leveloffset=+2]

modules/osdk-operator-sdk.adoc → modules/osdk-architecture.adoc

@@ -2,7 +2,7 @@
 //
 // * applications/operator_sdk/osdk-getting-started.adoc
 
-[id='osdk-operator-sdk-{context}']
+[id='osdk-architecture-{context}']
 = Architecture of the Operator SDK
 
 The link:https://coreos.com/operators/[Operator Framework] is an open source
@@ -24,8 +24,8 @@ providing:
 - Tools for scaffolding and code generation to quickly bootstrap a new project
 - Extensions to cover common Operator use cases
 
-[discrete]
-=== Operator SDK workflow
+[id='osdk-architecture-workflow-{context}']
+== Workflow
 
 The SDK provides the following workflow to develop a new Operator:
 
@@ -42,12 +42,12 @@ At a high level, an Operator using the SDK processes events for watched
 resources in a user-defined handler and takes actions to reconcile the state of
 the application.
 
-[discrete]
-=== Manager
+[id='osdk-architecture-manager-{context}']
+== Manager file
 
-The main program for the Operator is the manager `cmd/manager/main.go` file. The
-manager automatically registers the scheme for all Custom Resources (CRs) defined
-under `pkg/apis/` and runs all controllers under `pkg/controller/`.
+The main program for the Operator is the manager file at `cmd/manager/main.go`.
+The manager automatically registers the scheme for all Custom Resources (CRs)
+defined under `pkg/apis/` and runs all controllers under `pkg/controller/`.
 
 The manager can restrict the namespace that all controllers watch for resources:
 

modules/osdk-monitoring-prometheus-metrics-helper-modifying-port.adoc

@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+//
+// * applications/operator_sdk/osdk-monitoring-prometheus.adoc
+
+[id='osdk-monitoring-prometheus-metrics-helper-modifying-port-{context}']
+= Modifying metrics port
+
+Operator authors can modify the port that metrics are exposed on.
+
+.Prerequisites
+
+- Go-based Operator generated using the Operator SDK
+- Kubernetes-based cluster with the Prometheus Operator deployed
+
+.Procedure
+
+. In the generated Operator's `cmd/manager/main.go` file, change the `var
+metricsPort int32 = 8383` variable.

modules/osdk-monitoring-prometheus-metrics-helper.adoc

@@ -0,0 +1,53 @@
+// Module included in the following assemblies:
+//
+// * applications/operator_sdk/osdk-monitoring-prometheus.adoc
+
+[id='osdk-monitoring-prometheus-metrics-helper-{context}']
+= Metrics helper
+
+In Go-based Operators generated using the Operator SDK, the following helper
+function exposes general metrics about the running program:
+
+[source,go]
+----
+func ExposeMetricsPort(ctx context.Context, port int32) (*v1.Service, error)
+----
+
+These metrics are inherited from the `controller-runtime` library API. The
+metrics are by default served on `:8383/metrics`.
+
+A Service object is created with the metrics port exposed, which can be then
+accessed by Prometheus. The Service object is garbage collected when the leader
+Pod's root owner is deleted.
+
+The following example is present in the `cmd/manager/main.go` file in all
+Operators generated using the Operator SDK:
+
+[source,go]
+----
+    import(
+     "github.com/operator-framework/operator-sdk/pkg/metrics"
+	"sigs.k8s.io/controller-runtime/pkg/manager"
+    )
+
+    // Change the below variables to serve metrics on different host or port.
+    var metricsHost = "0.0.0.0" <1>
+    var metricsPort int32 = 8383 <2>
+
+    // Pass metrics address to controller-runtime manager
+	mgr, err := manager.New(cfg, manager.Options{
+		Namespace:          namespace,
+		MetricsBindAddress: fmt.Sprintf("%s:%d", metricsHost, metricsPort),
+	})
+
+    ...
+
+	// Create Service object to expose the metrics port.
+	_, err = metrics.ExposeMetricsPort(ctx, metricsPort)
+	if err != nil {
+        // handle error
+		log.Info(err.Error())
+	}
+----
+<1> Host the metrics are exposed on.
+<2> Port the metrics are exposed on.

modules/osdk-monitoring-prometheus-operator-support.adoc

@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+// * applications/operator_sdk/osdk-getting-started.adoc
+// * applications/operator_sdk/osdk-monitoring-prometheus.adoc
+
+[id='osdk-monitoring-prometheus-operator-support-{context}']
+= Prometheus Operator support in the Operator SDK
+
+link:https://prometheus.io/[Prometheus] is an open-source systems monitoring and
+alerting toolkit. The Prometheus Operator creates, configures, and manages
+Prometheus clusters running on Kubernetes-based clusters, such as
+{product-title}.
+
+Helper functions exist in the Operator SDK by default to automatically set up
+metrics in any generated Go-based Operator for use on clusters where the
+Prometheus Operator is deployed.

modules/osdk-monitoring-prometheus-servicemonitor-creating.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//
+// * applications/operator_sdk/osdk-monitoring-prometheus.adoc
+
+[id='osdk-monitoring-prometheus-servicemonitor-creating-{context}']
+= Creating ServiceMonitor resources
+
+Operator authors can add Service target discovery of created monitoring Services
+using the `metrics.CreateServiceMonitor()` helper function, which accepts the
+newly created Service.
+
+.Prerequisites
+
+- Go-based Operator generated using the Operator SDK
+- Kubernetes-based cluster with the Prometheus Operator deployed
+
+.Procedure
+
+. Add the `metrics.CreateServiceMonitor()` helper function to your Operator code,
+creating only one `ServiceMonitor` per application and namespace:
++
+[source,go]
+----
+    import "github.com/operator-framework/operator-sdk/pkg/metrics"
+
+    serviceMonitors, err := metrics.CreateServiceMonitors(config *rest.Config, ns string, services []*v1.Service) <1>
+    if err != nil {
+        <2>
+    }
+----
+<1> Pass the Service(s) to the helper function, which in turn returns the ServiceMonitor object.
+<2> Handle errors here.

modules/osdk-monitoring-prometheus-servicemonitor.adoc

@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// * applications/operator_sdk/osdk-monitoring-prometheus.adoc
+
+[id='osdk-monitoring-prometheus-servicemonitor-{context}']
+= ServiceMonitor resources
+
+A ServiceMonitor is a Custom Resource Definition (CRD) provided by the
+Prometheus Operator that discovers the `Endpoints` in Service objects and
+configures Prometheus to monitor those Pods.
+
+In Go-based Operators generated using the Operator SDK, the
+`GenerateServiceMonitor()` helper function can take a Service object and
+generate a ServiceMonitor Custom Resource (CR) based on it.
+
+.Additional resources
+
+- See the
+link:https://github.com/coreos/prometheus-operator/blob/7a25bf6b6bb2347dacb235659b73bc210117acc7/Documentation/design.md#servicemonitor[Prometheus Operator documentation]
+for more about the ServiceMonitor CRD.