Amazon.Extensions.Configuration.SystemsManager simplifies using AWS SSM's Parameter Store and AppConfig as a source for configuration information for .NET Core applications. This project was contributed by @KenHundley and @MichalGorski.
The library introduces the following dependencies:
- AWSSDK.Extensions.NETCore.Setup
- AWSSDK.SimpleSystemsManagement
- AWSSDK.AppConfig
- Microsoft.Extensions.Configuration
Follow the examples below to see how the library can be integrated into your application. This extension adheres to the same practices and conventions of Configuration in ASP.NET Core.
One of the common use cases for this library is to pull configuration from Parameter Store. You can easily add this functionality by adding 1 line of code:
public class Program
{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.ConfigureAppConfiguration(builder =>
{
builder.AddSystemsManager("/my-application/");
})
.UseStartup<Startup>();
}Second possibility is to pull configuration from AppConfig. You can easily add this functionality by adding 1 line of code:
public class Program
{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.ConfigureAppConfiguration(builder =>
{
builder.AddAppConfig("AppConfigApplicationId", "AppConfigEnvironmentId", "AppConfigConfigurationProfileId", , TimeSpan.FromSeconds(20));
})
.UseStartup<Startup>();
}Microsoft introduced .NET Generic Host to de-couple HTTP pipeline from the Web Host API. The Generic Host library allows you to write non-HTTP services using configuration, dependency injection, and logging features. The sample code below shows you how to use the the AWS .NET Configuration Extension library:
namespace HostBuilderExample
{
public static async Task Main(string[] args)
{
var host = new HostBuilder()
.ConfigureAppConfiguration((hostingContext, config) =>
{
config.AddSystemsManager("/my-application/");
config.AddAppConfig("AppConfigApplicationId", "AppConfigEnvironmentId", "AppConfigConfigurationProfileId", TimeSpan.FromSeconds(20));
})
.ConfigureServices((sc) => { ... })
.Build();
await host.RunAsync();
}
}Example of using a custom IParameterProcessor which provides a way to store and retreive null values. Since AWS Parameter Store params are string literals, there is no way to store a null value by default.
namespace CustomParameterProcessorExample
{
public class CustomParameterProcessor : DefaultParameterProcessor
{
const string NULL_STRING_LITERAL = "NULL";
public override string GetValue(Parameter parameter, string path)
{
string value = base.GetValue(parameter, path);
return value == NULL_STRING_LITERAL ? null : value;
}
}
public class Program
{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.ConfigureAppConfiguration(builder =>
{
builder.AddSystemsManager(config => {
config.Path = "/my-application/";
config.ParameterProcessor = new CustomParameterProcessor();
});
})
.UseStartup<Startup>();
}
}For more complete examples, take a look at sample projects available in samples directory.
The reloadAfter parameter on AddSystemsManager() and AddAppConfig() enables automatic reloading of configuration data from Parameter Store or AppConfig as a background task.
In AWS Lambda, background tasks are paused after processing a Lambda event. This could disrupt the provider from retrieving the latest configuration data from Systems Manager. To ensure the reload is performed within a Lambda event, we recommend calling the extension method WaitForSystemsManagerReloadToComplete from the IConfiguration object in your Lambda function. This method will immediately return unless a reload is currently being performed. See the example below:
using Amazon.Extensions.Configuration.SystemsManager
...
var configurationBuilder = new ConfigurationBuilder();
configurationBuilder.AddSystemsManager(IntegTestFixture.ParameterPrefix, fixture.AWSOptions);
var configurations = configurationBuilder.Build();
...
configurations.WaitForSystemsManagerReloadToComplete(TimeSpan.FromSeconds(5));For AppConfig in Lambda you should use Lambda Extension.
This extension is using AWSSDK.Extensions.NETCore.Setup in order to get AWSOptions from Configuration object and create AWS Systems Manager Client. You can edit and override the configuration by adding AWSOptions to your configuration providers such as appsettings.Development.json. Below is an example of a configuration provider:
{
...
"AWS": {
"Profile": "default",
"Region": "us-east-1",
"ResignRetries": true
}
...
}For more information and other configurable options please refer to Configuring the AWS SDK for .NET with .NET Core.
The AWS credentials used must have access to the ssm:GetParameters service operation from AWS System Manager. Below is an example IAM policy for this action.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "SSMPermissionStatement",
"Effect": "Allow",
"Action": "ssm:GetParameters",
"Resource": "arn:aws:ssm:${Region}:${Account}:parameter/${ParameterNamePrefix}*"
}
]
}The above policy gives user access to get and use parameters which begin with the specified prefix.
For more details, refer Restricting access to Systems Manager parameters using IAM policies.
If the application reads configuration values from AWS Systems Manager AppConfig, the AWS credentials used must have access to appconfig:GetConfiguration service operation. Below is an example IAM policy for this action.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"appconfig:GetConfiguration"
],
"Resource": [
"arn:${Partition}:appconfig:${Region}:${Account}:application/${ApplicationId}",
"arn:${Partition}:appconfig:${Region}:${Account}:application/${ApplicationId}/environment/${EnvironmentId}",
"arn:${Partition}:appconfig:${Region}:${Account}:application/${ApplicationId}/configurationprofile/${ConfigurationProfileId}"
]
}
]
}For more details, refer Configuring permissions for AWS AppConfig and Actions, resources, and condition keys for AWS AppConfig.
We use the GitHub issues for tracking bugs and feature requests and have limited bandwidth to address them.
If you think you may have found a bug, please open an issue.
We welcome community contributions and pull requests. See CONTRIBUTING.md for information on how to set up a development environment and submit code.
AWS .NET GitHub Home Page
GitHub home for .NET development on AWS. You'll find libraries, tools, and resources to help you build .NET applications and services on AWS.
AWS Developer Center - Explore .NET on AWS
Find all the .NET code samples, step-by-step guides, videos, blog content, tools, and information about live events that you need in one place.
AWS Developer Blog - .NET
Come see what .NET developers at AWS are up to! Learn about new .NET software announcements, guides, and how-to's.
@dotnetonaws Follow us on twitter!
Libraries in this repository are licensed under the Apache 2.0 License.