Skip to content

Latest commit

 

History

History
181 lines (143 loc) · 7.49 KB

README.md

File metadata and controls

181 lines (143 loc) · 7.49 KB
Raw

ingress-monitor-controller

Build Status Go Report Card GoDoc

A Kubernetes controller for automatically configuring website monitors for ingresses. Currently the following providers are supported:

  • Site24x7
  • Null provider (only useful for testing and debugging)

Building the Controller

Clone the repository and build a docker image by running:

make docker-build

This will build and tag the image as ingress-monitor-controller:latest. If you want to use a different image name and tag, override the IMAGE and TAG environment variables:

make docker-build IMAGE=my.registry/ingress-monitor-controller TAG="$(git rev-parse HEAD)"

Deploying the Controller

You can find example manifests for deploying the controller in the deploy/ directory. Be sure to customize them to your needs before applying them to your cluster:

kubectl apply -f deploy/

Configuration

CLI Flags

The following CLI flags are available:

Flag Description Default
--debug Enable debug logging. false
--provider The provider to use for creating monitors. site24x7
--provider-config Location of the config file for the monitor providers. ""
--name-template The template to use for the monitor name. Valid fields are: .IngressName, .Namespace. {{.Namespace}}-{{.IngressName}}
--namespace Namespace to watch. If empty, all namespaces are watched. ""
--creation-delay Duration to wait after an ingress is created before creating the monitor for it. 0s
--no-delete If set, monitors will not be deleted if the ingress is deleted. false

Provider Configuration File

The config file has the following YAML format:

name-of-the-provider:
  [...provider specific config like authentication...]
  monitorDefaults:
    [...provider specific default values for monitors if not overridden explicitly...]

Refer to pkg/config/providers.go for all available config keys and their documentation. For a usage example of the config file check out the ConfigMap and Deployment manifests in the deploy/ directory.

Example configuration for the Site24x7 provider:

site24x7:
  clientID: the-oauth-client-id
  clientSecret: the-oauth-client-secret
  refreshToken: the-oauth-refresh-token
  monitorDefaults:
    Actions:
      - alert_type: 0
        action_id: "123"
    AuthPass: ""
    AuthUser: ""
    AutoLocationProfile: true
    AutoMonitorGroup: true
    AutoNotificationProfile: true
    AutoThresholdProfile: true
    AutoUserGroup: true
    CheckFrequency: "1"
    CustomHeaders:
      - name: X-Monitor-Created-By
        value: ingress-monitor-controller
    HTTPMethod: G
    LocationProfileID: "123"
    MatchCase: true
    MonitorGroupIDs:
      - "123"
    NotificationProfileID: "456"
    ThresholdProfileID: "678"
    Timeout: 10
    UseNameServer: true
    UserAgent: "curl/v1.33.7"
    UserGroupIDs:
      - "456"

Ingress Annotations

To automatically create a website monitor for an ingress, it requires to be annotated with the ingress-monitor.bonial.com/enabled annotation:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress-monitor.bonial.com/enabled: "true"
  name: my-ingress
  namespace: my-namespace

Global Ingress Annotations

Global ingress annotations configure behaviour that is not specific to a certain provider. The following annotations are supported:

Annotation Description Default
ingress-monitor.bonial.com/enabled Controls whether a monitor should be created for the ingress or not false
ingress-monitor.bonial.com/force-https Forces the monitored URL to be HTTPS even if TLS is not configured for the ingress false
ingress-monitor.bonial.com/path-override By default, / is monitored. This can be overridden with this annotation (e.g. /health) /

Supported Third Party Annotations

The controller will honor the nginx.ingress.kubernetes.io/force-ssl-redirect annotation and force website monitors to be created for HTTPS if this annotation is set to true.

Provider Specific Annotations

You can control the configuration of a website monitor via provider specific annotations. For a full list of supported annotations check out the constants and their documentation in pkg/config/annotations.go.

Source Range Rewriting

The ingress-monitor-controller will automatically adds the monitor provider's source IP ranges to the nginx.ingress.kubernetes.io/whitelist-source-range annotation of an ingress if the following rules apply:

  • If the ingress-monitor.bonial.com/enabled annotation is false or not present, do nothing.
  • If the nginx.ingress.kubernetes.io/whitelist-source-range is not present or empty, do nothing.
  • If there are no source ranges for the used monitor provider, do nothing.
  • If the provider source ranges are not already present in the nginx.ingress.kubernetes.io/whitelist-source-range annotation, add them automatically.

Limitations

The controller only creates monitors for the host defined in the first ingress rule (spec.rules[0].host), or if using TLS, for the first host in the TLS spec (spec.tls[0].hosts[0]), and only if those do not contain wildcards (*). If you want to create monitors for multiple hostnames, simply create dedicated ingress objects for them.

Metrics

Prometheus metrics are exposed at 0.0.0.0:8080/metrics. Besides the metrics provided by the kubernetes controller-runtime the ingress-monitor-controller also exposes metric stats about monitor creations, updates and deletions prefixed with ingress_monitor_controller_*, see pkg/monitor/metrics.