u/Kralizek82

A little more than six years ago, I published a weekend project of mine: a small glue library between the .NET configuration system and AWS Secrets Manager.

The package got some traction over time. It was featured in a few YouTube videos and blog posts, and even in some AWS courses.

Most importantly, people kept using it.

Today, it has almost 10M downloads. Surely, some of those are NuGet mirrors, bots, and CI restores, but the steady flow of issues and PRs confirmed that there was a real need for this little library.

Many users. Many different use cases. New features added to AWS Secrets Manager itself. A few design decisions that made sense six years ago, but less so today.

No wonder the public API became a bit fragmented and unclear.

Over the past couple of weeks, I spent some time doing a full rework of the public surface, extracting needs and behaviors from open and closed issues, PRs, and real-world usage patterns.

What came out of it is a full 2.0.0 rewrite, with several breaking changes, changed default behaviors, and, hopefully, a much better developer experience.

The biggest conceptual change is that the library now separates two scenarios that used to be a bit mixed together:

• discovering secrets from AWS Secrets Manager
• loading secrets that the application already knows about

Discovery is useful when your app follows a naming convention and wants to load a group of secrets based on a prefix, tag, or filter. This is very similar to how the SSM configuration provider works.

Known-secret loading is useful when your infrastructure already tells the app exactly which secret to use.

That second scenario is the one I found myself using more and more.

The source configuration tells the app where the secret is. The secret provides the sensitive values.

For example, take a very common setup: configuring an SMTP client.

The application needs some non-secret settings:

{
  "Email": {
    "Host": "smtp.example.com",
    "Port": 587,
    "FromAddress": "no-reply@example.com",
    "SecretId": "my-application/email/smtp"
  }
}

The secret itself contains only the sensitive values:

{
  "Username": "smtp-user",
  "Password": "smtp-password"
}

With 2.0.0, the app can read the secret id from configuration and load that known secret into the same Email section:

if (builder.Configuration["Email:SecretId"] is { } secretId && !string.IsNullOrWhiteSpace(secretId))
{
    builder.Configuration.AddSecretsManagerKnownSecret(secretId, options =>
    {
        options.ReloadInterval = TimeSpan.FromMinutes(5);

        options.KeyMapping.TargetSection = "Email";
        options.KeyMapping.PrefixJsonKeysWithSecretName = false;
    });
}

builder.Services.Configure<EmailOptions>(builder.Configuration.GetSection("Email"));

The resulting configuration section behaves as if it had been composed like this:

{
  "Email": {
    "Host": "smtp.example.com",
    "Port": 587,
    "FromAddress": "no-reply@example.com",
    "SecretId": "my-application/email/smtp",
    "Username": "smtp-user",
    "Password": "smtp-password"
  }
}

So the rest of the application can stay completely boring:

public sealed class EmailOptions
{
    public required string Host { get; init; }
    public required int Port { get; init; }
    public required string FromAddress { get; init; }
    public required string Username { get; init; }
    public required string Password { get; init; }
}

No AWS SDK calls in the email sender.

No custom secret lookup service.

Just regular IConfiguration and the options pattern.

The 2.0.0 version is currently in beta, and the public API is mostly where I want it to be.

I still want to let it breathe a bit before stamping it as stable. The next step is one or more RC builds, then the final 2.0.0.

The project is available here:

• GitHub: https://github.com/Kralizek/AWSSecretsManagerConfigurationExtensions
• NuGet: https://www.nuget.org/packages/Kralizek.Extensions.Configuration.AWSSecretsManager

The latest stable version is still 1.7, so remember to explicitly select the 2.0.0 prerelease if you want to try the new API.

I'd really appreciate feedback, especially on naming, defaults, migration pain points, and common configuration scenarios that are still awkward.