What's New in ADC 0.8 & 0.9 & 0.10?

Introduction

ADC (APISIX Declarative CLI) is a declarative configuration tool introduced by API7.ai, providing a convenient toolset for users to implement GitOps. Users can easily integrate it into their CI/CD pipelines to manage the full API lifecycle, completing API upgrades and releases. After the release of [0.7 version, ADC released three new versions: 0.8, 0.9, and 0.10, with optimizations and updates in terms of functionality, performance, and user experience.

New Features of ADC

Improvements to Resource Change Detector: Differ

These modifications were introduced in versions 0.8 and 0.9.
We have introduced a new version of the resource change detector Differ, v3, which has significant improvements in functionality and code quality.

1. The new Differ introduces a default value merging mechanism for local resources, ensuring that the default values of the server side do not interfere with ADC's resource change checks.

   When the client sends a request to create a resource on the API7 or APISIX Admin API, the server performs Schema validation on the submitted request. During this process, some fields that have default values marked in the Schema but are not sent by the client will be automatically added to the submitted resource. As a result, when we read the resource from the API again, it will be different from the initial submission.

   Previous ADC versions would list these resources as "modified" and send update API requests to the Admin API. This behavior introduced some uncertainty for ADC, and this problem has been resolved through Differ.

2. The default value merging mechanism has been implemented in the API7 backend, ensuring that resource differences are only considered as modifications when the user has changed the local YAML configuration.

3. Refined Differ detection granularity: ADC currently performs resource change checks separately at the resource body and plugin dimensions, helping to reduce anomalies in the check.

4. Optimized code quality, simplified redundant code to improve readability, and fixed some bugs.

Resource Filters

We have added two resource filtering mechanisms based on resource labels and resource types. They can be used to exclude unnecessary resources during the fetch, difference check, and synchronization operations.

Resource Label Filter

The feature was introduced in version 0.8.
This filter performs filtering based on the labels field of the resources. Users can enable the filter by using the --label-selector key=value parameter on the command line. It supports configuring multiple filter conditions, and only remote resources that simultaneously meet these rules will be considered as existing, while local resources will be automatically added with these labels.

This ensures that we perform resource checks and synchronization within a small scope, helping to split the tasks executed in the CI/CD pipeline and prevent accidental synchronization from damaging resources that do not need to be modified.

Resource Type Filter

The feature was introduced in version 0.9.
We added two new command-line parameters: --include-resource-type <type> and --exclude-resource-type <type>, which can be configured multiple times, but the include and exclude parameters are mutually exclusive.

With these two parameters, we can filter out specific resource types from the current operation. For example, using include-resource-type can be used to set a whitelist and select the resource types to be included in the operation; while exclude-resource-type will determine the resource types to be excluded from the operation.

This helps us better handle resources that do not need to be frequently changed, such as plugin metadata and global rules of plugins.

Command Line Improvements

These improvements were introduced in version 0.9.

TLS Certificate Configuration

We have added a series of TLS-related parameters to the command line, such as:

• --ca-cert-file to specify the server's CA certificate file
• --tls-skip-verify to disable TLS server certificate verification
• --tls-client-cert-file and --tls-client-key-file to specify the mTLS client certificate files

These parameters help ADC establish a secure encrypted connection and prevent man-in-the-middle attacks.

Timeout Control

We have added the --timeout <duration> parameter to control the timeout duration of API calls, supporting syntax like 1m30s. When an Admin API call takes too long or gets stuck, the timeout mechanism will take effect to prevent it from waiting indefinitely.

Debug Mode

This feature was introduced in version 0.9.
When ADC performs resource operations internally, it needs to call a large number of APIs. Sometimes we may need to check these API calls to analyze whether they are being sent correctly or to verify that the server's responses meet expectations. While packet capture can be used to achieve this, the operation is not convenient, and there are significant difficulties when TLS is enabled.

Therefore, we have added a built-in debug mode to ADC, which can be enabled using the --verbose <integer> parameter. When this parameter is set to 2, ADC will print the request and response parts of each internal API call to help with debugging.

This parameter can also be used to hide logs. When this parameter is set to 0, ADC will hide all general logs except for errors.

Strengthening Remote Resource Processing

This feature was introduced in version 0.9.
Since ADC is not the only way to configure services, routes, etc., users can also use the API7 Enterprise dashboard to achieve this through simple operations. This has led to a problem: the operations on the dashboard will use randomly generated resource IDs, while ADC uses the resource name in the YAML configuration to generate a fixed resource ID for precise resource location.

This means that if the user creates a resource on the dashboard, ADC will not be able to locate it by the resource ID. ADC cannot modify or delete the resources created on the dashboard, but these resources will still appear in the change detection, but cannot be operated on correctly.

Therefore, we have optimized the relevant logic of the API7 backend ADC. If the remote and local both contain resources with the same name, but the IDs cannot be matched, ADC can correctly delete the remote resource and create a new one based on the local configuration, in which case the ID will be generated by ADC based on the resource name and can be used for subsequent resource lookup. API7 dashboard users will not be affected, and resources created by ADC can still be viewed on the dashboard.

Supporting ADC Extension Fields in OpenAPI Converter

This feature was introduced in version 0.10.
To build a coherent pipeline from OpenAPI to ADC to API7, the OpenAPI converter needs to inject the required fields into the ADC YAML configuration file based on our needs.

For example, to modify the pass_host field in the service's upstream, previously we could only manually use the converter to convert the OpenAPI to the ADC configuration file, manually modify the pass_host field, and then submit the modified file to the Git repository for the CI/CD pipeline to execute the ADC sync. This process is not coherent and requires a lot of manual intervention.

Now, through the introduced x-adc series of extensions, users only need to write the extension fields at specific locations in the OpenAPI document, and ADC will correctly write these fields in the generated configuration file. With these extensions, users can directly modify any content in the ADC configuration on the OpenAPI, such as adding labels, adding plugins, and overriding the default configuration of services/upstreams/routes.

As a result, by maintaining only one OpenAPI file, the OpenAPI-ADC-API7 pipeline can be implemented in a one-stop manner, greatly simplifying the GitOps workflow for API gateway configuration.

Conclusion

The declarative configuration tool ADC launched by API7.ai can help enterprises realize GitOps management of API gateways. In the new versions 0.8, 0.9, and 0.10, the tool has been functionally optimized and upgraded, adding features such as resource change monitoring and filtering. These new features inject new momentum into the full API lifecycle management.

These new capabilities allow ADC to better meet enterprises' needs for API gateway GitOps management, improving the efficiency and flexibility of API management.