Back to Details

omni-gateway-install

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Install Omni Gateway

安装 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).
mermaid
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]
PlatformReadCovers
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，注册到 Anypoint Platform）和本地模式（local mode，独立运行）。
mermaid
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]
平台阅读涵盖内容
Linux（Ubuntu/Debian，APT）
references/linux.md
APT 仓库设置、
flex-gateway
包、systemd 服务
Docker / Docker Compose
references/docker.md
镜像拉取、
docker run
和 Compose、
conf.d
绑定挂载
Kubernetes / OpenShift（Helm）
references/kubernetes.md
Helm 仓库、
values.yaml
、OpenShift SCC 设置
APT 指南未涵盖 RHEL、CentOS 和 Amazon Linux。请联系 MuleSoft Gateway 团队获取 RPM 仓库详情——不要在基于 RPM 的系统上使用 APT 仓库。
完成平台操作指南后，请返回此处进行连接模式验证和故障排查。

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.
所有三个平台都支持两种模式；请在开始前进行选择：
  • 连接模式（connected mode）——Gateway 注册到 Anypoint Platform，并显示在 Runtime Manager 中。需要 organization ID 和 registration token（签发 24 小时后过期）。
  • 本地模式（local mode）——Gateway 独立运行，不连接控制平面。跳过平台参考文件中的注册步骤。
每份平台参考文件都会明确说明本地模式需要跳过哪些步骤。

Confirm in Anypoint Runtime Manager (connected mode)

在 Anypoint Runtime Manager 中确认（连接模式）

After installation and registration, verify that the gateway is online.
安装并注册后，验证 Gateway 是否在线。

Option 1: Anypoint Platform UI

选项 1：Anypoint Platform UI

  1. Navigate to Anypoint Platform → Runtime Manager → Flex Gateways
  2. Find your gateway by name
  3. Confirm the status shows STARTED (green indicator)
  1. 导航至 Anypoint Platform → Runtime Manager → Flex Gateways
  2. 按名称查找 Gateway
  3. 确认状态显示 STARTED（绿色指示器）

Option 2: Flex Gateway Manager API

选项 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"
.
GET https://anypoint.mulesoft.com/flexgateway/api/v1/organizations/{orgID}/environments/{envID}/gateways/{gatewayID}
Authorization: Bearer <access-token>
预期返回 200 响应，其中包含 
"status": "STARTED"
。

Troubleshooting

故障排查

ProblemLikely CauseFix
authentication failed
or 
401 Unauthorized
Token expired or belongs to a different organizationGenerate 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 organizationVerify org ID in Anypoint Admin Settings and regenerate token in the correct organization
permission denied
or 
conf.d not writable
Output directory has restrictive permissionsRun 
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 AnypointUse 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 pathVerify 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 portChange 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 existCheck network egress rules; confirm tag with 
docker pull mulesoft/flex-gateway:<tag>
CrashLoopBackOff
(Kubernetes)		Missing registration secret, malformed ConfigMap YAML, or OpenShift SCC violationRun 
kubectl logs -n gateway deployment/ingress
Pending
pods (Kubernetes)		Resource quota or node affinity issuesRun 
kubectl describe pod -n gateway
问题可能原因修复方法
authentication failed
或 
401 Unauthorized
令牌已过期，或属于另一个组织在 Runtime Manager → Add Gateway → Self-managed 中生成新令牌，然后重新运行注册
environment not found
或 
404
Organization ID 错误，或令牌的作用范围为另一个组织在 Anypoint Admin Settings 中验证 org ID，并在正确的组织中重新生成令牌
permission denied
或 
conf.d not writable
输出目录权限受限运行 
sudo chown -R $USER /usr/local/share/mulesoft/flex-gateway/conf.d
（Linux），或调整卷权限（Docker/Kubernetes）
409 Conflict
——Gateway 已注册		Anypoint 中已存在同名 Gateway使用不同的 
<gateway-name>
，或从 Runtime Manager 中删除旧记录
重启后状态仍为 
DISCONNECTED
注册文件不在 
conf.d
中，或 Gateway 使用了错误的 
conf.d
路径		使用 
ls -la /usr/local/share/mulesoft/flex-gateway/conf.d/
进行验证；对于 Docker/Kubernetes，检查卷挂载路径
flexctl: command not found
（Linux）
flexctl
不在 
$PATH
中		重新安装 flex-gateway，或将安装目录添加到 
$PATH
容器启动后立即退出（Docker）缺少或格式错误的 
registration.yaml
、
conf.d/
权限不匹配，或端口被占用		运行 
docker logs flex-gateway
查看错误
bind: address already in use
其他进程正在占用映射端口更改宿主机端端口（例如 
-p 18081:8081
），或停止冲突进程
ImagePullBackOff
（Kubernetes）		节点无法访问 Docker Hub，或镜像 tag 不存在检查网络出站规则；使用 
docker pull mulesoft/flex-gateway:<tag>
确认 tag
CrashLoopBackOff
（Kubernetes）		缺少 registration secret、ConfigMap YAML 格式错误，或违反 OpenShift SCC 限制运行 
kubectl logs -n gateway deployment/ingress
Pod 处于 
Pending
状态（Kubernetes）		资源配额或节点亲和性问题运行 
kubectl describe pod -n gateway

Next Steps After Installation

安装后的后续步骤

Once the gateway is installed and running:
  1. Apply a policy to an API — configure API proxying and security: see 
    secure-api
    .
  2. Monitor logs — parse and interpret gateway log output: see 
    omni-gateway-logs
    .
  3. Validate your conf.d configuration — check YAML resource files for misconfigurations before deploying changes: see 
    omni-gateway-config
    .
Gateway 安装并运行后：
  1. 为 API 应用策略——配置 API 代理和安全：参见 
    secure-api
    。
  2. 监控日志——解析和解读 Gateway 日志输出：参见 
    omni-gateway-logs
    。
  3. 验证 conf.d 配置——在部署更改前检查 YAML 资源文件是否存在配置错误：参见 
    omni-gateway-config
    。

Related Jobs

相关 Job

  • omni-gateway-config
    — Validate conf.d YAML configuration
  • omni-gateway-logs
    — Parse and interpret gateway log output
  • omni-gateway-diagnose
    — End-to-end triage when the gateway returns errors
  • omni-gateway-config
    ——验证 conf.d YAML 配置
  • omni-gateway-logs
    ——解析和解读 Gateway 日志输出
  • omni-gateway-diagnose
    ——Gateway 返回错误时进行端到端故障分诊