GCP Metrics Integration

Overview

The Prometheus Stackdriver Exporter polls the Cloud Monitoring Metrics API on a configurable interval and exposes the results in Prometheus format, which Kloudfuse scrapes and stores. It supports single and multi-project configurations.

Metric type prefixes control which GCP services are collected. Common prefixes include:

See the Google Cloud metrics reference for the full list of available metric type prefixes.

Prerequisites

• A running Kloudfuse deployment on GKE.
• The gcloud CLI installed and authenticated, or access to the Google Cloud Console.
• Permissions to create service accounts and assign IAM roles in your GCP project.

Step 1: Create a Service Account

The Stackdriver Exporter authenticates to GCP using a service account JSON key.

Create the Service Account

 gcloud iam service-accounts create kloudfuse-gcp \
   --display-name="Kloudfuse GCP Integration" \
   --project=<project-id>

Assign IAM Roles

gcloud projects add-iam-policy-binding <project-id> \
  --member="serviceAccount:kloudfuse-gcp@<project-id>.iam.gserviceaccount.com" \
  --role="roles/monitoring.viewer"

# Required only if enabling metrics enrichment:
gcloud projects add-iam-policy-binding <project-id> \
  --member="serviceAccount:kloudfuse-gcp@<project-id>.iam.gserviceaccount.com" \
  --role="roles/compute.viewer"

For multi-project setups, repeat the role assignments for each additional project.

Create the JSON Key

gcloud iam service-accounts keys create kloudfuse-gcp-credentials.json \
  --iam-account=kloudfuse-gcp@<project-id>.iam.gserviceaccount.com

Step 2: Create the Kubernetes Secret

kubectl create secret generic kfuse-gcp-credentials \
  --from-file=credentials.json=kloudfuse-gcp-credentials.json \
  --namespace <kloudfuse-namespace>

Replace <kloudfuse-namespace> with the namespace your Kloudfuse installation is deployed into.

Step 3: Configure Kloudfuse via Helm

Enable the Cloud Exporter

In your custom-values.yaml, enable the cloud exporter and set the GCP credentials secret:

global:
  cloud-exporter:
    enabled: true
  gcpConfig:
    secretName: "kfuse-gcp-credentials"

Single Project Configuration

kfuse-cloud-exporter:
  prometheus-stackdriver-exporter:
    enabled: true
    stackdriver:
      httpTimeout: 30s
      maxRetries: 3
      projectId: "<project-id>" (1)
      metrics:
        typePrefixes: "compute.googleapis.com,container.googleapis.com,storage.googleapis.com" (2)

Multiple Projects Configuration

kfuse-cloud-exporter:
  prometheus-stackdriver-exporter:
    enabled: true
    stackdriver:
      httpTimeout: 30s
      maxRetries: 3
      metrics:
        typePrefixes: "compute.googleapis.com,container.googleapis.com"
    config:
      project_ids: (1)
        - project-id-1
        - project-id-2
        - project-id-3

Apply the Helm Upgrade

helm upgrade --install kfuse oci://us-east1-docker.pkg.dev/mvp-demo-301906/kfuse-helm/kfuse \
  -n kfuse \
  --version <VERSION> \ (1)
  -f custom-values.yaml

Configure GCP Metrics Enrichment

Metrics enrichment attaches GCP resource labels — such as custom labels applied to Compute Engine instances — to the corresponding metrics. This allows you to filter metrics in Kloudfuse by any label applied to your GCP resources.

Enrichment requires the roles/compute.viewer IAM role on the service account.

Global Enrichment Configuration

Add the following under the global section:

global:
  enrichmentEnabled:
    - gcp
  gcpConfig:
    secretName: "kfuse-gcp-credentials"

Ingester Enrichment Configuration

Configure the ingester scraper settings:

ingester:
  config:
    gcpScrapeIntervalMinutes: 30 (1)
    gcpProjectConfigs:
      - projectId: "<project-id>" (2)
        zones: (3)
          - "us-west1-b"
          - "us-central1-a"
        services: (4)
          - "GCE"
    gcpZones: (5)
      - "us-west1-b"
      - "us-central1-a"
    gcpServices:
      - "GCE"

Multi-Project Enrichment

ingester:
  config:
    gcpScrapeIntervalMinutes: 30
    gcpProjectConfigs:
      - projectId: "project-1"
        zones: ["us-west1-b"]
        services: ["GCE"]
      - projectId: "project-2"
        zones: ["europe-west1-b"]
        services: ["GCE"]

Verify the Integration

Confirm the Stackdriver Exporter is Running

kubectl get pods -n <kloudfuse-namespace> -l app=prometheus-stackdriver-exporter

The pod status must be Running. If it is CrashLoopBackOff, check the logs:

kubectl logs -n <kloudfuse-namespace> -l app=prometheus-stackdriver-exporter --tail=100

Confirm Metrics are Arriving in Kloudfuse

1. In the Kloudfuse UI, click the Metrics tab and select Explorer from the drop-down.
2. In the metric search field, type gcp_ to list all ingested GCP metrics. Metrics follow the naming convention gcp_<service>_<metric_name> in lowercase with underscores, for example:

3. Select a metric and set the time range to the last 15 minutes. A non-empty chart confirms end-to-end delivery.

Troubleshooting

Stackdriver Exporter Pod is in CrashLoopBackOff

kubectl logs -n <kloudfuse-namespace> -l app=prometheus-stackdriver-exporter --tail=50

Common causes:

No GCP Metrics Appear in Kloudfuse

1. Confirm the Stackdriver Exporter pod is Running.
2. Wait at least one full scrape interval after the pod starts.
3. Check the exporter logs for scrape errors:

   kubectl logs -n <kloudfuse-namespace> -l app=prometheus-stackdriver-exporter | grep -i error
   

4. Confirm the typePrefixes in custom-values.yaml match metric types that exist in your project.

Metrics from One Project are Missing

1. Confirm the project ID is listed under config.project_ids (or stackdriver.projectId) in custom-values.yaml.
2. Confirm the service account has roles/monitoring.viewer on that project:

   gcloud projects get-iam-policy <project-id> \
    --flatten="bindings[].members" \
    --filter="bindings.members:kloudfuse-gcp@" \
    --format="table(bindings.role)"
   

Enrichment Labels Not Appearing on Metrics

1. Confirm enrichmentEnabled includes gcp in custom-values.yaml.
2. Confirm the service account has roles/compute.viewer.
3. Check the ingester logs for enrichment errors:

   kubectl logs -n <kloudfuse-namespace> -l app=ingester | grep -i "gcp\|enrich\|error"
   

4. New labels may take up to gcpScrapeIntervalMinutes (default: 30 minutes) to appear. Wait one full interval.

External References

Prometheus Stackdriver Exporter

• prometheus-community/stackdriver_exporter — Prometheus exporter for Google Cloud Monitoring metrics

• stackdriver_exporter configuration flags

Google Cloud documentation

• Google Cloud metrics reference
• Create and manage service accounts
• Cloud Monitoring access control
• Cloud Monitoring Metrics API reference