What's New in ADC 0.11 & 0.12?

Since the release of ADC (API Declarative CLI) version 0.10 two months ago, we have been working tirelessly to deliver two major updates—versions 0.11 and 0.12, along with a series of targeted patch updates. These updates mainly focus on supporting Apache APISIX, improving existing features, and fixing bugs.

Add Backend Support to Apache APISIX

Starting from ADC 0.11, experimental support for the Apache APISIX backend has been introduced.

ADC is now integrated with the APISIX Admin API, enabling efficient resource export and synchronization. We will continue to enhance its usability. The apisix backend option is enabled by default in ADC; users only need to configure the Admin API endpoint and API key to connect.

Differences Between ADC and the Admin API

Please note that ADC does not aim to fully align with all the functionalities of APISIX but rather focuses on a core feature set and best practices. We believe that investing in features that users truly need, rather than blindly pursuing comprehensive coverage, is the path for ADC’s development.

Although APISIX offers a high degree of configuration flexibility, this freedom often comes with the complexity of long-term maintenance. When configuration management is transferred from one maintainer to another, the new maintainer typically faces the challenge of understanding the previous maintainer's unique configuration approach and style, instead of directly adopting a set of mature and widely recognized best practice rules.

For example, on the APISIX platform, users can configure routes that are not directly bound to specific services but instead specify upstream resources directly at the route level. However, this method is not natively supported by ADC. To align with logical norms and standardized operating procedures, the recommended approach is to include routes within a specific service and precisely set upstream addresses inline within that service.

For instance, in a product service, we define a service named Product Service and configure the upstream, enable plugins, and set routes within it. In this model, multiple routes can share the same upstream and plugin configuration, greatly simplifying the configuration process.

services:
  - name: Product Service
    upstream:
      type: roundrobin
      nodes:
        - host: product.ecommerce.svc.cluster.local
          port: 443
          weight: 100
      scheme: https
    plugins:
      key-auth: {}
    routes:
      - name: List Products
        uris:
          - /products
        methods: ["GET"]
      - name: Get Product
        uris:
          - /product/*
        methods: ["GET"]

The above example is a minimal format for service definition. Beyond this, ADC also supports advanced features such as service discovery, timeout settings, retry policies, and route prioritization, ensuring comprehensive and flexible configuration.

Given that APISIX supports richer configuration methods, ADC may encounter inconsistencies when exporting configurations compared to the APISIX Admin API display, such as:

• Routes not using services will be clustered into a service to meet the service-route hierarchy.
• Upstreams referenced by ID will be inlined at the point of use.
• Plugin template resources will be replaced by services containing routes.

Therefore, users need to carefully review the ADC definition files generated during the export process to ensure they still meet the original intent.

Why Is ADC Recommended?

When using the APISIX Dashboard, users often need to perform repetitive operations in forms, which can be cumbersome and prone to errors. In contrast, using ADC for declarative configuration involves simply writing YAML files and executing synchronization operations. ADC will automatically convert the configurations into Admin API calls, enabling quick deployment and management.

Thus, ADC can help simplify the management and deployment process, and it can easily achieve GitOps scenarios. This involves managing YAML definition files via a Git repository and using PR workflows and CI tools to automatically update configurations. This significantly reduces the amount of manual operations required, avoids the issues present in the APISIX Dashboard, and reduces the complexity of writing scripts to call the Admin API.

For new projects, we strongly recommend building gateway configurations starting with ADC. For existing projects, gradual migration to ADC management can be achieved by exporting and moderately modifying the configurations.

Backend Optimization of API7 Enterprise

Included in versions 0.11/0.12

In versions 0.11 and 0.12, we have implemented several optimizations for the API7 backend to enhance the developer experience. ADC is fully compatible with these improvements, meaning developers only need to keep their ADC version up to date to benefit from these enhancements without any modifications to existing definition files.

Optimizing ADC Definition Checks

Included in version 0.12

We have comprehensively optimized and fixed the schema rules for ADC definition checks to help developers detect and effectively avoid potential configuration issues in advance.

JSON Schema

Furthermore, we now support exporting the validation rules as a JSON Schema to assist editors using IDEs. Users will benefit from both syntax hints and real-time checks in their files, significantly improving coding efficiency and quality.

For developers who prefer Visual Studio Code, enabling the YAML plugin and adding the following comment at the top of the file will activate this feature:

# yaml-language-server: $schema=https://raw.githubusercontent.com/api7/adc/main/schema.json

Conclusion

As previously mentioned in our blogs, ADC will eventually be open-sourced. After six months of internal development and multiple iterations, ADC has been fully restructured into a TypeScript-based codebase, completely abandoning the original Go code. This makes it easier to learn and develop.

With the public release of ADC version 0.12, we invite developers worldwide to participate in its development and improvement. The codebase is now open at https://github.com/api7/adc, and we look forward to your contributions.