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.

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

Validate the Configuration

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.