File-Driven Standalone Mode Configurations

Learn about file-driven standalone configurations in Apache APISIX, which allow the gateway to load gateway configurations from a YAML or JSON file.

In file-driven standalone mode, APISIX fetches configuration from apisix.yaml or apisix.json instead of using etcd as the configuration center. These configurations are loaded into memory at startup and monitored for changes at a regular interval, without the requirement of manually reloading APISIX.

If you are working with apisix.yaml, please note that APISIX will not load the configurations if there is no #END at the end of the file.

This document provides some configuration examples for APISIX deployed in file-driven standalone mode. To learn more about the available configuration options, see the Admin API reference (but do not use these endpoints). These configuration options can be translated into YAML or JSON for use in file-driven standalone mode.

Configure Routes

This example creates two routes to forward requests to /hello and /hello2 to different upstreams:

apisix.yaml

routes:
  -
    uri: /hello
    upstream:
      nodes:
        "127.0.0.1:1980": 1
      type: roundrobin
  -
    uri: /hello2
    upstream:
      nodes:
        "127.0.0.1:1981": 1
      type: roundrobin
#END

apisix.json

{
  "routes": [
    {
      "uri": "/hello",
      "upstream": {
        "nodes": {
          "127.0.0.1:1980": 1
        },
        "type": "roundrobin"
      }
    },
    {
      "uri": "/hello2",
      "upstream": {
        "nodes": {
          "127.0.0.1:1981": 1
        },
        "type": "roundrobin"
      }
    }
  ]
}

Configure Routes and Services

This example creates a service and a route within the service:

apisix.yaml

routes:
  -
    uri: /hello
    service_id: 1
services:
  -
    id: 1
    upstream:
      nodes:
        "127.0.0.1:1980": 1
      type: roundrobin
#END

apisix.json

{
  "routes": [
    {
      "uri": "/hello",
      "service_id": 1
    }
  ],
  "services": [
    {
      "id": 1,
      "upstream": {
        "nodes": {
          "127.0.0.1:1980": 1
        },
        "type": "roundrobin"
      }
    }
  ]
}

Configure Routes and Upstreams

This example creates an upstream and a route that points to the upstream:

apisix.yaml

routes:
  -
    uri: /hello
    upstream_id: 1
upstreams:
  -
    id: 1
    nodes:
      "127.0.0.1:1980": 1
    type: roundrobin
#END

apisix.json

{
  "routes": [
    {
      "uri": "/hello",
      "upstream_id": 1
    }
  ],
  "upstreams": [
    {
      "id": 1,
      "nodes": {
        "127.0.0.1:1980": 1
      },
      "type": "roundrobin"
    }
  ]
}

Configure Routes, Services, and Upstreams

This example creates an upstream, a service, and a route within the service:

apisix.yaml

routes:
  -
    uri: /hello
    service_id: 1
services:
  -
    id: 1
    upstream_id: 2
upstreams:
  -
    id: 2
    nodes:
      "127.0.0.1:1980": 1
    type: roundrobin
#END

apisix.json

{
  "routes": [
    {
      "uri": "/hello",
      "service_id": 1
    }
  ],
  "services": [
    {
      "id": 1,
      "upstream_id": 2
    }
  ],
  "upstreams": [
    {
      "id": 2,
      "nodes": {
        "127.0.0.1:1980": 1
      },
      "type": "roundrobin"
    }
  ]
}

Configure Plugins

This example enables three plugins:

apisix.yaml

plugins:
  - name: ip-restriction
  - name: jwt-auth
  - name: mqtt-proxy
    stream: true
#END

apisix.json

{
  "plugins": [
    {
      "name": "ip-restriction"
    },
    {
      "name": "jwt-auth"
    },
    {
      "name": "mqtt-proxy",
      "stream": true
    }
  ]
}

Set stream to true for L4 plugins.

Note that this configuration will override the list of plugins enabled by default or in the configuration file.

Configure Plugin Configs

This example creates a plugin config which is referenced by a route:

apisix.yaml

plugin_configs:
  -
    id: 1
    plugins:
      response-rewrite:
        body: "hello\n"
routes:
  - id: 1
    uri: /hello
    plugin_config_id: 1
    upstream:
    nodes:
      "127.0.0.1:1980": 1
    type: roundrobin
#END

apisix.json

{
  "plugin_configs": [
    {
      "id": 1,
      "plugins": {
        "response-rewrite": {
          "body": "hello\n"
        }
      }
    }
  ],
  "routes": [
    {
      "id": 1,
      "uri": "/hello",
      "plugin_config_id": 1,
      "upstream": {
        "nodes": {
          "127.0.0.1:1980": 1
        },
        "type": "roundrobin"
      }
    }
  ]
}

Configure Plugin Global Rules

This example creates a plugin global rule:

apisix.yaml

global_rules:
  -
    id: 1
    plugins:
      response-rewrite:
        body: "hello\n"
#END

apisix.json

{
  "global_rules": [
    {
      "id": 1,
      "plugins": {
        "response-rewrite": {
          "body": "hello\n"
        }
      }
    }
  ]
}

Configure Plugin Metadata

This example creates plugin metadata:

apisix.yaml

upstreams:
  - id: 1
    nodes:
      "127.0.0.1:1980": 1
    type: roundrobin
routes:
  -
    uri: /hello
    upstream_id: 1
    plugins:
      http-logger:
        batch_max_size: 1
        uri: http://127.0.0.1:1980/log
plugin_metadata:
  - id: http-logger
    log_format:
      host: "$host",
      remote_addr: "$remote_addr"
#END

apisix.json

{
  "upstreams": [
    {
      "id": 1,
      "nodes": {
        "127.0.0.1:1980": 1
      },
      "type": "roundrobin"
    }
  ],
  "routes": [
    {
      "uri": "/hello",
      "upstream_id": 1,
      "plugins": {
        "http-logger": {
          "batch_max_size": 1,
          "uri": "http://127.0.0.1:1980/log"
        }
      }
    }
  ],
  "plugin_metadata": [
    {
      "id": "http-logger",
      "log_format": {
        "host": "$host",
        "remote_addr": "$remote_addr"
      }
    }
  ]
}

Configure SSL

This example configures SSL:

apisix.yaml

ssls:
  - 
    cert: ${{SERVER_CERT}}
    key: ${{SERVER_KEY}}
    snis:
      - "yourdomain.com"
#END

apisix.json

{
  "ssls": [
    {
      "cert": "${{SERVER_CERT}}",
      "key": "${{SERVER_KEY}}",
      "snis": [
        "yourdomain.com"
      ]
    }
  ]
}

To learn more about setting environment variables, see Use Environment Variables in Configuration Files.

Configure Consumers

This example creates a consumer:

apisix.yaml

consumers:
  - username: jwt
    plugins:
      jwt-auth:
        key: user-key
        secret: my-secret-key
#END

apisix.json

{
  "consumers": [
    {
      "username": "jwt",
      "plugins": {
        "jwt-auth": {
          "key": "user-key",
          "secret": "my-secret-key"
        }
      }
    }
  ]
}

Configure Stream Routes

This example creates a stream route:

apisix.yaml

stream_routes:
  - server_addr: 127.0.0.1
    server_port: 1985
    id: 1
    upstream:
       nodes:
         "127.0.0.1:1981": 1
       type: roundrobin
    plugins:
      mqtt-proxy:
        protocol_name: "MQTT"
        protocol_level: 4
#END

apisix.json

{
  "stream_routes": [
    {
      "server_addr": "127.0.0.1",
      "server_port": 1985,
      "id": 1,
      "upstream": {
        "nodes": {
          "127.0.0.1:1981": 1
        },
        "type": "roundrobin"
      },
      "plugins": {
        "mqtt-proxy": {
          "protocol_name": "MQTT",
          "protocol_level": 4
        }
      }
    }
  ]
}

Configure Protos

This example creates a proto object:

apisix.yaml

protos:
  - id: helloworld
    desc: hello world
    content: >
      syntax = "proto3";
      package helloworld;

      service Greeter {
        rpc SayHello (HelloRequest) returns (HelloReply) {}
      }
      message HelloRequest {
        string name = 1;
      }
      message HelloReply {
        string message = 1;
      }
#END

apisix.json

{
  "protos": [
    {
      "id": "helloworld",
      "desc": "hello world",
      "content": "syntax = \"proto3\";\npackage helloworld;\n\nservice Greeter {\n  rpc SayHello (HelloRequest) returns (HelloReply) {}\n}\nmessage HelloRequest {\n  string name = 1;\n}\nmessage HelloReply {\n  string message = 1;\n}"
    }
  ]
}