title	Deploying Custom Plugins: Volume Mounts vs Bundles
description	Understand the trade-offs between volume-mounted files and plugin bundles when supplying custom middleware to Tyk Gateway.
tags	Custom Plugins Plugin Bundles Deployment Kubernetes

Why plugin location matters

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.

Option 1: Volume-mounted (or baked-in) files

How it works

• 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) or x-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.

Advantages

• 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.

Trade-offs

• 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.

Operational tips

• 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 Deployment rollout strategies or GitOps tooling so that plugin changes follow the same promotion pipeline as other config.

Option 2: Plugin bundles

How it works

• Package one or more plugins plus manifest.json into a ZIP bundle using tyk bundle build or 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_bundle or pluginConfig.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.

Advantages

• 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.

Trade-offs

• 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.

Operational tips

• 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.

Quick comparison

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

Choosing the right option

• 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.

Related resources

• [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***} ");