Skip to main content

Third-party Integrations

This chapter outlines how Cirrus CDN integrates with external systems across three areas: API ecosystem (automation), logging and events, and BI/monitoring platforms.

1. API Ecosystem (API‑first)​

  • Style: RESTful JSON under /api/v1/*. See the full endpoints in the API Reference.
  • OpenAPI: Interactive docs (Swagger UI) and the OpenAPI schema are available at runtime; use them to generate SDKs.
  • Auth & tokens:
    • Cookie session (browser Dashboard).
    • Bearer tokens (machine-to-machine): master token and service tokens. Use service tokens for CI/automation, scoped by project/env and rotated regularly.
  • Idempotency & retries:
    • GET is naturally idempotent.
    • PUT is idempotent (same payload → same result).
    • Task-style endpoints (e.g., certificate issuance) return 202; poll status via follow-up calls or rely on logs/metrics.
  • Rate limiting & backoff: Implement exponential backoff on 429/5xx and avoid hot loops (ACME, mass purge).
  • Least privilege: Keep the master token for token lifecycle only; never ship it to edges or clients.
  • Auditability: Record request IDs, caller identity/token ID, and changed resources so you can correlate with logs and alerts.

Quick start: use the API Reference curl examples to create a service token with the master token, then drive domain CRUD, cache purge, and certificate lifecycle automation using that service token.

2. Logging and Events Integration​

All components log to stdout/stderr with structured output. Centralize container logs into your platform of choice (Loki/ELK/Datadog).

  • OpenResty access/error logs:
    • Prometheus metrics are instrumented for request phases and latency histograms.
    • Recommended: push container logs directly to Loki via the Loki Docker logging driver (see the repo’s Loki integration guide).
    • Suggested fields: timestamp, domain/host, path, status, upstream timing, cache status for SLO dashboards.
  • Background jobs (ACME/DNS/health):
    • Celery emits structured logs including task IDs and domain context.
    • Fail/skip/lock branches are explicit for easier retry orchestration.
  • Event bus (advanced):
    • Internally uses Redis Pub/Sub (e.g., cdn:purge, cdn:cname:dirty). If you need an enterprise bus, bridge selected events safely to Kafka/Pulsar with a private connector.

Best practices:

  • Treat container logs as the single source and ship via a driver/sidecar; avoid app-level custom push logic.
  • Add labels (env/team/business) for filters and cost attribution.
  • Connect alerts to dashboards so error-rate/slow-request thresholds link to the same Grafana views.

3. BI / Monitoring Platform Integration​

  • Metrics:
    • OpenResty exposes Prometheus metrics on port 9145; see Operations & Observability.
    • Backend jobs also contribute counters and logs. Import the repository’s prometheus/ and grafana/ assets during deployment.
  • Grafana dashboards:
    • Prebuilt dashboards (OpenResty requests/cache, cert health, node status) are included; wire them to Loki + Prometheus.
    • Use variables for environment/tenant to create ops/dev/on-call views.
  • Alerting:
    • Prometheus: error rate, P95/P99 latency, cache hit ratio, cert expiry window, consecutive health-check failures.
    • Loki: error-log spikes / specific patterns to complement metric alerts.
  • BI data:
    • Export metrics or perform periodic ETL from logs into your data warehouse for domain-level UV/PV, origin ratio, bandwidth cost models.
    • Sources: Prometheus export → DWH, or Loki/ELK query exports; for configuration snapshots, poll /api/v1 periodically.

4. Security & Compliance Notes​

  • Secrets & tokens: distribute service tokens only in controlled environments; master token for token lifecycle only; rotate and scope access.
  • Transport & storage: TLS end-to-end; protect Redis with ACL/networking; restrict access to certificate PEM data.
  • Data minimization: de-identify business data in logs/metrics to satisfy privacy regulations.
  • Change audit: record who/when/what for domain/node changes and correlate with Cirrus logs/metrics.

5. Integration Checklist​

  • API automation:
    • Use the API Reference to automate domain CRUD, cache purge, and certificate issuance/renewal.
    • Use service tokens in CI/automation and implement backoff on 429/5xx.
  • Log aggregation:
    • Push container logs (recommend Loki driver). Tag with domain/env/business/team.
  • Metrics & dashboards:
    • Scrape OpenResty 9145, import grafana/ dashboards, and connect alert channels.
  • Compliance & security:
    • Least privilege tokens, Redis access control, log de-identification.

6. Roadmap​

  • Webhook events: certificate issued, domain ready, node health changes.
  • Finer-grained access control for multi-team/multi-tenant deployments.
  • Official SDKs generated from the OpenAPI spec with sample projects.

For enterprise bus (Kafka/Pulsar) or SIEM/SOX integrations, contact ops or open an issue for reference implementations and best practices.