Put a Gateway in the Request Path

Orders runs in Mule, inventory runs in Java, and delivery estimates come from another team’s service. All three need authentication, traffic limits and a consistent public entry point, and reimplementing those controls in each service creates three places for the same policy to drift. They can share an entry policy without sharing an integration runtime: a separate gateway places that policy boundary in front of several implementation technologies.

Enforcing the policies in one place also puts another component in the request path, with its own configuration, certificates and failure modes. That boundary has a blast radius — a bad listener or authentication-policy change can affect several services even when their own deployments remain healthy. A separate gateway earns its place when several services need the same boundary and one team can own it, so the question worth asking first is where enforcement should run and who is allowed to change it.

Mule Gateway provides enforcement embedded in Mule. Omni Gateway is an independently operated, Envoy-based gateway for Mule and non-Mule services — its version and the Mule runtime’s are chosen independently. It does not execute the order application’s Mule archive or replace its database transaction and recovery logic. Gateway comparison.

For the orders API alone, embedded enforcement can mean fewer separately operated components: no self-managed gateway fleet exists simply to reach one Mule endpoint. The mixed orders, inventory and delivery estate is what makes the separate process attractive, because it supplies a common network boundary without requiring the Java inventory service to become a Mule application.

The technical interfaces still use names such as flexctl and mulesoft/flex-gateway. Omni is the product name used by the pinned gateway edition; changing those interface strings to match it would produce different, unsupported commands.

Keep the gateway configuration beside the application

In ACB Explorer, open book/platform/omni and its README. Inspect the route and policy YAML files named below using the text editor. Omni is a separate process: these files do not become Mule flow components, and ACB’s Run Mule Application command does not start a gateway.

Keep the orders application’s Listener settings visible while reviewing the upstream address and path. Run the documented gateway commands in a separate terminal only after satisfying its registration and runtime prerequisites. Retain the generated registration material outside shared source and screenshots. The exercises below distinguish the configuration to review from gateway behavior that still needs an environment test.

Choose who owns route configuration

Suppose the orders route lives in API Manager and someone adds a local ApiInstance file expecting it to override that route. The result is an uncertain deployment, and the mode is the decision that prevents it. Connected Mode obtains API and policy configuration through Anypoint’s control plane. Local Mode uses declarative gateway resources maintained by the operator’s configuration workflow. Both require registration. Mode describes configuration ownership; standalone, ingress, egress and sidecar describe placement — keep those two decisions separate.

Which mode suits you follows from who should hold the route. Connected Mode suits a team whose API operators manage instances and policies centrally, and Local Mode suits a team that wants routing and policies delivered through its own configuration pipeline. The route below is Local Mode, in one visible file, so the first gateway request does not require learning two sources of configuration at once; Appendix D preserves the Connected Mode procedure as a separate workshop.

Register before starting the gateway

Registration and startup are separate operations — creating the identity does not launch the process. Use a fresh private registration directory and an authorized gateway registration identity for the selected organization/environment. Follow the pinned version’s Local Mode registration procedure and retain registration.yaml as secret material: it carries identity, which is why the application repository ignores that file rather than treating it as an ordinary route to commit.

The companion README gives the Docker startup command and required mount. In the Docker Desktop lab, port 18880 on host loopback maps to gateway port 8080. The upstream is the host’s checkpoint on port 18881. Other container environments need an explicit supported host/network route; localhost inside a container refers to that container.

Example 074 — Route the known orders API through Omni Gateway

Source: platform/omni/orders.yaml.

apiVersion: gateway.mulesoft.com/v1alpha1
kind: ApiInstance
metadata:
  name: local-orders
spec:
  address: http://0.0.0.0:8080
  services:
    orders:
      address: http://host.docker.internal:18881/
      routes:
        - rules:
            - path: /api/orders(/.*)
  policies:
    - policyRef:
        name: rate-limiting-flex
      config:
        rateLimits:
          - maximumRequests: 5
            timePeriodInMilliseconds: 60000
        keySelector: "#[attributes.method]"
        clusterizable: false
        exposeHeaders: true

The route selects /api/orders and its child paths. It forwards the same path to the upstream; no strip-prefix or rewrite is implied. A request for /api/orders/A-1001 should therefore reach the endpoint already implemented by the companion. /lab/ diagnostics must remain unmatched.

A rate limit is easy to add and easy to misinterpret. The policy here supplies a small five-request, one-minute quota keyed by method, per replica, which is useful for observing a limit with a few calls. It is not a per-consumer allowance, and this route does not authenticate callers. For a production contract the identity comes before the number, because a group keyed by something the caller controls lets the caller create new groups by changing it. Replica count matters for the same reason: if two replicas each accept five requests, the pair is not enforcing a five-request ceiling.

Keep the experiment on loopback. Network access is what completes an enforcement boundary — if a client can call the unprotected orders service directly, gateway policy is optional from that client’s point of view. Before a public deployment, configure the chosen identity policy, upstream trust and network controls and repeat their acceptance matrix.

The source is a complete Local Mode API resource, but registration, startup, policy version resolution and traffic have not been run for this edition. A mounted YAML file is evidence of intent; traffic through the intended enforcement path is evidence of behavior, so review resource acceptance in the gateway logs before believing the route exists. Local configuration reference.

Trace one request through the new hop

A response arriving through a new hop has two possible authors, and a 5xx alone does not identify which component produced it. So prepare the upstream order first and retrieve it directly to establish the application baseline. Then retrieve through port 18880 and correlate the upstream invocation. Exercise the root path, child path, unmatched path, quota exhaustion and an unavailable upstream, and give a gateway-generated response and an application-generated response distinct operational identities.

A gateway policy migration requires tests, even when policy names resemble those on Mule Gateway. Expressions, extension mechanisms and rejection contracts differ — a migration has to inventory the supported policies and retest custom behavior rather than trust a familiar name. The gateway should enforce its boundary while the upstream application still checks trusted ownership; a new edge does not remove the application’s business authorization requirement.

Separate control-plane loss from request failure

A running gateway losing management connectivity is not the same condition as an upstream timing out. What existing configuration remains usable, what a new process requires, and which updates can be applied depend on the mode/version and retained state. An existing process may be serving traffic on configuration it loaded before the disconnection, while a replacement process still has to obtain that configuration from somewhere — so test warm disconnection and cold startup separately.

Timeouts belong to the same argument, because they now span two components. If the client abandons checkout before the gateway gives up on Mule, the service can still commit an order after the caller has seen a failure. Raising the gateway timeout changes how long it waits; it does not establish whether repeating the create-order request is safe.

A policy update can affect several upstreams simultaneously. Record the route bundle, policy versions, image digest and upstream release. Rolling back the application does not restore the gateway bundle; rolling back the gateway does not undo accepted orders.

Try it

1. Follow the path. What upstream path should a gateway request for /api/orders/A-1001 use here?

Show answer

The same /api/orders/A-1001 path. The configured route selects traffic but declares no rewrite. Test root and child cases as well as a nonmatching diagnostic path.

2. Identify the limit. Does the example quota mean five requests per retailer across all replicas?

Show answer

No. It is keyed by method and configured per replica. Consumer identity and shared accounting require a different supported policy configuration and tests.

3. Disconnect management. Why are a warm gateway and a new gateway separate tests?

Show answer

The warm process may have retained usable configuration or credentials that a new process lacks. A warm success cannot establish cold-start enforcement or update behavior during control-plane loss.

Not run. Omni Gateway 1.14.0 registration, route acceptance, policy enforcement, network topology and failure behavior remain account-dependent acceptance work. No gateway traffic was generated for this edition.

The final chapter returns to the local service and demonstrates the acceptance and recovery boundaries already implemented throughout the book.

Next: Demonstrate Acceptance and Recovery