Opc.AwsSettings 1.2.2

Opc.AwsSettings

A .NET library that simplifies loading configuration from AWS services including Parameter Store, Secrets Manager, and AppConfig into your application's configuration system.

Features

• 🔧 AWS Systems Manager Parameter Store - Load configuration from hierarchical parameters
• 🔐 AWS Secrets Manager - Securely load secrets into your configuration
• ⚙️ AWS AppConfig - Load feature flags and freeform configuration
• 🔄 Auto-reload - Optionally reload configuration at specified intervals
• 🎯 Easy Integration - Seamlessly integrates with .NET's IConfiguration system
• 🌍 Environment-aware - Support for environment-specific configurations

Installation

Install the NuGet package:

dotnet add package Opc.AwsSettings

Quick Start

Basic Usage with Host Builder

using Microsoft.Extensions.Hosting;

var host = Host.CreateDefaultBuilder(args)
    .AddAwsSettings() // Add AWS configuration sources
    .ConfigureServices(services =>
    {
        // Your service configuration
    })
    .Build();

await host.RunAsync();

Manual Configuration Builder Usage

using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddAwsSettings() // Add AWS configuration sources
    .Build();

Configuration

Configure the library using the AwsSettings section in your appsettings.json:

{
  "AwsSettings": {
    "ReloadAfter": "00:05:00",
    "ParameterStore": {
      "Paths": ["/myapp/prod"],
      "Keys": []
    },
    "SecretsManager": {
      "LoadAll": false,
      "AcceptedSecretArns": [],
      "Prefix": null,
      "Optional": false
    },
    "AppConfig": {
      "ApplicationIdentifier": "my-app",
      "UseLambdaCacheLayer": false,
      "ConfigurationProfiles": []
    }
  }
}

Usage Examples

1. Parameter Store Configuration

Simple Path-Based Loading

Load all parameters under a specific path prefix:

{
  "AwsSettings": {
    "ParameterStore": {
      "Paths": ["/myservice"]
    }
  }
}

If your Parameter Store contains:

• /myservice/Database/ConnectionString = "Server=..."
• /myservice/Database/MaxPoolSize = "100"
• /myservice/Api/Endpoint = "https://api.example.com"

They will be mapped to:

{
  "Database": {
    "ConnectionString": "Server=...",
    "MaxPoolSize": "100"
  },
  "Api": {
    "Endpoint": "https://api.example.com"
  }
}

Custom Key Mapping with Aliases

Use custom aliases to map Parameter Store keys to cleaner configuration names:

{
  "AwsSettings": {
    "ParameterStore": {
      "Keys": [
        {
          "Path": "/aws/reference/secretsmanager/prod-db-credentials",
          "Alias": "Database:ConnectionString"
        },
        {
          "Path": "/myservice/config/api-key",
          "Alias": "ApiSettings:Key",
          "Optional": true
        }
      ]
    }
  }
}

Loading Secrets Manager via Parameter Store

Reference Secrets Manager values through Parameter Store:

{
  "AwsSettings": {
    "ParameterStore": {
      "Keys": [
        {
          "Path": "/aws/reference/secretsmanager/my-secret",
          "Alias": "MySecret"
        }
      ]
    }
  }
}

2. Secrets Manager Configuration

Load All Secrets

Load all secrets from Secrets Manager:

{
  "AwsSettings": {
    "SecretsManager": {
      "LoadAll": true,
      "Optional": false
    }
  }
}

Load Specific Secrets by ARN

{
  "AwsSettings": {
    "SecretsManager": {
      "LoadAll": false,
      "AcceptedSecretArns": [
        "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/database",
        "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/api-keys"
      ]
    }
  }
}

Load Secrets with Prefix

Filter secrets by name prefix:

{
  "AwsSettings": {
    "SecretsManager": {
      "LoadAll": true,
      "Prefix": "prod/myapp/"
    }
  }
}

3. AppConfig Configuration

Load AppConfig Profiles

{
  "AwsSettings": {
    "AppConfig": {
      "ApplicationIdentifier": "my-application",
      "ConfigurationProfiles": [
        {
          "Identifier": "my-config-profile",
          "Optional": false
        },
        {
          "Identifier": "feature-flags",
          "Optional": true
        }
      ]
    }
  }
}

With Lambda Cache Layer

For AWS Lambda functions, enable the cache layer for improved performance:

{
  "AwsSettings": {
    "AppConfig": {
      "ApplicationIdentifier": "my-application",
      "UseLambdaCacheLayer": true,
      "ConfigurationProfiles": [
        {
          "Identifier": "my-config-profile"
        }
      ]
    }
  }
}

4. Auto-Reload Configuration

Enable automatic reloading of configuration at specified intervals:

{
  "AwsSettings": {
    "ReloadAfter": "00:05:00",  // Reload every 5 minutes
    "ParameterStore": {
      "Paths": ["/myapp"]
    }
  }
}

5. Environment-Specific Configuration

The library respects the ASPNETCORE_ENVIRONMENT or DOTNET_ENVIRONMENT variables:

var host = Host.CreateDefaultBuilder(args)
    .AddAwsSettings() // Automatically uses current environment
    .Build();

Or specify the environment explicitly:

var configuration = new ConfigurationBuilder()
    .AddAwsSettings(environmentName: "Production")
    .Build();

6. Using Configuration in Your Application

Bind to Strongly-Typed Options

public class DatabaseSettings
{
    public string ConnectionString { get; set; }
    public int MaxPoolSize { get; set; }
}

// In Program.cs
services.Configure<DatabaseSettings>(
    configuration.GetSection("Database")
);

// In your service
public class MyService
{
    private readonly DatabaseSettings _settings;
    
    public MyService(IOptions<DatabaseSettings> options)
    {
        _settings = options.Value;
    }
}

Direct Configuration Access

var connectionString = configuration["Database:ConnectionString"];
var apiEndpoint = configuration["Api:Endpoint"];

Using GetSettings Extension Method

var awsSettings = configuration.GetSettings<AwsSettings>();

7. With Logging

Enable logging to see what configuration is being loaded:

using Microsoft.Extensions.Logging;

var loggerFactory = LoggerFactory.Create(builder => 
{
    builder.AddConsole();
});

var logger = loggerFactory.CreateLogger("AwsSettings");

var host = Host.CreateDefaultBuilder(args)
    .AddAwsSettings(logger)
    .Build();

Complete Example

Here's a complete example combining multiple AWS configuration sources:

{
  "AwsSettings": {
    "ReloadAfter": "00:10:00",
    "ParameterStore": {
      "Paths": ["/myapp/prod"],
      "Keys": [
        {
          "Path": "/aws/reference/secretsmanager/db-connection",
          "Alias": "Database:ConnectionString"
        }
      ]
    },
    "SecretsManager": {
      "LoadAll": false,
      "AcceptedSecretArns": [
        "arn:aws:secretsmanager:us-east-1:123456789012:secret:api-keys"
      ]
    },
    "AppConfig": {
      "ApplicationIdentifier": "myapp",
      "ConfigurationProfiles": [
        {
          "Identifier": "application-config"
        },
        {
          "Identifier": "feature-flags"
        }
      ]
    }
  }
}

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((context, config) =>
    {
        config.AddJsonFile("appsettings.json");
        config.AddAwsSettings(context.HostingEnvironment.EnvironmentName);
    })
    .ConfigureServices((context, services) =>
    {
        // Configure your services using the loaded configuration
        services.Configure<DatabaseSettings>(
            context.Configuration.GetSection("Database")
        );
        services.Configure<ApiSettings>(
            context.Configuration.GetSection("Api")
        );
    })
    .Build();

await host.RunAsync();

AWS Permissions Required

Ensure your application has the necessary AWS IAM permissions:

Parameter Store

{
  "Effect": "Allow",
  "Action": [
    "ssm:GetParameter",
    "ssm:GetParameters",
    "ssm:GetParametersByPath"
  ],
  "Resource": "arn:aws:ssm:*:*:parameter/myapp/*"
}

Secrets Manager

{
  "Effect": "Allow",
  "Action": [
    "secretsmanager:GetSecretValue",
    "secretsmanager:ListSecrets"
  ],
  "Resource": "arn:aws:secretsmanager:*:*:secret:*"
}

AppConfig

{
  "Effect": "Allow",
  "Action": [
    "appconfig:GetConfiguration",
    "appconfig:StartConfigurationSession"
  ],
  "Resource": "*"
}

Best Practices

1. Use Parameter Store paths for hierarchical configuration - Organize your parameters by environment and service
2. Use Secrets Manager for sensitive data - Store passwords, API keys, and certificates in Secrets Manager
3. Enable auto-reload for dynamic configuration - Set appropriate ReloadAfter intervals for configuration that changes
4. Use AppConfig for feature flags - Leverage AppConfig for runtime feature toggles
5. Set optional flags appropriately - Mark non-critical configuration as optional to prevent startup failures
6. Use environment-specific prefixes - Organize parameters like /myapp/prod/... and /myapp/dev/...

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source. Please check the repository for license details.

Links

• GitHub Repository
• NuGet Package

Opc.AwsSettings

An opinionated .NET Standard 2.0 library that provides support for all AWS settings options including Parameter Store, Secrets Manager, AppConfig Freeform and AppConfig Feature Flags.