cd-operator

cd-operator

A production-grade Kubernetes operator for continuous deployment automation that manages ArgoCD-based deployments across multiple clusters.

Features

• Automated PR Pipeline: Discovers, qualifies, and auto-merges pull requests
• Drift Monitoring: Tracks deployment status across multiple ArgoCD instances
• Multi-Cluster Support: Manages deployments across different Kubernetes clusters
• Label-Based Workflow: Uses GitHub labels for state management
• Production-Ready: Built with observability, security scanning, and comprehensive testing

Architecture

Dual Pipeline Design

1. PR Pipeline: Discovers PRs → Qualifies → Auto-merges → Updates labels
2. Drift Pipeline: Monitors merged PRs → Queries ArgoCD clusters → Evaluates drift → Updates status

Custom Resource Definitions (CRDs)

• PullRequestTracker - Tracks PR lifecycle (discovered → qualified → merged)
• DriftMonitor - Monitors deployment drift per merged PR across clusters
• CDOperatorConfig - Operator configuration (cluster-scoped singleton)
• ClusterConfig - Per-cluster ArgoCD connection configuration

Quick Start

Prerequisites

• Go 1.26+
• Kubernetes cluster (v1.31+)
• kubectl
• Docker (for building images)

Building

# Build the operator
go build -o cd-operator cmd/cd-operator/main.go

# Run tests
go test -v ./...

# Run integration tests (requires Kubernetes cluster)
go test -v -tags=integration ./tests/integration/...

Installation

# Install CRDs
kubectl apply -f config/crd/bases/

# Deploy the operator
kubectl apply -f config/manifests/

# Verify deployment
kubectl get pods -n cd-operator-system

Docker Image

# Build image
docker build -t cd-operator:latest .

# Run locally
docker run --rm cd-operator:latest --help

Pre-built multi-arch images are available at:

docker pull ghcr.io/grhili/cd-operator:latest

Configuration

The operator can be configured via:

• ConfigMaps (legacy, configs/config.yaml, clusters.yaml, labels.yaml)
• CRDs (recommended, CDOperatorConfig and ClusterConfig resources)

Development

Project Structure

cd-operator/
├── cmd/cd-operator/           # Entry point
├── internal/                  # Business logic
│   ├── app/                  # Main operator orchestrator
│   ├── controller/           # Kubernetes controllers
│   ├── prpipeline/           # PR discovery & merge pipeline
│   ├── driftpipeline/        # Post-merge drift monitoring
│   ├── qualification/        # PR validation logic
│   └── labels/               # GitHub label lifecycle management
├── pkg/                      # Reusable packages
│   ├── github/               # GitHub API client
│   ├── argocd/               # ArgoCD API client
│   ├── httpclient/           # Retryable HTTP client
│   └── workerpool/           # Generic worker pool
├── api/v1alpha1/             # CRD definitions
└── config/                   # Kubernetes manifests

Running Tests

# Unit tests
go test -v ./...

# With coverage
go test -v -race -coverprofile=coverage.out ./...

# Integration tests (requires kind/k8s cluster)
go test -v -tags=integration ./tests/integration/...

Code Quality

Quality Gates: All code must pass automated quality gates before merging.

# Run all quality gates (matches CI)
make quality-gates

# Individual checks
make quality-format-check  # Code formatting
make quality-qlty-check    # Qlty analysis with thresholds
make quality-coverage-check # Test coverage ≥70%
make quality-security-check # Basic security scans

# Auto-fix formatting issues
make fmt
# or: qlty fmt

# View all issues
qlty check --all

# Install quality tools
make quality-install

Quality Thresholds (enforced in CI):

• ❌ Critical issues: 0 (hard fail)
• ❌ High severity: ≤10 (hard fail)
• ❌ Test coverage: ≥70% (hard fail)
• ❌ Code formatting: 100% (hard fail)

📚 Documentation:

• Quality Gates Guide - Full documentation
• Quick Reference - Developer cheat sheet

CI/CD Workflows

The project includes comprehensive GitHub Actions workflows:

• ci.yml: Runs on every PR/push - lint, build, test, quality gates, coverage
• integration.yml: Runs integration tests with kind cluster
• release.yml: Builds and pushes multi-arch Docker images to GHCR
• security.yml: Security scanning (gosec, nancy, govulncheck, trivy)

All quality gates are enforced in the quality-gates job of ci.yml.

Observability

• Metrics: Prometheus metrics on port 8081
• Tracing: OpenTelemetry support
• Logging: Structured JSON logging (zap)
• Health Checks: Liveness and readiness probes

License

[Add license information]

Contributing

[Add contribution guidelines]