# googlecloudplatform/k8s-stackdriver architecture

> Architecture diagram of the GitHub repository googlecloudplatform/k8s-stackdriver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/k8s-stackdriver
- Repository: https://github.com/googlecloudplatform/k8s-stackdriver

## Overview

This repository is a suite of GKE-installed Cloud Operations integrations, plus a user-facing custom-metrics adapter and experimental Monitoring proxy. Their main workflows collect Kubernetes, kubelet, or Prometheus data, translate or expose it, and connect to Cloud Monitoring. The graph keeps each product separate. Edges are limited to relationships visible in excerpts, the SOURCE INDEX, or README; several subsystem internals are unsampled, so their unverified wiring is omitted.

Main entry points: [`cloud-monitoring-proxy/cmd/cloud-monitoring-proxy/main.go`](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/cloud-monitoring-proxy/cmd/cloud-monitoring-proxy/main.go) (Proxy runtime), [`cloud-monitoring-proxy/internal/poll/manager.go`](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/cloud-monitoring-proxy/internal/poll/manager.go) (Metric poller), [`event-exporter/main.go`](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/event-exporter/main.go) (Exporter runtime), [`prometheus-to-sd/main.go`](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/prometheus-to-sd/main.go) (Scrape runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_proxy["Monitoring proxy"]
  node_proxy_main["Proxy runtime<br/>[main.go]"]
  node_proxy_config["Configuration"]
  node_proxy_gcm["Monitoring client<br/>[client.go]"]
  node_proxy_scope["Metric scoping<br/>[scope.go]"]
  node_proxy_poller["Metric poller<br/>[manager.go]"]
  node_proxy_translate["Metric translation<br/>[translate.go]"]
  node_proxy_cache[("Series cache<br/>[cache.go]")]
  node_proxy_export["Metrics endpoint"]
  node_proxy_telemetry["Proxy telemetry"]
end

subgraph group_adapter["Custom metrics adapter"]
  node_adapter_runtime["Adapter server<br/>[adapter.go]"]
  node_adapter_provider["Metrics provider<br/>[provider.go]"]
  node_adapter_core["Core metrics<br/>[client.go]"]
  node_adapter_query["Query builder<br/>[query_builder.go]"]
  node_adapter_translate["Response translation"]
  node_adapter_filters["Filter builder<br/>[filter_builder.go]"]
end

subgraph group_events["Event exporter"]
  node_event_runtime["Exporter runtime<br/>[main.go]"]
  node_event_dispatch["Event dispatch<br/>[event_exporter.go]"]
  node_event_watch["Kubernetes watchers<br/>[watcher.go]"]
  node_event_labels["Pod label informer"]
  node_event_sink["Monitoring sink<br/>[sink.go]"]
end

subgraph group_promsd["Prometheus exporter"]
  node_prom_runtime["Scrape runtime<br/>[main.go]"]
  node_prom_sources["Dynamic discovery<br/>[dynamic_source.go]"]
  node_prom_config["Source configuration<br/>[source_config.go]"]
  node_prom_translate["Time-series translation<br/>[translator.go]"]
  node_prom_descriptors[("Descriptor cache")]
end

subgraph group_kubelet["Kubelet monitor"]
  node_kubelet_runtime["Monitor daemon<br/>[daemon.go]"]
  node_kubelet_config["Monitor configuration<br/>[initialize.go]"]
  node_kubelet_client["Kubelet client<br/>[client.go]"]
end

node_proxy_user(("Scrape client"))
node_adapter_user(("Metrics API client"))
node_adapter_gcm[("Monitoring API")]
node_event_cloud[("Cloud Logging and Monitoring")]
node_kube_api(("Kubernetes API"))
node_prom_cloud[("Cloud Monitoring")]

node_proxy_user -->|"scrapes"| node_proxy_export
node_proxy_main -->|"loads"| node_proxy_config
node_proxy_main -->|"initializes"| node_proxy_gcm
node_proxy_main -->|"starts"| node_proxy_poller
node_proxy_main -->|"creates"| node_proxy_cache
node_proxy_main -->|"configures"| node_proxy_scope
node_proxy_main -->|"serves"| node_proxy_export
node_proxy_main -->|"registers"| node_proxy_telemetry
node_proxy_poller -->|"queries"| node_proxy_gcm
node_proxy_poller -->|"scopes"| node_proxy_scope
node_proxy_poller -->|"translates"| node_proxy_translate
node_proxy_poller -->|"updates"| node_proxy_cache
node_proxy_export -->|"reads"| node_proxy_cache
node_adapter_user -->|"requests metrics"| node_adapter_runtime
node_adapter_runtime -->|"constructs"| node_adapter_provider
node_adapter_runtime -->|"configures"| node_adapter_query
node_adapter_runtime -->|"configures"| node_adapter_core
node_adapter_provider -->|"translates"| node_adapter_translate
node_adapter_query -->|"uses"| node_adapter_filters
node_adapter_core -->|"queries"| node_adapter_gcm
node_adapter_core -->|"uses"| node_adapter_query
node_event_runtime -->|"initializes"| node_event_labels
node_event_runtime -->|"creates"| node_event_sink
node_event_runtime -->|"runs"| node_event_dispatch
node_event_dispatch -->|"watches"| node_event_watch
node_event_dispatch -->|"dispatches"| node_event_sink
node_event_sink -->|"uses"| node_event_labels
node_event_sink -.->|"writes events"| node_event_cloud
node_event_runtime -->|"connects"| node_kube_api
node_prom_runtime -->|"discovers"| node_prom_sources
node_prom_runtime -->|"builds"| node_prom_config
node_prom_runtime -->|"translates"| node_prom_translate
node_prom_runtime -->|"sends time series"| node_prom_cloud
node_prom_translate -->|"uses"| node_prom_descriptors
node_prom_sources -->|"lists pods"| node_kube_api
node_kubelet_runtime -->|"initializes"| node_kubelet_config
node_kubelet_runtime -->|"uses"| node_kubelet_client

click node_proxy_main "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/cloud-monitoring-proxy/cmd/cloud-monitoring-proxy/main.go"
click node_proxy_config "https://github.com/googlecloudplatform/k8s-stackdriver/tree/master/cloud-monitoring-proxy/internal/config"
click node_proxy_gcm "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/cloud-monitoring-proxy/internal/gcm/client.go"
click node_proxy_scope "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/cloud-monitoring-proxy/internal/scope/scope.go"
click node_proxy_poller "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/cloud-monitoring-proxy/internal/poll/manager.go"
click node_proxy_translate "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/cloud-monitoring-proxy/internal/translate/translate.go"
click node_proxy_cache "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/cloud-monitoring-proxy/internal/cache/cache.go"
click node_proxy_export "https://github.com/googlecloudplatform/k8s-stackdriver/tree/master/cloud-monitoring-proxy/internal/export"
click node_proxy_telemetry "https://github.com/googlecloudplatform/k8s-stackdriver/tree/master/cloud-monitoring-proxy/internal/telemetry"
click node_adapter_runtime "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/custom-metrics-stackdriver-adapter/adapter.go"
click node_adapter_provider "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/custom-metrics-stackdriver-adapter/pkg/adapter/provider/provider.go"
click node_adapter_core "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/custom-metrics-stackdriver-adapter/pkg/adapter/coreprovider/client.go"
click node_adapter_query "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/custom-metrics-stackdriver-adapter/pkg/adapter/translator/query_builder.go"
click node_adapter_translate "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/custom-metrics-stackdriver-adapter/pkg/adapter/translator/response_translator.go"
click node_adapter_filters "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/custom-metrics-stackdriver-adapter/pkg/adapter/translator/utils/filter_builder.go"
click node_event_runtime "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/event-exporter/main.go"
click node_event_dispatch "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/event-exporter/event_exporter.go"
click node_event_watch "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/event-exporter/kubernetes/watchers/events/watcher.go"
click node_event_labels "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/event-exporter/kubernetes/podlabels/pod_labels_informer.go"
click node_event_sink "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/event-exporter/sinks/stackdriver/sink.go"
click node_prom_runtime "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/prometheus-to-sd/main.go"
click node_prom_sources "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/prometheus-to-sd/config/dynamic_source.go"
click node_prom_config "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/prometheus-to-sd/config/source_config.go"
click node_prom_translate "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/prometheus-to-sd/translator/translator.go"
click node_prom_descriptors "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/prometheus-to-sd/translator/metric_descriptor_cache.go"
click node_kubelet_runtime "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/kubelet-to-gcm/monitor/main/daemon.go"
click node_kubelet_config "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/kubelet-to-gcm/monitor/config/initialize.go"
click node_kubelet_client "https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/kubelet-to-gcm/monitor/kubelet/client.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_proxy_main,node_proxy_config,node_proxy_gcm,node_proxy_scope,node_proxy_poller,node_proxy_translate,node_proxy_cache,node_proxy_export,node_proxy_telemetry,node_proxy_user,node_adapter_user toneBlue
class node_adapter_runtime,node_adapter_provider,node_adapter_core,node_adapter_query,node_adapter_translate,node_adapter_filters,node_adapter_gcm,node_event_cloud,node_prom_cloud toneAmber
class node_event_runtime,node_event_dispatch,node_event_watch,node_event_labels,node_event_sink,node_kube_api toneMint
class node_prom_runtime,node_prom_sources,node_prom_config,node_prom_translate,node_prom_descriptors toneRose
class node_kubelet_runtime,node_kubelet_config,node_kubelet_client toneIndigo
```

## Components

### Monitoring proxy

- [Proxy runtime](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/cloud-monitoring-proxy/cmd/cloud-monitoring-proxy/main.go): `cloud-monitoring-proxy/cmd/cloud-monitoring-proxy/main.go`
- [Configuration](https://github.com/googlecloudplatform/k8s-stackdriver/tree/master/cloud-monitoring-proxy/internal/config): `cloud-monitoring-proxy/internal/config`
- [Monitoring client](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/cloud-monitoring-proxy/internal/gcm/client.go): `cloud-monitoring-proxy/internal/gcm/client.go`
- [Metric scoping](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/cloud-monitoring-proxy/internal/scope/scope.go): `cloud-monitoring-proxy/internal/scope/scope.go`
- [Metric poller](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/cloud-monitoring-proxy/internal/poll/manager.go): `cloud-monitoring-proxy/internal/poll/manager.go`
- [Metric translation](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/cloud-monitoring-proxy/internal/translate/translate.go): `cloud-monitoring-proxy/internal/translate/translate.go`
- [Series cache](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/cloud-monitoring-proxy/internal/cache/cache.go): `cloud-monitoring-proxy/internal/cache/cache.go`
- [Metrics endpoint](https://github.com/googlecloudplatform/k8s-stackdriver/tree/master/cloud-monitoring-proxy/internal/export): `cloud-monitoring-proxy/internal/export`
- [Proxy telemetry](https://github.com/googlecloudplatform/k8s-stackdriver/tree/master/cloud-monitoring-proxy/internal/telemetry): `cloud-monitoring-proxy/internal/telemetry`

### Custom metrics adapter

- [Adapter server](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/custom-metrics-stackdriver-adapter/adapter.go): `custom-metrics-stackdriver-adapter/adapter.go`
- [Metrics provider](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/custom-metrics-stackdriver-adapter/pkg/adapter/provider/provider.go): `custom-metrics-stackdriver-adapter/pkg/adapter/provider/provider.go`
- [Core metrics](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/custom-metrics-stackdriver-adapter/pkg/adapter/coreprovider/client.go): `custom-metrics-stackdriver-adapter/pkg/adapter/coreprovider/client.go`
- [Query builder](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/custom-metrics-stackdriver-adapter/pkg/adapter/translator/query_builder.go): `custom-metrics-stackdriver-adapter/pkg/adapter/translator/query_builder.go`
- [Response translation](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/custom-metrics-stackdriver-adapter/pkg/adapter/translator/response_translator.go): `custom-metrics-stackdriver-adapter/pkg/adapter/translator/response_translator.go`
- [Filter builder](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/custom-metrics-stackdriver-adapter/pkg/adapter/translator/utils/filter_builder.go): `custom-metrics-stackdriver-adapter/pkg/adapter/translator/utils/filter_builder.go`

### Event exporter

- [Exporter runtime](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/event-exporter/main.go): `event-exporter/main.go`
- [Event dispatch](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/event-exporter/event_exporter.go): `event-exporter/event_exporter.go`
- [Kubernetes watchers](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/event-exporter/kubernetes/watchers/events/watcher.go): `event-exporter/kubernetes/watchers/events/watcher.go`
- [Pod label informer](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/event-exporter/kubernetes/podlabels/pod_labels_informer.go): `event-exporter/kubernetes/podlabels/pod_labels_informer.go`
- [Monitoring sink](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/event-exporter/sinks/stackdriver/sink.go): `event-exporter/sinks/stackdriver/sink.go`

### Prometheus exporter

- [Scrape runtime](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/prometheus-to-sd/main.go): `prometheus-to-sd/main.go`
- [Dynamic discovery](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/prometheus-to-sd/config/dynamic_source.go): `prometheus-to-sd/config/dynamic_source.go`
- [Source configuration](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/prometheus-to-sd/config/source_config.go): `prometheus-to-sd/config/source_config.go`
- [Time-series translation](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/prometheus-to-sd/translator/translator.go): `prometheus-to-sd/translator/translator.go`
- [Descriptor cache](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/prometheus-to-sd/translator/metric_descriptor_cache.go): `prometheus-to-sd/translator/metric_descriptor_cache.go`

### Kubelet monitor

- [Monitor daemon](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/kubelet-to-gcm/monitor/main/daemon.go): `kubelet-to-gcm/monitor/main/daemon.go`
- [Monitor configuration](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/kubelet-to-gcm/monitor/config/initialize.go): `kubelet-to-gcm/monitor/config/initialize.go`
- [Kubelet client](https://github.com/googlecloudplatform/k8s-stackdriver/blob/master/kubelet-to-gcm/monitor/kubelet/client.go): `kubelet-to-gcm/monitor/kubelet/client.go`

### Other components

- **Scrape client**
- **Metrics API client**
- **Monitoring API**
- **Cloud Logging and Monitoring**
- **Kubernetes API**
- **Cloud Monitoring**

## Connections

- Scrape client → Metrics endpoint: scrapes
- Proxy runtime → Configuration: loads (evidence: `cloud-monitoring-proxy/cmd/cloud-monitoring-proxy/main.go`)
- Proxy runtime → Monitoring client: initializes (evidence: `cloud-monitoring-proxy/cmd/cloud-monitoring-proxy/main.go`)
- Proxy runtime → Metric poller: starts (evidence: `cloud-monitoring-proxy/cmd/cloud-monitoring-proxy/main.go`)
- Proxy runtime → Series cache: creates (evidence: `cloud-monitoring-proxy/cmd/cloud-monitoring-proxy/main.go`)
- Proxy runtime → Metric scoping: configures (evidence: `cloud-monitoring-proxy/cmd/cloud-monitoring-proxy/main.go`)
- Proxy runtime → Metrics endpoint: serves (evidence: `cloud-monitoring-proxy/cmd/cloud-monitoring-proxy/main.go`)
- Proxy runtime → Proxy telemetry: registers (evidence: `cloud-monitoring-proxy/cmd/cloud-monitoring-proxy/main.go`)
- Metric poller → Monitoring client: queries (evidence: `cloud-monitoring-proxy/internal/poll/manager.go`)
- Metric poller → Metric scoping: scopes (evidence: `cloud-monitoring-proxy/internal/poll/manager.go`)
- Metric poller → Metric translation: translates (evidence: `cloud-monitoring-proxy/internal/poll/manager.go`)
- Metric poller → Series cache: updates (evidence: `cloud-monitoring-proxy/internal/poll/manager.go`)
- Metrics endpoint → Series cache: reads (evidence: `cloud-monitoring-proxy/internal/cache/cache.go`)
- Metrics API client → Adapter server: requests metrics (evidence: `custom-metrics-stackdriver-adapter/adapter.go`)
- Adapter server → Metrics provider: constructs (evidence: `custom-metrics-stackdriver-adapter/adapter.go`)
- Adapter server → Query builder: configures (evidence: `custom-metrics-stackdriver-adapter/adapter.go`)
- Adapter server → Core metrics: configures (evidence: `custom-metrics-stackdriver-adapter/adapter.go`)
- Metrics provider → Response translation: translates (evidence: `custom-metrics-stackdriver-adapter/pkg/adapter/provider/provider.go`)
- Query builder → Filter builder: uses (evidence: `custom-metrics-stackdriver-adapter/pkg/adapter/translator/query_builder.go`)
- Core metrics → Monitoring API: queries (evidence: `custom-metrics-stackdriver-adapter/pkg/adapter/coreprovider/client.go`)
- Core metrics → Query builder: uses (evidence: `custom-metrics-stackdriver-adapter/pkg/adapter/coreprovider/client.go`)
- Exporter runtime → Pod label informer: initializes (evidence: `event-exporter/main.go`)
- Exporter runtime → Monitoring sink: creates (evidence: `event-exporter/main.go`)
- Exporter runtime → Event dispatch: runs (evidence: `event-exporter/event_exporter.go`)
- Event dispatch → Kubernetes watchers: watches (evidence: `event-exporter/event_exporter.go`)
- Event dispatch → Monitoring sink: dispatches (evidence: `event-exporter/event_exporter.go`)
- Monitoring sink → Pod label informer: uses (evidence: `event-exporter/sinks/stackdriver/sink.go`)
- Monitoring sink → Cloud Logging and Monitoring: writes events
- Exporter runtime → Kubernetes API: connects (evidence: `event-exporter/main.go`)
- Scrape runtime → Dynamic discovery: discovers (evidence: `prometheus-to-sd/main.go`)
- Scrape runtime → Source configuration: builds (evidence: `prometheus-to-sd/main.go`)
- Scrape runtime → Time-series translation: translates (evidence: `prometheus-to-sd/main.go`)
- Scrape runtime → Cloud Monitoring: sends time series (evidence: `prometheus-to-sd/main.go`)
- Time-series translation → Descriptor cache: uses (evidence: `prometheus-to-sd/translator/translator.go`)
- Dynamic discovery → Kubernetes API: lists pods (evidence: `prometheus-to-sd/config/dynamic_source.go`)
- Monitor daemon → Monitor configuration: initializes (evidence: `kubelet-to-gcm/monitor/main/daemon.go`)
- Monitor daemon → Kubelet client: uses (evidence: `kubelet-to-gcm/monitor/main/daemon.go`)