DocsICP FilingConsole
官方文档
首页

Route and policy orchestration

更新时间：
复制 MD 格式
产品详情
我的收藏

Automate service and domain preparation, route and policy configuration, and deployment through OpenAPI. Includes guidance on concurrency, status verification, and conflict avoidance.

1. Key takeaways

1.2 Concurrent operations

Stage

Concurrency recommended

Recommendation

Service preparation (CreateService) and domain preparation (GetDomain/CreateDomain)

Yes

These resources are independent and can run concurrently.

Creating multiple policies (CreatePolicy)

Yes

You can create different policies concurrently.

Attaching multiple policies to different routes or domains

Yes

To run these operations concurrently, shard them by resource ID.

Updating, attaching policies to, or deploying the same route

No

Execute these operations sequentially to avoid state conflicts, such as Deploying or Undeploying.

Creating multiple routes with the same path prefix in bulk

No

Run sequentially with pre-checks to avoid path conflicts.

1.3 Verifying changes

  • Route deployment status: Call GetHttpApiRoute and verify that the deployStatus is Deployed. Check deployErrorMessage for any issues.

  • Policy attachment: Call GetPolicyAttachment and verify that the response contains the target attachResourceId and attachResourceType.

  • Domain association: Call GetDomain with withStatistics=true and review the statistics, or check the domainInfos field in the route details.

1.4 Common conflict scenarios

  • Duplicate resources: Creating a service, domain, API, or route with a name that already exists. Attaching the same type of policy to a resource more than once.

  • State competition: Attempting to deploy or modify a route while it is already in the Deploying or Undeploying state.

  • Attachment conflict: Mismatched policy attachment types or violating constraints when attaching the same policy across different environments or gateways.

2. Service and domain preparation

2.1 Create or query a service (CreateService / GetService)

API reference:

2.1.1 CreateService

POST CreateService
Content-Type: application/json

{
  "gatewayId": "gw-xxx",
  "sourceType": "DNS",
  "serviceConfigs": [
    {
      "name": "orders-backend",
      "addresses": [
        "orders.backend.svc.cluster.local:80"
      ]
    }
  ]
}

Key parameters:

  • gatewayId: Required. The ID of the target gateway instance.

  • sourceType: Required. Common values include DNS, VIP, K8s, and MseNacos.

  • serviceConfigs[]: Required. Supports creating multiple services in a single request.

  • Use the serviceIds[] from the response to reference the services in subsequent route backend configurations.

2.1.2 GetService

GET GetService

Recommendations:

  • The serviceId must be an existing service ID, typically in the format svc-.... The legacy format gs-... is also supported.

  • Before creating a route, validate that the service exists and that its key fields (address, port, protocol) are correct.

2.2 Query a domain (GetDomain)

API reference:

GET GetDomain
Query: domainId=d-xxx&withStatistics=true

Key parameters:

  • domainId: The domain ID (for example, d-...).

  • withStatistics: Optional. If set to true, the response includes statistics about resources associated with the domain, which is useful for post-deployment verification.

2.3 Create a domain (CreateDomain)

API reference:

POST CreateDomain
Content-Type: application/json

{
  "name": "api.example.com",
  "protocol": "HTTP",
  "gatewayType": "API"
}

Key parameters:

  • name: Required. The domain name.

  • protocol: Required. Valid values: HTTP and HTTPS.

  • We recommend setting gatewayType to API. If omitted, a default value is used.

  • If protocol is HTTPS, you must also provide certificate-related parameters, such as forceHttps and certIdentifier.

3. Domain-level policies

3.1 Create a domain-level policy (CreatePolicy)

API reference:

Note

We recommend that you use CreatePolicy to create a policy and then use CreatePolicyAttachment to attach it. Avoid using CreateAndAttachPolicy, which combines both actions.

POST CreatePolicy
Content-Type: application/json

{
  "name": "domain-ip-whitelist",
  "className": "IpAccessControl",
  "description": "domain-level IP whitelist",
  "config": "{\"name\":\"domain-ip-whitelist\",\"ipAccessControlResourceName\":\"api.example.com\",\"ipAccessControlResourceType\":\"Domain\",\"ipAccessControlType\":\"White\",\"ipAccessControlContent\":\"10.0.0.0/8,192.168.0.0/16\",\"enable\":true,\"protocolLayer\":\"L7\"}"
}

Key parameters:

  • name: Required. The policy name, which must be unique within the same gateway.

  • className: Required. The type of the policy.

  • config: Required. A JSON-formatted string, not a JSON object.

3.2 Attach a domain-level policy (CreatePolicyAttachment)

API reference:

POST CreatePolicyAttachment
Content-Type: application/json

{
  "policyId": "p-xxx",
  "attachResourceId": "d-xxx",
  "attachResourceType": "Domain",
  "gatewayId": "gw-xxx"
}

Key parameters:

  • policyId: Required. The ID of the policy.

  • attachResourceId: Required. The ID of the domain (for example, d-...).

  • attachResourceType: Required. The value is fixed to Domain.

  • gatewayId: Required.

  • environmentId: Domain-level policies are environment-agnostic. The server treats this parameter as *.

4. APIs and routes

4.1 Create an HTTP API (CreateHttpApi)

API reference:

POST CreateHttpApi
Content-Type: application/json

{
  "name": "orders-http-api",
  "description": "orders route collection",
  "type": "Http",
  "protocols": [
    "HTTP",
    "HTTPS"
  ]
}

Key parameters:

  • name: Required. The name of the API.

  • type: Required. For an HTTP API, set this to Http.

  • protocols: Optional. If omitted, the default protocol is used.

4.2 Create an HTTP API route (CreateHttpApiRoute)

API reference:

POST CreateHttpApiRoute
Content-Type: application/json

Parameters:

  • httpApiId: Required.

{
  "environmentId": "env-xxx",
  "name": "orders-route",
  "domainIds": [
    "d-xxx"
  ],
  "match": {
    "path": {
      "type": "Prefix",
      "value": "/orders"
    },
    "methods": [
      "GET",
      "POST"
    ]
  },
  "backendConfig": {
    "scene": "SingleService",
    "services": [
      {
        "serviceId": "svc-xxx",
        "protocol": "HTTP",
        "port": 80,
        "weight": 100
      }
    ]
  }
}

Key parameters:

  • environmentId, name, match, and backendConfig are required.

  • The name must be 64 characters or less and contain only lowercase letters, digits, hyphens (-), or periods (.).

  • When backendConfig.scene is SingleService, specify only one backend in the services array.

  • domainIds can be empty during creation, but you must associate a deployable domain to deploy the route.

5. Route policies and deployment

5.1 Create a route-level policy (CreatePolicy)

As with domain-level policies, use the following operation:

POST CreatePolicy

Example of a route-level IpAccessControl policy:

{
  "name": "route-ip-whitelist",
  "className": "IpAccessControl",
  "description": "route-level IP whitelist",
  "config": "{\"name\":\"route-ip-whitelist\",\"ipAccessControlResourceName\":\"orders-route\",\"ipAccessControlResourceType\":\"GatewayRoute\",\"ipAccessControlType\":\"White\",\"ipAccessControlContent\":\"10.10.0.0/16\",\"enable\":true,\"protocolLayer\":\"L7\"}"
}

5.2 Attach a route-level policy (CreatePolicyAttachment)

POST CreatePolicyAttachment
Content-Type: application/json

{
  "policyId": "p-yyy",
  "attachResourceId": "hr-yyy",
  "attachResourceType": "GatewayRoute",
  "environmentId": "env-xxx",
  "gatewayId": "gw-xxx"
}

Key parameters:

  • attachResourceId: The ID of the route, which must start with the prefix hr-.

  • attachResourceType: For route-level policies, set this to GatewayRoute.

  • We recommend explicitly specifying environmentId for most route-level policies. IpAccessControl is an exception and does not require this parameter.

  • gatewayId: Required.

5.3 Deploy an API (DeployHttpApi)

API reference:

POST DeployHttpApi
Content-Type: application/json

Parameters:

  • httpApiId: Required.

{
  "routeId": "hr-yyy",
  "isInternalRoute": false
}

Notes:

  • For HTTP APIs, the core parameter is routeId.

  • This is an asynchronous operation. A successful API call indicates only that the request was accepted. Poll the route status to confirm deployment completion.

5.4 Optional: Conflict detection (DetectHttpApiConflicts)

POST DetectHttpApiConflicts
Content-Type: application/json

Parameters:

  • httpApiId: Required.

{
  "routeId": "hr-yyy",
  "isInternalRoute": false
}

Recommendations:

  • This pre-check is especially useful when multiple teams modify routes concurrently on a custom domain.

  • If the operation detects conflicts, adjust the path, method, or domain binding before calling DeployHttpApi.

6. Verifying changes

Follow these four steps to verify your changes:

  1. Check the route deployment status

    • Call GetHttpApiRoute (GET) and pass the httpApiId and routeId.

    • Check the status:

      • deployStatus=Deployed: The deployment was successful.

      • deployStatus=DeployFailed: The deployment failed. Check the deployErrorMessage for details.

  2. Check the policy attachment

    • Call GetPolicyAttachment (GET) and pass the policyAttachmentId.

    • Confirm that attachResourceId, attachResourceType, and gatewayId match your intended configuration.

  3. Check the domain association

    • Call GetDomain (GET) and pass the domainId and withStatistics=true.

    • Alternatively, check the route details to confirm that domainInfos contains the target domain.

  4. Verify with live traffic

    • Send a request to the target domain and path to confirm that the route forwards traffic as expected and that the policy (such as a whitelist) is enforced correctly.

7. Conflict scenarios and solutions

Note

The service maps the TypeConflict error code to an HTTP 409 status code.

  1. CreateService conflicts

    • Common errors: ServiceExisted, ServiceQuotaPerGatewayExceed.

    • Avoidance: Use a consistent naming convention for services within the same gateway. Estimate your quota usage before performing batch creations.

  2. CreateDomain conflicts

    • Common error: DomainExisted.

    • Avoidance: Ensure domain names are globally unique, scoped by the combination of name and gatewayType.

  3. CreatePolicy / CreatePolicyAttachment conflicts

    • Common errors:

      • PolicyExisted.

      • PolicyAttachResourceBounded (attaching the same policy to the same resource more than once).

      • PolicyAttachConflict (another policy of the same class already exists on the resource, especially for singleton route-level policies).

      • PolicyAttachResourceTypeNotMatch (attaching the same policy to different resource types).

    • Avoidance: Use the combination of resourceId and className as an idempotency key. Before attaching a policy, check for existing attachments.

  4. CreateHttpApi / CreateHttpApiRoute conflicts

    • Common errors:

      • ApiNameDuplicated / ApiNameDuplicatedWithInstance.

      • ApiVersionDuplicated (for multi-version REST APIs).

      • RouteNameDuplicated.

      • RoutePathHasDefinedByApi (path/method conflict).

    • Avoidance: Ensure API names are unique within the same gateway. Create routes with the same path segment sequentially and perform validation first.

  5. DeployHttpApi conflicts

    • Common errors:

      • DeployRouteForbidden (the route is in the Deploying or Undeploying state).

      • ApiNameDuplicatedWithInstance (name conflict with a deployed instance).

    • Avoidance: Strictly serialize the policy modification and deployment operations for the same route. Avoid deploying the same routeId concurrently.

8. Execution checklist

  • Run the service and domain preparation steps concurrently to obtain the serviceId and domainId.

  • Create the HttpApi first, then create the HttpApiRoute.

  • For route policies, follow this sequence: create a route -> create a policy -> attach the policy -> deploy the route.

  • After deployment, poll the route's deployStatus until it becomes Deployed.

  • Handle HTTP 409 scenarios idempotently: check if a resource exists before creating it, or gracefully handle "duplicate creation" errors.

References

Previous：Route requests of gRPC applications based on Cloud-native API GatewayNext：Developer Reference