Monitoring Ambassador API Gateway with Vigilmon

Ambassador — now called Emissary-Ingress — is a Kubernetes-native API gateway and ingress controller built on top of Envoy Proxy. It handles TLS termination, rate limiting, authentication, and routing for microservices running in your cluster. But when Ambassador itself goes down or misconfigures a route, every service behind it becomes unreachable. Vigilmon gives you continuous visibility into Ambassador's diagnostics interface, the underlying Envoy admin API, SSL certificates, and custom heartbeat checks for your critical Mappings.

What You'll Set Up

• HTTP monitor for the Ambassador diagnostics endpoint (/ambassador/v0/diag/)
• HTTP monitor for the Envoy admin API (port 8001)
• TCP port monitors for ingress traffic on ports 80 and 443
• SSL certificate expiry alerts for TLS-terminated hostnames
• Heartbeat monitoring to verify end-to-end routing health

Prerequisites

• Ambassador / Emissary-Ingress 2.x+ running in a Kubernetes cluster
• The Ambassador diagnostics service exposed (NodePort, LoadBalancer, or port-forward)
• A free Vigilmon account

Step 1: Monitor the Ambassador Diagnostics Endpoint

Ambassador exposes a built-in diagnostics UI at /ambassador/v0/diag/ that reports the health of all configured Mappings, Hosts, and listeners. Probing this endpoint confirms Ambassador's control plane is functional.

Expose the diagnostics service if it is not already reachable externally. The default service is ambassador-admin on port 8877:

kubectl port-forward svc/ambassador-admin 8877:8877 -n ambassador

For production monitoring, expose the diagnostics service via a restricted NodePort or a load balancer with IP allowlisting.

Add a Vigilmon monitor:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: https://your-cluster-host:8877/ambassador/v0/diag/
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

A 200 response confirms Ambassador's diagnostics service is up. The page also includes JSON output that integrations can parse for mapping health.

Step 2: Monitor the Envoy Admin API

Ambassador is built on Envoy Proxy. Envoy exposes an admin API on port 8001 that provides listener status, cluster health, and configuration dumps. Monitoring /ready on the Envoy admin port is a lightweight liveness check:

kubectl port-forward svc/ambassador-admin 8001:8001 -n ambassador

Add a second Vigilmon monitor:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-cluster-host:8001/ready
3. Check interval: 1 minute
4. Expected HTTP status: 200
5. Click Save.

The /ready endpoint returns LIVE when Envoy has finished initializing and is ready to accept traffic. A non-200 response or timeout means Envoy is not serving — even if the Ambassador pod appears running in kubectl get pods.

Step 3: TCP Port Monitors for Ingress Traffic

Ambassador terminates client traffic on ports 80 (HTTP) and 443 (HTTPS). A TCP check on these ports confirms the load balancer and Ambassador listener are accepting connections, independent of application-layer health.

1. Click Add Monitor → TCP Port.
2. Enter the public hostname or IP of your Ambassador load balancer service.
3. Set Port to 80.
4. Click Save.
5. Repeat for port 443.

Get the external IP with:

kubectl get svc ambassador -n ambassador
# NAME         TYPE           EXTERNAL-IP      PORT(S)
# ambassador   LoadBalancer   203.0.113.50     80:31234/TCP,443:31567/TCP

Use 203.0.113.50 (or the assigned DNS name) as the TCP monitor target.

Step 4: SSL Certificate Alerts for TLS Hostnames

Ambassador terminates TLS using certificates managed by Host resources — either provisioned by cert-manager or manually supplied as Kubernetes Secrets. Certificate renewal failures are silent until a certificate expires and clients start seeing TLS errors.

For each hostname Ambassador terminates TLS for:

1. Open the HTTP / HTTPS monitor for that hostname (or create a new one targeting https://your-app.example.com).
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

List all TLS-enabled Hosts in your cluster:

kubectl get hosts -n ambassador
# NAME              HOSTNAME                     STATE   PHASE
# example-host      api.example.com              Ready   Running

Add an SSL monitor for each HOSTNAME in the list. A 21-day window gives you enough lead time to investigate cert-manager ACME challenges or manually rotate certificates before clients are affected.

Step 5: Heartbeat Monitoring for Mapping Routing Health

Ambassador routes traffic through Mapping resources. Even when the Ambassador pod is healthy, a misconfigured Mapping or a downed upstream service can silently drop requests. A heartbeat probe that exercises an actual route end-to-end catches these failures that diagnostics-endpoint checks miss.

Create a dedicated lightweight health-check upstream — for example, a small HTTP responder that always returns 200:

apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: healthcheck-mapping
  namespace: ambassador
spec:
  hostname: api.example.com
  prefix: /ambassador-health
  service: healthcheck-svc:8080

Then set up a cron job or sidecar to ping this route and forward success signals to Vigilmon:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 5 minutes.
3. Copy the heartbeat URL: https://vigilmon.online/heartbeat/abc123.
4. Deploy a CronJob in Kubernetes that pings the route and signals success:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: ambassador-heartbeat
  namespace: ambassador
spec:
  schedule: "*/5 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: ping
            image: curlimages/curl:latest
            command:
            - sh
            - -c
            - |
              curl -sf https://api.example.com/ambassador-health && \
              curl -sf https://vigilmon.online/heartbeat/abc123
          restartPolicy: Never

If the Ambassador Mapping breaks, the first curl fails and the heartbeat URL is never pinged. Vigilmon alerts after the expected interval passes.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. Set Consecutive failures before alert to 2 on the diagnostics and Envoy admin monitors — transient pod restarts during rolling upgrades can cause a single probe to fail.
3. For the SSL monitors, set Consecutive failures to 1 — certificate expiry windows don't recover on their own.

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP — diagnostics | /ambassador/v0/diag/ on port 8877 | Ambassador control-plane failure | | HTTP — Envoy admin | /ready on port 8001 | Envoy not ready to serve traffic | | TCP port 80 | Load balancer IP | Listener down, LB misconfiguration | | TCP port 443 | Load balancer IP | TLS listener down | | SSL certificate | Each TLS hostname | Certificate expiry, renewal failure | | Cron heartbeat | /ambassador-health route | Mapping misconfiguration, upstream down |

Ambassador is the front door to your Kubernetes services — when it fails, everything fails. With Vigilmon watching the diagnostics interface, Envoy readiness, ingress ports, TLS certificates, and end-to-end routing, you catch Ambassador problems before your users do.