Monitoring regclient with Vigilmon: Keeping Your OCI Registry CLI and Library Healthy

regclient is a Go CLI and library for interacting with OCI-compliant registries — pulling manifests, copying images between registries, tagging and deleting images, and inspecting layer content without pulling entire images to disk. Teams use regclient to build image promotion pipelines, mirror production registries, automate tag lifecycle management, and inspect image metadata at scale. When the registries regclient depends on go down — or when regclient-based automation jobs start failing silently — image promotion stops, mirroring drifts out of sync, and artifact pipelines break. Vigilmon gives you external monitoring that watches the registries regclient talks to and validates that your regclient automation jobs are completing successfully.

What You'll Build

• Vigilmon HTTP monitors for the OCI registry endpoints regclient targets
• A heartbeat monitor that validates image copy/promotion jobs are completing
• A tag inventory probe that verifies expected tags exist after automation runs
• Alert channels routed to your platform engineering team

Prerequisites

• regclient installed (regctl, regsync, or regbot) and running in your environment
• At least one OCI-compliant registry (Docker Hub, GHCR, ECR, Harbor, Quay, or self-hosted)
• A free account at vigilmon.online

Why Monitoring regclient Matters

regclient is typically embedded in automated image promotion and mirroring pipelines. Its failure modes are largely silent from an operator's perspective:

Registry connectivity loss prevents regclient from completing copy or tag operations. A regsync job that cannot reach the source registry will log an error and exit non-zero — but without a monitor watching job completion, your image mirror drifts out of date silently. Production systems reading from the mirror continue serving stale images.

Partial copy failures are the hardest regclient failure to detect. If a multi-platform image copy partially succeeds — individual platform manifests copied but the index manifest not updated — consumers may pull architecture-mismatched images without any error at the pull layer, only discovering the problem at runtime.

Tag management job failures silently leave stale tags or fail to create new ones. A pipeline that tags latest after a successful build may fail if the registry is briefly unavailable at tag time, leaving latest pointing to an older image indefinitely.

Rate limiting and authentication expiry cause regclient operations to fail transiently. These failures are often invisible in metrics dashboards because the job was never instrumented.

External monitoring with Vigilmon catches registry outages and validates job completion from outside the pipeline.

Step 1: Monitor the OCI Registry API Endpoint

regclient communicates with registries over the OCI Distribution API. Monitor the registry's /v2/ base endpoint, which all OCI-compliant registries expose:

# Verify the registry API is reachable
curl -I https://registry.yourdomain.com/v2/
# Expected: 200 OK (for public/anonymous) or 401 Unauthorized (for authenticated registries)
# Both 200 and 401 confirm the API is alive

In the Vigilmon dashboard:

1. Go to Add Monitor → HTTP
2. Configure:

| Field | Value | |---|---| | Name | OCI registry /v2/ | | URL | https://registry.yourdomain.com/v2/ | | Method | GET | | Expected status | 200, 401 | | Check interval | 1 minute | | Timeout | 10 seconds | | Alert after | 2 consecutive failures |

The /v2/ endpoint is the universal OCI registry health signal. A 401 is expected for authenticated registries (the Www-Authenticate header tells clients how to authenticate) and is just as valid as a 200 for confirming the registry process is alive.

Step 2: Monitor Registry Catalog or Specific Repository

If you're monitoring a self-hosted registry (Harbor, Distribution, Quay), add a catalog or repository-level probe for deeper validation:

# Check a specific repository is accessible
curl -H "Authorization: Bearer $TOKEN" \
  https://registry.yourdomain.com/v2/myorg/myimage/tags/list
# Expected: {"name":"myorg/myimage","tags":["latest","v1.2.3"]}

In Vigilmon:

| Field | Value | |---|---| | Name | registry myorg/myimage tags | | URL | https://registry.yourdomain.com/v2/myorg/myimage/tags/list | | Method | GET | | Request headers | Authorization: Bearer YOUR_READ_TOKEN | | Expected status | 200 | | Response body contains | tags | | Check interval | 5 minutes | | Timeout | 15 seconds | | Alert after | 2 consecutive failures |

Step 3: Heartbeat Monitor for Image Copy Jobs

The most critical regclient automation is the image copy/sync pipeline. Add a heartbeat that your regsync or custom copy jobs ping after each successful run:

# regsync-config.yml — add a postScript to ping Vigilmon on success
sync:
  - source: registry.source.com/myorg/myimage
    target: registry.target.com/myorg/myimage
    type: repository
    tags:
      allow:
        - "v[0-9]+\\.[0-9]+\\.[0-9]+"
        - "latest"

# Wrap the regsync call in a shell script that reports heartbeat

Create a wrapper script for your regsync cron job:

#!/bin/bash
# regsync-with-heartbeat.sh
set -e

HEARTBEAT_URL="${VIGILMON_REGSYNC_HEARTBEAT_URL}"

echo "Starting regsync image copy at $(date)"

if regsync sync --config /etc/regsync/config.yml; then
    echo "regsync completed successfully at $(date)"
    curl -fsS --max-time 10 "$HEARTBEAT_URL" > /dev/null
    echo "Heartbeat sent to Vigilmon"
else
    echo "ERROR: regsync failed at $(date)" >&2
    exit 1
fi

Deploy as a Kubernetes CronJob:

# regsync-cronjob.yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: regsync-image-mirror
  namespace: platform-engineering
spec:
  schedule: "*/30 * * * *"
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 3
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: regsync
              image: ghcr.io/regclient/regsync:latest
              env:
                - name: VIGILMON_REGSYNC_HEARTBEAT_URL
                  valueFrom:
                    secretKeyRef:
                      name: vigilmon-secrets
                      key: regsync-heartbeat-url
              volumeMounts:
                - name: regsync-config
                  mountPath: /etc/regsync
              command:
                - /bin/sh
                - -c
                - |
                  set -e
                  regsync sync --config /etc/regsync/config.yml
                  wget -qO- "$VIGILMON_REGSYNC_HEARTBEAT_URL"
                  echo "Heartbeat sent"
          volumes:
            - name: regsync-config
              configMap:
                name: regsync-config

Create the heartbeat monitor in Vigilmon:

1. Add Monitor → Heartbeat
2. Name: regsync image mirror
3. Expected interval: 30 minutes
4. Grace period: 15 minutes

Step 4: Validate Tag Existence After Promotion

Image promotion pipelines often fail to create the expected tag without surfacing an error to callers. Add a probe that verifies expected tags exist after promotion runs:

# regclient-tag-probe.yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: regclient-tag-probe
  namespace: platform-engineering
spec:
  schedule: "*/15 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: tag-probe
              image: ghcr.io/regclient/regctl:latest
              env:
                - name: REGISTRY
                  value: "registry.yourdomain.com"
                - name: IMAGE
                  value: "myorg/myimage"
                - name: EXPECTED_TAG
                  value: "latest"
                - name: HEARTBEAT_URL
                  valueFrom:
                    secretKeyRef:
                      name: vigilmon-secrets
                      key: regclient-tag-heartbeat-url
              command:
                - /bin/sh
                - -c
                - |
                  set -e

                  # Check the expected tag exists and resolves to a valid manifest
                  if regctl manifest get "$REGISTRY/$IMAGE:$EXPECTED_TAG" > /dev/null 2>&1; then
                    echo "Tag $EXPECTED_TAG exists and resolves correctly"
                    wget -qO- "$HEARTBEAT_URL"
                    echo "Tag validation heartbeat sent"
                  else
                    echo "ERROR: Tag $EXPECTED_TAG missing or manifest fetch failed" >&2
                    exit 1
                  fi

Create the heartbeat monitor in Vigilmon:

1. Add Monitor → Heartbeat
2. Name: regclient tag validation
3. Expected interval: 15 minutes
4. Grace period: 10 minutes

Step 5: Monitor regbot Policy Jobs

If you use regbot to automate tag lifecycle policies (expiring old tags, enforcing retention), monitor that policy runs are completing:

#!/bin/bash
# regbot-with-heartbeat.sh
set -e

HEARTBEAT_URL="${VIGILMON_REGBOT_HEARTBEAT_URL}"

if regbot once --config /etc/regbot/config.yml; then
    curl -fsS --max-time 10 "$HEARTBEAT_URL" > /dev/null
    echo "regbot policy run complete, heartbeat sent"
else
    echo "ERROR: regbot policy run failed" >&2
    exit 1
fi

Create the heartbeat monitor in Vigilmon:

1. Add Monitor → Heartbeat
2. Name: regbot tag lifecycle policy
3. Expected interval: match your regbot schedule (e.g., 1 hour for hourly policy runs)
4. Grace period: 15 minutes

Step 6: Configure Alert Channels

Route regclient alerts to your platform engineering team:

1. In Vigilmon: Alert Channels → Add Channel → Slack Webhook
2. Add your #platform-engineering webhook URL
3. Assign to all regclient monitors

For the image mirror heartbeat (sync drift can be a security issue if the mirror serves outdated images):

1. Alert Channels → Add Channel → PagerDuty or email
2. Add your on-call rotation
3. Assign to the regsync image mirror heartbeat

Create the Kubernetes secret:

kubectl create secret generic vigilmon-secrets \
  --from-literal=regsync-heartbeat-url='https://vigilmon.online/heartbeat/YOUR_REGSYNC_TOKEN' \
  --from-literal=regclient-tag-heartbeat-url='https://vigilmon.online/heartbeat/YOUR_TAG_TOKEN' \
  --from-literal=regbot-heartbeat-url='https://vigilmon.online/heartbeat/YOUR_REGBOT_TOKEN' \
  -n platform-engineering

What You're Now Monitoring

| Component | Monitor Type | What It Detects | |---|---|---| | OCI registry /v2/ | HTTP GET | Registry process down, API unreachable | | Repository tag list | HTTP GET | Specific repository or namespace unavailable | | regsync image mirror | Heartbeat (30 min) | Mirror job failed or stalled | | Tag validation probe | Heartbeat (15 min) | Expected tags missing after promotion | | regbot policy runs | Heartbeat (schedule) | Lifecycle policy job crashed |

Conclusion

regclient is powerful precisely because it operates without pulling full image layers — but that efficiency makes its failures easy to miss. A regsync mirror job that failed at 2am leaves no obvious trace until a developer pulls from the mirror and gets a days-old image. A regbot policy run that crashed leaves tags piling up with no cleanup. External monitoring with Vigilmon catches these failures from outside the pipeline by validating both registry reachability and job completion.

Get started free at vigilmon.online. The registry /v2/ probe and regsync heartbeat together give you the two most critical regclient signals in under ten minutes: is the registry reachable, and is the mirror pipeline keeping pace?