Manage Apache APISIX Declaratively with ADC

API Declarative CLI (ADC) lets you manage Apache APISIX configuration from YAML files instead of maintaining a collection of individual Admin API calls. You can export the running configuration, review changes in Git, validate them against the target gateway, preview the operations ADC will perform, and then synchronize the approved state.

This guide walks through that workflow for an Admin API-backed Apache APISIX deployment. By the end, you will have a reviewable adc.yaml file and a safer sequence for applying it.

When to Use ADC

ADC is useful when you want to treat gateway configuration as code. A typical workflow is:

1. Export the current APISIX state or write an ADC file.
2. Store that file in version control.
3. Check the file locally and validate it against the target gateway.
4. Review the difference between the local and running states.
5. Synchronize the approved configuration.

ADC communicates with the APISIX Admin API. It does not replace the gateway data plane, and it does not make every operation safe automatically. The local file represents the desired state within the command scope, so adc sync can create, update, and delete remote resources. Always inspect the diff before syncing.

The official ADC backend documentation currently labels Apache APISIX support as experimental and documents version-specific support and limitations. In particular, ADC does not support external upstream_id references, plugin templates (plugin_configs), or Consumer Groups. It also normalizes some APISIX resources when dumping them. Check that page against your APISIX and ADC versions before adopting the workflow in production.

Prerequisites

Before starting, make sure you have:

• A running Apache APISIX instance whose Admin API is reachable from your workstation or CI runner
• An APISIX Admin API key
• curl and a shell environment
• Permission to inspect and modify the target gateway configuration

For a local test deployment, follow the Apache APISIX getting started guide. Use a non-production environment while learning the workflow.

Install ADC

The current ADC project provides an installation script:

curl -sL "https://run.api7.ai/adc/install" | sh

Alternatively, download the appropriate Linux, macOS, or Windows binary from the ADC releases page. Verify the installation with:

adc --help

ADC supports Apache APISIX and API7 Enterprise backends. This guide explicitly selects the apisix backend.

Connect ADC to Apache APISIX

ADC accepts connection settings through command-line flags, environment variables, or a .env file. Environment variables are convenient for an interactive session:

export ADC_BACKEND=apisix
export ADC_SERVER=http://127.0.0.1:9180
export APISIX_ADMIN_API_KEY="replace-with-your-admin-api-key"
export ADC_TOKEN="$APISIX_ADMIN_API_KEY"

Do not commit the Admin API key to Git. In CI, provide it through the platform's secret store.

Check that ADC can reach the target backend:

adc ping

If the Admin API uses a private certificate authority, pass a trusted CA file with --ca-cert-file. Reserve --tls-skip-verify for local testing because it disables certificate verification.

Start from the Running Configuration

For a gateway that already has routes, services, or plugins, start by exporting the current state:

adc dump --with-id -o adc.yaml

The --with-id option preserves the IDs of resources created through the Dashboard or Admin API. Without those IDs, ADC may treat an existing resource as different from a local resource with a generated ID. Review the ADC resource ID guidance before adopting an existing gateway.

Treat the exported file as sensitive. A dump can include consumer credentials, TLS private keys, and other secret-bearing configuration. Inspect it before storage, remove or externalize secrets according to your organization's policy, and restrict access to any unredacted copy. If secret-bearing resource types are outside ADC's ownership boundary, exclude them using the resource filters supported by your ADC version.

Commit only a sanitized, reviewed baseline to a protected repository. From that point, changes to adc.yaml can go through pull requests and the same approval process as application code.

Define APISIX Resources in YAML

You can also write a configuration file directly. The following example defines a service, an upstream, a route, and key authentication:

services:
  - name: httpbin-service
    upstream:
      name: default
      scheme: http
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: get-ip
        uris:
          - /ip
        methods:
          - GET
        plugins:
          key-auth: {}

consumers:
  - username: demo-user
    credentials:
      - name: primary-key
        type: key-auth
        config:
          key: <api-key>

This example is a starting point, not a production policy. Replace the placeholder key, use an appropriate secret-management process, and consult the ADC configuration reference for supported resources and fields.

Check the Configuration Locally

Run lint before contacting the gateway:

adc lint -f adc.yaml

adc lint checks the file's syntax and ADC schema rules. It cannot determine whether a plugin or field is supported by your specific APISIX deployment because it does not connect to the backend.

Validate Against the Target Gateway

Use backend-side validation to catch target-specific problems without applying the configuration:

adc validate -f adc.yaml

This step builds the corresponding backend requests and asks APISIX to validate them. It complements local linting; it does not replace reviewing the resulting changes.

Preview the Difference

Compare the desired configuration with the running state:

adc diff -f adc.yaml

Review every create, update, and delete operation. ADC also writes a machine-readable diff.yaml file. Because it can contain complete old and new resource values, inspect it for secrets before publishing it as a CI artifact. Restrict artifact access and retention when the file contains sensitive configuration.

Pay particular attention to deletions. A remote resource that is within ADC's command scope but absent from the local file can be removed during synchronization.

Synchronize the Approved State

After the diff has been reviewed, apply the file:

adc sync -f adc.yaml

Run adc diff -f adc.yaml again after synchronization. An empty diff confirms that the running configuration matches the desired file within the selected scope. However, APISIX may populate default values or normalize resources, so some entries can remain marked as changed after a successful sync. Review a persistent diff against the documented APISIX backend limitations instead of repeatedly syncing to force an empty result.

For shared gateways, use a label selector or resource-type filters to keep one team's pipeline from taking ownership of another team's resources. Test the ownership boundary in a non-production environment before enabling automatic synchronization.

Convert an OpenAPI Document

ADC can convert an OpenAPI 3 document into ADC configuration:

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

OpenAPI describes an API contract, while an API gateway also needs runtime details such as upstream defaults, plugins, labels, and route behavior. Treat generated output as a draft. Review it, add the required gateway settings, and run the same lint, validate, and diff sequence before synchronization.

ADC supports x-adc-* extensions for controlling gateway-specific conversion behavior. See the OpenAPI converter reference for the supported extensions.

Use ADC in a CI/CD Workflow

A conservative pipeline separates checks from deployment:

adc lint -f adc.yaml
adc validate -f adc.yaml
adc diff -f adc.yaml

# Run only after review or deployment approval.
adc sync -f adc.yaml

Use separate credentials and target endpoints for development, staging, and production. Restrict who can run sync, protect the production environment with an approval gate, and retain a sanitized diff as deployment evidence only when your access and retention policies allow it.

ADC makes configuration changes reviewable, but it is not a continuous reconciliation controller by itself. Your CI/CD system decides when commands run, how approvals work, and whether a failed deployment should trigger a rollback.

Common Adoption Mistakes

Syncing Before Establishing a Baseline

On an existing gateway, dumping the running state with --with-id reduces the risk of ADC interpreting established resources as replacements. Inspect the exported file before declaring it the desired state.

Treating Lint as Deployment Validation

lint checks the local file. Use validate for backend-aware checks and diff to understand the operations that synchronization would perform.

Mixing Manual and Declarative Ownership

Dashboard or Admin API changes can create drift from the version-controlled file. Decide which resources ADC owns, document that boundary, and use labels or resource-type filters when multiple workflows share a gateway.

Assuming OpenAPI Contains Every Gateway Setting

Generated configuration still needs review. OpenAPI alone usually does not express all traffic, security, observability, and upstream policies required by the gateway.

Conclusion

ADC provides a practical configuration-as-code workflow for Apache APISIX: export or author the desired state, check it locally, validate it against the target, inspect the diff, and synchronize only after approval. The key safety principle is simple: treat the diff as a deployment plan and review it before every production sync.

For the complete command and configuration reference, see the ADC documentation and the Apache APISIX ADC reference.