How file-driven standalone mode runs Apache APISIX without etcd
In file-driven standalone mode, APISIX loads routes, upstreams and plugins from conf/apisix.yaml or conf/apisix.json, checks that file for changes every second and hot-reloads it without a restart. For a team that wants the gateway configured entirely from files in Git, this removes the need to operate an etcd cluster. The trade-off is that this mode has no Admin API write path: every change to routes or plugins ships as a change to the file, through the same review and deployment pipeline as the rest of your infrastructure code. Teams usually choose this mode when they want a small, auditable configuration surface, when etcd operations are not something they want to own, or when the gateway runs in an environment where a central configuration store is hard to justify.
The mode is set through the deployment block, which must declare the data_plane role with a config_provider of yaml or json. The choice of format also changes how the file must be written: a YAML file must end with the #END marker, and APISIX treats the file as incomplete without it, so a truncated file generated by a pipeline can fail silently if nobody checks for the marker. Confirm the exact role and provider names against the deployment modes documentation for the APISIX version you run, and add a pipeline step that rejects any YAML file missing the marker before it reaches a gateway host.
The file also has to carry settings that etcd would otherwise generate or hold. The openid-connect plugin needs an explicit session.secret in apisix.yaml in standalone mode, because etcd does not create one. Treat that value as a secret: it belongs in your secrets manager, rendered into the file at deploy time, and never committed to Git in plain text. Before you adopt the mode, list every setting your current deployment gets from etcd or the Admin API, and decide where each one will live before the first file is written.
Configuration options for file-driven standalone mode
This table compares the settings that select and shape file-driven standalone mode and sets them against API-driven standalone mode. Read each row as a decision: what the setting controls and the situation in which a team would choose it. The main takeaway is that file-driven mode depends on a few mandatory settings and file conventions, and that API-driven mode is a different mechanism with different intended users.
| Setting or mode | What it controls | When to choose it |
|---|---|---|
| deployment.role: data_plane | Starts APISIX as a data plane with no control plane or etcd dependency. Required for file-driven standalone mode. | Any gateway that should read its routes from a file and not from an Admin API or etcd cluster. |
| config_provider: yaml | Tells the data plane to load its configuration from conf/apisix.yaml. | Teams that want YAML files that are readable and commented, and that already use YAML for other configuration. |
| config_provider: json | Tells the data plane to load its configuration from conf/apisix.json. | Teams whose pipelines generate JSON, or that want to avoid YAML indentation and the #END requirement. |
| apisix.yaml versus apisix.json | The file format of the routes, upstreams, consumers and plugin settings. The file name must match the config_provider value. | Choose YAML for hand-edited review in Git. Choose JSON when a tool produces it and the file is never edited by hand. |
| #END marker in YAML files | A required last line in apisix.yaml. Without it the file is not treated as a complete configuration. | Always, for any YAML file in this mode. Add a validation step in CI that fails when the marker is missing. |
| session.secret in openid-connect | Signs and encrypts the session that the openid-connect plugin keeps. In standalone mode it must be set explicitly because etcd does not generate it. | Any route that uses openid-connect in this mode. Store the value in a secret manager and inject it at delivery time. |
| API-driven standalone mode (contrast) | Keeps rules in memory and updates them through PUT /apisix/admin/configs. The documentation describes it as intended for the Ingress Controller and ADC. | Choose it when a controller or ADC tool pushes configuration. Choose file-driven mode when a Git-tracked file should be the source of truth. |
Which delivery pattern fits your environment
On virtual machines or bare metal, the team installs APISIX from system packages and keeps the configuration file in the APISIX configuration directory on each host. The file is written to conf/apisix.yaml or conf/apisix.json, and the host's configuration management or deployment tool replaces it. Each node reads its own copy, so the team must make sure every node receives the same version at the same time.
- File placement: Confirm the exact path your package layout uses and that the APISIX service account can read the file.
- Reload confirmation: Change a harmless test route on one node first, then send a request through the route and check the gateway error log for load messages.
- Node drift: Compare file checksums across nodes after each push, since a failed copy on one host leaves it serving older rules.
- Validation before deploy: Keep the
deployment.roleandconfig_providersettings inconf/config.yamlidentical across hosts. - Monitoring: Watch access logs, error logs and upstream health on every node, and alert when a node stops responding to test requests.
Confirm with your own platform team how files are pushed, rolled out in batches and rolled back if a node fails the post-change test.
In Docker, the team mounts the configuration file into the container as a volume, so the file lives on the host or in a volume store and the container reads it at runtime. Editing the mounted file on the host updates what the container sees, and the gateway picks up the change without a container restart. The container image and the file are versioned separately, which lets the team change rules without rebuilding the image.
- Volume mount: Confirm that the bind mount or named volume points at the file APISIX reads, and that the file is not replaced by a directory mount.
- Reload confirmation: Apply a test change, then check the container logs and send a test request through the changed route.
- Container restarts: Verify that a restart reads the same file, because a stale copy on the host can silently return the old rules.
- Image upgrades: Treat an image change as a separate change from a rule change, and test both in staging first.
- Monitoring: Track container health, restart counts, and gateway error logs across every replica, with an alert on failed reloads.
Confirm your container runtime's mount behavior and file permissions in your own environment before relying on hot reload.
On Kubernetes, the team typically supplies the file through a ConfigMap or a similar mechanism and mounts it into the gateway pods. This makes the file part of the cluster's desired state, so it can be reviewed, versioned and applied with the same tooling as other workloads. The team must confirm how the chosen mechanism updates the file inside running pods, because the propagation path determines when APISIX sees the change.
- Mount method: Confirm how your cluster and chart expose the file to the gateway, and whether a change to the source object reaches running pods.
- Reload confirmation: Check the gateway logs on each pod after a change, and send a test request through a changed route on each replica.
- Rollout behavior: Decide whether a rule change should trigger a pod rollout or rely on in-place reload, and test both paths.
- Replica consistency: Confirm that all replicas read the same revision, since pods may update at different times.
- Monitoring: Watch pod readiness, gateway error logs, and upstream health, and alert when replicas disagree about routes.
Confirm with your cluster administrators how the object is updated, how large files are handled, and what your admission and review controls require before a change reaches production.
In a GitOps pattern, the file is stored in a Git repository and a controller syncs it to the target environment. Changes go through review and merge, and the controller applies the approved revision. This gives the team a history of every rule change and a clear rollback point, but the sync layer adds its own failure modes that the operations team must watch.
- Repository layout: Keep the gateway file in a dedicated path with its own review rules, and separate environment variants into distinct files or directories.
- Sync confirmation: Check that the controller reports the expected revision as applied, then verify the reload on the gateway with a test request.
- Pre-merge checks: Run YAML parsing and an APISIX configuration check in continuous integration, and confirm the
#ENDmarker is present in YAML files. - Rollback: Test reverting a commit in a non-production environment, and confirm how quickly the controller applies the previous revision.
- Monitoring: Alert on sync failures, drift between the repository and the running file, and gateway errors after each sync.
Confirm your sync tool's behavior, its access model and how it handles secrets, which should not be stored in plain text in the repository.
What etcd used to generate and you now set yourself
In etcd-backed modes, some values are created or managed by the control plane, so operators rarely see them. In file-driven standalone mode there is no control plane writing them, so every value the gateway depends on must be present in the file. The most important of these for teams using the openid-connect plugin is the session.secret. The openid-connect documentation states that it must be set explicitly in apisix.yaml in standalone mode because etcd does not generate it. If it is missing or left at a placeholder, sign-in flows that depend on sessions will not behave as the team expects, so check it as part of every change to the file, not only at first deployment.
Treat the session secret as a credential. Decide where the value is generated, who can read it, and where it is stored, such as your existing secrets manager, and make sure the file that contains it is not committed to a repository in plain text. Plan rotation before go-live: confirm with the APISIX documentation how existing sessions behave when the secret changes, and schedule rotation so that users are not disrupted unexpectedly. Restrict who can read the rendered file on hosts and in container images, and record each rotation so that an incident responder can tell which secret version was active at a given time.
Your team owns three things once the file is the source of truth: its integrity, the lifecycle of the session secret, and consistency across replicas. Every gateway instance that loads the file must see the same values, or requests will succeed on some nodes and fail on others. Confirm how your delivery pipeline renders and distributes the file to each replica, and add a check that compares a hash or version of the rendered file across nodes after each change. Assign a named owner for the secret and for the file so that neither is changed by hand on a single host.
Setting up file-driven standalone mode step by step
This sequence takes an APISIX gateway from a version check to a verified, hot-reloading configuration file with no etcd cluster, so each step produces a checkable result before the next one starts.
Confirm the APISIX version and install method
Your platform engineer confirms which APISIX release and install method (container image, RPM or DEB package, or source) the gateway will run, and checks that the release notes cover file-driven standalone mode. Record the exact version in your change ticket so later upgrades can be compared against it. Done when the running binary reports the version you recorded, for example with the version command your install method provides, and the version matches the release you intend to operate.
Set the data plane role and config provider
Edit the gateway configuration file (conf/config.yaml or the mounted equivalent) so that deployment.role is data_plane and the config provider is set to yaml or json, matching the file format you will use. Remove or disable any etcd endpoint settings for this node, since the gateway will not read configuration from etcd. Done when a configuration check or a dry start shows the node in data plane mode with no etcd connection attempts in its logs.
Write routes, upstreams, consumers and plugins
Author conf/apisix.yaml (or conf/apisix.json) with the routes, upstreams, consumers and plugin definitions for one test API, using the same object structure the Admin API would accept. Keep the first file small, covering a single route with one upstream and one authentication plugin, so failures are easy to isolate. Done when the file parses without syntax errors in your editor or linter and every upstream address and plugin name resolves to what you intended.
Close the YAML file with the END marker
For YAML files, add the #END marker as the final line of apisix.yaml so the gateway knows the file is complete before it reloads. A partially written file without the marker is not treated as a complete configuration, so automated writers should add the marker last. Done when the last line of the file is #END and a copy of the file with the marker removed is rejected or ignored by the gateway in a test environment.
Set the openid-connect session secret
If any route uses the openid-connect plugin, set session.secret explicitly in apisix.yaml. Etcd normally generates this value in other modes, but standalone mode does not, so a missing secret leaves the plugin without a session key. Generate the value in your secrets tooling, store it outside the repository, and inject it into the file at deployment time. Done when the plugin configuration contains a non-empty secret and a login attempt through the test route creates a session without an error in the gateway log.
Start the gateway and confirm it loads the file
Start APISIX with the configuration in place and check the error log for the file load event. Then call the test route and confirm it returns the response the file defines, for example by matching a status code or a header you set in the upstream. Done when the error log shows the file was read and the route responds as configured, with no etcd-related errors.
Test a route and confirm the one-second reload
Make a controlled change to one route in apisix.yaml, such as a changed response header or a new allowed method, and save the file. Within about one second the gateway checks the file and applies the change without a restart, so repeat the request and confirm the new behavior. Then revert the change and confirm the original behavior returns. Done when both the change and the revert appear on the test route within a few seconds, and the process ID is unchanged across the test.
Security risks of file-driven standalone mode
File-driven standalone mode moves the gateway's configuration out of etcd and into a file that your team owns. The risks below share one root cause: the file becomes the control point for routes, credentials and sessions, so the controls around it (storage, review, delivery and logging) must be designed by your team rather than inherited from a database-backed control plane.
Secrets stored in plain text
The apisix.yaml file holds route-level credentials, upstream settings and plugin keys in readable form. If that file is committed to a repository or copied to a build artifact, anyone with read access can take the secrets. Check whether any secret values appear in Git history, container images or CI logs, and consider a secret manager that renders the file at deploy time so only the running process gets the values.
Unreviewed changes reaching production
APISIX checks the file every second and hot-reloads it, so an edit that lands on a production host takes effect almost immediately. Without a review step, a typo in a route match or a removed authentication plugin can expose an upstream within seconds. Consider branch protection with required reviewers on the directory that holds the file, plus a validation job that rejects a file failing schema checks before it can merge.
Drift between replicas
Each gateway node reads its own local copy of the file. If one node is updated and another is not, or a rollout stops partway, replicas answer the same request with different routes and policies. Check that every node pulls from the same released revision, record the revision identifier in your deployment metadata, and alert when nodes report different file hashes.
Write access broader than intended
Anyone who can write to the file, or to the directory that delivers it, can change how the gateway routes traffic, bypassing your change process entirely. This includes automation accounts and configuration management tools with wide permissions. Limit write access to the delivery pipeline's service identity, restrict file permissions on the host to the APISIX service user, and review who holds the credentials for the repository.
Exposed openid-connect session secret
The openid-connect plugin needs a session.secret set explicitly in apisix.yaml in standalone mode, because etcd no longer generates it. That value signs and protects user sessions, so exposing it lets an attacker forge or decrypt sessions. Confirm the value is generated with enough entropy, stored only in the secret manager, rotated through a planned process, and never placed in example files copied from documentation.
Weak audit trail for changes
The file itself does not record who changed a route, when, or why. In a traditional deployment the Admin API and etcd history provide some of that record, but a file delivered by copy or sync leaves gaps. Ask your team to define which system is the system of record for changes, require a commit author and linked ticket for each revision, and keep gateway access logs that you can correlate with the deployed revision.
What do teams ask before running APISIX from a file?
What drives the cost of running APISIX in file-driven standalone mode?
The cost depends on how much configuration has to be translated and proven before cutover. The main drivers are the number of routes and upstreams, how many built-in plugins each route uses, whether custom Lua or plugin runner code must be written or ported, how many identity providers are involved, and how many environments need the same file promoted through them. Costs split into one-time work (inventory, file design, plugin mapping, testing, cutover) and recurring work (upgrades, file changes, on-call). Ask any partner for a quote built from a written scope that lists these counts and the environments in use, and check whether the quote covers testing and handover documentation as well as configuration.
How long does a migration from an etcd-backed APISIX setup usually take?
The duration is set by the state of the current setup, not by the file format itself. Teams with a clean inventory of routes, consumers and plugins, existing CI pipelines and a staging environment usually move faster than teams whose configuration exists only in the Admin API or has drifted between environments. Other factors include the number of plugin behaviors that must be verified, whether identity integration needs new client registrations, how much parallel running the business requires, and change approval windows. Ask for a timeline that names each of these inputs so you can see which ones your team controls.
What does the work need from our team?
Expect to provide access that lets the work be tested end to end. The usual list includes read access to the current APISIX configuration (ideally an export from the Admin API or etcd snapshot), write access to the Git repository that will hold the file, access to non-production hosts or clusters where the data plane runs, and a named contact for each identity provider used by openid-connect or other auth plugins. Your team also needs to provide the secret store location for the session secret and admin-related values, and someone who can approve production changes. Confirm the exact access list with your partner before the scope is signed.
Can a competent platform team run this without an outside partner?
Yes, a platform team with experience in APISIX, YAML-driven delivery and gateway operations can do this internally. The mode is simpler than etcd-backed deployments because there is no etcd cluster to run, but the team still has to handle the parts that do not appear in the reference docs: translating plugin behavior from existing setups, deciding how reloads are validated before they reach production, and designing the session and secret handling. An outside partner is most useful when the team lacks time, when the route count is large, or when the cutover carries regulatory evidence requirements. Your team can take on part of the work and buy specific pieces, such as a plugin mapping review or a cutover test plan.
What breaks most often when a file-driven gateway goes live?
The most common failures are syntax errors that make a reload fail, missing #END markers in YAML files, and secrets or session settings left out because etcd used to generate them. Because the file is checked every second, a bad change can reach the running gateway quickly unless the pipeline validates it first. Plugin differences between the old and new setup, such as default values or header handling, also cause surprises. Test the file against the same routes used in production traffic, and keep a known-good version ready for rollback.
Does standalone mode change how we handle the Admin API and secrets?
Yes. In file-driven standalone mode the configuration lives in conf/apisix.yaml or conf/apisix.json, so changes come from the file rather than the Admin API. The openid-connect plugin requires an explicit session.secret in apisix.yaml because etcd no longer generates one. Plan where that value is stored, who can read it, and how it is rotated. Confirm with your security team how the file is delivered and protected on each host, since the file now carries sensitive values. Hardening choices for the gateway itself should be reviewed against your own control set.
How should we deliver the configuration file through GitOps?
Store the file in Git, validate it in CI, and promote the same version through each environment rather than editing hosts directly. A typical pipeline lints the YAML, confirms the #END marker and deployment role, runs a test reload in a non-production gateway, and only then merges to the production branch. Your existing CI and GitOps tooling determines how much of this is reused. Ask for the pipeline design as part of the scope, including how emergency changes are handled and how drift between files and running hosts is detected.
Limits to confirm before you choose file-driven standalone mode
File-driven standalone mode removes etcd and changes how configuration is stored, changed and recovered. Each item below is a limit your team should confirm in its own environment before committing, because it affects features, release choice, recovery, tooling and testing.
Feature support in this mode
Confirm that every route, plugin and protocol your gateway needs works with config_provider set to yaml or json. Some capabilities are tied to the Admin API or to etcd-backed state, so a plugin that works in traditional mode is not automatically supported here. Ask the vendor for a written list of features that are unsupported or limited in standalone mode, and check each against the official deployment modes documentation.
Release and support status
Choose the APISIX release before you write the file, because the file format and standalone behavior depend on the version. The downloads page does not mark any release as long-term support, so ask the vendor or the project which release line your organization can rely on and for how long. Record the version you test with and the one you deploy, and keep them identical.
Rebuild from file after failure
With no etcd cluster holding state, the configuration file becomes the only source of truth. Confirm where the file is stored, who can change it, and how a replacement node gets the same file within your recovery target. Test a full rebuild on an empty host, including the session secret and any TLS material, rather than assuming the Git repository alone is enough.
Dynamic changes from other tools
File-driven mode is not designed for live changes through the Admin API, so any tool that expects to write routes at runtime needs a different mode. Inventory every system that writes gateway configuration, including dashboards, scripts and controllers. The documentation describes API-driven standalone mode as intended for the Ingress Controller and ADC, so confirm that choice before you build on it.
Plugins that depend on stored state
Some plugins keep runtime state or generated values that etcd would normally hold. For example, the openid-connect plugin requires an explicit session secret in apisix.yaml in standalone mode, because etcd does not generate it. List each plugin in your design, identify any state or generated secret it needs, and confirm with the plugin documentation how it behaves when that state is supplied from the file.
Testing a file change before production
A file change takes effect within about one second of being saved, so a bad edit reaches live traffic quickly. Define a pipeline that validates the YAML, ends the file with the required #END marker, applies it to a staging gateway, and runs request tests against it before promotion. Confirm who approves production changes and how you roll back to the previous file.
How DeployOpen scopes and delivers file-driven APISIX gateways
DeployOpen plans, builds, documents and supports self-hosted APISIX inside your own infrastructure, including file-driven standalone gateways that run without etcd. Each engagement starts with a written scope that fixes deliverables, and the work covers the YAML or JSON configuration, the data plane role, secrets and the delivery pipeline for the file.
How we scope
- We confirm which APISIX version and deployment role your gateways will run, and whether the file is YAML or JSON.
- We inventory routes, upstreams, plugins and authentication flows that must move into the single configuration file.
- We agree in writing which secrets, session settings and OpenID Connect providers the scope includes before work starts.
How we build
- We set up the data plane role and config provider, then write the configuration file with the required end marker for YAML.
- We check that secrets, including the OpenID Connect session secret that etcd would otherwise generate, are set explicitly.
- We test reload behavior by editing the file under load and confirming routes change without a restart.
How we hand over
- We deliver the configuration repository, delivery pipeline for the file, and runbooks for editing and rolling back changes.
- We document the verification steps, including reload checks and authentication tests, so your team can repeat them.
- We walk your engineers through the design decisions and the limits of file-driven mode compared with etcd-backed deployments.
How we support
- Engagements are fixed-scope, and changes after handover are scoped and quoted separately in writing.
- Ongoing support, upgrades and continuous testing are available as a retainer, which you can ask us to quote.
- We can review future APISIX upgrades and configuration changes against the documented deployment modes before they reach production.
