OpenResty Edge inherently offers robust configuration management capabilities. Every change made via the Admin Console UI or API is fully auditable with a complete change history and includes a built-in review and release process. For most teams and scenarios, these native mechanisms are sufficiently reliable and user-friendly.

However, in discussions with our customers, we’ve identified a specific set of needs—particularly prevalent among teams deeply integrated with the Kubernetes ecosystem or those who have established a GitOps framework:

• They prefer to store all infrastructure configurations as text files in Git repositories, driving changes through PR/MR workflows.
• Their CI/CD pipelines are mature, and they want gateway configuration changes to integrate into this automated system, rather than relying on a separate UI-based process.
• They frequently need to replicate configurations across multiple environments (development, testing, production) and seek a scriptable way to achieve this.
• When dealing with numerous similarly structured configuration items, they prefer editing text files directly over clicking through items one by one in the UI.

The essence of these requirements is to integrate OpenResty Edge configurations into their existing Configuration as Code workflows, rather than maintaining a separate management process outside of the OpenResty Edge Admin.

If your team primarily manages configurations through the Admin UI, the tool introduced in this article is not a necessity; you can continue using the native mechanisms. Consider adopting edge2yaml when you encounter needs such as GitOps integration, multi-environment synchronization, or bulk editing.

What is edge2yaml

edge2yaml is an official command-line tool provided by OpenResty Edge that enables bidirectional conversion between local YAML files and the OpenResty Edge platform. It offers three core operations:

• Import (import): Pushes local YAML configuration files to Edge Admin, creating or updating configurations.
• Export (export): Pulls existing configurations from Edge Admin locally, generating structured YAML files. Sensitive information (such as SSL private keys, user passwords) is replaced by placeholders during export.
• Cleanup (cleanup): Removes configuration items in Edge Admin according to a specified scope. It supports various granularities, from “cleaning up an entire application” to “only cleaning up a specific type of configuration under a particular application.” It’s important to note that when “automatic synchronization to other partitions” is enabled in Edge, global configurations will not be actually reset or deleted during cleanup operations. This is to ensure compatibility with scenarios involving multiple local configurations. If “automatic synchronization” is not enabled, redundant configurations that are absent locally will be reset or cleaned up.

The tool communicates with the platform via the Edge Admin API and requires an API Token for authentication. Configuration files are organized by partition and application, featuring a clear directory structure that facilitates tracking with version control systems. In terms of capability coverage, it supports managing global configurations, global/application-level upstreams, page rules, and other features. This covers most functionalities available on OpenResty Edge, essentially addressing the primary configurable objects for daily operations.

Note: edge2yaml currently only supports the enterprise version of OpenResty Edge.

Usecase

1. GitOps Workflow

Exported YAML files are stored in a Git repository. Configuration changes are submitted via PR/MR, and after code review, they are automatically imported by a CI/CD pipeline calling edge2yaml. This approach ensures that the gateway configuration change process aligns with the application code release process, making it suitable for teams that have established GitOps practices.

2. Multi-Environment Configuration Synchronization

Export configurations from the production environment, modify environment-specific parameters (such as upstream addresses, domain names), and then import them into testing or pre-production environments. Compared to repetitive manual operations across multiple UIs, this method offers greater control and simplifies discrepancy troubleshooting.

3. External Versioned Backup

Regularly execute the export command to commit the generated YAML files to a Git repository. By leveraging Git’s history, you can view configuration snapshots at any point in time and re-import them when needed.

4. Batch Editing

When similar structural changes are required for a large number of configuration items (e.g., batch adjusting upstream timeout parameters, batch adding a specific rule), directly editing the YAML files or generating them via scripts and then importing them all at once is more efficient than performing individual UI operations. During the import process, if the YAML contains issues such as invalid fields, the tool will provide error messages pinpointing the specific file and line number, facilitating quick fixes.

edge2yaml vs. OpenResty Edge Admin’s Native Capabilities

Before deciding whether to adopt edge2yaml, it’s essential to understand the built-in configuration management capabilities of OpenResty Edge Admin, as well as edge2yaml’s role and limitations in comparison.

OpenResty Edge Admin’s Built-in Capabilities

OpenResty Edge Admin’s configuration management is database-driven and offers the following features:

• Complete change records: Every operation’s initiator, time, and content are recorded, providing clear context;
• Built-in review and release process: Supports change review and controlled releases, with real-time visibility into the status of operations;
• Platform-level reliability and data backup mechanism: Data consistency is guaranteed by the platform, which also provides corresponding backup and recovery capabilities;
• Concurrency safety: The database transaction mechanism ensures that configuration overwrites or losses do not occur during simultaneous operations by multiple users.

For most configuration management requirements, OpenResty Edge Admin’s native approach is a more reliable and comprehensive choice.

edge2yaml is suitable for integrating OpenResty Edge configurations into Git and CI/CD systems. However, it has several inherent limitations: the exported YAML file is a point-in-time snapshot, and the granularity and completeness of the version history depend on the team’s commit practices, which are typically less fine-grained than the change records automatically maintained by the platform. Furthermore, some runtime states and internal platform dependencies cannot be fully expressed through static YAML.

Additionally, for security reasons, sensitive information such as SSL private keys and user passwords is replaced by placeholders during export. These configurations require separate handling when migrating across environments.

Suggested Usage

Leverage OpenResty Edge Admin as the primary entry point for daily configuration management, fully utilizing its built-in version control, review and release, and backup capabilities. In the following specific scenarios, edge2yaml can serve as a supplementary tool:

• Your team already has a mature GitOps system and wishes to incorporate Edge configurations into unified management.
• You need to migrate configurations between multiple environments.
• You need to integrate configuration changes into existing CI/CD pipelines.
• You need to maintain a text backup of the configuration in an external system.

These two approaches are not mutually exclusive; a sensible division of labor can accommodate both workflow preferences and platform reliability.

Summary

edge2yaml offers an official pathway for teams that prefer a GitOps workflow, allowing OpenResty Edge configuration management to integrate seamlessly with Git and CI/CD systems. If your team is accustomed to managing infrastructure configurations with Git, or needs to synchronize configurations in bulk across multiple environments, edge2yaml is a valuable tool to consider.

For more comprehensive installation instructions, command parameters, and configuration directory structure, please refer to the official documentation: YAML-based OpenResty Edge Configuration Mirroring, and the corresponding Usage Examples.

What is OpenResty Edge

OpenResty Edge is our all-in-one gateway software for microservices and distributed traffic architectures. It combines traffic management, private CDN construction, API gateway, security, and more to help you easily build, manage, and protect modern applications. OpenResty Edge delivers industry-leading performance and scalability to meet the demanding needs of high concurrency, high load scenarios. It supports scheduling containerized application traffic such as K8s and manages massive domains, making it easy to meet the needs of large websites and complex applications.

About The Author

Yichun Zhang (Github handle: agentzh), is the original creator of the OpenResty^® open-source project and the CEO of OpenResty Inc..

Yichun is one of the earliest advocates and leaders of “open-source technology”. He worked at many internationally renowned tech companies, such as Cloudflare, Yahoo!. He is a pioneer of “edge computing”, “dynamic tracing” and “machine coding”, with over 22 years of programming and 16 years of open source experience. Yichun is well-known in the open-source space as the project leader of OpenResty^®, adopted by more than 40 million global website domains.

OpenResty Inc., the enterprise software start-up founded by Yichun in 2017, has customers from some of the biggest companies in the world. Its flagship product, OpenResty XRay, is a non-invasive profiling and troubleshooting tool that significantly enhances and utilizes dynamic tracing technology. And its OpenResty Edge product is a powerful distributed traffic management and private CDN software product.

As an avid open-source contributor, Yichun has contributed more than a million lines of code to numerous open-source projects, including Linux kernel, Nginx, LuaJIT, GDB, SystemTap, LLVM, Perl, etc. He has also authored more than 60 open-source software libraries.