| title | description | tags | ||||
|---|---|---|---|---|---|---|
Deploying Custom Plugins: Volume Mounts vs Bundles |
Understand the trade-offs between volume-mounted files and plugin bundles when supplying custom middleware to Tyk Gateway. |
|
Tyk Gateway only runs a custom plugin if the file (JavaScript, Python, gRPC stub, Go .so, etc.) is reachable at the path declared in custom_middleware or middleware.global within your API definition. You therefore need a repeatable way to make that file available inside every Gateway instance—either by shipping it with the container filesystem or by letting the Gateway download it at runtime. This page compares the two supported patterns so you can choose the right fit for your environments.
- Build a custom Gateway image or mount a ConfigMap/Secret/CSI volume so that the plugin file ends up under
/opt/tyk-gateway/middleware/...(or another relative path you reference). - Point your API definition at that file via
custom_middleware.*[].path(Tyk Classic) orx-tyk-api-gateway.middleware.global.pluginConfig.data.path(Tyk OAS). - Roll out the updated Deployment/StatefulSet so each pod has the plugin file before the Gateway loads the API definition.
- Offline-friendly: No external bundle server is required; the plugin ships with the pod.
- Predictable startup: Pods fail fast if the file is missing, which simplifies troubleshooting.
- Simple security posture: No need to manage signing keys or outbound access for bundle downloads.
- Update cadence tied to pod restarts: Any plugin change demands a new image build or an updated volume plus a rollout.
- Multi-cluster duplication: Each cluster needs its own copy of the ConfigMap/Secret or image, which can fragment version control.
- Limited auditability: Tracking which pods run which plugin build depends on image/ConfigMap naming discipline.
- Use immutable ConfigMap names (e.g.
example-plugin-v2) and update the Deployment spec to point to the new name; this guarantees pods restart with the correct version. - If you prefer baking plugins into the image, keep them under
/opt/tyk-gateway/middleware/so that your API definition can use short relative paths. - Combine this method with
Deploymentrollout strategies or GitOps tooling so that plugin changes follow the same promotion pipeline as other config.
- Package one or more plugins plus
manifest.jsoninto a ZIP bundle usingtyk bundle buildor your own tooling. - Host the ZIP on an HTTP(S) server (S3 + CloudFront, GCS, artifact repo, etc.) that every Gateway can reach.
- Configure Gateway-level settings (
bundle_base_url, TLS options, optional signature verification) and reference the bundle filename in each API definition (custom_middleware_bundleorpluginConfig.bundle.path). - On startup or API reload, the Gateway downloads the bundle, verifies/signs it if configured, caches it locally, and executes the plugins specified in the manifest.
- Centralized distribution: A single hosted ZIP can be shared across many APIs, clusters, and environments.
- Fast rollouts: Point your API at a new bundle filename and reload Gateway; no pod restart is required.
- Built-in integrity checks: Bundle signing lets you enforce that only authorized artifacts run inside the Gateway.
- Version history: You can keep multiple bundle versions (
bundle-1.0.0.zip,bundle-1.0.1.zip, etc.) and roll forward/backward by updating the API definition.
- Hosting required: You must stand up and maintain a reliable web server or object store endpoint.
- Caching nuances: The Gateway caches bundles, so reusing the same filename after updating the ZIP will not take effect—always publish a unique filename.
- External dependency: Startup depends on the bundle endpoint being reachable; plan for retries or sidecar caches if the network is unreliable.
- Treat bundle filenames as immutable artifacts. Embed semantic versions, build numbers, or Git SHAs and automate API updates via CI/CD or the Dashboard API.
- Enable bundle signing (
private_key_path/public_key_path) for production gateways so that tampered bundles are rejected at download time. - Host bundles behind HTTPS with authentication if you need additional access control; the Gateway supports custom headers in
bundle_base_url.
| Dimension | Volume-mounted / baked-in files | Plugin bundles |
|---|---|---|
| Distribution scope | Per cluster/pod (image or ConfigMap per deployment) | Global; any Gateway that can reach the bundle server |
| Update workflow | Replace ConfigMap or rebuild image, then restart | Publish new ZIP, update API bundle path, reload Gateway |
| External dependencies | None beyond your cluster storage | Requires HTTP(S) hosting and (optionally) signing keys |
| Rollback | Roll pods back to older image/ConfigMap | Point API back to previous bundle filename |
| Best fit | Air-gapped/offline clusters, simple lab setups | Multi-cluster fleets, frequent plugin updates, shared assets |
| Failure mode | Pods crash if volume missing | Gateway keeps last cached bundle if download fails |
- Use volume mounts or custom images when you operate in restricted networks, prefer zero runtime dependencies, or already have strong image promotion workflows.
- Use bundles when you need a single source of truth across environments, want rapid plugin iterations without redeploying pods, or require signed artifacts with auditable versioning.
- Some teams start with volume mounts for experimentation and graduate to bundles once plugins become shared assets; you can mix both approaches in the same fleet as long as each API definition clearly states where its middleware lives.
- [Custom plugins with Tyk Operator]({{< ref "product-stack/tyk-operator/advanced-configurations/custom-plugins" >}}) – end-to-end examples of mounting files with the Operator.
- [Plugin bundles overview]({{< ref "api-management/plugins/overview#plugin-bundles" >}}) – detailed instructions for building, signing, and configuring bundles. *** End Patch***} ");