File-Driven Standalone Mode Configurations

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.

important

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:

YAML

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

JSON

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:

YAML

apisix.yaml

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

JSON

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:

YAML

apisix.yaml

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

JSON

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:

YAML

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

JSON

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:

YAML

apisix.yaml

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

JSON

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:

YAML

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

JSON

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:

YAML

apisix.yaml

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

JSON

apisix.json

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

Configure Plugin Metadata

This example creates plugin metadata:

YAML

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

JSON

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:

YAML

apisix.yaml

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

JSON

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:

YAML

apisix.yaml

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

JSON

apisix.json

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

Configure Stream Routes

This example creates a stream route:

YAML

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

JSON

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:

YAML

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

JSON

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}"
    }
  ]
}