Use ADC for Declarative Configuration

ADC (API Declarative CLI) lets you manage your gateway configuration declaratively using YAML files. This enables GitOps workflows, version-controlled configuration, and reproducible deployments across different environments.

Instead of making imperative API calls, you define the desired state in a YAML file and ADC reconciles it with the gateway.

Prerequisites

• An API7 Enterprise instance is running.
• A Gateway Group is created and a Gateway instance is running.
• A token from the Dashboard.
• ADC is installed. See ADC Command Reference for installation details.

Configure ADC for API7 Enterprise

You can configure ADC using environment variables or a .env file to establish a connection to your API7 Enterprise Control Plane.

Set the following environment variables in your terminal:

export ADC_BACKEND=api7ee
export ADC_SERVER=https://localhost:7443
export ADC_TOKEN=${API_KEY}
export ADC_GATEWAY_GROUP=default

If you are connecting to a local control plane with a self-signed certificate, add --tls-skip-verify to the ADC command.

Alternatively, you can create a .env file in your working directory:

.env

ADC_BACKEND=api7ee
ADC_SERVER=https://localhost:7443
ADC_TOKEN=${API_KEY}
ADC_GATEWAY_GROUP=default

Verify the connectivity to the API7 Enterprise Control Plane:

adc ping

Write a Declarative Configuration

Define your gateway resources such as services, routes, and consumers in a adc.yaml file.

adc.yaml

services:
  - name: adc-workflow-httpbin-service
    upstream:
      name: default
      scheme: http
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: adc-workflow-route
        uris:
          - /anything/adc-workflow
        methods:
          - GET
        plugins:
          key-auth:
            header: apikey

consumers:
  - username: adc-workflow-consumer
    credentials:
      - name: adc-workflow-key
        type: key-auth
        config:
          key: adc-workflow-api-key

The configuration file uses top-level keys to organize resources such as services, consumers, global_rules, and plugin_metadata.

Validate the Configuration Locally

Before applying changes, use the lint command to check your configuration for syntax errors and best practices.

adc lint -f adc.yaml

Preview Changes

The diff command shows you exactly what changes ADC will make to the gateway configuration to match your local file.

adc diff -f adc.yaml

This output helps you avoid accidental deletions or modifications before applying the configuration.

Apply the Configuration

Once you have verified the changes, use the sync command to apply the configuration to the gateway.

adc sync -f adc.yaml

caution

adc sync is a reconciliation operation. It will create, update, and delete resources to match the desired state in your YAML file. Resources that exist on the gateway but are not in the YAML file will be removed.

Back Up the Current Configuration

You can export the current gateway configuration to a YAML file using the dump command. This is useful for creating backups or migrating configurations between environments.

adc dump -o backup.yaml

Convert from OpenAPI

ADC can generate a declarative configuration from an existing OpenAPI specification file. Both OpenAPI 2.0 (Swagger) and OpenAPI 3.x are accepted, in either JSON or YAML format.

adc convert openapi -f openapi.yaml -o adc.yaml

Customize the Conversion With x-adc-* Extensions

A plain OpenAPI document only describes endpoints. To configure API7 Gateway-specific behavior on the converted output — plugins, labels, upstream defaults, route defaults, and so on — annotate the specification with x-adc-* extension fields. The converter recognizes:

Extension	Allowed levels	Effect
x-adc-name	root, operation	Override the generated service or route name.
x-adc-labels	root, operation	Attach a label map. Values may be a string or an array of strings.
x-adc-plugins	root, path, operation	Attach a map of plugin name to plugin configuration.
x-adc-plugin-[plugin-name]	root, path, operation	Attach a single plugin. At the same level, this overrides an entry of the same name in x-adc-plugins.
x-adc-service-defaults	root, path, operation	Override fields on the generated service.
x-adc-upstream-defaults	root, path, operation	Override fields on the generated upstream.
x-adc-route-defaults	root, path, operation	Override fields on the generated route.
x-adc-upstream-node-defaults	on each entry of servers:	Override fields on the upstream nodes derived from servers:.

x-adc-upstream-node-defaults and any sub-level servers: block only apply when the source is OpenAPI 3.x — OpenAPI 2.0 (Swagger) does not have a servers: field.

Setting x-adc-service-defaults, x-adc-upstream-defaults, or a sub-level servers: entry on a specific path or operation causes that operation to be moved into its own separate service in the output, because per-route upstream or service configuration cannot live on a shared service. Sub-level plugins, labels, route defaults, and x-adc-name are applied in place and do not split the service.

For example, the following specification sets root-level labels and a key-auth plugin, plus operation-level defaults that will cause the GET /anything/* route to be split out:

openapi.yaml

openapi: 3.0.0
info:
  title: httpbin API
  description: httpbin API example for API7 Gateway.
  version: 1.0.0
servers:
  - url: 'http://httpbin.org:80'
x-adc-labels:
  server: production
  api: httpbin
x-adc-plugins:
  key-auth:
    _meta:
      disable: false
paths:
  /anything/*:
    get:
      summary: Returns anything that is passed into the request.
      x-adc-name: httpbin-anything
      x-adc-service-defaults:
        path_prefix: /api
      x-adc-upstream-defaults:
        timeout:
          connect: 10
          send: 10
          read: 10
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: string

Running adc convert openapi -f openapi.yaml -o adc.yaml produces:

adc.yaml

services:
  - description: httpbin API example for API7 Gateway.
    labels:                              # inherited from root x-adc-labels
      api: httpbin
      server: production
    name: httpbin-API_anything*_get      # auto-generated from title + path + method
    plugins:                             # inherited from root x-adc-plugins
      key-auth:
        _meta:
          disable: false
    routes:
      - description: Returns anything that is passed into the request.
        methods:
          - GET
        name: httpbin-anything           # from operation x-adc-name
        uris:
          - /api/anything/*              # path_prefix from x-adc-service-defaults is
                                         # inlined into the URI for APISIX compatibility
    upstream:
      nodes:
        - host: httpbin.org              # derived from servers[0].url
          port: 80
          weight: 100
      pass_host: pass
      scheme: http
      timeout:                           # from operation x-adc-upstream-defaults
        connect: 10
        read: 10
        send: 10

For the full extension matrix, schema details, and additional examples, see the ADC OpenAPI converter README.

Verify the Configured Route

Send a request without the API key first. The gateway should reject it with 401 Unauthorized:

curl -i "http://127.0.0.1:9080/anything/adc-workflow"

Then send a request with the configured key:

curl -i "http://127.0.0.1:9080/anything/adc-workflow" \
  -H "apikey: adc-workflow-api-key"

You should receive 200 OK.

If the route returns 404 immediately after adc sync, wait a few seconds for the latest configuration to reach the gateway and retry.

A typical ADC workflow consists of the following steps:

1. Lint: adc lint -f adc.yaml
2. Diff: adc diff -f adc.yaml
3. Sync: adc sync -f adc.yaml
4. Dump: adc dump -o backup.yaml

Next Steps

• ADC Command Reference — see all available commands and options.
• Configure Secret Management — securely manage credentials in your configs.