AWS Workload Credentials Provider: A Localhost Cache for Secrets Manager and an ACM Exporter
The AWS Workload Credentials Provider (formerly the AWS Secrets Manager Agent) is a client-side solution that helps you standardize how you consume credentials from AWS services across your compute environments.
At a glance
- What is it?
- AWS's renamed Secrets Manager Agent is now two capabilities in one Rust binary: an in-memory secrets cache served over localhost HTTP, and an opt-in ACM certificate exporter. This review covers the mechanism, the configuration surface, the stale-secret failure mode, and who should skip it.
- Who is it for?
- Adopt this if you run many processes on ECS, EKS, EC2, or Lambda that each call Secrets Manager directly and you want one localhost cache with a tunable TTL, or if you need ACM certificates written to disk and reloaded on a schedule. Do not adopt it if you need cache invalidation on rotation, encrypted at-rest caching, or write access to secrets; a sidecar that only reads and caches cannot rotate credentials for you.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 13 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: every process calling Secrets Manager on its own
If ten services on one EC2 instance each call GetSecretValue, you pay for ten API calls, ten sets of retry logic, and ten places where a secret can end up in a log. The Workload Credentials Provider collapses that into one local HTTP endpoint. Applications read secrets from localhost instead of talking to Secrets Manager directly, and the provider holds an in-memory cache in front of the API. The README describes it as a way to "standardize how you consume credentials from AWS services across your compute environments," and the supported targets are specific: AWS Lambda, Amazon ECS, Amazon EKS, and Amazon EC2. The certificate side is narrower, EC2 and on-premise hosts only. This is infrastructure plumbing for platform teams, not an application library. If you have one service on one host, the provider adds a process, a port, and a configuration file for a cache you could implement in a few lines of SDK code. The value appears at the point where secrets reads become numerous and repetitive.
How the cache actually works, and when it goes stale
The provider keeps secret values in memory and serves them over a localhost HTTP interface. It can only read secrets, never modify them, and it returns values in the same format as the GetSecretValue response, so an application that already parses that shape can switch without reshaping its data. Refresh is lazy, not scheduled: the provider checks the TTL when you attempt to read a secret, and only then does it fetch a new value if the entry has expired. The default TTL is 300 seconds and is configurable. Two consequences follow from this design. First, the cache is empty after every restart, so the first request after a restart always hits Secrets Manager. Second, and more important, the README states plainly that the provider "does not include cache invalidation," so if a secret rotates before the cache entry expires, the provider can return a stale value. There is no push notification from Secrets Manager to the provider. If your rotation window is shorter than your TTL, you have built a system that serves revoked credentials for the difference. The README also notes that secret values are not encrypted in the cache. That is memory, not disk, but it means the provider process's memory is a place where plaintext secrets accumulate.
Certificate export: independent tasks, one per certificate
The second capability is opt-in and does something different: it exports certificates from AWS Certificate Manager and writes them as PEM files to the local filesystem. It checks for updated certificates every 24 hours, and after each successful refresh it can run a user-configured command, which the README gives as a way to reload a web server. Up to 50 certificates are supported, and each one is managed by an independent background task. That isolation matters: a failure on one certificate does not stop the others from refreshing. The provider assumes the role you configure for each certificate using the AWS credentials in its environment, then calls ACM to export. This is the part of the project that requires elevated permissions. The install script on Linux, or install.ps1 on Windows, configures the permissions needed to write certificate files and execute refresh commands, and the README calls that script the recommended setup path. If you want to manage permissions yourself on Linux, the documented escape hatches are --no-privileges and --no-sudoers rather than skipping the install script entirely. A provider that writes files and runs commands on your behalf is a privileged component, and the project treats it as one.
Getting it running: build, install, configure, query
The README splits setup into a build step and an install step, with per-platform instructions for RPM-based systems, Debian-based systems, Windows, and native cross-compilation. Installation paths are documented for Amazon EC2 on Linux, Windows EC2, container sidecars, and AWS Lambda. Configuration is passed with the sm start --config /path/to/config.toml command line argument, and the configurable values named in the README are the maximum number of connections, the TTL, the localhost HTTP port, and the cache size. Secrets retrieval is an HTTP call to localhost, with curl and Python examples given in the README. There is a refreshNow parameter with its own documented behavior section, plus examples for GET requests using it, so you can force a refresh instead of waiting for the TTL to expire. Two features sit on top of the basic read path: role chaining for cross-account access, and pre-fetching. On Windows the flag naming differs by context: -Config C:\path\to\config.toml when invoking the PowerShell scripts, and --Config C:\path\to\config.toml when executing the binary directly. Configuration can also be reloaded while the provider is running, and on reload the provider re-applies permissions and restarts the ACM service. The README also documents logging, optional features, and a security considerations section, plus local integration test instructions with required AWS permissions and IAM roles for the role-chaining tests.
Where the design forces a trade-off
The stale-secret behavior is the sharpest limitation, but it is not the only one. The provider reads secrets and cannot write them, so it is not a rotation mechanism; rotation still belongs to Secrets Manager and whatever orchestrates it. The cache lives in process memory, so horizontal scaling multiplies caches rather than sharing one, and each replica has its own TTL clock. There is no documented cache invalidation API, which means the only levers against staleness are a shorter TTL, which increases Secrets Manager API traffic, or an explicit refreshNow call from the application, which pushes cache-management logic back into the client. The certificate side has its own boundary: EC2 and on-premise hosts only, so if your workloads run exclusively on Lambda or EKS, that capability is not available to you. The 50-certificate ceiling is documented, and the 24-hour refresh interval is fixed by the README's description rather than presented as configurable. The provider also enables the post-quantum ML-KEM key exchange as the highest-priority key exchange by default, which is a forward-looking default but one worth confirming against your TLS stack and any interception appliances in the path. None of these are defects. They are the shape of the tool, and they determine whether it fits.
Alternatives: what changes if you do not use it
The direct alternative is calling Secrets Manager from each application with the AWS SDK, optionally with the SDK's own caching layer. That approach removes a process, a localhost port, and a privileged installer, and it keeps the secret-fetching logic in the language your application already uses. The difference in approach is where the cache lives: with the SDK, each process caches independently and you control invalidation inside your own code; with the provider, one process caches for every client on the host and you get a uniform TTL and a uniform localhost interface, at the cost of losing per-application control and gaining a component to operate. A second alternative, for the certificate capability specifically, is fetching certificates through your configuration management or deployment pipeline and writing them to disk yourself. That gives you full control over file permissions and reload commands, but you own the 24-hour polling loop, the per-certificate fault isolation, and the retry behavior that the provider implements as independent background tasks. The provider's advantage is that these are already built and documented; its disadvantage is that the permissions it needs are broad by design.
Maintenance, licensing, and what to check before adopting
The project is Apache-2.0 licensed, written in Rust, and actively released: v3.0.0 in June 2026, v3.1.0 in July 2026, and v3.1.1 later that same month. The 3.x line follows a rename from AWS Secrets Manager Agent, so older documentation, scripts, and internal runbooks that reference the old name will need updating. The upgrade cost is concentrated in the configuration file and the install scripts, because reload re-applies permissions and restarts the ACM service, which means a config change is not a no-op for anything currently serving certificates. On the licence side, Apache-2.0 permits commercial use and modification and includes a patent grant; it also requires that you preserve copyright and licence notices. That is the standard reading, not legal advice, and if you redistribute the binary inside a product, have counsel review the notice obligations. Two things to verify first: whether your secret rotation interval is longer than the TTL you intend to configure, since the provider will serve stale values until the TTL expires, and whether the permission changes made by install or install.ps1 are acceptable to your security team, since the README recommends those scripts over manual permission management. If either answer is no, the provider is the wrong layer for your secrets.
Editorial conclusion
Adopt this if you run many processes on ECS, EKS, EC2, or Lambda that each call Secrets Manager directly and you want one localhost cache with a tunable TTL, or if you need ACM certificates written to disk and reloaded on a schedule. Do not adopt it if you need cache invalidation on rotation, encrypted at-rest caching, or write access to secrets; a sidecar that only reads and caches cannot rotate credentials for you. Before rollout, verify the TTL against your rotation schedule, confirm the install script's permission changes against your own security baseline, and check that your build toolchain supports the post-quantum ML-KEM key exchange the provider enables by default.
Community notes