🔗 OpenResty Edge Installation FAQ

🔗 System Requirements and Architecture

🔗 What are the main components of OpenResty Edge and their respective roles?

OpenResty Edge mainly consists of three core components: Edge Admin (management console), Edge Log Server (log and metrics server), and Edge Node (gateway node). Additionally, there are two data storage components: Edge Admin Database and Edge Log Server Database.

🔗 What hardware configuration is required to install OpenResty Edge?

A production environment requires at least three machines, each installing Edge Admin + Admin DB, Log Server + Log Server DB, and Edge Node. For clusters with less than 10 nodes, it is recommended that Edge Admin and Log Server have at least 4 cores, 16GB RAM, and 200GB SSD. The configuration for Edge Node depends on the business volume, generally 1 core with 2GB RAM.

🔗 My network environment has firewall restrictions. Which ports and domains need to be opened?

You need to whitelist port 443 of openresty.com, openresty.org, pkg.openresty.com, and api.openresty.com. Specific ports also need to be opened between components: Edge Admin requires ports 443 and 12345, and Log Server requires ports 12346 and 8089.

🔗 Installation Process

🔗 How to obtain the installation package for OpenResty Edge?

You can obtain the configuration package (openresty-edge-VERSION.tar.gz) for online installation and the complete offline installation package (openresty-edge-bundle-VERSION.tar.gz) from the OpenResty download center (https://openresty.com/en/dashboard/downloads).

🔗 How to get the login account and password for the Edge Admin management interface after installation?

You can use the "Get Default Info" feature of the installer to obtain the default login information, or contact technical support to reset the password.

🔗 How to verify if each component is working properly after installation?

You can check the status of each service using the systemctl status command, such as sudo systemctl status oredge-admin. You can also check the log directories of each component, such as /usr/local/oredge-admin/logs, for any abnormal information.

🔗 Configuration and High Availability

🔗 How to improve the availability of Edge Admin and Log Server?

You can configure two Edge Admin services in dual-master mode or deploy multiple Log Server instances. Edge Admin requires modifying the clone_admin configuration in config.ini, and Edge Node needs to configure the host2 field under the admin section. Multiple Log Server instances need to be added to the configuration of both Edge Admin and Edge Node.

🔗 How to ensure data security? What are the data backup solutions?

It is recommended to regularly back up the database. You can refer to the Database Backup section in the documentation. You can also set up a database cluster to achieve automatic master-slave switching and improve database availability.

🔗 How to update the SSL certificate of Edge Admin after installation?

You can manually replace the /usr/local/oredge-admin/conf/ssl/ssl.crt and /usr/local/oredge-admin/conf/ssl/ssl.key files, or specify the certificate path using the -s and -k parameters during installation. Alternatively, you can use Edge Node to proxy the traffic of Edge Admin and issue SSL certificate for Edge Admin.

🔗 Troubleshooting

🔗 What to do if the "not yet approved" error appears after installing Edge Node?

This is a normal phenomenon, indicating that Edge Node has successfully connected to Edge Admin and needs to be approved in the Edge Admin management console to join. You can refer to the Gateway Cluster documentation for operation.

🔗 OpenResty Edge™ SDK Customer FAQ

🔗 Where to obtain the most critical authentication information (address, port, username, password) when using the SDK?

This information is consistent with the information you use to log in to the Edge Admin Web console. The parameters required for Edge2Client initialization are your backend access address and login credentials. If your Admin uses a non-standard HTTPS port, be sure to specify it clearly in the address.

🔗 My development environment uses a self-signed certificate, and the SDK reports an SSL error when connecting. How to handle it?

This is a very common scenario. You only need to execute client.set_ssl_verify(False) before calling client.login() to skip certificate verification. However, in a production environment, it is strongly recommended to configure a valid certificate issued by an authoritative CA to ensure security.

🔗 I called the API to modify the configuration, why didn't it take effect? What is the correct release process?

All configuration changes in the SDK are transactional and will not be automatically published. This is a safety design to prevent misoperations from affecting online services. The correct process is "Modify -> Publish -> Verify":

1. Modify: Call interfaces such as new_rule(), put_app() to make changes.
2. Publish: Call client.new_release() to create a new version of all pending changes and make it effective.
3. Verify: (Optional but recommended) Call client.sync_status() to check if the configuration has been synchronized to all nodes.

🔗 What are the best practices for automating operations (such as batch updating rules, IP lists) using the SDK?

1. Idempotency: Before performing a create operation, first query whether the target exists to avoid duplicate creation. When performing updates, ensure that the script can be run repeatedly.
2. Robustness: Use try...except to catch exceptions in all API calls and record detailed logs.
3. Performance considerations: For large-scale batch operations (such as updating thousands of IPs at once), it is recommended to process the data in batches and add a short delay (such as 1 second) between batches to avoid triggering the Admin's protection mechanism due to high request frequency.

🔗 How do I integrate the SDK into my CI/CD pipeline (such as Jenkins, GitLab CI) to achieve Configuration as Code?

This is the most valuable application scenario of the SDK. The usual approach is:

1. Code Configuration: Store your Edge application configuration (such as upstreams, rules, etc.) in a specific format (such as YAML, JSON) in the code repository.
2. Write a synchronization script: Develop a Python script that reads the coded configuration file and calls the SDK interface to apply the configuration to Edge Admin.
3. Integrate into CI/CD: Add a stage in your CI/CD pipeline that automatically triggers the Python script to complete the configuration change and release it to Edge when the configuration code changes.
4. Credential Management: Store the high-privilege password for logging into Edge Admin in the CI/CD system's secret management tool and pass it to the script securely to avoid plaintext storage.

🔗 OpenResty Edge Dynamic Metrics FAQ

🔗 What is the core value of the "Dynamic Metrics" feature? In what scenarios should I use it?

Its core value is to provide deep customized business and security insights that standard dashboards cannot satisfy. You should use it in the following scenarios:

• Track specific business metrics: For example, count the number of requests from VIP users, the success rate of API calls for a newly launched event, the distribution of requests from different Android versions, etc.
• Conduct fine-grained security analysis: For example, find the Top 10 IP addresses that attack a specific URI the most, or count the proportion of requests intercepted by WAF from a specific country.
• Implement custom performance monitoring: For example, calculate the P99 response latency of a specific upstream service, rather than just the average.

🔗 Before writing a query, how do I know which data tables and fields are available? Is there a data dictionary?

This is the most critical first step. The data sources you can rely on are mainly the reqs (request logs) and waf_hits (WAF logs) virtual tables. To know the exactly available fields they contain (such as client_ip, status, uri, resp_header('Content-Type'), etc.), the most authoritative way is to consult the Dynamic Metrics section in the OpenResty Edge official documentation.

🔗 I want to count a business metric, such as "count the Top 10 users with the highest request volume based on the user_id field in JWT", is it possible?

Yes, this is exactly the strength of dynamic metrics. Assuming your user_id is in the request header named X-Jwt-Claim-User-Id, the query can be written as follows:

-- Assuming user_id is in the request header 'X-Jwt-Claim-User-Id'
SELECT ngx_var('http_x_jwt_claim_user_id') as user_id, count(*) as count
FROM reqs
WHERE ngx_var('http_x_jwt_claim_user_id') != ''
GROUP BY user_id
ORDER BY count DESC
LIMIT 10;

The key is to use the ngx_var() function to obtain custom request headers (with the http_ prefix) or other Nginx variables, thereby associating business logic with log data.

🔗 Where are dynamic metrics queries executed? Will they affect the performance of the online gateway?

This is a very important security question. Dynamic metrics queries are executed on the Edge Log Server, which processes log data collected from the gateway nodes in bypass mode. Therefore, no matter how complex your queries are, they will not affect the performance of the Edge Node (gateway node) that handles real-time business traffic. You can safely use this feature for complex data analysis.

🔗 OpenResty Edge Edgelang FAQ

🔗 In what scenarios should I use Edgelang instead of the standard page rules UI?

This is the most core decision issue. You should consider using Edgelang in scenarios where standard UI rules cannot meet the requirements, are complex, dynamic, or have extreme performance requirements.

• Standard Rules UI: Suitable for common, static logic, such as "redirect to new-url when URI is /path". It is simple, intuitive, and ready to use.
• Edgelang: Suitable for scenarios that require "programming" logic, such as:
  • Complex conditions: Need to make combined judgments based on multiple request headers, Cookies, client IP geographic location, etc.
  • Response processing: Need to dynamically modify the response body content (such as inserting JS scripts in HTML) or response headers.
  • Dynamic routing: Need to dynamically select upstream services based on specific request parameters (such as user ID, and area code).
  • Performance optimization: When you have hundreds of rules, the Edgelang compiler will optimize them into an efficient single code block, which usually performs better than the sequential execution of hundreds of independent page rules.

🔗 What is the most powerful application scenario of Edgelang? Can you give an example?

The most powerful aspect of Edgelang is its deep programming and control capabilities over requests and responses. The most typical "killer" application scenarios are A/B testing and staging releases.

Example: Implement staging release based on user ID Assume you want users with a user ID ending in "7" to access the new upstream service new-backend-upstream, while other users access the old version.

# Rule: staging Release
# When the cookie in the request contains userid, and userid ends with '7'
req-cookie("userid"), req-cookie("userid") suffix "7" =>
  set-upstream-name("new-backend-upstream");

This logic can also be implemented with standard UI rules, but it is more concise and efficient with Edgelang.

🔗 I have written a piece of Edgelang code, how do I deploy and execute it?

Edgelang code is not deployed independently but is executed as an action of a page rule. The process is as follows:

1. Write code: Write your Edgelang rules in a code editor.
2. Create a page rule: Create a new page rule under an application in Edge Admin.
3. Set conditions: (Optional) Set trigger conditions for the requests you want to execute Edgelang, such as "URI path prefix is /api/".
4. Select action: In the "action" section of the rule, select "Execute Edgelang" as the action.
5. Paste code: Paste your written Edgelang code into the action input box.
6. Save and publish: Save and publish this page rule.

After that, when a request matches the conditions you set, your embedded Edgelang code will be executed.

🔗 What is the execution order of Edgelang? How does it cooperate with other rules such as WAF and caching?

As part of the page rules, Edgelang's execution follows the Nginx processing phases and the priority of page rules. A simplified request processing flow is as follows:

1. Page rules (including Edgelang or WAF): The request will enter the processing logic of the page rules. At this time, rules containing Edgelang or WAF will be executed according to their priority (which can be dragged and sorted in the UI) and trigger conditions.
2. Caching: Edgelang can control subsequent behavior. For example, you can call the enable-proxy-cache() action in an Edgelang rule to decide whether to enable caching for a request.

🔗 How is the performance and security of Edgelang? What if I write problematic code?

• Performance: Extremely high. The Edgelang compiler will deeply analyze and optimize your rules (even across multiple rules) to generate very efficient Lua code. Its performance is usually better than the combination of a large number of independent page rules.
• Security:
  • Compile-time check: The Edgelang compiler will perform strict syntax and logic checks when you save the rules, and most low-level errors (such as syntax errors, and function name typos) will be discovered and prevented from being saved.
  • Sandbox environment: The execution of Edgelang is restricted to a secure sandbox environment, where it can only call the built-in functions and actions listed in the manual, and cannot execute arbitrary system commands or dangerous operations.
  • Testing: Although there is currently no independent "dry run" mode, the best practice is to first deploy and test your Edgelang rules on a non-production application or service to verify their logical correctness before applying them to the production environment.