Track live a7 CLI validation findings and remaining coverage

[guoqqqi]

Background

We started validating whether the current a7 CLI is stable by connecting the real CLI to a local API7 environment, instead of relying on test framework results or mocks.

Validation environment:

• API7 control plane: local HTTPS environment
• Gateway group: product
• API7 image version: 3.8.23
• Validation method: create, read, update, and delete resources only through a7, then assert the result through a7 get/list/dump/diff/sync

This issue tracks live CLI findings and remaining coverage. We should finish the full CLI validation first, then split fixes into PRs.

Verified Working CLI Paths

• context create --tls-skip-verify --use
• gateway-group list
• service create/get/list/update/export/delete
• route create/get/list --service-id/delete
• route update -f
• consumer create/get/list/delete
• credential create -f/list/get/delete
• config sync can create, update, and delete service + route resources
• config diff can confirm synced resources as unchanged
• config dump can read back the current gateway group configuration

Findings

1. context create does not persist a token supplied through A7_TOKEN

Behavior:

• Run context create with the API token supplied only through A7_TOKEN
• The context is created successfully
• Later commands fail unless A7_TOKEN is supplied again:

Error: no API token configured; run 'a7 context create' or set A7_TOKEN

We need to confirm whether this is intended behavior. If environment tokens are intentionally not persisted, the docs and error message should make that clear.

2. route list without --service-id is rejected by the API

Behavior:

Error: API error (status 400): validate request failed: parameter "service_id" in query has an error: value is required but missing

route list --help already says --service-id is required by API7 EE, but the CLI does not validate it locally and lets the API return the error.

Questions:

• Should route list support listing all routes?
• If API7 EE requires service_id, the CLI should validate this locally and return a clearer error.

3. service update uses full replacement semantics and can drop fields

Behavior:

• Create a service with name
• Run service update <id> --desc ... --labels ... --host ... without --name
• Run service get; the name field is gone

This suggests the flag-based update path sends a full PUT body without reading and merging the existing object first. That can accidentally remove fields.

We need to check whether other update commands have the same risk.

4. route update --uri does not map to API7 EE paths

Behavior:

• route create --uri ... succeeds, so create maps uri to paths
• route update --uri ... fails because the API requires paths

Error:

request body has an error: property "paths" is missing

Current workaround:

• Use route update -f with an explicit paths payload

5. credential create <id> does not map to the API-required name

Behavior:

• Run credential create <id> --consumer ... --plugins-json ...
• The API returns name is missing

Current workaround:

• Use credential create --consumer ... -f credential.json
• Include name in the file payload

We need to confirm whether the positional <id> should map to name in the API7 EE credential model, or whether the CLI help/docs should change.

6. secret create flag/positional mode returned resource not found

Behavior:

• secret list returns an empty list, so the read path is at least reachable
• secret create ... returned:

Error: resource not found

Need to confirm:

• Whether the current API7 3.8.23 environment supports secret provider writes
• Whether the endpoint used by a7 matches the current API7 EE version
• Whether create/update/delete require a different path or request shape

7. plugin-config list/create returns resource not found

Behavior:

• plugin-config list returns resource not found
• plugin-config create returns resource not found

Based on the current PRD, plugin-config is an APISIX reusable plugin configuration resource that routes can reference to reuse plugin settings. The PRD also states that API7 EE Admin API does not expose this resource:

Plugin configs are not exposed via the API7 EE Admin API.
The a7 plugin-config commands exist for APISIX compatibility but will not work against API7 EE.

Decisions needed:

• Should a7 plugin-config stay as an APISIX compatibility command?
• If yes, should it return a clearer message in API7 EE environments?
• Should it be excluded from the default API7 EE E2E/live CLI validation scope?
• Should declarative config continue ignoring plugin_configs?

Remaining Coverage

Live CLI validation still needs these resources/scenarios:

• ssl CRUD
• ssl SNI/SNIs behavior, including multiple SNIs, updating SNI, and readback assertions
• Full secret provider create/read/update/delete path
• Global rule / global plugin resource CRUD
• Plugin metadata CRUD
• Proto CRUD
• Stream route CRUD
• Whether upstream commands still apply to the current API7 EE version
• Whether consumer group is supported by API7 EE or is an APISIX compatibility resource like plugin-config
• Service template / gateway group read-only and optional CRUD boundaries
• Whether other resource updates have the same field-dropping issue as service update
• Whether flag mode and -f file mode behave consistently for each resource
• config sync create/update/delete/readback coverage across more resource types

Suggested Follow-Up

Continue the full live CLI validation first. Do not fix everything in this issue directly.

After validation is complete, split fixes by problem type:

• CLI flag to API7 EE schema mapping issues
• Update replacement/merge semantics
• API7 EE unsupported resources or endpoint mismatches
• Documentation/help/error message clarification
• E2E or live CLI checklist coverage

[coderabbitai]

🔗 Related PRs

#2 - test: align E2E coverage with current EE models [merged]
#3 - test: migrate runtime coverage toward ginkgo e2e [merged]
#6 - test: strengthen E2E readback assertions [merged]
#7 - docs: align mTLS skill with service model [merged]
#9 - docs: migrate traffic recipes to service model [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[guoqqqi]

Additional real a7 CLI validation results. This round still did not use the test framework.

Newly Verified Working Paths

• ssl create/list/get/export/update/delete
  • Multiple SNI creation works
  • Updated SNI values can be read back with ssl get
• global-rule create/get/export/update/delete
  • Validated with the prometheus global rule and cleaned it up immediately
• proto create/get/export/update/delete
• service-template create/get/update/delete
• stream-route create/get/update/delete
  • Used a temporary service dependency and cleaned resources in dependency order
• plugin-metadata create/get/update/delete
• secret create/get/list/update/delete
  • File mode works
• Cleaned up cli-live-* / e2e-* prefixed service templates left by live CLI validation and the accidental E2E run
• Final config dump returned an empty runtime configuration

Newly Found Issues

8. Bare relative paths are not treated as files by ssl create --cert/--key

Failing usage:

a7 ssl create --cert test/e2e/testdata/test.crt --key test/e2e/testdata/test.key ...

The API receives the path string as certificate content and returns:

tls: failed to find any PEM data in certificate input

Workaround:

a7 ssl create --cert ./test/e2e/testdata/test.crt --key ./test/e2e/testdata/test.key ...

The current looksLikePath check appears to only recognize paths starting with /, ./, or ~/. We should decide whether to support normal relative paths or document the current behavior clearly.

9. secret create/update --token conflicts with the global API token flag

secret update ... --token <provider-token> overwrites the global API token with the provider token and fails with:

Error: authentication failed: check your API token

File mode works around this:

a7 secret update <id> -f secret.json

This is high priority because secret create/update define a local --token flag with the same name as the root/global API token flag.

10. secret create flag/positional mode behaves differently from file mode

This failed:

a7 secret create vault/<id> --uri ... --prefix ... --token ...

with resource not found.

But file mode works:

{
  "id": "vault/<id>",
  "uri": "...",
  "prefix": "...",
  "token": "..."
}

We need to inspect the provider/id payload mapping in flag mode. The --token collision may also be part of the root cause.

11. stream-route list/export does not handle the required service_id

stream-route create/get/update/delete works, but these commands fail:

a7 stream-route list -o json
a7 stream-route export --label ...

with:

parameter "service_id" in query has an error: value is required but missing

Problems:

• stream-route list --help does not expose --service-id
• stream-route export does not provide a service filter
• Similar to route list, we need to confirm whether API7 EE requires service-scoped queries and validate or support that explicitly in the CLI

12. service-template get does not read back all supplied fields

The service template create/update file included:

• description
• hosts
• path_prefix
• upstream

But service-template get only returned:

• id
• name
• labels
• timestamps

We need to confirm whether this is API response trimming, missing CLI struct fields, or an endpoint mismatch.

13. service create/config sync can leave service-template/control-plane service records

During cleanup, deleting the runtime service was not enough. service-template list still showed same-name control-plane service/template records.

Observed behavior:

• service delete removes the runtime resource
• service-template list can still show a same-name/same-label object

We need to clarify whether a7 service operates runtime published services, control-plane service templates, or both. If this boundary is unclear, tests and users can leave residual resources after cleanup.

API7 EE Support Boundary Updates

• plugin-metadata is available. The earlier 404 happened because no metadata had been created yet.
• plugin-config still returns resource not found; continue treating it as an APISIX compatibility resource not exposed by API7 EE.
• upstream list and consumer-group list still return resource not found; confirm whether they are also unsupported/not exposed by API7 EE.

Suggested Fix Priority

1. Fix the secret --token flag conflict.
2. Fix flag-to-API-schema mapping issues such as route update --uri and credential create <id>.
3. Clarify the real boundary between service and service-template, including delete semantics.
4. Add local service-id validation or full-list support for route/stream-route list/export.
5. Clarify API7 EE behavior for APISIX compatibility resources such as plugin-config, upstream, and consumer-group.