<!-- Provide a general summary of your changes in the Title above -->
## Description
Ticket: https://tyktech.atlassian.net/browse/TT-17297
Adds a file-based KV provider to Tyk Gateway so that KV references in
gateway config and API definitions can resolve to the contents of local
files. This is the primary mechanism for consuming Kubernetes secrets
mounted as volume files on data-plane pods - enabling certificates and
tokens to be referenced by name without ever storing private key
material in the management plane.
## Related Issue
Part of a two-ticket solution:
TT-17297 (this PR) — file-based KV provider: file:// URI scheme for
load-time resolution, $secret_file. prefix for runtime resolution
TT-17295 (dependency) — PEM string support in API definitions: allows a
certificate field to contain the raw PEM content rather than a file path
The mTLS client certificate use case (K8s secret → API definition → mTLS
handshake) requires both PRs to be merged. This PR resolves the KV
reference to the PEM content; TT-17295 makes the gateway accept that PEM
content string as a certificate.
## Motivation and Context
Currently the management plane stores private key material for every TLS
certificate used in mTLS. This creates a security risk by centralising
sensitive keys. The proposed solution: the management plane stores only
a reference (file://client.crt), and the data-plane gateway resolves it
from a K8s secret mounted as a volume at runtime - the private key never
leaves the pod.
## How This Has Been Tested
1. Automated tests
2. Manual testing
#### NOTE:
1. I've done some manual testing with local setup and asked LLM to
generate some guide file; attached the file to the ticket.
2. To test pem cert value on api def e2e we have to combine changes from
TT-17297 and TT-17295. Because raw cert pem value can be added to api
def and code from TT-17295 make it work. I've created parent branch
where both ticket's change are included:
https://github.com/TykTechnologies/tyk/tree/TT-15079
## DEMO
_Given the api def with client cert added with using file:// syntax to
allowed list. Then client send request with using valid cert, then cert
is updated with new one and temporaly old cert is still valid until
gateway is hot-reloaded. Then we trigger the hot-reload with api def
update and old cert stopped working but new cert value was used without
gateway process shutdown_
https://github.com/user-attachments/assets/ea3514f5-c339-4710-8b50-f0d5e0833640
_Given the config file with file:// reference by using relative path_
https://github.com/user-attachments/assets/1a22cb1f-9e50-44cb-a705-402bc83947eb
_Given the config file with file:// reference by using absolute path_
https://github.com/user-attachments/assets/5e5a32e5-907d-492e-8cb3-7c55eca7bfc8
_Given api def with rewrite URL pattern to add query param with file
referencing_
https://github.com/user-attachments/assets/78b23ec1-11f2-4cc1-86ff-584488e2a0e6
## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Refactoring or add test (improvements in base code or adds test
coverage to functionality)
## Checklist
#### TODO: VALIDATE DOCS WITH ANDY
- [ ] I ensured that the documentation is up to date
- [x] I explained why this PR updates go.mod in detail with reasoning
why it's required
- [x] I would like a code coverage CI quality gate exception and have
explained why
<!---TykTechnologies/jira-linter starts here-->
### Ticket Details
<details>
<summary>
<a href="https://tyktech.atlassian.net/browse/TT-17297" title="TT-17297"
target="_blank">TT-17297</a>
</summary>
| | |
|---------|----|
| Status | In Code Review |
| Summary | Support File Based KV Referencing. |
Generated at: 2026-06-03 12:17:15
</details>
<!---TykTechnologies/jira-linter ends here-->
---------
Co-authored-by: Vlad Zabolotnyi <vlad.z@tyk.io>
