Skip to content

README.md

Latest commit

 

History

History
174 lines (135 loc) · 6.44 KB

README.md

File metadata and controls

174 lines (135 loc) · 6.44 KB
Raw

DigitalOcean Uptime Monitor Operator

Tests Helm Lint License: MIT

This Kubernetes Operator automates the creation, update, and deletion of DigitalOcean Uptime Monitors and related alerts based on Ingress annotations. The Operator creates a Custom Resource of kind DoMonitor, which is the single source of truth and is in charge of creating DigitalOcean resources (monitors and alerts).

Quick Links

Installation

  1. Add the public Helm repository

    helm repo add do-uptime-operator https://charts.douz.io
helm repo update

  2. Install with a new DigitalOcean token secret

    helm upgrade --install do-uptime-operator do-uptime-operator/do-uptime-operator \
  --namespace kube-system \
  --create-namespace \
  --set digitalocean.createSecret=true \
  --set digitalocean.token='<DIGITALOCEAN_TOKEN>'

  3. Or install using an existing secret

    helm upgrade --install do-uptime-operator do-uptime-operator/do-uptime-operator \
  --namespace kube-system \
  --create-namespace \
  --set digitalocean.createSecret=false \
  --set digitalocean.existingSecret=do-token-secret

Helm Repo Hosting (charts.douz.io)

This repository is configured to publish Helm charts from charts/ into the centralized repository douz/helm-charts using helm/chart-releaser-action, with the chart repository URL set to https://charts.douz.io.

Operator Logs

If you need to troubleshoot or verify that the operator is running correctly, you can view its logs:

kubectl logs -f deployment/do-monitor-operator -f -n kube-system

Usage

The do-monitor-operator will watch for Ingress resources with the douz.io/do-monitor: "true" annotation and create the Uptime Monitor and associated alerts accordingly. For example:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: default
  annotations:
    douz.io/do-monitor: "true"
    douz.io/do-monitor-email: "your-email@example.com"
    douz.io/do-monitor-slack-webhook: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
    douz.io/do-monitor-slack-channel: "#your-slack-channel"
    douz.io/do-monitor-latency-threshold: "200"
    douz.io/do-monitor-latency-period: "2m"
    douz.io/do-monitor-ssl-expiry: "30"
spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: example-service
                port:
                  number: 80

In this example, an Uptime Monitor (check) named example-ingress-default-domonitor (<ingressName>-<namespace>-domonitor) will be created, along with down, latency, and sslExpiry alerts, sending notifications to the specified email address and Slack channel.

The same results can be achieved by creating a DoMonitor Resource as follows:

---
apiVersion: douz.io/v1
kind: DoMonitor
metadata:
  name: ingress-test-default-domonitor
  namespace: default
spec:
  ingressName: ingress-test
  host: "example.com"
  config:
    email: "your-email@example.com"
    emailAlert: true
    slackWebhook: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
    slackChannel: "#your-slack-channel"
    slackAlert: true
    latencyThreshold: 200
    latencyPeriod: "2m"
    sslExpiryPeriod: 30

Ingress Annotations

  • douz.io/do-monitor: Set to "true" to enable the Operator for an Ingress resource.
  • douz.io/do-monitor-email: Email address to send alerts to (only verified emails in the DigitalOcean dashboard will work).
  • douz.io/do-monitor-slack-webhook: Slack webhook URL for sending alerts to a channel.
  • douz.io/do-monitor-slack-channel: Slack channel name (e.g., #your-slack-channel).
  • douz.io/do-monitor-latency-threshold: Latency threshold in milliseconds.
  • douz.io/do-monitor-latency-period: Period over which to measure latency (e.g., "2m").
  • douz.io/do-monitor-ssl-expiry: Number of days before SSL certificate expiry to trigger an alert.

At least one notification channel (email or Slack) must be provided.

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests. Please follow the DigitalOcean Uptime Monitor docs and Kubernetes Operator patterns when making changes.

Running Tests

python3 -m unittest discover -s tests -p 'test_*.py'

Publish Process

This repository publishes artifacts from GitHub Actions on pushes to main:

  • Docker image publishing: .github/workflows/build-push-image.yml
    • Builds and pushes ghcr.io/douz/do-uptime-kubernetes-operator
    • Publishes latest and commit-SHA tags
  • Helm chart publishing: .github/workflows/helm-release.yml
    • Packages charts under charts/
    • Publishes chart artifacts/index to https://charts.douz.io via douz/helm-charts

No tag-triggered GitHub Release automation is required for image/chart publishing.

Versioning and Traceability

  • Human-readable change tracking: CHANGELOG.md
  • Helm release/version source: charts/do-uptime-operator/Chart.yaml (version, appVersion)
  • Runtime artifact traceability:
    • Container image tags include commit SHA
    • Helm packages are published to https://charts.douz.io

Project Ownership and Support

  • Maintainer details: MAINTAINERS.md
  • Community support expectations: SUPPORT.md
  • Vulnerability reporting: SECURITY.md

Community and Governance

This repository includes:

  • LICENSE (MIT)
  • CONTRIBUTING.md
  • CODE_OF_CONDUCT.md
  • SECURITY.md
  • GitHub issue templates and PR template under .github/

License

This project is licensed under the MIT License.