# giantswarm/cluster-api-monitoring-app architecture

> Architecture diagram of the GitHub repository giantswarm/cluster-api-monitoring-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/giantswarm/cluster-api-monitoring-app
- Repository: https://github.com/giantswarm/cluster-api-monitoring-app

## Overview

##### Project Type and Purpose
- The project is a Helm chart for deploying a custom fork of kube-state-metrics with additional support for exposing metrics from ClusterAPI custom resources. Its goal is to enable collection of metrics from these CRs (such as those from Flux) in a management cluster.
- The README explains that this app (or “chart”) is used to install a dedicated kube-state-metrics (KSM) instance with the alpha CustomResourceStateMetrics feature enabled and further extended to monitor additional CRs by parsing configuration files.

##### Main Architectural Components
a. CI/CD Pipeline Components:
- CircleCI and GitHub Actions – the .circleci and .github directories hold configuration files, workflows, build scripts, and release tools.
- Renovate configuration for dependency updates.
b. The Helm Chart Itself:
- The helm/cluster-api-monitoring directory is central. It contains:
- Chart.yaml: The chart metadata.
- configuration directory: Multiple YAML files for CR configurations that enable metrics collection for various ClusterAPI and Flux related resources.
- templates directory: Kubernetes resource templates (like deployments, service accounts, ConfigMaps, PodMonitors, etc.).
- values.yaml and values.schema.json: Default configuration and schema definitions.
c. The Application Domain:
- The deployed application will run inside a Kubernetes (management) cluster.
- It acts as an independent instance of kube-state-metrics with custom enhancements for ClusterAPI custom resources.
- It interfaces with Kubernetes API servers and CRDs to extract state metrics.

##### Relationships and Interactions
- CI/CD Workflows → Build & Release: Your GitHub Actions and CircleCI pipelines trigger tasks like linting, building container images, verifying configuration schema, and creating releases. These pipelines ensure that every change to the Helm chart is validated and released seamlessly.
- Helm Chart → Kubernetes Cluster Deployment: The Helm chart (comprising templates, configurations, and values files) is used to install the monitoring application into a management cluster. Configurations (found under the “configuration” directory) define how different monitored resources are handled.
- Data Flow within the Application: When installed, the kube-state-metrics fork reads Kubernetes CRs based on the configuration specified (for example, using custom YAML files for flux resources) and then exports the corresponding metrics. This data flow can be depicted as “Kubernetes API Call → CR Data Extraction → Metrics Generation.”

##### Architectural Patterns and Design Principles
- Separation of Concerns: Notice the clear separation between configuration (under configuration/), templating (under templates/), and CI/CD integration (under .circleci and .github). This modularization makes it easier to maintain.
- Infrastructure as Code: The use of Helm charts to declare desired Kubernetes states.
- Declarative Configuration: YAML configuration and templating emphasize a declarative approach that is typical in Kubernetes-centric applications.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Pipeline Subgraph
    subgraph "CI/CD Pipeline"
        GitHubActions["GitHub Actions Workflows"]:::ci_cd
        CircleCI["CircleCI Pipeline"]:::ci_cd
        Renovate["Renovate Automation"]:::ci_cd
    end

    %% Helm Chart Repository Subgraph
    subgraph "Helm Chart Repository - cluster-api-monitoring"
        ChartMetadata["Chart Metadata (Helm)"]:::helm
        ConfigFiles["Configuration Files for Custom Metrics"]:::helm
        Templates["Kubernetes Resource Templates"]:::helm
        DefaultConfig["Default Configuration (values.yaml)"]:::helm
        SchemaDefs["Schema Definitions (values.schema.json)"]:::helm
    end

    %% Deployment Subgraph
    subgraph "Deployment"
        KSMApp["Kube-state-metrics Fork (Deployed App)"]:::runtime
        KubeCluster["Kubernetes Management Cluster"]:::runtime
    end

    %% Connections from CI/CD Pipeline to Helm Chart Repository
    GitHubActions -->|"triggers"| ChartMetadata
    CircleCI -->|"triggers"| ChartMetadata
    Renovate -->|"updates"| ChartMetadata

    %% Internal relationships within Helm Chart Repository
    ConfigFiles -->|"influences"| Templates
    DefaultConfig -->|"definesDefaults"| Templates
    SchemaDefs -->|"validates"| DefaultConfig
    Templates -->|"integratesWith"| ChartMetadata

    %% Deployment Flow: Helm Chart Deployment to Runtime
    ChartMetadata -->|"deploys"| KSMApp
    KSMApp -->|"pullsCRdata"| KubeCluster

    %% Classes for styling
    classDef ci_cd fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef helm fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef runtime fill:#abebc6,stroke:#1e8449,stroke-width:2px;

    %% Click Events
    click CircleCI "https://github.com/giantswarm/cluster-api-monitoring-app/blob/main/.circleci/config.yml"
    click GitHubActions "https://github.com/giantswarm/cluster-api-monitoring-app/tree/main/.github/workflows/"
    click Renovate "https://github.com/giantswarm/cluster-api-monitoring-app/blob/main/renovate.json5"
    click ChartMetadata "https://github.com/giantswarm/cluster-api-monitoring-app/blob/main/helm/cluster-api-monitoring/Chart.yaml"
    click ConfigFiles "https://github.com/giantswarm/cluster-api-monitoring-app/tree/main/helm/cluster-api-monitoring/configuration"
    click Templates "https://github.com/giantswarm/cluster-api-monitoring-app/tree/main/helm/cluster-api-monitoring/templates"
    click DefaultConfig "https://github.com/giantswarm/cluster-api-monitoring-app/blob/main/helm/cluster-api-monitoring/values.yaml"
    click SchemaDefs "https://github.com/giantswarm/cluster-api-monitoring-app/blob/main/helm/cluster-api-monitoring/values.schema.json"
```
