omni-gateway-dump

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Analyze Gateway Dump

分析 Gateway Dump

Dump Format Reference

转储格式参考

The dump is a ZIP archive containing a

dump/

directory with flat JSON files. Each JSON file holds an array of Kubernetes-style resources with

apiVersion

kind

metadata

spec

, and

status

fields.

dump-<timestamp>.zip
└── dump/
    ├── api-instances.json        # Live ApiInstance resources
    ├── policy-bindings.json      # Live PolicyBinding resources
    ├── services.json             # Live Service resources
    ├── configurations.json       # Gateway Configuration (includes registration)
    ├── extensions.json           # Policy extension definitions (may be large — skip unless needed)
    └── control-node-storage.json # Gateway agent ID: {"store": "<agentId>"}

Note: dumps from newer gateway versions may include additional files. Index all files found.

该转储是一个 ZIP 压缩包，内含一个

dump/

目录，其中存放扁平结构的 JSON 文件。每个 JSON 文件都包含一个 Kubernetes 风格资源数组，资源带有

apiVersion

、

kind

、

metadata

、

spec

和

status

字段。

dump-<timestamp>.zip
└── dump/
    ├── api-instances.json        # Live ApiInstance resources
    ├── policy-bindings.json      # Live PolicyBinding resources
    ├── services.json             # Live Service resources
    ├── configurations.json       # Gateway Configuration (includes registration)
    ├── extensions.json           # Policy extension definitions (may be large — skip unless needed)
    └── control-node-storage.json # Gateway agent ID: {"store": "<agentId>"}

注意：较新 Gateway 版本的转储可能包含额外文件。请为找到的所有文件建立索引。

Key Fields to Read Per Resource

每个资源需要读取的关键字段

```
metadata.name
```
— resource identity
```
metadata.namespace
```
— resource scope (
```
default
```
,
```
gateway
```
, or environment UUID)

metadata.labels["flex.mulesoft.com/deployment-desired-status"]

— on ApiInstances:

STARTED

STOPPED

```
spec
```
— the live deployed configuration

status.conditions

—

[{type: "Ready", status: "True|False"}]

indicates operational state

```
metadata.name
```
— 资源标识
```
metadata.namespace
```
— 资源作用域（
```
default
```
、
```
gateway
```
或环境 UUID）

metadata.labels["flex.mulesoft.com/deployment-desired-status"]

— 对于 ApiInstances：

STARTED

或

STOPPED

```
spec
```
— 实时部署的配置

status.conditions

—

[{type: "Ready", status: "True|False"}]

表示运行状态

Sample Resource Structure

资源结构示例

An ApiInstance has:

json

{
  "apiVersion": "gateway.mulesoft.com/v1beta1",
  "kind": "ApiInstance",
  "metadata": {
    "name": "apii-4808971-flex-test-api",
    "namespace": "676c8822-4ae3-44c2-afd8-df46ae69f202",
    "labels": {
      "flex.mulesoft.com/apiinstance-id": "4808971",
      "flex.mulesoft.com/apiinstance-name": "flex-test-api",
      "flex.mulesoft.com/deployment-desired-status": "STARTED"
    }
  },
  "spec": {
    "address": "http://0.0.0.0:8081/",
    "policies": [...]
  },
  "status": {
    "conditions": [{"type": "Ready", "status": "True"}]
  }
}

A PolicyBinding has:

json

{
  "apiVersion": "gateway.mulesoft.com/v1alpha1",
  "kind": "PolicyBinding",
  "metadata": {"name": "internal-pe-env-api-context", "namespace": "default"},
  "spec": {
    "targetRef": {"kind": "Selector", "selector": {"kind": "ApiInstance"}},
    "policyRef": {"name": "api-context"}
  },
  "status": {"conditions": [{"type": "Ready", "status": "True"}]}
}

A Configuration entry (for registration):

json

{
  "apiVersion": "gateway.mulesoft.com/v1alpha1",
  "kind": "Configuration",
  "metadata": {"name": "registration"},
  "spec": {
    "platformConnection": {
      "agentId": "3710bdd7-...",
      "anypoint": "https://anypoint.mulesoft.com",
      "assetName": "flex1"
    }
  }
}

一个 ApiInstance 包含：

json

{
  "apiVersion": "gateway.mulesoft.com/v1beta1",
  "kind": "ApiInstance",
  "metadata": {
    "name": "apii-4808971-flex-test-api",
    "namespace": "676c8822-4ae3-44c2-afd8-df46ae69f202",
    "labels": {
      "flex.mulesoft.com/apiinstance-id": "4808971",
      "flex.mulesoft.com/apiinstance-name": "flex-test-api",
      "flex.mulesoft.com/deployment-desired-status": "STARTED"
    }
  },
  "spec": {
    "address": "http://0.0.0.0:8081/",
    "policies": [...]
  },
  "status": {
    "conditions": [{"type": "Ready", "status": "True"}]
  }
}

一个 PolicyBinding 包含：

json

{
  "apiVersion": "gateway.mulesoft.com/v1alpha1",
  "kind": "PolicyBinding",
  "metadata": {"name": "internal-pe-env-api-context", "namespace": "default"},
  "spec": {
    "targetRef": {"kind": "Selector", "selector": {"kind": "ApiInstance"}},
    "policyRef": {"name": "api-context"}
  },
  "status": {"conditions": [{"type": "Ready", "status": "True"}]}
}

一个 Configuration 条目（用于注册）：

json

{
  "apiVersion": "gateway.mulesoft.com/v1alpha1",
  "kind": "Configuration",
  "metadata": {"name": "registration"},
  "spec": {
    "platformConnection": {
      "agentId": "3710bdd7-...",
      "anypoint": "https://anypoint.mulesoft.com",
      "assetName": "flex1"
    }
  }
}

Analysis Checklist

分析检查清单

Step 1 — Unzip and index

第 1 步 — 解压并建立索引

Extract the dump and list all files:

bash

unzip dump.zip -d dump-analysis/
ls -la dump-analysis/dump/

For each JSON file, count the resources and record in a table:

File	Resource Count	Notes
api-instances.json
policy-bindings.json
services.json
configurations.json
extensions.json		Skip unless investigating a specific policy
control-node-storage.json	—	Agent ID only

If additional files are present, note them in a "Other files" section.

Also record gateway metadata from:

Agent ID:
```
control-node-storage.json
```
→
```
store
```
value

Platform connection:

configurations.json

→ resource with

metadata.name: registration

→

spec.platformConnection.anypoint

spec.platformConnection.assetName

Dump timestamp: ZIP filename (format:
```
dump-<timestamp>.zip
```
)

解压转储并列出所有文件：

bash

unzip dump.zip -d dump-analysis/
ls -la dump-analysis/dump/

对于每个 JSON 文件，统计资源数量并记录在表中：

文件	资源数量	备注
api-instances.json
policy-bindings.json
services.json
configurations.json
extensions.json		除非正在调查特定策略，否则跳过
control-node-storage.json	—	仅包含 Agent ID

如果存在其他文件，请在“其他文件”部分中注明。

还要从以下位置记录 Gateway 元数据：

Agent ID：
```
control-node-storage.json
```
→
```
store
```
值

平台连接：

configurations.json

→

metadata.name: registration

的资源 →

spec.platformConnection.anypoint

、

spec.platformConnection.assetName

转储时间戳： ZIP 文件名（格式：
```
dump-<timestamp>.zip
```
）

Step 2 — Build resource inventory

第 2 步 — 构建资源清单

Read all resources from

api-instances.json

policy-bindings.json

services.json

, and

configurations.json

. For each, produce a comprehensive table:

Kind	Name	Namespace	Ready Status	Desired Status	Notes

Populate columns:

Ready Status: Extract from
```
status.conditions[type="Ready"].status
```
. If absent, mark as
```
Unknown
```
.
Desired Status: For ApiInstances, extract from
```
metadata.labels["flex.mulesoft.com/deployment-desired-status"]
```
. For other resources, leave blank.
Notes: Any critical field values, label context, or anomalies observed.

Sort by resource kind, then by namespace, then by name for readability.

读取

api-instances.json

、

policy-bindings.json

、

services.json

和

configurations.json

中的所有资源。为每个资源生成一张综合表：

类型	名称	命名空间	就绪状态	期望状态	备注

填充以下列：

就绪状态： 从
```
status.conditions[type="Ready"].status
```
中提取。如果不存在，则标记为
```
Unknown
```
。
期望状态： 对于 ApiInstances，从
```
metadata.labels["flex.mulesoft.com/deployment-desired-status"]
```
中提取。对于其他资源，留空。
备注： 记录任何关键字段值、标签上下文或观察到的异常。

为了便于阅读，按资源类型、命名空间、名称依次排序。

Step 3 — Cross-reference PolicyBindings → ApiInstances

第 3 步 — 交叉核对 PolicyBindings → ApiInstances

For each PolicyBinding in the inventory:

Check the
```
spec.targetRef
```
field:
- If
  kind: ApiInstance
  with
  name
  : Verify that
```
name
```
  exactly matches an ApiInstance in
```
api-instances.json
```
  . If no match, flag as orphaned (the policy references a non-existent API instance and will silently not apply).
- If
  kind: Selector
  with
  selector.kind: ApiInstance
  : The policy is global and applies to all ApiInstances. This is valid; note it in the table but do not flag as an error.
- If
  kind
  is something else or
  targetRef
  is malformed: Flag as malformed.
For each orphaned or malformed PolicyBinding, record:
- PolicyBinding name
- Reason (e.g., "targetRef.name 'xyz' does not match any ApiInstance")

对于清单中的每个 PolicyBinding：

检查
```
spec.targetRef
```
字段：
- 如果
  kind: ApiInstance
  且包含
  name
  ：验证
```
name
```
  是否与
```
api-instances.json
```
  中的 ApiInstance 完全匹配。如果不匹配，则标记为孤立（该策略引用了不存在的 API 实例，并且会静默失效）。
- 如果
  kind: Selector
  且
  selector.kind: ApiInstance
  ：该策略是全局策略，适用于所有 ApiInstances。这是有效情况；请在表中注明，但不要将其标记为错误。
- 如果
  kind
  为其他值或
  targetRef
  格式错误：标记为格式错误。
对于每个孤立或格式错误的 PolicyBinding，记录：
- PolicyBinding 名称
- 原因（例如，
```
targetRef.name 'xyz'
```
  与任何 ApiInstance 均不匹配）

Step 4 — Cross-reference Services → ApiInstances

第 4 步 — 交叉核对 Services → ApiInstances

For each Service in

services.json

System services (namespace
```
x-flex-internal
```
or label
```
managed-by: flex-static
```
) are internal gateway resources. Do not flag as potentially unused.
User-defined services (namespace
```
gateway
```
,
```
default
```
, or an environment UUID):
- Check if the Service name is referenced in any ApiInstance under
```
spec.services
```
  or in any PolicyBinding.
- If not referenced by any ApiInstance or PolicyBinding, mark as potentially unused (may be a leftover from a previous deployment).
Record any potentially unused Services:
- Service name
- Namespace
- Last reference check result

对于

services.json

中的每个 Service：

系统服务（命名空间为
```
x-flex-internal
```
，或标签为
```
managed-by: flex-static
```
）是 Gateway 内部资源。不要将其标记为可能未使用。
用户定义服务（命名空间为
```
gateway
```
、
```
default
```
或环境 UUID）：
- 检查 Service 名称是否被任何 ApiInstance 的
```
spec.services
```
  或任何 PolicyBinding 引用。
- 如果没有任何 ApiInstance 或 PolicyBinding 引用，则将其标记为可能未使用（可能是上一次部署遗留的资源）。
记录任何可能未使用的 Service：
- Service 名称
- 命名空间
- 最近一次引用检查结果

Step 5 — Identify anomalies

第 5 步 — 识别异常

Scan all resources for health and consistency issues:

Critical issues (block API execution):

Resources with
```
status.conditions[type="Ready"].status: False
```
— extract the condition message if present.
ApiInstances missing
```
spec.address
```
or with an invalid address format.
PolicyBindings missing
```
spec.targetRef
```
or
```
spec.policyRef
```
.
PolicyBindings with a non-existent
```
policyRef.name
```
(the referenced policy definition does not exist in
```
extensions.json
```
or is not available).

Warning issues (may indicate configuration drift):

ApiInstances with

metadata.labels["flex.mulesoft.com/deployment-desired-status"]: STOPPED

but

status.conditions[type="Ready"].status: True

(desired != actual).

Resources with missing
```
metadata.namespace
```
or
```
metadata.labels
```
.
JSON parse errors during extraction (indicates a corrupt or incomplete dump).

扫描所有资源中的健康状态和一致性问题：

严重问题（会阻止 API 执行）：

资源的
```
status.conditions[type="Ready"].status
```
为
```
False
```
——如果存在 condition message，请一并提取。
ApiInstances 缺少
```
spec.address
```
，或地址格式无效。
PolicyBindings 缺少
```
spec.targetRef
```
或
```
spec.policyRef
```
。
PolicyBindings 引用了不存在的
```
policyRef.name
```
（被引用的策略定义不存在于
```
extensions.json
```
中，或当前不可用）。

警告问题（可能表明配置漂移）：

ApiInstances 的

metadata.labels["flex.mulesoft.com/deployment-desired-status"]

为

STOPPED

，但

status.conditions[type="Ready"].status

为

True

（期望状态与实际状态不一致）。

资源缺少
```
metadata.namespace
```
或
```
metadata.labels
```
。
解压过程中出现 JSON 解析错误（表明转储已损坏或不完整）。

Step 6 — Compare against conf.d (if provided)

第 6 步 — 与 conf.d 进行比较（如果已提供）

If the user also provides their

conf.d/

directory or local configuration files:

Index local files: Parse all YAML or JSON files in
```
conf.d/
```
and extract resource names, kinds, and namespaces.
In dump but not in conf.d: Resource exists in the live gateway dump but not in the user's local configuration. Possible causes:
- Resource is managed by the control plane (connected mode deployment).
- Resource is a stale deployment that was not removed from the gateway.
- User's local conf.d is out of sync with the deployed version.
In conf.d but not in dump: Resource is configured locally but not present in the live dump. Possible causes:
- File has a syntax error and was rejected at deploy time.
- Gateway crashed or was restarted before persisting the resource.
- Resource was manually deleted from the gateway after initial deployment.
Record mismatches:
- Filename/resource name
- Kind
- Status (in dump only / in conf.d only)

如果用户还提供了

conf.d/

目录或本地配置文件：

为本地文件建立索引： 解析
```
conf.d/
```
中的所有 YAML 或 JSON 文件，并提取资源名称、类型和命名空间。
转储中存在但 conf.d 中不存在： 资源存在于实时 Gateway 转储中，但不在用户的本地配置中。可能原因包括：
- 资源由 control plane 管理（connected mode 部署）。
- 资源是未从 Gateway 清理的陈旧部署。
- 用户的本地 conf.d 与已部署版本不同步。
conf.d 中存在但转储中不存在： 资源已在本地配置，但未出现在实时转储中。可能原因包括：
- 文件存在语法错误，部署时被拒绝。
- Gateway 在持久化资源之前崩溃或重启。
- 资源在首次部署后被手动删除。
记录不匹配项：
- 文件名或资源名称
- 类型
- 状态（仅存在于转储中／仅存在于 conf.d 中）

Step 7 — Produce dump analysis report

第 7 步 — 生成转储分析报告

Structure your findings as follows:

undefined

按以下结构整理分析结果：

undefined

Gateway Dump Analysis Report

Dump file: [filename] Captured: [timestamp or datetime] Gateway agent ID: [agentId from control-node-storage.json]

Gateway Registration

Platform URL: [from configurations.json spec.platformConnection.anypoint]
Asset name: [from configurations.json spec.platformConnection.assetName]

Platform URL: [from configurations.json spec.platformConnection.anypoint]
Asset name: [from configurations.json spec.platformConnection.assetName]

Resource Inventory

[Table from Step 2]

Anomalies

Critical Issues (Ready: False or Malformed)

[List each resource with its Ready status and condition message, or "None found"]

Example:

ApiInstance
apii-123-api
(namespace
```
env-456
```
): Ready=False, condition: "Pod failed to start: OOMKilled"
PolicyBinding
rate-limit-binding
: malformed targetRef, references non-existent ApiInstance
```
apii-999-api
```

[List each resource with its Ready status and condition message, or "None found"]

Example:

ApiInstance
apii-123-api
(namespace
```
env-456
```
): Ready=False, condition: "Pod failed to start: OOMKilled"
PolicyBinding
rate-limit-binding
: malformed targetRef, references non-existent ApiInstance
```
apii-999-api
```

Orphaned PolicyBindings

[List each PolicyBinding that references a non-existent ApiInstance, or "None found"]

Example:

PolicyBinding
deprecated-policy
targets ApiInstance
```
apii-old-deployment
```
which does not exist in the dump

[List each PolicyBinding that references a non-existent ApiInstance, or "None found"]

Example:

PolicyBinding
deprecated-policy
targets ApiInstance
```
apii-old-deployment
```
which does not exist in the dump

Potentially Unused Services

[List each Service not referenced by any ApiInstance or PolicyBinding, or "None found"]

Example:

Service
backend-cache
(namespace
```
gateway
```
): not referenced by any ApiInstance

[List each Service not referenced by any ApiInstance or PolicyBinding, or "None found"]

Example:

Service
backend-cache
(namespace
```
gateway
```
): not referenced by any ApiInstance

Configuration Drift (conf.d vs. dump)

[If conf.d was provided, show mismatches. Otherwise, note "No local configuration provided for comparison."]

Example:

In dump only:
```
configurations.json
```
entries not in local conf.d (possible control-plane managed resources)
In conf.d only:
```
api-instances.yaml
```
entries not in dump (possible file not deployed)

[If conf.d was provided, show mismatches. Otherwise, note "No local configuration provided for comparison."]

Example:

In dump only:
```
configurations.json
```
entries not in local conf.d (possible control-plane managed resources)
In conf.d only:
```
api-instances.yaml
```
entries not in dump (possible file not deployed)

Escalation Recommendation

No anomalies: Gateway state appears healthy at the time of dump capture. No immediate action required.
Warnings present: Configuration drift or unused resources detected. Recommend reviewing the "Potentially Unused Services" and "Configuration Drift" sections. Reconcile local conf.d with dump state.
Critical issues present: Ready=False resources or orphaned bindings indicate active problems. Immediate escalation recommended. Provide this dump and the gateway logs (see
```
omni-gateway-logs
```
skill) to support.

undefined

No anomalies: Gateway state appears healthy at the time of dump capture. No immediate action required.
Warnings present: Configuration drift or unused resources detected. Recommend reviewing the "Potentially Unused Services" and "Configuration Drift" sections. Reconcile local conf.d with dump state.
Critical issues present: Ready=False resources or orphaned bindings indicate active problems. Immediate escalation recommended. Provide this dump and the gateway logs (see
```
omni-gateway-logs
```
skill) to support.

undefined

Related Skills

Tips for Effective Dump Analysis

高效分析转储的提示

Start with anomalies: If the report shows no critical issues, the gateway state was likely stable at capture time. Focus on warnings and drift.
Use timestamps: Compare dump timestamp with error logs. Errors after the dump timestamp are new; errors before indicate pre-existing issues.
Check namespaces: Resources in different namespaces may be intentional (environment isolation). Do not assume all namespaces are equivalent.
PolicyBinding selectors: Global policies (Selector + ApiInstance) apply to all APIs. Verify that the intended policy is actually configured correctly.
Extensions file: Only inspect
```
extensions.json
```
if investigating a specific policy definition or if policy bindings reference undefined policies. The file is often large and can be skipped for routine analysis.
Agent ID: If the agent ID in the dump does not match the expected gateway agent in your Anypoint environment, the dump may be from a different gateway or a stale backup.

从异常开始： 如果报告未显示严重问题，则 Gateway 状态在捕获时可能稳定。关注警告和配置漂移。
使用时间戳： 将转储时间戳与错误日志进行比较。转储时间戳之后的错误是新出现的；之前的错误表示预先存在的问题。
检查命名空间： 不同命名空间中的资源可能是有意设置的（环境隔离）。不要假设所有命名空间都等价。
PolicyBinding 选择器： 全局策略（Selector + ApiInstance）适用于所有 API。验证预期策略是否确实已正确配置。
Extensions 文件： 仅在调查特定策略定义或 PolicyBinding 引用了未定义策略时，才检查
```
extensions.json
```
。该文件通常很大，例行分析时可以跳过。
Agent ID： 如果转储中的 Agent ID 与预期 Anypoint 环境中的 Gateway Agent 不匹配，则该转储可能来自不同的 Gateway 或陈旧备份。

omni-gateway-dump

Original

Translation

Analyze Gateway Dump

分析 Gateway Dump

Dump Format Reference

转储格式参考

Key Fields to Read Per Resource

每个资源需要读取的关键字段

Sample Resource Structure

资源结构示例

Analysis Checklist

分析检查清单

Step 1 — Unzip and index

第 1 步 — 解压并建立索引

Step 2 — Build resource inventory

第 2 步 — 构建资源清单

Step 3 — Cross-reference PolicyBindings → ApiInstances

第 3 步 — 交叉核对 PolicyBindings → ApiInstances

Step 4 — Cross-reference Services → ApiInstances

第 4 步 — 交叉核对 Services → ApiInstances

Step 5 — Identify anomalies

第 5 步 — 识别异常

Step 6 — Compare against conf.d (if provided)

第 6 步 — 与 conf.d 进行比较（如果已提供）

Step 7 — Produce dump analysis report

第 7 步 — 生成转储分析报告

Gateway Dump Analysis Report

Gateway Dump Analysis Report

Gateway Registration

Gateway Registration

Resource Inventory

Resource Inventory

Anomalies

Anomalies

Critical Issues (Ready: False or Malformed)

Critical Issues (Ready: False or Malformed)

Orphaned PolicyBindings

Orphaned PolicyBindings

Potentially Unused Services

Potentially Unused Services

Configuration Drift (conf.d vs. dump)

Configuration Drift (conf.d vs. dump)

Escalation Recommendation

Escalation Recommendation

Related Skills

相关 Skills

Tips for Effective Dump Analysis

高效分析转储的提示