APISIX Declarative CLI (ADC)

Many users of APISIX get started with APISIX and become familiarized managing APISIX resources through the Admin API. However, as configurations increase in complexity, managing resources imperatively through the Admin API becomes more challenging.

The APISIX Declarative CLI (ADC) is a command-line tool that allows you to manage your APISIX resources in a declarative manner. It offers simplicity and clarity in defining the desired state of APISIX, allowing developers and administrators to focus on the end result rather than the procedural steps. The declarative configurations could serve as a single source of truth that can be managed through version control systems.

The ADC tool has the following general syntax:

adc [command] [options]

with global options:

• -V, --version to check the version
• -h, --help to print the help menu of the command

Commands

adc sync

Configure APISIX backend type and instance location.

Options	Default Value	Description	Valid Value	Env Variable
--backend <backend-type>	apisix	Configure backend type.	apisix or api7ee	ADC_BACKEND
--server <server-addr>	http://localhost:9180	Configure backend server address.		ADC_SERVER
--token <token>		Configure API token used to access the APISIX server.		ADC_TOKEN
--gateway-group <gateway-group-name>	default	Specify gateway group to operate on (API7EE only).		ADC_GATEWAY_GROUP
--label-selector <selectors>		Specify resource labels to filter for.
-f, --file <file-path>		Synchronize configuration file.

Sample Usage

adc sync -f service-a.yaml -f service-b.yaml

adc ping

Ping APISIX instance to verify connectivity.

Options	Default Value	Description	Valid Value	Env Variable
--backend <backend-type>	apisix	Configure backend type.	apisix or api7ee	ADC_BACKEND
--server <server-addr>	http://localhost:9180	Configure backend server address.		ADC_SERVER
--token <token>		Configure API token used to access the APISIX server.		ADC_TOKEN
--gateway-group <gateway-group-name>	default	Specify gateway group to operate on (API7EE only).		ADC_GATEWAY_GROUP
--label-selector <selectors>		Specify resource labels to filter for.

Sample Usage

adc ping --backend apisix --server http://localhost:9180

adc dump

Dump configurations from the backend.

Options	Default Value	Description	Valid Value	Env Variable
--backend <backend-type>	apisix	Configure backend type.	apisix or api7ee	ADC_BACKEND
--server <server-addr>	http://localhost:9180	Configure backend server address.		ADC_SERVER
--token <token>		Configure API token used to access the APISIX server.		ADC_TOKEN
--gateway-group <gateway-group-name>	default	Specify gateway group to operate on (API7EE only).		ADC_GATEWAY_GROUP
--label-selector <selectors>		Specify resource labels to filter for.
-o, --output <file-path>		Specify the file path where the backend data should be dumped.

Sample Usage

adc dump -o apisix-dump.yaml

adc diff

Show differences between local and backend configurations.

Options	Default Value	Description	Valid Value	Env Variable
--backend <backend-type>	apisix	Configure backend type.	apisix or api7ee	ADC_BACKEND
--server <server-addr>	http://localhost:9180	Configure backend server address.		ADC_SERVER
--token <token>		Configure API token used to access the APISIX server.		ADC_TOKEN
--gateway-group <gateway-group-name>	default	Specify gateway group to operate on (API7EE only).		ADC_GATEWAY_GROUP
--label-selector <selectors>		Specify resource labels to filter for.
-f, --file <file-path>		Compare with local configuration file.

Sample Usage

adc diff -f service-a.yaml -f service-b.yaml

adc convert

Convert API specifications to ADC configurations.

Options	Default Value	Description	Valid Value	Env Variable
openapi		Convert OpenAPI spec to ADC Configurations.

Sample Usage

adc convert openapi -f open-api-spec.yaml -o adc.yaml

adc lint

Lint the provided configuration files to ensure the configurations meet ADC requirements.

Options	Default Value	Description	Valid Value	Env Variable
-f, --file <file-path>		Files to lint.

Sample Usage

adc lint -f service-a.yaml -f service-b.yaml

adc help

Print help menu.

Sample Usage

adc help

Using Environment Variables

A number of variables, such as backend type, server address, token, and gateway group, can be configured in environment variables.

For instance, you could define the variables in .env file as such:

.env

ADC_BACKEND=apisix
ADC_SERVER=http://localhost:9180

Alternatively, you could export these variables in the terminal:

export ADC_BACKEND=apisix
export ADC_SERVER=http://localhost:9180

Once defined, you can run ADC commands without configuring these values repetitively in the --backend and --server flags.