add mcp ingress annotations (#1178)

## Summary

Adds annotations for experimental model context protocol support in
Pomerium.
MCP support must be enabled with `runtime_flags: mcp: true` in the
Pomerium global config.

## Related issues

<!-- For example...
Fixes #159
-->


## Checklist

- [ ] reference any related issues
- [ ] updated docs
- [ ] updated unit tests
- [ ] updated UPGRADING.md
- [x] add appropriate tag (`improvement` / `bug` / etc)
- [x] ready for review

Author: wasaga

Makefile

@@ -128,10 +128,12 @@ internal/ui/dist/index.js: internal/ui/node_modules
 	@echo "==> $@"
 	@cd internal/ui && yarn build
 
+# run the controller locally (i.e. with docker-desktop)
+# that assumes that the CRDs and ingress class are already installed
 .PHONY: run
 run: generated
 	@echo "==> $@"
-	@go run $(GOTAGS) ./main.go
+	@go run $(GOTAGS) ./main.go all-in-one --pomerium-config global --update-status-from-service=pomerium/pomerium-proxy
 
 .PHONY: docker-build
 docker-build: build test ## Build docker image with the manager.

model/ingress_config.go

@@ -52,6 +52,22 @@ const (
 	CAKey = "ca.crt"
 	// SSHPrivateKey is the ssh privatekey secret key
 	SSHPrivateKey = "ssh-privatekey"
+	// MCPServer indicates this route is an MCP server without any additional configuration
+	MCPServer = "mcp_server"
+	// MCPClient indicates this route is an MCP client without any additional configuration
+	MCPClient = "mcp_client"
+	// MCPServerMaxRequestBytes sets the maximum request body size for MCP server routes
+	MCPServerMaxRequestBytes = "mcp_server_max_request_bytes"
+	// MCPServerUpstreamOAuth2Secret references a secret containing OAuth2 configuration for MCP server upstream authentication
+	MCPServerUpstreamOAuth2Secret = "mcp_server_upstream_oauth2_secret" //nolint: gosec
+	// MCPServerUpstreamOAuth2TokenURL sets the OAuth2 token URL for MCP server upstream authentication
+	MCPServerUpstreamOAuth2TokenURL = "mcp_server_upstream_oauth2_token_url" //nolint: gosec
+	// MCPServerUpstreamOAuth2Scopes sets the OAuth2 scopes for MCP server upstream authentication
+	MCPServerUpstreamOAuth2Scopes = "mcp_server_upstream_oauth2_scopes"
+	// MCPServerUpstreamOAuth2ClientIDKey defines the key within the OAuth2 secret that contains the client ID
+	MCPServerUpstreamOAuth2ClientIDKey = "client_id"
+	// MCPServerUpstreamOAuth2ClientSecretKey defines the key within the OAuth2 secret that contains the client secret
+	MCPServerUpstreamOAuth2ClientSecretKey = "client_secret"
 )
 
 // SSHSecrets is a grouping of ssh-related secrets.

pomerium/ingress_annotations.go

@@ -3,6 +3,7 @@ package pomerium
 import (
 	"encoding/base64"
 	"fmt"
+	"strconv"
 	"strings"
 
 	envoy_config_cluster_v3 "github.com/envoyproxy/go-control-plane/envoy/config/cluster/v3"
@@ -72,6 +73,16 @@ var (
 		model.KubernetesServiceAccountTokenSecret,
 		model.SetRequestHeadersSecret,
 		model.SetResponseHeadersSecret,
+		model.MCPServerUpstreamOAuth2Secret,
+	})
+	mcpServerAnnotations = boolMap([]string{
+		model.MCPServer,
+		model.MCPServerMaxRequestBytes,
+		model.MCPServerUpstreamOAuth2TokenURL,
+		model.MCPServerUpstreamOAuth2Scopes,
+	})
+	mcpClientAnnotations = boolMap([]string{
+		model.MCPClient,
 	})
 	handledElsewhere = boolMap([]string{
 		model.PathRegex,
@@ -95,18 +106,20 @@ func boolMap(keys []string) map[string]bool {
 }
 
 type keys struct {
-	Base, Envoy, Policy, TLS, Etc, Secret map[string]string
+	Base, Envoy, Policy, TLS, Etc, Secret, MCPServer, MCPClient map[string]string
 }
 
 func removeKeyPrefix(src map[string]string, prefix string) (*keys, error) {
 	prefix = fmt.Sprintf("%s/", prefix)
 	kv := keys{
-		Base:   make(map[string]string),
-		Envoy:  make(map[string]string),
-		Policy: make(map[string]string),
-		TLS:    make(map[string]string),
-		Etc:    make(map[string]string),
-		Secret: make(map[string]string),
+		Base:      make(map[string]string),
+		Envoy:     make(map[string]string),
+		Policy:    make(map[string]string),
+		TLS:       make(map[string]string),
+		Etc:       make(map[string]string),
+		Secret:    make(map[string]string),
+		MCPServer: make(map[string]string),
+		MCPClient: make(map[string]string),
 	}
 
 	for k, v := range src {
@@ -129,6 +142,8 @@ func removeKeyPrefix(src map[string]string, prefix string) (*keys, error) {
 			{policyAnnotations, kv.Policy},
 			{tlsAnnotations, kv.TLS},
 			{secretAnnotations, kv.Secret},
+			{mcpServerAnnotations, kv.MCPServer},
+			{mcpClientAnnotations, kv.MCPClient},
 			{handledElsewhere, kv.Etc},
 		} {
 			if m.keys[k] {
@@ -167,6 +182,9 @@ func applyAnnotations(
 	if err = applySecretAnnotations(r, kv.Secret, ic.Secrets, ic.Ingress.Namespace); err != nil {
 		return err
 	}
+	if err = applyMCPAnnotations(r, kv.MCPServer, kv.MCPClient); err != nil {
+		return err
+	}
 	p := new(pomerium.Policy)
 	r.Policies = []*pomerium.Policy{p}
 	if err := unmarshalPolicyAnnotations(p, kv.Policy); err != nil {
@@ -285,6 +303,47 @@ func applySecretAnnotations(
 				return nil
 			},
 		},
+		model.MCPServerUpstreamOAuth2Secret: {
+			corev1.SecretTypeOpaque,
+			func(data map[string][]byte) error {
+				clientID, hasClientID := data[model.MCPServerUpstreamOAuth2ClientIDKey]
+				clientSecret, hasClientSecret := data[model.MCPServerUpstreamOAuth2ClientSecretKey]
+
+				if !hasClientID && !hasClientSecret {
+					return fmt.Errorf("secret must have at least one of %s or %s keys",
+						model.MCPServerUpstreamOAuth2ClientIDKey, model.MCPServerUpstreamOAuth2ClientSecretKey)
+				}
+
+				if r.Mcp == nil {
+					r.Mcp = &pomerium.MCP{
+						Mode: &pomerium.MCP_Server{
+							Server: &pomerium.MCPServer{},
+						},
+					}
+				} else if r.Mcp.GetServer() == nil {
+					if r.Mcp.GetClient() != nil {
+						return fmt.Errorf("route is already configured as MCP client, cannot add OAuth2 secret")
+					}
+					r.Mcp.Mode = &pomerium.MCP_Server{
+						Server: &pomerium.MCPServer{},
+					}
+				}
+
+				server := r.Mcp.GetServer()
+				if server.UpstreamOauth2 == nil {
+					server.UpstreamOauth2 = &pomerium.UpstreamOAuth2{}
+				}
+
+				if hasClientID {
+					server.UpstreamOauth2.ClientId = string(clientID)
+				}
+				if hasClientSecret {
+					server.UpstreamOauth2.ClientSecret = string(clientSecret)
+				}
+
+				return nil
+			},
+		},
 	}
 
 	for key, secretName := range annotations {
@@ -310,6 +369,113 @@ func applySecretAnnotations(
 	return nil
 }
 
+func applyMCPAnnotations(r *pomerium.Route, serverKVs, clientKVs map[string]string) error {
+	hasServer := len(serverKVs) > 0
+	hasClient := len(clientKVs) > 0
+
+	if hasServer && hasClient {
+		return fmt.Errorf("cannot specify both MCP server and client configurations")
+	}
+
+	if hasServer {
+		return applyMCPServerAnnotations(r, serverKVs)
+	}
+
+	if hasClient {
+		return applyMCPClientAnnotations(r, clientKVs)
+	}
+
+	r.Mcp = nil
+	return nil
+}
+
+func applyMCPServerAnnotations(r *pomerium.Route, kvs map[string]string) error {
+	// Initialize or get existing server config
+	var serverConfig *pomerium.MCPServer
+	if r.Mcp != nil && r.Mcp.GetServer() != nil {
+		serverConfig = r.Mcp.GetServer()
+	} else {
+		serverConfig = &pomerium.MCPServer{}
+	}
+
+	for k, v := range kvs {
+		if v == "" && k != model.MCPServer {
+			continue
+		}
+		switch k {
+		case model.MCPServer:
+			if v != "" && v != "true" {
+				return fmt.Errorf("mcp_server annotation should be 'true' or omitted, got %q", v)
+			}
+			continue
+		case model.MCPServerMaxRequestBytes:
+			val, err := strconv.ParseUint(v, 10, 32)
+			if err != nil {
+				return fmt.Errorf("invalid max_request_bytes value %q: %w", v, err)
+			}
+			maxBytes := uint32(val)
+			serverConfig.MaxRequestBytes = &maxBytes
+		case model.MCPServerUpstreamOAuth2TokenURL:
+			if serverConfig.UpstreamOauth2 == nil {
+				serverConfig.UpstreamOauth2 = &pomerium.UpstreamOAuth2{}
+			}
+			if serverConfig.UpstreamOauth2.Oauth2Endpoint == nil {
+				serverConfig.UpstreamOauth2.Oauth2Endpoint = &pomerium.OAuth2Endpoint{}
+			}
+			serverConfig.UpstreamOauth2.Oauth2Endpoint.TokenUrl = v
+		case model.MCPServerUpstreamOAuth2Scopes:
+			if serverConfig.UpstreamOauth2 == nil {
+				serverConfig.UpstreamOauth2 = &pomerium.UpstreamOAuth2{}
+			}
+			serverConfig.UpstreamOauth2.Scopes = strings.Split(v, ",")
+			for i, scope := range serverConfig.UpstreamOauth2.Scopes {
+				serverConfig.UpstreamOauth2.Scopes[i] = strings.TrimSpace(scope)
+			}
+		default:
+			return fmt.Errorf("unknown MCP server annotation %s", k)
+		}
+	}
+
+	// Only create new MCP structure if it doesn't exist
+	if r.Mcp == nil {
+		r.Mcp = &pomerium.MCP{
+			Mode: &pomerium.MCP_Server{
+				Server: serverConfig,
+			},
+		}
+	} else if r.Mcp.GetServer() == nil {
+		if r.Mcp.GetClient() != nil {
+			return fmt.Errorf("route is already configured as MCP client, cannot add server configuration")
+		}
+		r.Mcp.Mode = &pomerium.MCP_Server{
+			Server: serverConfig,
+		}
+	}
+	return nil
+}
+
+func applyMCPClientAnnotations(r *pomerium.Route, kvs map[string]string) error {
+	for k, v := range kvs {
+		switch k {
+		case model.MCPClient:
+			if v != "" && v != "true" {
+				return fmt.Errorf("mcp_client annotation should be 'true' or omitted, got %q", v)
+			}
+			continue
+		default:
+			return fmt.Errorf("unknown MCP client annotation %s", k)
+		}
+	}
+
+	clientConfig := &pomerium.MCPClient{}
+	r.Mcp = &pomerium.MCP{
+		Mode: &pomerium.MCP_Client{
+			Client: clientConfig,
+		},
+	}
+	return nil
+}
+
 func b64(secret *corev1.Secret, annotation, key string) (string, error) {
 	data := secret.Data[key]
 	if len(data) == 0 {