From 784ff29b5a084240efb0bb85f8bb370b2ad911a5 Mon Sep 17 00:00:00 2001 From: Alex Dellapenta Date: Tue, 19 Feb 2019 11:19:00 -0500 Subject: [PATCH] Add monitoring to OSDK --- _topic_map.yml | 2 + .../operator_sdk/osdk-getting-started.adoc | 6 ++- .../osdk-migrating-to-v0-1-0.adoc | 2 +- .../osdk-monitoring-prometheus.adoc | 15 ++++++ ...erator-sdk.adoc => osdk-architecture.adoc} | 16 +++--- ...metheus-metrics-helper-modifying-port.adoc | 18 +++++++ ...-monitoring-prometheus-metrics-helper.adoc | 53 +++++++++++++++++++ ...onitoring-prometheus-operator-support.adoc | 16 ++++++ ...ng-prometheus-servicemonitor-creating.adoc | 32 +++++++++++ ...-monitoring-prometheus-servicemonitor.adoc | 20 +++++++ 10 files changed, 169 insertions(+), 11 deletions(-) create mode 100644 applications/operator_sdk/osdk-monitoring-prometheus.adoc rename modules/{osdk-operator-sdk.adoc => osdk-architecture.adoc} (85%) create mode 100644 modules/osdk-monitoring-prometheus-metrics-helper-modifying-port.adoc create mode 100644 modules/osdk-monitoring-prometheus-metrics-helper.adoc create mode 100644 modules/osdk-monitoring-prometheus-operator-support.adoc create mode 100644 modules/osdk-monitoring-prometheus-servicemonitor-creating.adoc create mode 100644 modules/osdk-monitoring-prometheus-servicemonitor.adoc diff --git a/_topic_map.yml b/_topic_map.yml index 484f6b86aff7..3568d42f573f 100644 --- a/_topic_map.yml +++ b/_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 diff --git a/applications/operator_sdk/osdk-getting-started.adoc b/applications/operator_sdk/osdk-getting-started.adoc index c94a2b0ab4b5..9465ecfd9927 100644 --- a/applications/operator_sdk/osdk-getting-started.adoc +++ b/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] diff --git a/applications/operator_sdk/osdk-migrating-to-v0-1-0.adoc b/applications/operator_sdk/osdk-migrating-to-v0-1-0.adoc index e8428136a4f8..168622c07a5e 100644 --- a/applications/operator_sdk/osdk-migrating-to-v0-1-0.adoc +++ b/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 diff --git a/applications/operator_sdk/osdk-monitoring-prometheus.adoc b/applications/operator_sdk/osdk-monitoring-prometheus.adoc new file mode 100644 index 000000000000..8fce73ed052f --- /dev/null +++ b/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] diff --git a/modules/osdk-operator-sdk.adoc b/modules/osdk-architecture.adoc similarity index 85% rename from modules/osdk-operator-sdk.adoc rename to modules/osdk-architecture.adoc index 523bdb33e217..bbf6d4d00565 100644 --- a/modules/osdk-operator-sdk.adoc +++ b/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: diff --git a/modules/osdk-monitoring-prometheus-metrics-helper-modifying-port.adoc b/modules/osdk-monitoring-prometheus-metrics-helper-modifying-port.adoc new file mode 100644 index 000000000000..22f6b00c268e --- /dev/null +++ b/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. diff --git a/modules/osdk-monitoring-prometheus-metrics-helper.adoc b/modules/osdk-monitoring-prometheus-metrics-helper.adoc new file mode 100644 index 000000000000..72ed5e86fd35 --- /dev/null +++ b/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. diff --git a/modules/osdk-monitoring-prometheus-operator-support.adoc b/modules/osdk-monitoring-prometheus-operator-support.adoc new file mode 100644 index 000000000000..460679f0215c --- /dev/null +++ b/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. diff --git a/modules/osdk-monitoring-prometheus-servicemonitor-creating.adoc b/modules/osdk-monitoring-prometheus-servicemonitor-creating.adoc new file mode 100644 index 000000000000..50285a0d281e --- /dev/null +++ b/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. diff --git a/modules/osdk-monitoring-prometheus-servicemonitor.adoc b/modules/osdk-monitoring-prometheus-servicemonitor.adoc new file mode 100644 index 000000000000..d0638672e0a5 --- /dev/null +++ b/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.