tutorial

Monitoring Emissary-Ingress with Vigilmon

Emissary-Ingress routes all your Kubernetes traffic — if it misconfigures a route or its Envoy proxy crashes, every downstream service goes dark. Here's how to monitor Emissary-Ingress health with Vigilmon.

Emissary-Ingress (formerly Ambassador API Gateway) is an open-source Kubernetes ingress controller built on Envoy Proxy. It handles edge routing, TLS termination, rate limiting, and authentication for all traffic entering your cluster. Because Emissary sits in front of every service, a misconfiguration or crash propagates immediately to all your APIs and apps — but Kubernetes itself won't flag it as a problem unless pods crash entirely. That's where Vigilmon comes in. Monitor your Emissary-Ingress routes from outside the cluster so you catch routing failures, Envoy misconfigurations, and TLS issues the moment they hit users.

What You'll Set Up

  • HTTP monitors for routes managed by Emissary-Ingress
  • TCP monitor for the Emissary-Ingress admin/diagnostics port
  • HTTP monitor for the Envoy stats endpoint
  • Alert channel to page your team when a route stops working

Prerequisites

  • Emissary-Ingress installed in your Kubernetes cluster (emissary-ingress namespace)
  • At least one Mapping or Host resource configured and serving traffic
  • A free Vigilmon account
  • kubectl access to your cluster

Step 1: Identify Your Emissary-Ingress Routes

Emissary-Ingress uses Mapping CRDs to route traffic to backend services. List all active mappings:

# List all Mappings across the cluster
kubectl get mappings -A

# Show a specific Mapping
kubectl describe mapping my-api-mapping -n production

Each mapping exposes an external route through your LoadBalancer or NodePort. Get the external IP:

kubectl get svc -n emissary-ingress
# NAME                        TYPE           EXTERNAL-IP      PORT(S)
# emissary-ingress            LoadBalancer   203.0.113.50     80:31000/TCP,443:31443/TCP

Test your routes:

# Test a mapped route
curl -v https://api.example.com/v1/users

# Check Emissary's built-in diagnostics page
curl http://203.0.113.50:8877/ambassador/v0/diag/

Step 2: Add HTTP Monitors for Your Mapped Routes

Every route managed by Emissary-Ingress should have a Vigilmon HTTP monitor. Emissary configuration errors (bad Mapping, certificate issues, service selectors pointing at deleted pods) result in 404s, 503s, or connection resets — exactly what Vigilmon detects.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Select HTTP / HTTPS.
  3. Enter a mapped route URL: https://api.example.com/v1/health.
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

Add monitors for all critical routes:

# List all Hosts managed by Emissary
kubectl get hosts -A
# NAME               HOSTNAME              STATE   PHASE COMPLETED  PHASE PENDING  MESSAGE
# api.example.com    api.example.com       Ready
# app.example.com    app.example.com       Ready

Create a Vigilmon monitor for each Host. A Host resource that leaves STATE stuck at Pending means TLS provisioning failed — Vigilmon will catch the resulting HTTPS failure within a minute.

For routes that don't have a dedicated health endpoint, monitor the root or a lightweight path that exercises the routing layer:

# Emissary Mapping example — ensures a /health path is routed
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: my-api-health
  namespace: production
spec:
  hostname: "api.example.com"
  prefix: /health
  service: my-api:80

Step 3: Monitor the Emissary Diagnostics Endpoint

Emissary-Ingress exposes a diagnostics page on port 8877 that shows routing table status and Envoy configuration. Monitor this port via TCP to confirm the admin plane is alive:

  1. In Vigilmon, click Add Monitor → TCP.
  2. Enter your LoadBalancer IP and port: 203.0.113.50 : 8877.
  3. Set Check interval to 1 minute.
  4. Click Save.

If you expose the diagnostics endpoint internally on a separate Service, you can also add an HTTP monitor:

# Verify diagnostics is reachable
curl http://emissary-diagnostics.emissary-ingress.svc.cluster.local:8877/ambassador/v0/diag/

# Check if any Mappings are in error state
curl -s http://emissary-diagnostics:8877/ambassador/v0/diag/ | \
  python3 -c "import json,sys; d=json.load(sys.stdin); [print(r) for r in d.get('errors',[])]"

A non-responsive diagnostics port often precedes routing failures — catching it early via Vigilmon buys you time to investigate before users are affected.

Step 4: Monitor TLS Certificate Health

Emissary-Ingress manages TLS via Host resources, often backed by cert-manager. Certificate renewal failures are silent until HTTPS stops working.

  1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
  2. Enter your HTTPS endpoint: https://api.example.com/health.
  3. Enable SSL certificate expiry monitoring.
  4. Set an alert threshold of 14 days before expiry.
  5. Click Save.

Also check your cert-manager Certificate resources directly:

# List all certificates and their expiry
kubectl get certificates -A
# NAME        READY   SECRET          AGE
# api-tls     True    api-tls-secret  30d

# Describe to see renewal status
kubectl describe certificate api-tls -n production

Vigilmon's TLS monitoring catches cert-manager failures from the outside, regardless of whether kubectl shows the Certificate as Ready.

Step 5: Set Up Alert Channels and Escalation

Emissary-Ingress sits in front of everything, so a failure is high priority:

  1. Go to Alert Channels in Vigilmon.
  2. Add your on-call Slack channel, email list, or PagerDuty integration.
  3. Set Consecutive failures before alert to 1 for production routes — a single failure from multiple regions means the route is broken.
  4. Assign channels to all route monitors and the TCP admin port monitor.

When you update Emissary configuration (new Mapping, CRD upgrades, Envoy version bumps), create a maintenance window to suppress flap alerts during the rollout:

curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "abc123", "duration_minutes": 10}'

Step 6: Correlate Vigilmon Alerts with Emissary Diagnostics

When Vigilmon fires an alert for a route, use these commands to isolate the failure:

# Check if Emissary pods are running
kubectl get pods -n emissary-ingress

# Check the routing table for the failing host
kubectl get mappings -n production -l hostname=api.example.com

# Look for Ambassador/Envoy errors in logs
kubectl logs -n emissary-ingress \
  -l app.kubernetes.io/name=emissary-ingress \
  --since=5m | grep -i error

# Verify the backend service has healthy endpoints
kubectl get endpoints my-api -n production

If endpoints is empty, your Service selector doesn't match any pods — the route is live in Emissary but sending requests to nothing. Vigilmon's 503 alert tells you users are broken; the endpoints command tells you why.

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP health | Each Emissary-managed route | Mapping errors, 404s, 503s, crashed backends | | HTTP health | HTTPS with SSL expiry | TLS failures, cert-manager renewal issues | | TCP | Port 8877 (diagnostics) | Admin plane failure, Envoy crash |

Emissary-Ingress is the front door to your cluster. Vigilmon watches that door from outside, so you know immediately when traffic stops flowing — before users tell you.

Get started free at vigilmon.online — no credit card, monitors running in under a minute.

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