tutorial

How to Monitor Cloud Native Buildpacks with Vigilmon (Build Health, Cache, and Registry Status)

Cloud Native Buildpacks (CNB) transform application source code into OCI-compliant container images without Dockerfiles — using the `pack` CLI, `lifecycle` b...

Cloud Native Buildpacks (CNB) transform application source code into OCI-compliant container images without Dockerfiles — using the pack CLI, lifecycle binary, or platforms like Paketo. They're embedded in Heroku, Google Cloud Run, Kpack, and Tekton pipelines. When buildpack infrastructure degrades, build pipelines stall, releases block, and teams lose the ability to deploy.

In this tutorial you'll set up external monitoring for your Cloud Native Buildpacks infrastructure using Vigilmon — free tier, no credit card required.

What can go wrong in a Buildpacks pipeline

CNB failures are often silent — the build job fails, CI reports a red pipeline, and an engineer has to dig through logs to understand whether the problem is:

  • Buildpack detection failure — no buildpack in the stack can detect the language or framework; the build exits with "no buildpacks participating"
  • Layer cache poisoning — a corrupted cache layer causes subsequent builds to fail with cryptic filesystem errors
  • Registry push failure — the build succeeds but pushing the final image to the container registry fails due to authentication expiry, quota limits, or network issues
  • Lifecycle binary download timeout — the pack CLI fetches the lifecycle binary from GitHub on each build; if GitHub is slow or rate-limited, every build hangs
  • Builder image pull failure — the platform buildpack builder image (e.g., paketobuildpacks/builder:base) can't be pulled from DockerHub due to rate limiting or registry unavailability
  • Build cache storage unavailable — cache volumes on Kubernetes (using Kpack) go into an error state, causing every build to start cold

External monitoring of your CNB infrastructure components catches these failures before they block an entire release pipeline.

What you'll need

  • A CNB-based build pipeline (Kpack on Kubernetes, Tekton with CNB tasks, or a self-hosted pack CI runner)
  • A container registry (DockerHub, GCR, ECR, or self-hosted)
  • Optionally: a Kpack installation with a REST API
  • A free Vigilmon account

Step 1: Identify your CNB infrastructure endpoints

The endpoints you need to monitor depend on your CNB platform:

| Platform | Key endpoints to monitor | |----------|------------------------| | Kpack (Kubernetes) | Kpack controller health, builder image registry | | Tekton + CNB | Tekton API, pipeline store | | Heroku / Cloud Run | Platform API health endpoints | | Self-hosted pack CI | CI runner health, registry endpoint |

For Kpack, check the controller status:

kubectl get pods -n kpack
# NAME                                READY   STATUS    RESTARTS
# kpack-controller-7d9f8c4b5-xk2mp   1/1     Running   0
# kpack-webhook-6c8b9d7f4-p8qrs      1/1     Running   0

Step 2: Expose a build pipeline health endpoint

Add a build health HTTP endpoint to your CI/CD system that reports the status of recent builds. Here's a simple Node.js example that wraps Kpack image build status:

// build-health-server.js
const express = require('express');
const { execSync } = require('child_process');
const app = express();

app.get('/health/builds', (req, res) => {
  try {
    // Check last 5 Kpack image builds
    const output = execSync(
      'kubectl get images.kpack.io -A -o json',
      { timeout: 5000 }
    ).toString();
    const images = JSON.parse(output);
    
    const failedBuilds = images.items.filter(img => {
      const cond = img.status?.conditions?.find(c => c.type === 'Ready');
      return cond?.status === 'False';
    });

    if (failedBuilds.length === 0) {
      res.json({ status: 'ok', failed_builds: 0 });
    } else {
      res.status(503).json({
        status: 'degraded',
        failed_builds: failedBuilds.length,
        images: failedBuilds.map(i => i.metadata.name)
      });
    }
  } catch (err) {
    res.status(503).json({ status: 'error', message: err.message });
  }
});

app.listen(8080);

Expose this service in your cluster and add an Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: build-health
  namespace: kpack
spec:
  rules:
    - host: build-health.example.com
      http:
        paths:
          - path: /health
            pathType: Prefix
            backend:
              service:
                name: build-health-svc
                port:
                  number: 8080

Step 3: Monitor your container registry

Build success depends entirely on the container registry being reachable for both pulling builder images and pushing output images. Monitor your registry's health endpoint:

DockerHub:

https://hub.docker.com/ (HTTP 200 check)

GCR (Google Container Registry):

https://gcr.io/ (HTTP 200 check)

Self-hosted registry (e.g., Harbor, Nexus):

https://registry.example.com/v2/ (HTTP 200 — returns empty JSON)

For self-hosted registries, the /v2/ endpoint is the Docker Registry v2 API discovery endpoint and requires no authentication for a basic health check.

Step 4: Create monitors in Vigilmon

Log into Vigilmon and create monitors for each component.

Monitor 1: Buildpack build health

| Field | Value | |-------|-------| | Monitor type | HTTP(S) | | Name | Kpack Build Health | | URL | https://build-health.example.com/health/builds | | Check interval | 2 minutes | | Expected status | 200 | | Alert threshold | 1 consecutive failure |

Use an alert threshold of 1 failure for the build health endpoint — a build stuck in failed state should alert immediately, not after two checks.

Monitor 2: Container registry availability

| Field | Value | |-------|-------| | Monitor type | HTTP(S) | | Name | Container Registry | | URL | https://registry.example.com/v2/ | | Check interval | 1 minute | | Expected status | 200 | | Alert threshold | 2 consecutive failures |

Monitor 3: Registry response latency

Slow registry responses directly cause build timeouts. Enable latency tracking:

  1. Open the Container Registry monitor
  2. Enable Response Time Tracking
  3. Set Response Time Alert to 3000ms — slow layer pushes often manifest as response times creeping up before full timeouts occur

Monitor 4: Builder image availability check

Monitor the availability of your CNB builder image in the registry:

| Field | Value | |-------|-------| | Monitor type | HTTP(S) | | Name | CNB Builder Image (Paketo base) | | URL | https://registry-1.docker.io/v2/paketobuildpacks/builder/manifests/base | | Check interval | 5 minutes | | Expected status | 200 |

Note: for DockerHub's manifest endpoint you may need an authentication token. Alternative: monitor a self-mirrored copy of the builder image in your own registry, which is also best practice for production buildpack pipelines.

Step 5: Monitor buildpack cache storage

CNB cache layers are stored in OCI image format in your registry. Cache corruption manifests as failed builds with layer-not-found errors. Add a cache health check that verifies the cache index is reachable:

#!/bin/bash
# check-cache.sh — runs as a CronJob in the cluster
CACHE_IMAGE=$(kubectl get image.kpack.io my-app -n default \
  -o jsonpath='{.status.latestBuildImageGeneration}')

if [ -n "$CACHE_IMAGE" ]; then
  echo "Cache accessible, generation: $CACHE_IMAGE"
  exit 0
else
  echo "Cache inaccessible or build never ran"
  exit 1
fi

For broader cache monitoring, wrap this in a Kubernetes CronJob that posts status to a simple HTTP endpoint Vigilmon can check.

Step 6: Track build success rates with a custom metric endpoint

Build success rate is a key SLO for CNB infrastructure. Expose a metrics endpoint from your build health server:

// Add to build-health-server.js
app.get('/metrics/build-success-rate', (req, res) => {
  // Query last 50 builds from Kpack
  const output = execSync('kubectl get builds.kpack.io -A -o json').toString();
  const builds = JSON.parse(output).items;
  
  const total = builds.length;
  const succeeded = builds.filter(b => 
    b.status?.conditions?.find(c => c.type === 'Succeeded')?.status === 'True'
  ).length;
  
  const rate = total > 0 ? (succeeded / total * 100).toFixed(1) : 0;
  const status = rate >= 95 ? 'ok' : 'degraded';
  
  res.status(status === 'ok' ? 200 : 503).json({
    status,
    success_rate_percent: parseFloat(rate),
    total_builds: total,
    succeeded_builds: succeeded
  });
});

Monitor this endpoint in Vigilmon with a keyword check for "status":"ok".

Step 7: Configure alerts for build pipeline failures

Go to Settings → Alerts in Vigilmon and configure routing.

Slack alert for build failures

{
  "text": "🔴 CNB Build Pipeline Alert: {{monitor.name}} is DOWN\nThis may be blocking releases.\nCheck: {{monitor.url}}\nTime: {{alert.time}}"
}

Route to your #ci-cd-alerts or #platform-team Slack channel.

PagerDuty for registry outages

Registry outages block all builds and all deployments simultaneously. Configure PagerDuty for the container registry monitor — this failure mode warrants immediate on-call escalation:

{
  "routing_key": "YOUR_PD_ROUTING_KEY",
  "event_action": "trigger",
  "payload": {
    "summary": "Container registry {{monitor.name}} is unreachable — all builds blocked",
    "severity": "critical",
    "source": "vigilmon"
  }
}

Step 8: Status page for release engineering

Create a Vigilmon status page to give your release engineering and platform teams visibility into CNB infrastructure health:

  1. Go to Status Pages → New
  2. Add all CNB monitors (build health, registry, builder image)
  3. Title it "Build Pipeline Status"
  4. Embed the status widget in your internal developer portal

What to monitor: Cloud Native Buildpacks checklist

| Component | Monitor type | What it catches | |-----------|-------------|----------------| | Build health endpoint | HTTP status | Failed or stuck Kpack image builds | | Build success rate | HTTP keyword | Degraded success rate (<95%) | | Container registry | HTTP status + latency | Registry outages and slow pushes | | Builder image manifest | HTTP status | Builder image unavailable (can't pull) | | Cache storage | HTTP via probe | Cache corruption / inaccessible layers | | TCP port on registry | TCP | Network-level registry failures |

Common Buildpacks failure patterns

DockerHub rate limiting: The free DockerHub tier rate-limits anonymous pulls to 100/6h and authenticated to 200/6h. Builder image pulls fail with toomanyrequests. The builder image monitor fires, alerting you to mirror the builder to your own registry.

Lifecycle binary fetch timeout: pack build downloads the lifecycle binary from GitHub Releases on each invocation (unless cached). GitHub Releases has occasional slowdowns. Build jobs hang at "Downloading lifecycle" for 10+ minutes. A CI runner health endpoint tracking build durations will catch this.

Kpack controller CrashLoopBackOff: The Kpack controller pod enters CrashLoopBackOff after a failed upgrade. All image builds stop triggering. The build health monitor fires within the next 2-minute check cycle.

Registry TLS certificate expiry: A self-hosted registry with a Let's Encrypt certificate fails to renew. Builds start failing with TLS verification errors. The registry HTTP monitor fires immediately on the first check after expiry.

Cache layer size limit: Some registries have maximum layer size limits. Large CNB cache layers start failing to push at exactly the limit. The build health monitor catches the degraded state from failed cache pushes.

Summary

| What | Why | |------|-----| | Build health HTTP monitor | Catches failed/stuck builds in Kpack or Tekton | | Build success rate monitor | SLO tracking — alerts when failure rate exceeds 5% | | Registry availability + latency | Registry outages block all builds; slow responses cause timeouts | | Builder image manifest check | Catches when the CNB builder image becomes inaccessible | | Alert to #ci-cd-alerts | Release engineers see build infrastructure failures immediately | | Status page | Self-service visibility for engineers wondering why CI is red |

Cloud Native Buildpacks turn source code into deployable images reliably — until they don't. Vigilmon's external monitoring gives your platform team an early warning signal when build infrastructure degrades, so release pipelines get unblocked faster.

Sign up for Vigilmon free →

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles