Monitoring Red Hat Quay Container Registry with Vigilmon

Red Hat Quay is a self-hosted container registry that teams run on OpenShift or bare Kubernetes to store, scan, and distribute container images securely. When Quay goes down, image pulls fail and deployments stall. Vigilmon gives you external uptime monitoring for your Quay instance — health endpoint checks, SSL certificate alerts, and heartbeat monitoring for Quay's background build workers.

What You'll Set Up

• HTTP uptime monitor for the Quay API health endpoint
• Registry v2 API check to confirm image pull functionality
• SSL certificate expiry alerts for the registry domain
• Cron heartbeat for Quay's background build workers
• Alert channels for on-call notification

Prerequisites

• Red Hat Quay 3.8+ running on OpenShift, Kubernetes, or Docker Compose
• HTTPS configured with a valid certificate on your registry domain
• A free Vigilmon account

Step 1: Monitor the Quay Health Endpoint

Quay exposes a built-in health endpoint at /health/instance that checks internal subsystems including database connectivity, Redis connectivity, and storage backend access. This is the primary signal that Quay is operational.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your Quay health URL: https://quay.yourdomain.com/health/instance
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

Verify the endpoint yourself before adding the monitor:

curl -s https://quay.yourdomain.com/health/instance | jq .
# {
#   "data": {
#     "services": {
#       "database": true,
#       "redis": true,
#       "storage": true
#     }
#   },
#   "status_code": 200
# }

If the response contains "status_code": 200 and all services show true, the monitor will stay green. Any service returning false changes the HTTP response code to 503, which Vigilmon will detect and alert on.

Step 2: Monitor the Container Registry v2 API

The Docker Registry v2 API base endpoint confirms that the registry can accept docker pull and docker push operations. This is distinct from Quay's internal health — the API gateway could be up while Quay's backend is degraded.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter: https://quay.yourdomain.com/v2/
3. Set Expected HTTP status to 401.
4. Set Check interval to 5 minutes.
5. Click Save.

A 401 Unauthorized response from /v2/ means the registry is up and enforcing authentication — exactly what you want. A 502, 503, or connection timeout means the registry is unreachable.

# Verify: should return 401
curl -I https://quay.yourdomain.com/v2/
# HTTP/2 401
# www-authenticate: Bearer realm="https://quay.yourdomain.com/v2/auth"

Step 3: SSL Certificate Alerts for the Registry Domain

A certificate expiry on a container registry is catastrophic — docker pull will fail for every engineer and CI pipeline across the organization. Set up early warning in Vigilmon:

1. Open the Quay health monitor created in Step 1.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 30 days.
4. Click Save.

Thirty days gives you enough buffer to renew through cert-manager, Let's Encrypt, or your enterprise CA before any outage occurs.

For Quay deployments using cert-manager on Kubernetes, check your certificate resource:

kubectl get certificate -n quay-enterprise
# NAME           READY   SECRET              AGE
# quay-tls       True    quay-tls-secret     120d

If READY is False, cert-manager failed renewal. Vigilmon's 30-day alert window gives you time to investigate before the certificate expires.

Step 4: Heartbeat Monitoring for Quay Build Workers

Quay's build system processes container image builds via background workers (the quay-builder component). These workers don't expose an HTTP endpoint — they consume a build queue and emit logs. Use Vigilmon's cron heartbeat to detect stalled or crashed build workers.

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set Expected ping interval to 10 minutes.
3. Copy the heartbeat URL: https://vigilmon.online/heartbeat/YOUR_ID

Add a liveness probe script that runs alongside your Quay build worker:

#!/bin/bash
# /usr/local/bin/quay-worker-watchdog.sh
# Run every 5 minutes via cron

# Check if quay-builder process is running
if pgrep -f "quay-builder" > /dev/null; then
    curl -s https://vigilmon.online/heartbeat/YOUR_ID
else
    echo "quay-builder not running — skipping heartbeat ping"
fi

Schedule it in cron:

*/5 * * * * /usr/local/bin/quay-worker-watchdog.sh

If the build worker crashes, the heartbeat stops pinging, and Vigilmon alerts after the 10-minute window passes.

On Kubernetes, you can ping the heartbeat from a sidecar container or a CronJob:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: quay-build-heartbeat
  namespace: quay-enterprise
spec:
  schedule: "*/5 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: ping
            image: curlimages/curl:latest
            command: ["curl", "-s", "https://vigilmon.online/heartbeat/YOUR_ID"]
          restartPolicy: OnFailure

Step 5: TCP Port Monitor for the Registry Listener

If Quay sits behind a load balancer or HAProxy, monitor the raw TCP port to catch network-layer failures that HTTP checks might miss during a partial outage:

1. Click Add Monitor → TCP Port.
2. Enter your registry host: quay.yourdomain.com
3. Set Port to 443.
4. Set Check interval to 1 minute.
5. Click Save.

This monitor fires if TLS termination fails, the load balancer drops connections, or a firewall rule blocks inbound traffic — failures that return no HTTP response at all.

Step 6: Configure Alert Channels

1. In Vigilmon, go to Alert Channels and add Slack, PagerDuty, email, or a webhook.
2. Set Consecutive failures before alert to 2 on the health and v2 API monitors to avoid noise from transient network blips.
3. Use Vigilmon's Maintenance windows to suppress alerts during planned Quay upgrades:

# Open a maintenance window before a Quay upgrade
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monitor_id": "YOUR_MONITOR_ID", "duration_minutes": 30}'

For GitOps teams, add this to your Quay upgrade pipeline so engineers aren't paged during planned maintenance.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Health endpoint | /health/instance | Database, Redis, or storage failure | | Registry v2 API | /v2/ | Registry API unavailable | | SSL certificate | Registry domain | Certificate expiry (30-day warning) | | TCP port | :443 | Network or load balancer failure | | Cron heartbeat | Heartbeat URL | Build worker crash or stall |

Quay handles image distribution for your entire organization — when it's down, every deployment pipeline stalls. With Vigilmon watching the health endpoint, v2 API, SSL certificate, and build worker heartbeat, you catch Quay issues before engineers start filing tickets wondering why their docker pull commands are failing.