API7 Gateway 3.10.6: Reduce the Blast Radius of Custom Plugin Delivery

Key Takeaways

Custom gateway code needs an environment boundary as much as it needs code review. Otherwise, one upload can change every gateway group that shares the same plugin object.
API7 Gateway 3.10.6, released on August 25, 2026, moves custom plugins from Control Plane-wide resources to gateway-group resources.
Staging and production can now run different builds under the same plugin name, so teams can validate a change in one group before promoting it to another.
The resource model, Admin API, plugin catalog, and permission policies now use the gateway group as the scope of authority.
The upgrade migrates plugins that were already deployed and rewrites relevant policies, but undeployed plugins, stale route references, and rollback behavior require explicit review.
A safer rollout treats the plugin source, dependencies, metadata, permissions, configuration, and rollback artifact as one versioned release unit.

Custom plugins let an API gateway connect proprietary identity systems, enforce organization-specific policy, transform unusual protocols, and add logic that a built-in plugin does not provide. That flexibility is valuable precisely because the code runs inside the gateway request lifecycle. It also means a plugin update can affect authentication, routing, payloads, latency, and logging for production traffic.

The risk is not only whether the Lua code is correct. It is also the scope of the delivery action.

Before API7 Gateway 3.10.6, a custom plugin was one Control Plane-wide object. The same code was bound to one or more gateway groups, and uploading a new build replaced that shared object for every bound group. A team could test a new plugin in staging before its first production rollout, but once staging and production shared the object, updating staging also updated production.

That model made an operational convention carry too much responsibility. Reviewers could ask a team to validate in staging first, yet the product resource boundary did not keep the production copy unchanged during that validation.

API7 Gateway 3.10.6 changes the unit of ownership. A custom plugin now belongs to one gateway group. The result is a smaller blast radius for extension delivery: a build uploaded to a test group stays in that group, while production continues to run its existing copy until the team deliberately promotes the change.

Custom Plugin Risk Is a Deployment-Scope Problem

Gateway extensions combine two different concerns: what the code is allowed to do and where that code is deployed. Secure code review addresses the first concern. A release boundary addresses the second.

Consider a platform with development, staging, and production gateway groups. All three use a custom plugin named tenant-policy. The team wants to change how the plugin reads a claim and adds a request header.

With a shared Control Plane-wide object, the name identifies one code artifact. Updating that artifact can change every group where it is deployed. The team can create a second temporary plugin name for testing, but that also changes the route configuration being tested. The final production action is still an update to the shared object.

With a gateway-group resource, each environment owns its copy. Development and staging can run the candidate build while production keeps the last approved build under the same tenant-policy name. Routes, services, and plugin metadata do not need a temporary name merely to create an isolation boundary.

This is not the same as making custom code harmless. A plugin can still block traffic, expose data, or consume excessive resources inside the group where it runs. Teams still need code review, schema validation, performance tests, security tests, and observability. The change makes those controls more useful by ensuring that a test deployment does not also replace the production artifact.

3.10.6 Turns Gateway Groups Into Release Boundaries

The custom Lua plugin guide now describes a group-scoped rollout. Upload the plugin to a test gateway group, enable it on representative traffic, validate its behavior, and then upload the approved build to the production group.

The same plugin name can exist in multiple gateway groups with different code. That makes the gateway group a practical release boundary:

Development can iterate quickly against synthetic or local dependencies.
Staging can run the candidate build with production-like routes, identity flows, and upstream behavior.
Production remains on the approved build until the promotion action targets its gateway group.

flowchart LR
    source[Versioned Plugin Package] --> review[Code and Security Review]
    review --> test[Upload to Test Gateway Group]
    test --> validate[Validate Traffic, Logs, and Failure Paths]
    validate --> decision{Promotion Approved?}
    decision -- No --> revise[Revise Plugin]
    revise --> review
    decision -- Yes --> prod[Upload to Production Gateway Group]
    prod --> observe[Observe Production and Preserve Rollback Artifact]

The diagram represents a promotion process, not automatic artifact synchronization. API7 Gateway does not infer that the staging copy is approved for production. The production upload is a separate, intentional action.

This separation also improves ownership. A team responsible for one gateway group can manage its plugin copy without replacing code used by another group. The scope of the resource, deployment action, and permission can now describe the same environment boundary.

API and Permission Changes Align with the New Scope

A smaller deployment boundary only works if every management surface uses it. API7 Gateway 3.10.6 therefore changes the API and permission model along with plugin storage.

The custom-plugin endpoints move from:

/api/custom_plugins

to:

/api/gateway_groups/{gateway_group_id}/custom_plugins

Calls to the old paths return HTTP 410 and identify the replacement path. PUT is now create-or-replace by plugin name, so a delivery pipeline can upload one build to one gateway group in one operation. The previous gateway_groups list disappears from the request and response because the gateway group is already part of the resource path. GET /api/plugins also requires a gateway_group_id query parameter so the catalog answers for a specific group.

Automation should not treat the HTTP 410 as a transient failure. It is an explicit migration signal. Pipelines need to select the target gateway group, call the new endpoint, and verify that later route or service changes query the plugin catalog in the same group.

Permissions move with the resource. Custom-plugin actions previously targeted arn:api7:gateway:gatewaysetting/*; they now target the relevant arn:api7:gateway:gatewaygroup/{gateway_group_id} resource. gateway:CreateCustomPlugin is removed because PUT performs create-or-replace behind gateway:UpdateCustomPlugin. Reading plugin source now requires gateway:GetCustomPlugin.

That read permission matters. Before 3.10.6, any signed-in user could read the source of any custom plugin. After the upgrade, a role without the new read action cannot list or read that source. Teams should use the current permission action and resource reference to grant access only to roles and gateway groups that need it.

For delivery automation, the useful policy question is no longer “may this identity manage custom plugins somewhere in the Control Plane?” It is “may this identity read or replace this custom plugin in this gateway group?” That is a more reviewable least-privilege boundary.

Migration Preserves Runtime Behavior but Exposes Drift

The 3.10.6 upgrader handles the common case automatically. Each existing custom plugin is expanded into one row for every gateway group where it was deployed, allowing those groups to continue running the plugin after the resource model changes.

Relevant permission policies are rewritten as well. Custom-plugin actions move from the old gateway-settings resource to a gateway-group statement with the same effect and conditions. gateway:CreateCustomPlugin is rewritten, gateway:GetCustomPlugin is added, and the replaced policy document is retained in permission_policy_backup for review.

Automatic migration cannot invent intent that the old data never contained. Two cases require operator attention:

A plugin was deployed to no gateway group. There is no group to which the upgrader can assign it, so the plugin is logged rather than migrated. Upload it to each gateway group that actually needs it.
A route referenced a plugin that was never deployed to its own gateway group. The old Control Plane accepted the reference even though the plugin never ran there. After the upgrade, the group has no such plugin, and the next write to that route reports an unknown plugin. Upload the intended plugin to the group or remove the stale configuration.

The second case is valuable operational feedback. It converts silent configuration drift into a write-time error. However, it can surprise a team that assumes every stored plugin reference was active. Inventory references before the upgrade and distinguish “configured” from “actually available in this gateway group.”

Policy migration deserves the same care. Compare the generated gateway-group statements with the roles that own development, staging, and production. An automatically preserved broad grant may be compatible, but it may not represent the tighter separation the new model makes possible.

Rollback Is Now a Code-Version Decision

The new resource model also changes what rollback means. Plugin code uploaded while the Control Plane runs 3.10.6 is stored in the new gateway-group table. If the Control Plane is rolled back to an earlier release, that older version reads the pre-upgrade table and serves whatever plugin code remained there.

In other words, rolling back the product version does not automatically copy post-upgrade plugin changes into the old storage model. A team could restore the earlier Control Plane and find that its plugin code has also reverted to the pre-upgrade artifact, even if a newer build was promoted after the 3.10.6 upgrade.

Treat the application version and plugin version as two related rollback inputs. Before rollout, preserve:

the pre-upgrade plugin source or package for every gateway group;
the candidate and promoted artifacts with checksums;
the mapping between plugin name, gateway group, and approved version;
the relevant route, service, consumer, global-rule, and plugin-metadata configuration;
the pre-upgrade policy document and the migrated gateway-group policies.

A rollback rehearsal should verify both control-plane recovery and traffic behavior. Confirm which plugin build the older Control Plane exposes, which routes reference it, and whether dependencies on the Data Plane remain compatible. Do not assume that a successful container rollback restores the intended extension state.

A Safer Promotion Model for Custom Gateway Code

The group-scoped model supports a straightforward delivery discipline. The exact implementation may use the Dashboard, Admin API, or internal automation, but the release unit should remain consistent.

Version the complete artifact. Store the plugin source, dependencies, and metadata together. Record a digest even when the public plugin name remains stable.
Review privileged behavior. Check request and response access, network calls, secret handling, logging, failure modes, and execution cost—not only Lua syntax.
Upload to one non-production group. Target the gateway group explicitly and verify that no production group changed.
Test the real configuration shape. Enable the plugin on representative routes or services with the same schema and surrounding plugin order used in production.
Exercise failure paths. Test invalid configuration, dependency failure, upstream timeout, malformed input, and the plugin's behavior during reload or restart.
Promote the same reviewed artifact. Upload the exact digest to the production gateway group instead of rebuilding between environments.
Observe before expanding. Watch errors, latency, status codes, upstream behavior, and business-specific signals before promoting to additional groups.
Keep rollback group-specific. Preserve the last approved build for every production group rather than assuming all groups run one version.

This model keeps “same plugin name” separate from “same build everywhere.” That distinction is useful for staged delivery, but it also creates a new inventory responsibility. Operators should be able to answer which build of a plugin is running in each gateway group.

What to Validate Before Upgrading

Use the API7 Gateway upgrade guide together with the 3.10.6 release notes, then validate the custom-plugin lifecycle that applies to your deployment:

Export an inventory of custom plugins, their deployed gateway groups, and every route, service, consumer, global rule, and plugin metadata object that references them.
Identify plugins with no deployed group and decide whether to upload them after the upgrade or retire them.
Find references to plugins that are absent from the referencing resource's gateway group; correct the drift before routine post-upgrade edits expose it.
Update automation from /api/custom_plugins to the gateway-group endpoint, handle PUT as create-or-replace, and pass gateway_group_id when reading the plugin catalog.
Review role mappings for gateway:UpdateCustomPlugin and gateway:GetCustomPlugin on the intended gateway-group resources.
Inspect migrated policies and keep permission_policy_backup available until access behavior is confirmed.
Test that existing plugins continue to run in every previously deployed group and that changing a test-group copy does not alter production.
Record the pre-upgrade and promoted plugin artifacts, then rehearse rollback far enough to verify the code an older Control Plane actually serves.
Monitor plugin errors, route compatibility reports, traffic outcomes, and audit events throughout the rollout.

API Gateway extensibility is safest when code scope, deployment scope, and authorization scope match. API7 Gateway 3.10.6 makes the gateway group the common boundary for all three. That does not remove the need for disciplined plugin engineering; it gives that discipline a resource model that can enforce environment isolation.

Read the complete API7 Gateway 3.10.6 release notes, review the plugin execution and scope model, and turn every migration and rollback condition that applies to your deployment into a staging assertion before production promotion.