After a month, the new version came again. This APISIX 3.1.0 is the first new version since the 3.0 major version. In the new era of 3.x, we will continue to provide you with more new functions in each version.

Version 3.1.0 released this time adds support for encrypted storage of plug-in configurations and storage in external security services, focusing on enabling users to use their configurations more securely and with confidence. In addition, we have also introduced many new features aimed at optimizing the experience of using APISIX.

New feature: encrypted storage of plugin configuration

The new version supports encrypted storage of specific fields of plugins into etcd.

In previous versions, APISIX provided a key_encrypt_salt The configuration item supports encrypting the SSL key stored in etcd to avoid storing private key data in plain text. After all, for sensitive data such as private keys, one less place to store plaintext can provide more peace of mind.Then for other equally sensitive configurations, such as jwt-auth Can we also encrypt the secret in the plug-in to avoid storing plaintext in etcd?

In version 3.1, the function of encrypted storage is extended to other fields.With this function, we can specify the fields that need to be encrypted on a specific plug-in, and then config.yaml Encryption is enabled in the file to avoid plaintext storage.

As an example, we give jwt-auth The plugin adds the following tags:

     encrypt_fields = {"secret", "private_key"},

when we are config.yaml The encryption function of the field is enabled in:

apisix:
    data_encryption:
        enable: true
        keyring:
            - edd1c9f0985e76a2

Then write to etcd jwt-auth The secret and private_key in the plug-in configuration will be encrypted and stored.pass etcdctl get --prefix / The configuration you see will be data such as “”secret”:”77+NmbYqNfN+oL…”” instead of the original configuration information.

New Feature: Store Sensitive Information in External Secure Services

In addition to encrypting and storing sensitive information in etcd, you can also choose to dynamically obtain sensitive information from other systems, instead of requiring sensitive information to be stored in APISIX configuration storage (such as etcd).

In version 3.1, we launched a function called APISIX Secret. APISIX Secret allows users to store secrets in APISIX through some key management services (Vault, etc.), and read them according to the key when using them, so as to ensure that secrets do not exist in plain text in the entire platform.

APISIX currently supports storing secrets in the following ways:

• environment variable
• HashiCorp Vault

related examples

by key-auth Taking the plugin as an example, let’s briefly demonstrate how to use this feature.

Sensitive information storage based on environment variables

Step 1: Create environment variables before the APISIX instance starts

export JACK_AUTH_KEY=abc

Step 2: In key-auth Reference environment variables in plugins

curl http://127.0.0.1:9180/apisix/admin/consumers \\
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "username": "jack",
    "plugins": {
        "key-auth": {
            "key": "$ENV://JACK_AUTH_KEY"
        }
    }
}'

Through the above steps, the key-auth The key configuration in the plug-in is saved in the environment variable instead of being displayed in plain text when configuring the plug-in.

Vault-based storage of sensitive information

Step 1: Create the corresponding configuration in Vault, you can use the following command:

vault kv put apisix/jack auth-key=value

Step 2: Add Secret resource through Admin API, configure Vault address and other connection information:

curl http://127.0.0.1:9180/apisix/admin/secrets/vault/1 \\
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "https://127.0.0.1:8200"，
    "prefix": "apisix",
    "token": "root"
}'

Step 3: In key-auth The APISIX Secret resource is referenced in the plug-in, and the location of the configuration in Vault is filled:

curl http://127.0.0.1:9180/apisix/admin/consumers \\
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "username": "jack",
    "plugins": {
        "key-auth": {
            "key": "$secret://vault/1/jack/auth-key"
        }
    }
}'

Through the above steps, the key-auth The key configuration in the plug-in is stored in the Vault instead of being displayed in plain text when configuring the plug-in.

New feature: Experimental gRPC-based etcd configuration synchronization

In this new release, we also introduced experimental gRPC-based etcd configuration synchronization. The current APISIX synchronous etcd configuration is based on HTTP long pulling, which requires etcd to enable gRPC-gateway (fortunately, it is enabled by default).

In practice, we encountered problems with etcd’s HTTP API, perhaps because synchronous configuration via HTTP is not the mainstream way of using etcd, so it is more likely to encounter bugs. By switching etcd configuration synchronization from HTTP long pulling to gRPC, APISIX has achieved a synchronization method that is in line with the mainstream.

In addition, because gRPC itself provides multiplexing support, switching to gRPC synchronization configuration can greatly reduce the number of connections from APISIX to etcd. Currently APISIX needs to have an independent HTTP connection for each type of configuration synchronization. After switching to gRPC, each process has only one connection for configuration synchronization (if the L4 proxy is enabled, then there are two connections).

Enables experimental gRPC-based configuration synchronization, requires a configuration file config.yaml set in use_grpc: true,As follows:

  etcd:
    use_grpc: true
    timeout: 3600
    host:
      - "http://127.0.0.1:2379"
    prefix: "/apisix"

New feature: Consul-based service discovery

In previous versions of APISIX, enthusiastic contributors provided a service discovery implementation based on Consul KV. However, Consul KV is somewhat different from Consul’s own service discovery function. Consul’s own service discovery supports some additional functions, such as health checks for registered services, so it will be more widely used. In this version 3.1, another enthusiastic contributor provides Consul-based service discovery to fill this gap.

Consul-based service discovery has a similar configuration to Consul KV-based service discovery in previous versions.First, you need to config.yaml The service discovery is enabled in the file:

discovery:
  consul:
    servers:
      - "http://127.0.0.1:8500"

Then configure the corresponding in the specific upstream service_name with discovery_type:

curl http://127.0.0.1:9180/apisix/admin/upstreams/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
{
    "service_name": "service_a",
    "discovery_type": "consul"
}'

During the use of the corresponding upstream, the real upstream node will be obtained according to the value configured in Consul.

New feature: built-in debug plugin

If a worker wants to do a good job, he must first sharpen his tools. Debugging is part of a programmer’s daily work. As a gateway focusing on debugging experience, APISIX built a Lua debugger plug-in in the form of a plug-in in version 3.1, which supports dynamic setting of breakpoints, adding callbacks, etc.

The default configuration is as follows:

plugins:
    ...
    - inspect
    ...

plugin_attr:
  inspect:
    delay: 3
    hooks_file: "/usr/local/apisix/plugin_inspect_hooks.lua"

After APISIX is started, it will regularly check the configured hooks_file (here “/usr/local/apisix/plugin_inspect_hooks.lua”). If there is content in the file, it will set breakpoints and callbacks according to the content.For example, the following content will set a breakpoint on line 88 of limit-req.lua, and register a callback function on the breakpoint function(info) ... end.

local dbg = require "apisix.inspect.dbg"

dbg.set_hook("limit-req.lua", 88, require("apisix.plugins.limit-req").access, function(info)
    ngx.log(ngx.INFO, debug.traceback("foo traceback", 3))
    return true
end)

New features: optimizations and more small features

In addition to the several major features mentioned above, this release also contains many changes worth mentioning, such as: