> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/configuration-and-automation/import-export-rollback.md).

# Import, export, diff, and rollback

This runbook covers the full Admin API workflow. Replace example IDs and keep bearer tokens out of shell history where possible.

```bash
export KANGAL_URL='https://kangal.example.com'
export KANGAL_TOKEN='kangaladm_...'
export TENANT_ID='tenant-acme'
```

## 1. Export live state

JSON:

```bash
curl -fsS \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Accept: application/json' \
  "$KANGAL_URL/api/v1/admin/config/export?tenant_id=$TENANT_ID&format=json" \
  -o "${TENANT_ID}-before.json"
```

YAML:

```bash
curl -fsS \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Accept: application/yaml' \
  "$KANGAL_URL/api/v1/admin/config/export?tenant_id=$TENANT_ID&format=yaml" \
  -o "${TENANT_ID}-before.yaml"
```

Export requires a tenant and redacts plaintext secrets. Verify the artifact parses, protect it as operationally sensitive, and do not treat it as a credential backup.

## 2. Validate desired state

```bash
curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/yaml' \
  "$KANGAL_URL/api/v1/admin/config/validate?strict=true&format=yaml" \
  --data-binary @desired.yaml | tee validation.json | jq
```

Validation detects request-schema problems, duplicate declarative identities, plugin configuration errors, and resource references. With `strict=false`, missing service/upstream references can be warnings; with `strict=true`, they are errors.

Validation is a `POST` and therefore requires write permission even though it does not modify live resources.

## 3. Diff desired and live state

```bash
curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/yaml' \
  "$KANGAL_URL/api/v1/admin/config/diff?tenant_id=$TENANT_ID&strict=true&format=yaml" \
  --data-binary @desired.yaml | tee diff.json | jq
```

The response groups each resource type into added, removed, and changed items, with before/after values and changed fields, plus a summary. A desired resource missing from live appears added; a live resource missing from desired appears removed in the diff, but import/sync does **not** automatically delete it.

Diff requires `tenant_id` in the query or bundle. Treat a non-empty `removed` set as a review prompt, not a deletion plan.

## 4. Import preview and apply

`POST /config/import` accepts the bundle fields and `overwrite` at the top level. Its query parameter `dry_run` defaults to `false`, so always state it explicitly in automation.

JSON request example:

```bash
jq '. + {overwrite: true}' desired.json > import-request.json

curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/json' \
  "$KANGAL_URL/api/v1/admin/config/import?dry_run=true" \
  --data-binary @import-request.json | tee import-preview.json | jq
```

Review the validation result, bundle fingerprint, resource counts, diff, and `would_insert`, `would_update`, and `would_skip` counts. Then apply the exact same artifact:

```bash
curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/json' \
  "$KANGAL_URL/api/v1/admin/config/import?dry_run=false" \
  --data-binary @import-request.json | tee import-result.json | jq
```

`overwrite=false` skips matching resources. `overwrite=true` replaces matching documents. Import is sequential, non-transactional, and non-pruning.

## 5. Prefer sync for promotion

Sync combines strict validation, live export, diff, preview, optional snapshot, and import. The API defaults are dry-run, overwrite, strict validation, and pre-apply snapshot.

YAML body example:

```yaml
tenant_id: tenant-acme
overwrite: true
dry_run: true
strict: true
snapshot_before_apply: true
snapshot_note: release 2026.07.17
created_by: change-1842
gateways: []
services: []
routes: []
upstreams: []
targets: []
```

Preview:

```bash
curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/yaml' \
  "$KANGAL_URL/api/v1/admin/config/sync?tenant_id=$TENANT_ID&format=yaml" \
  --data-binary @sync-request.yaml | tee sync-preview.json | jq
```

For apply, change `dry_run` to `false` in a reviewed copy and send it to the same endpoint. The endpoint rejects a mismatch between query and payload tenant IDs.

Do not set `snapshot_before_apply=false` merely to save time during a production change. A snapshot is useful configuration evidence, though it remains subject to redaction and non-transactional rollback limits.

## 6. Create and list snapshots

Create a manual snapshot:

```bash
curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/json' \
  "$KANGAL_URL/api/v1/admin/config/snapshots?tenant_id=$TENANT_ID" \
  -d '{"note":"before certificate rotation","created_by":"change-1842"}' \
  | tee snapshot.json | jq

SNAPSHOT_ID=$(jq -r '.id' snapshot.json)
```

List newest versions first:

```bash
curl -fsS -G \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  --data-urlencode "tenant_id=$TENANT_ID" \
  --data-urlencode 'limit=20' \
  "$KANGAL_URL/api/v1/admin/config/snapshots" | jq
```

The list limit is `1..100` and defaults to 20. Each snapshot records a tenant-relative version, checksum, counts, note, creator, and creation time.

## 7. Preview rollback

Rollback is import of the selected snapshot, not a database rewind. Preview it first:

```bash
curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/json' \
  "$KANGAL_URL/api/v1/admin/config/snapshots/$SNAPSHOT_ID/rollback?tenant_id=$TENANT_ID" \
  -d '{"overwrite":true,"dry_run":true}' \
  | tee rollback-preview.json | jq
```

The snapshot lookup is tenant-scoped; an unknown ID or wrong tenant returns `404`. Strict validation runs before rollback.

Before apply, verify:

* The snapshot tenant, timestamp, checksum, note, and resource counts.
* Which live resources will be replaced and which will remain untouched.
* How secrets and credentials will be restored if the snapshot contains redacted values.
* Database backup availability and a forward-recovery plan.
* Maintenance window and route-level smoke tests.

## 8. Apply rollback

```bash
curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  -H 'Content-Type: application/json' \
  "$KANGAL_URL/api/v1/admin/config/snapshots/$SNAPSHOT_ID/rollback?tenant_id=$TENANT_ID" \
  -d '{"overwrite":true,"dry_run":false}' \
  | tee rollback-result.json | jq
```

The rollback API defaults to `overwrite=true` and `dry_run=false`; explicit values make operator intent reviewable. Because application is sequential, inspect the result and live export even when the request returns success.

## 9. Verify

```bash
curl -fsS \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  "$KANGAL_URL/api/v1/admin/config/export?tenant_id=$TENANT_ID" \
  -o "${TENANT_ID}-after.json"

curl -fsS \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  "$KANGAL_URL/api/v1/admin/gateways/gw-production/overview" | jq

curl -fsS \
  -H "Authorization: Bearer $KANGAL_TOKEN" \
  "$KANGAL_URL/api/v1/admin/gateways/gw-production/traffic/recent?limit=20" | jq
```

Run synthetic requests through changed routes, inspect recent traffic and application errors, and compare the final export to the intended bundle. Preserve the before/after artifacts and API results with the change record.

## Failure handling

| Failure                     | Action                                                                                            |
| --------------------------- | ------------------------------------------------------------------------------------------------- |
| Parse or schema error       | Correct JSON/YAML structure; distinguish `400` parse/config errors from `422` request validation. |
| Strict reference error      | Correct the reference or include the dependency; do not bypass strict mode without review.        |
| Timeout during apply        | Assume partial application is possible. Export live state before retrying.                        |
| Partial import              | Diff live state against desired, then apply a forward fix or a tested snapshot rollback.          |
| Redacted credential applied | Stop affected integration traffic and restore the credential from the authorized secret system.   |
| Snapshot not found          | Confirm tenant and ID; snapshots cannot be retrieved across tenant lookup scope.                  |
| Unexpected resources remain | Expected for non-pruning import. Delete them explicitly after dependency review.                  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kangal.dev/configuration-and-automation/import-export-rollback.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.