How to use APISIX with IaC + CI/CD Pipelines

[cfitzw]

Is there not a way to have the best-of-both-worlds when using APISIX -- the ability to use a UI dashboard but also be able to export that to a config to run it with?

How are others building pipelines for promoting changes between envrionments? Any guidance is appreciated.

These questions are based from this understanding...

APISIX has two very different ways to hold config:

1. “Traditional” mode (default): APISIX stores config in etcd
   • This is what APISIX Dashboard supports, because the Dashboard manages APISIX resources through the Admin API, which in turn persists to etcd.
2. “Standalone / declarative” mode: APISIX loads config from a local YAML file (apisix.yaml)
   • This gives you “config as code” with no etcd.
   • But you lose the Dashboard-driven management/view, because there’s no etcd-backed Admin API state for the Dashboard to work against.

So the key constraint is:
You can’t run APISIX “standalone (YAML)” and still have the Dashboard manage/reflect that YAML as the live source of truth.
Dashboard expects an etcd-backed APISIX.

This was a somewhat similar discussion found, but was fairly vague...
#5004

[dosubot[bot]]

Hi @cfitzw! I'm Dosu and I’m helping the apisix team.

Your understanding of the two modes is spot on. Here's how the community is tackling this:

The key tool: ADC (APISIX Declarative CLI)

ADC (adc) is the main IaC bridge for APISIX. It lets you dump a running APISIX config to YAML, diff local config against a live instance, lint for validation, and sync declarative config back to APISIX via the Admin API [1]. This works with etcd-backed mode, so you can still use the Dashboard for exploration while managing production config declaratively.

Recommended pipeline pattern [2] [3]:

1. Develop/explore using the Dashboard or Admin API (etcd-backed mode)
2. Export config with adc dump
3. Store in Git as your source of truth, with per-environment directories
4. CI/CD pipeline runs adc lint → adc diff → adc sync to push config to each environment
5. Environment-specific values handled via environment variable substitution (${{DB_HOST}}) [4] or APISIX_PROFILE for loading environment-specific config files like config-prod.yaml

repo/
├── environments/
│   ├── dev/apisix.yaml
│   ├── staging/apisix.yaml
│   └── production/apisix.yaml
└── .github/workflows/deploy.yml

If you're on Kubernetes, you also have the option of the APISIX Ingress Controller with CRDs (ApisixRoute, ApisixUpstream, etc.) managed via GitOps tools like ArgoCD or FluxCD [5].

A few things worth noting:

• The APISIX Dashboard is not actively maintained and has limited APISIX 3.x support [6], so leaning into ADC-based workflows is the more future-proof path.
• There is no official Terraform provider for APISIX as of now.
• For standalone mode (no etcd), you get pure GitOps but lose the Dashboard entirely — there's no plan to build a UI for it [7].

So the "best of both worlds" approach is: use etcd-backed mode + ADC. Dashboard for ad-hoc visibility/exploration, Git + ADC + CI/CD for all actual environment promotion.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}
   

[cfitzw]

@dosu if sticking with the standalone, non-etc, model, but desiring to do local development using docker and deploying to Kubernetes (non CRD route), is there a method to which this can be accomplished - having the apisix.yaml file utilized for both?

What about the config.yaml? Can/should that be utilized for both as well, or should the helm values be used for k8s and a separate config.yaml be used to docker?

[dosubot[bot]]

Yes — you can absolutely share the same apisix.yaml between Docker and Kubernetes in standalone mode. The key is using environment variable substitution (${{VAR}} syntax) to handle environment-specific differences like upstream hostnames [1].

Shared apisix.yaml template:

routes:
  - uri: /api
    id: "1"
    upstream:
      nodes:
        "${{UPSTREAM_HOST:=localhost:8080}}": 1
      type: roundrobin
#END

For Docker, bind-mount it and pass env vars [2]:

docker run -d \
  -e APISIX_STAND_ALONE=true \
  -e UPSTREAM_HOST=my-backend:8080 \
  --mount type=bind,source="$(pwd)"/conf/apisix.yaml,target=/usr/local/apisix/conf/apisix.yaml \
  --mount type=bind,source="$(pwd)"/conf/config.yaml,target=/usr/local/apisix/conf/config.yaml \
  apache/apisix

For Kubernetes (Helm), provide the same content via ConfigMap or inline in values [3]:

# values.yaml
apisix:
  deployment:
    mode: standalone
    role: traditional
    role_traditional:
      config_provider: yaml
  standalone:
    config: |
      routes:
        - uri: /api
          id: "1"
          upstream:
            nodes:
              "${{UPSTREAM_HOST}}": 1
            type: roundrobin
      #END
etcd:
  enabled: false

Then inject environment-specific values via Helm envVars per environment.

Regarding config.yaml — handle it differently per environment. In Docker, you create and mount an explicit config.yaml that enables standalone mode. In Kubernetes, the Helm chart auto-generates config.yaml from your values.yaml [4], so you configure it through Helm values rather than a separate file. This means you'll have a config.yaml for Docker and Helm values for K8s — they express the same settings, just in different formats.

You can also use APISIX_PROFILE to load environment-specific files (e.g., APISIX_PROFILE=dev loads apisix-dev.yaml and config-dev.yaml) [5], but env var substitution in a single template is usually simpler.

One gotcha for K8s: there's a known health check issue where /status/ready returns 503 when apisix.yaml exists before APISIX starts (common with ConfigMaps). You may need to adjust your readiness probe or use a post-start hook to touch the file [6].

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}