# Ambassador Pattern > Choose or review a local outbound proxy when discovery or routing changes require client releases, a canary or shadow needs routing outside the app, or retries overlap across app, proxy and mesh. Define the listener, policy ownership, deadlines and failure behavior. Covers shard-map consumption and experiment routing, not shard algorithms (sharding-and-partitioning), container lifecycle (sidecar-pattern), or output normalization (adapter-sidecar-pattern). - Skill: `robsonkades/ambassador-pattern` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add robsonkades/ambassador-pattern` - Raw SKILL.md: https://api.skillmd.com/api/skills/robsonkades/ambassador-pattern/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: robsonkades (https://skillmd.com/u/robsonkades) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/robsonkades/ambassador-pattern --- # Ambassador Pattern ## Purpose and boundary An ambassador mediates the application's outbound calls through a local peer process. The app can delegate topology and transport policy, but still owns business intent and observes latency, errors and deadlines. This skill covers that delegation, not ingress gateways or the Ambassador-branded product. Pod mechanics belong to `sidecar-pattern`. Policy can change independently of application code **if** the selected proxy supports the required configuration updates. Hot reload, proxy replacement and a pod rollout have different restart consequences; name the actual update mechanism before promising no restart. ## Workflow 1. **Establish the evidence.** Obtain the outbound call path, protocols on both hops, proxy/mesh and client versions, effective routes and retry settings, deadline semantics, upstream operation contracts, replica count and relevant latency/load limits. For a diagnosis, request correlated app/proxy/upstream traces, attempt counts and queue metrics. Configuration shows intent; runtime counters and fault tests show behavior. If evidence is missing, name the gap and proceed only with conditional options, not deployable settings or a claimed root cause. For Java client or deadline changes, apply the compatibility checks in [Failure and policy composition](references/failure-and-policy-composition.md#java-client-compatibility). 2. **Choose what moves.** Inventory discovery, shard maps, retries, timeouts, pools and TLS, then assign each responsibility explicitly; the inventory is not an automatic migration list. Keep business authorization and operation identity in the application. Prefer an existing mesh when it supports the required protocol and policy; document a concrete gap before adding another proxy and specify which layer owns each overlapping function. 3. **Define the local contract.** State explicit loopback versus transparent interception, listener/port, protocol, upstream selection and TLS termination points. A dedicated TCP listener can select an upstream without parsing HTTP. Routing by path or `Host`/`:authority` requires visible HTTP; TLS pass-through cannot inspect those fields. Allowlist destinations and define missing/forged routing-key behavior. Locality alone does not authenticate callers. 4. **Check cost and failure semantics.** Compare the maintained client-library baseline with independent policy rollout and operational ownership. Measure added latency under representative concurrency and payloads; no service-count or millisecond threshold alone decides adoption. For policy migration, configuration or incidents, read [Failure and policy composition](references/failure-and-policy-composition.md). 5. **Validate the selected route.** For shards, canaries, A/B or mirroring, read [Routing and experiments](references/routing-and-experiments.md). Before shipping, exercise the real proxy version's attempt bounds, deadline expiry, failure and config rollback in an isolated environment. Report unexecuted checks explicitly. ## Decision rules - Use an ambassador when independent topology/policy changes or language coverage justify the extra process and it can implement the upstream protocol correctly. A missing SDK is not proof that a generic proxy can replace its authentication or protocol semantics. - Prefer a client library when policy changes with business code and a maintained client already meets the requirements. Keep decisions requiring unavailable application state in the application, or define a trusted metadata contract before delegating them. - Prefer one retry owner and bound **total attempts, including the original**, across all layers. Three attempts at each of two layers can yield nine upstream attempts; three retries at each can yield sixteen. A bounded retry policy permits duplicates but guarantees neither delivery nor exactly-once execution. Require idempotent semantics and replayable requests; a deduplication header alone is not evidence of server-side deduplication. - Preserve the caller's remaining deadline across the hop, including queues and backoff; a static route timeout can be an additional ceiling, not a replacement for the caller budget. - Specify failure behavior per fault: proxy unavailable, route absent, discovery stale and upstream failing. Bypass is possible only with a designed alternate path; do not silently bypass mandatory authentication, TLS or destination restrictions to improve availability. - Prefer validated, observable hot reload for frequent routing changes when supported. Controlled rollouts can suit rare changes. Both need config-version visibility, convergence checks and rollback; config acceptance is not proof that a route serves traffic correctly. ## Minimum deliverable For a small review, provide the decision or finding, evidence and consequence, proposed adjustment and the check that would confirm or refute it. For a design/configuration change, also record the local/upstream contract, policy owners, attempt/deadline bounds and failure/ rollback behavior. Separate observed facts from hypotheses; do not label a plausible proxy bottleneck a confirmed cause without measurements from both sides of the hop. When evaluating this skill or rehearsing difficult decisions, use [Validation cases](references/validation-cases.md). These are agent behavior cases, separate from tests of a deployed proxy.