feat(aigw): consolidate admin server into a single port (envoyproxy#1236)

**Description**

This consolidates the extproc admin server from two separate ports
(metricsPort and healthPort) into a single adminPort (default 1064)
serving both /metrics and /health endpoints. The `aigw run` and the new
`aigw healthcheck` commands now take --admin-port flags, propagating
this to extproc.

Previously, extproc exposed metrics on port 1064 and health checks on
port 1065. Now both are served from a single HTTP server on port 1064,
simplifying configuration and Docker HEALTHCHECK setup.

The Docker HEALTHCHECK is now functional, using the new healthcheck
subcommand which polls the admin server's /health endpoint. This /health
endpoint proxies to the extproc gRPC health check, returning HTTP 200
when SERVING. A new subcommand (`aigw healthcheck`) was needed as the
image is distroless (has no curl etc).

When aigw run starts Envoy, it polls for readiness using either the
Envoy admin address (when configured in EnvoyProxy bootstrap) or by
checking if the Gateway listener port accepts TCP connections. This
ensures startup completes reliably with minimal Gateway configurations.

Gateway validation now requires at least one listener to be configured.

---------

Signed-off-by: Adrian Cole <[email protected]>

Author: codefromthecrypt

Dockerfile

@@ -35,4 +35,10 @@ COPY --from=envoy-downloader /tmp/envoy-gateway /tmp/envoy-gateway
 COPY ./out/${COMMAND_NAME}-${TARGETOS}-${TARGETARCH} /app
 
 USER nonroot:nonroot
+
+# The healthcheck subcommand performs an HTTP GET to localhost:1064/healthlthy for "aigw run".
+# NOTE: This is only for aigw in practice since this is ignored by Kubernetes.
+HEALTHCHECK --interval=10s --timeout=5s --start-period=5s --retries=3 \
+    CMD ["/app", "healthcheck"]
+
 ENTRYPOINT ["/app"]

cmd/aigw/docker-compose-otel.yaml

@@ -62,7 +62,7 @@ services:
       - OPENAI_API_KEY=unused
     ports:
       - "1975:1975"  # OpenAI compatible endpoint at /v1
-      - "1064:1064"  # Prometheus endpoint at /metrics
+      - "1064:1064"  # Admin server: /metrics (Prometheus) and /health endpoints
     extra_hosts:  # localhost:host-gateway trick doesn't work with aigw
       - "host.docker.internal:host-gateway"
     command: ["run"]

cmd/aigw/docker-compose.yaml

@@ -38,7 +38,7 @@ services:
       - OPENAI_API_KEY=unused
     ports:
       - "1975:1975"  # OpenAI compatible endpoint at /v1
-      - "1064:1064"  # Prometheus endpoint at /metrics
+      - "1064:1064"  # Admin server: /metrics (Prometheus) and /health endpoints
     extra_hosts:  # localhost:host-gateway trick doesn't work with aigw
       - "host.docker.internal:host-gateway"
     command: ["run"]

cmd/aigw/healthcheck.go

@@ -0,0 +1,50 @@
+// Copyright Envoy AI Gateway Authors
+// SPDX-License-Identifier: Apache-2.0
+// The full text of the Apache license is available in the LICENSE file at
+// the root of the repo.
+
+package main
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+)
+
+// healthcheck performs an HTTP GET request to the admin server health endpoint.
+// This is used by Docker HEALTHCHECK to verify the aigw admin server is responsive.
+// It exits with code 0 on success (healthy) or 1 on failure (unhealthy).
+func healthcheck(ctx context.Context, port int, stdout, _ io.Writer) error {
+	url := fmt.Sprintf("http://localhost:%d/health", port)
+
+	client := &http.Client{
+		Timeout: 5 * time.Second,
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return fmt.Errorf("failed to create request: %w", err)
+	}
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return fmt.Errorf("failed to connect to admin server")
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("unhealthy: status %d, body: %s", resp.StatusCode, string(body))
+	}
+
+	// Optionally read and print the response for debugging
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return fmt.Errorf("failed to read response: %w", err)
+	}
+
+	_, _ = fmt.Fprintf(stdout, "%s", body)
+	return nil
+}

cmd/aigw/healthcheck_test.go

@@ -0,0 +1,81 @@
+// Copyright Envoy AI Gateway Authors
+// SPDX-License-Identifier: Apache-2.0
+// The full text of the Apache license is available in the LICENSE file at
+// the root of the repo.
+
+package main
+
+import (
+	"bytes"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strconv"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func Test_healthcheck(t *testing.T) {
+	tests := []struct {
+		name        string
+		closeServer bool
+		statusCode  int
+		respBody    string
+		expOut      string
+		expErr      string
+	}{
+		{
+			name:       "success",
+			statusCode: http.StatusOK,
+			respBody:   "OK",
+			expOut:     "OK",
+		},
+		{
+			name:       "unhealthy status",
+			statusCode: http.StatusServiceUnavailable,
+			respBody:   "not ready",
+			expErr:     "unhealthy: status 503, body: not ready",
+		},
+		{
+			name:       "internal error",
+			statusCode: http.StatusInternalServerError,
+			respBody:   "server error",
+			expErr:     "unhealthy: status 500, body: server error",
+		},
+		{
+			name:        "connection failure",
+			closeServer: true,
+			expErr:      "failed to connect to admin server",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			s := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(tt.statusCode)
+				_, _ = w.Write([]byte(tt.respBody))
+			}))
+			t.Cleanup(s.Close)
+
+			u, err := url.Parse(s.URL)
+			require.NoError(t, err)
+			port, err := strconv.Atoi(u.Port())
+			require.NoError(t, err)
+
+			if tt.closeServer {
+				s.Close()
+			}
+
+			stdout := &bytes.Buffer{}
+			err = healthcheck(t.Context(), port, stdout, nil)
+
+			if tt.expErr != "" {
+				require.Equal(t, tt.expErr, err.Error())
+				require.Empty(t, stdout.String())
+			} else {
+				require.NoError(t, err)
+				require.Equal(t, tt.expOut, stdout.String())
+			}
+		})
+	}
+}

cmd/aigw/main.go

@@ -28,6 +28,8 @@ type (
 		Translate cmdTranslate `cmd:"" help:"Translate yaml files containing AI Gateway resources to Envoy Gateway and Kubernetes resources. The translated resources are written to stdout."`
 		// Run is the sub-command parsed by the `cmdRun` struct.
 		Run cmdRun `cmd:"" help:"Run the AI Gateway locally for given configuration."`
+		// Healthcheck is the sub-command to check if the aigw server is healthy.
+		Healthcheck cmdHealthcheck `cmd:"" help:"Docker HEALTHCHECK command."`
 	}
 	// cmdTranslate corresponds to `aigw translate` command.
 	cmdTranslate struct {
@@ -36,8 +38,13 @@ type (
 	}
 	// cmdRun corresponds to `aigw run` command.
 	cmdRun struct {
-		Debug bool   `help:"Enable debug logging emitted to stderr."`
-		Path  string `arg:"" name:"path" optional:"" help:"Path to the AI Gateway configuration yaml file. Optional when at least OPENAI_API_KEY is set." type:"path"`
+		Debug     bool   `help:"Enable debug logging emitted to stderr."`
+		Path      string `arg:"" name:"path" optional:"" help:"Path to the AI Gateway configuration yaml file. Optional when at least OPENAI_API_KEY is set." type:"path"`
+		AdminPort int    `help:"HTTP port for the admin server (serves /metrics and /health endpoints)." default:"1064"`
+	}
+	// cmdHealthcheck corresponds to `aigw healthcheck` command.
+	cmdHealthcheck struct {
+		AdminPort int `help:"HTTP port for the admin server (serves /metrics and /health endpoints)." default:"1064"`
 	}
 )
 
@@ -53,10 +60,11 @@ type (
 	subCmdFn[T any] func(context.Context, T, io.Writer, io.Writer) error
 	translateFn     subCmdFn[cmdTranslate]
 	runFn           func(context.Context, cmdRun, runOpts, io.Writer, io.Writer) error
+	healthcheckFn   func(context.Context, int, io.Writer, io.Writer) error
 )
 
 func main() {
-	doMain(ctrl.SetupSignalHandler(), os.Stdout, os.Stderr, os.Args[1:], os.Exit, translate, run)
+	doMain(ctrl.SetupSignalHandler(), os.Stdout, os.Stderr, os.Args[1:], os.Exit, translate, run, healthcheck)
 }
 
 // doMain is the main entry point for the CLI. It parses the command line arguments and executes the appropriate command.
@@ -70,6 +78,7 @@ func main() {
 func doMain(ctx context.Context, stdout, stderr io.Writer, args []string, exitFn func(int),
 	tf translateFn,
 	rf runFn,
+	hf healthcheckFn,
 ) {
 	var c cmd
 	parser, err := kong.New(&c,
@@ -96,6 +105,11 @@ func doMain(ctx context.Context, stdout, stderr io.Writer, args []string, exitFn
 		if err != nil {
 			log.Fatalf("Error running: %v", err)
 		}
+	case "healthcheck":
+		err = hf(ctx, c.Healthcheck.AdminPort, stdout, stderr)
+		if err != nil {
+			log.Fatalf("Health check failed: %v", err)
+		}
 	default:
 		panic("unreachable")
 	}

cmd/aigw/main_test.go

@@ -24,6 +24,7 @@ func Test_doMain(t *testing.T) {
 		env          map[string]string
 		tf           translateFn
 		rf           runFn
+		hf           healthcheckFn
 		expOut       string
 		expPanicCode *int
 	}{
@@ -48,6 +49,9 @@ Commands:
   run [<path>] [flags]
     Run the AI Gateway locally for given configuration.
 
+  healthcheck [flags]
+    Docker HEALTHCHECK command.
+
 Run "aigw <command> --help" for more information on a command.
 `,
 			expPanicCode: ptr.To(0),
@@ -130,9 +134,11 @@ Arguments:
               least OPENAI_API_KEY is set.
 
 Flags:
-  -h, --help     Show context-sensitive help.
+  -h, --help               Show context-sensitive help.
 
-      --debug    Enable debug logging emitted to stderr.
+      --debug              Enable debug logging emitted to stderr.
+      --admin-port=1064    HTTP port for the admin server (serves /metrics and
+                           /health endpoints).
 `,
 			expPanicCode: ptr.To(0),
 		},
@@ -155,10 +161,10 @@ Flags:
 			out := &bytes.Buffer{}
 			if tt.expPanicCode != nil {
 				require.PanicsWithValue(t, *tt.expPanicCode, func() {
-					doMain(t.Context(), out, os.Stderr, tt.args, func(code int) { panic(code) }, tt.tf, tt.rf)
+					doMain(t.Context(), out, os.Stderr, tt.args, func(code int) { panic(code) }, tt.tf, tt.rf, tt.hf)
 				})
 			} else {
-				doMain(t.Context(), out, os.Stderr, tt.args, nil, tt.tf, tt.rf)
+				doMain(t.Context(), out, os.Stderr, tt.args, nil, tt.tf, tt.rf, tt.hf)
 			}
 			require.Equal(t, tt.expOut, out.String())
 		})