# enix/x509-certificate-exporter architecture

> Architecture diagram of the GitHub repository enix/x509-certificate-exporter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/enix/x509-certificate-exporter
- Repository: https://github.com/enix/x509-certificate-exporter

## Overview

##### Project Type and Purpose
- This is a backend monitoring tool written in Go: a Prometheus exporter focused on X.509 certificate expiration.
- It runs as a standalone service or inside Kubernetes (via Helm chart), scans PEM files, directories, kubeconfigs and Kubernetes Secrets, then exposes metrics on an HTTP endpoint.

##### File Structure Analysis
- Top-level:
- cmd/x509-certificate-exporter: entry point (main.go, utility.go)
- internal/: core logic (certificate parsing, collectors, Kubernetes client, utility and version)
- deploy/: deployment manifests and Helm chart for Kubernetes, systemd unit for Linux, OpenBSD daemon script
- docker-compose.yml, Dockerfile: containerized execution
- hack/: development scripts (kind cluster setup, build server)
- test/: fixture files and automated tests for certificates and YAML configs
- docs/: Grafana dashboard screenshot
- Configuration files: .env, .air.toml (live-reload), go.mod/sum, CI pipelines under .github/workflows

##### README Insights
- Describes metrics, usage modes (CLI flags, Docker image, Helm chart), Prometheus alert rules.

##### Main Components
a. Exporter Service (Go binary)
- CLI / configuration loader
- File watcher (scan files & directories)
- Kubernetes watcher (client-go API, list/watch secrets)
- Certificate Collector (parses PEM data, computes not-before/after)
- Metrics Registry (Prometheus client library)
- HTTP Server or systemd socket listener (exposes /metrics)
b. Configuration & Deployment
- CLI flags or environment variables
- Docker container or systemd service unit
- Helm chart layering: Deployment, DaemonSet, ServiceMonitor, Grafana Dashboard
c. External Services
- Prometheus server scrapes the /metrics endpoint
- (Optional) Grafana dashboard visualizes metrics
- Kubernetes API (when --watch-kube-secrets enabled)

##### Interactions and Data Flow
- On startup, the Exporter reads configuration flags (CLI, kubeconfig path, watch dirs/files, include/exclude filters).
- File watcher emits file paths → Collector parses certificates → Metrics Registry updates gauges.
- Kubernetes watcher uses client-go → streams Secrets → Collector extracts certificates → Metrics Registry updates.
- HTTP server serves /metrics with current metric values.
- Prometheus polls /metrics → stores time series → Grafana queries Prometheus for dashboards/alerts.

##### Architectural Patterns and Principles
- Modular layering: cmd (orchestration) → internal packages (domain logic) → Prometheus client
- Dependency injection for Kubernetes client and file system interfaces (testable via fake clientset).
- Separation of concerns: watching vs parsing vs metrics vs serving.
- Use of standard exporter pattern (single‐responsibility metrics server).

##### Technologies and Frameworks
- Go modules, Go standard library (net/http, time, io/fs)
- client-go/kubernetes/fake for Kubernetes API interactions
- Prometheus Go client library
- Helm for Kubernetes chart
- Docker, containerd (via Dockerfile, docker-compose)
- systemd socket activation (optional)
- Kind for local Kubernetes in hack scripts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Init
    subgraph "Configuration & Init"
        CLI["Exporter Service (Go binary)\nmain.go, utility.go"]:::internal
        ConfigLoader["Configuration Loader & Init\ninternal/exporter.go\n.env, .air.toml"]:::internal
    end

    %% Watchers
    subgraph "Watchers"
        FileWatcher["File Watcher\ninternal/collector.go\ninternal/utility.go"]:::internal
        K8sWatcher["Kubernetes Watcher\ninternal/kubernetes.go\ninternal/kubernetes_test.go"]:::internal
    end

    %% Core Collector
    subgraph "Core Collector"
        CertParser["Certificate Parser\ninternal/certificate.go"]:::internal
    end

    %% Metrics Server
    subgraph "Metrics Server"
        MetricsRegistry["Metrics Registry & HTTP Server\ninternal/exporter.go"]:::internal
    end

    %% Deployment & Environment
    subgraph "Deployment & Environment"
        HelmChart["Helm Chart\ndeploy/charts/x509-certificate-exporter"]:::deployment
        DockerSetup["Docker Setup\nDockerfile, docker-compose.yml"]:::deployment
        Systemd["systemd Service Unit\ndeploy/linux/x509-certificate-exporter.service"]:::deployment
        OpenBSD["OpenBSD Daemon Script\ndeploy/openbsd/x509exporter"]:::deployment
        DevScripts["Dev & Local Cluster Scripts\nhack/kind.sh, hack/air-build-server.sh"]:::deployment
    end

    %% External Systems
    subgraph "External Systems"
        FileSystem["File System"]:::external
        K8sAPI["Kubernetes API"]:::external
        Prometheus["Prometheus Server"]:::external
        Grafana["Grafana Dashboard"]:::external
    end

    %% Connections
    FileSystem -->|watches| FileWatcher
    K8sAPI -->|streams Secrets| K8sWatcher
    FileWatcher -->|provides PEM files| CertParser
    K8sWatcher -->|provides PEM data| CertParser
    CertParser -->|updates metrics| MetricsRegistry
    ConfigLoader -->|initializes| FileWatcher
    ConfigLoader -->|initializes| K8sWatcher
    ConfigLoader -->|initializes| MetricsRegistry
    CLI -->|provides flags| ConfigLoader
    MetricsRegistry -->|serves /metrics| Prometheus
    Prometheus -->|scrapes /metrics| MetricsRegistry
    Prometheus -->|feeds data| Grafana

    %% Click Events
    click CLI "https://github.com/enix/x509-certificate-exporter/blob/main/cmd/x509-certificate-exporter/main.go"
    click ConfigLoader "https://github.com/enix/x509-certificate-exporter/blob/main/internal/exporter.go"
    click FileWatcher "https://github.com/enix/x509-certificate-exporter/blob/main/internal/collector.go"
    click K8sWatcher "https://github.com/enix/x509-certificate-exporter/blob/main/internal/kubernetes.go"
    click CertParser "https://github.com/enix/x509-certificate-exporter/blob/main/internal/certificate.go"
    click MetricsRegistry "https://github.com/enix/x509-certificate-exporter/blob/main/internal/exporter.go"
    click HelmChart "https://github.com/enix/x509-certificate-exporter/tree/main/deploy/charts/x509-certificate-exporter/"
    click DockerSetup "https://github.com/enix/x509-certificate-exporter/tree/main/Dockerfile"
    click Systemd "https://github.com/enix/x509-certificate-exporter/blob/main/deploy/linux/x509-certificate-exporter.service"
    click OpenBSD "https://github.com/enix/x509-certificate-exporter/tree/main/deploy/openbsd/x509exporter"
    click DevScripts "https://github.com/enix/x509-certificate-exporter/blob/main/hack/kind.sh"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
    classDef deployment fill:#FFA500,stroke:#000,stroke-width:1px
```
