mulesoft Install Omni Gateway
Choose Your Platform
Pick the target platform, then read the matching reference file for the full step-by-step walkthrough. Each reference covers both connected mode (registered with Anypoint Platform) and local mode (standalone).
flowchart TD
Start{Which platform?}
Start -->|Linux Ubuntu/Debian| L[references/linux.md]
Start -->|Docker or Docker Compose| D[references/docker.md]
Start -->|Kubernetes or OpenShift| K[references/kubernetes.md]
| Platform | Read | Covers |
|---|---|---|
| Linux (Ubuntu/Debian, APT) | references/linux.md |
APT repo setup, flex-gateway package, systemd service |
| Docker / Docker Compose | references/docker.md |
Image pull, docker run and Compose, conf.d bind mount |
| Kubernetes / OpenShift (Helm) | references/kubernetes.md |
Helm repo, values.yaml, OpenShift SCC settings |
RHEL, CentOS, and Amazon Linux are not covered by the APT instructions. Contact the MuleSoft gateway team for RPM repository details — do not use the APT repository on RPM-based systems.
After completing the platform walkthrough, return here for connected-mode verification and troubleshooting.
Connected mode vs. local mode
All three platforms support two modes; pick before you start:
- Connected mode — the gateway registers with Anypoint Platform and appears in Runtime Manager. Requires an organization ID and a registration token (expires 24 hours after issue).
- Local mode — the gateway runs standalone with no control-plane connection. Skip the registration step in the platform reference.
Each platform reference spells out which steps to skip for local mode.
Confirm in Anypoint Runtime Manager (connected mode)
After installation and registration, verify that the gateway is online.
Option 1: Anypoint Platform UI
- Navigate to Anypoint Platform → Runtime Manager → Flex Gateways
- Find your gateway by name
- Confirm the status shows STARTED (green indicator)
Option 2: Flex Gateway Manager API
GET https://anypoint.mulesoft.com/flexgateway/api/v1/organizations/{orgID}/environments/{envID}/gateways/{gatewayID}
Authorization: Bearer <access-token>
Expect a 200 response with "status": "STARTED".
Troubleshooting
| Problem | Likely Cause | Fix |
|---|---|---|
authentication failed or 401 Unauthorized |
Token expired or belongs to a different organization | Generate a fresh token from Runtime Manager → Add Gateway → Self-managed, then re-run registration |
environment not found or 404 |
Organization ID wrong or token scoped to a different organization | Verify org ID in Anypoint Admin Settings and regenerate token in the correct organization |
permission denied or conf.d not writable |
Output directory has restrictive permissions | Run sudo chown -R $USER /usr/local/share/mulesoft/flex-gateway/conf.d (Linux) or adjust volume permissions (Docker/Kubernetes) |
409 Conflict — gateway already registered |
A gateway with this name already exists in Anypoint | Use a different <gateway-name> or delete the old record from Runtime Manager |
Status stays DISCONNECTED after restart |
Registration file not in conf.d, or gateway using wrong conf.d path | Verify with ls -la /usr/local/share/mulesoft/flex-gateway/conf.d/; for Docker/Kubernetes check volume mount path |
flexctl: command not found (Linux) |
flexctl is not in $PATH |
Reinstall flex-gateway or add the installation directory to $PATH |
| Container exits immediately (Docker) | Missing or malformed registration.yaml, permissions mismatch on conf.d/, or port in use |
Run docker logs flex-gateway to see the error |
bind: address already in use |
Another process is listening on the mapped port | Change the host-side port (e.g., -p 18081:8081) or stop the conflicting process |
ImagePullBackOff (Kubernetes) |
Node cannot reach Docker Hub or image tag does not exist | Check network egress rules; confirm tag with docker pull mulesoft/flex-gateway:<tag> |
CrashLoopBackOff (Kubernetes) |
Missing registration secret, malformed ConfigMap YAML, or OpenShift SCC violation | Run kubectl logs -n gateway deployment/ingress |
Pending pods (Kubernetes) |
Resource quota or node affinity issues | Run kubectl describe pod -n gateway |
Next Steps After Installation
Once the gateway is installed and running:
- Apply a policy to an API — configure API proxying and security: see
secure-api. - Monitor logs — parse and interpret gateway log output: see
omni-gateway-logs. - Validate your conf.d configuration — check YAML resource files for misconfigurations
before deploying changes: see
omni-gateway-config.
Related Jobs
omni-gateway-config— Validate conf.d YAML configurationomni-gateway-logs— Parse and interpret gateway log outputomni-gateway-diagnose— End-to-end triage when the gateway returns errors