Introducing the AWS AppConfig Python Helper Library

AWS AppConfig enables you to manage and quickly deploy application configurations without doing time-consuming code deployments. With AWS AppConfig, you can create an application configuration, validate it to make sure it is free of syntax or semantic errors, and deploy it to your targets at a controlled rate at runtime. If AWS AppConfig encounters errors during deployment, it rolls back the configuration to the previous version to minimize application outage. After the deployment is complete, your application needs to poll AWS AppConfig to retrieve the new configuration update. The AWS AppConfig helper library is a sample open source Python library that you can add to your application to quickly integrate AWS AppConfig with your application, using best practices.

In this post, I’ll show you how to use the library in a sample application that serves a simple HTTP API. AWS AppConfig and the library work anywhere you can run your Python code (and the AWS AppConfig API endpoint can be reached), including in AWS Lambda. The code for the example used in this post is available on GitHub.

Solution Overview

You create a Python application that presents an API endpoint through HTTP. AWS AppConfig accepts a unit of text and returns it to the user reversed, uppercased, or both. The solution includes two feature flags, controlled by AWS AppConfig, to specify which transformations should apply. The solution uses AWS AppConfig to update the feature flag to see the change picked up by the application without requiring a code deployment.

Figure 1: Architecture and request flow for a simple test application using Python and AWS AppConfig

Walkthrough

These are the high-level steps:

• Create the AWS AppConfig resources to hold the configuration.
• Create the Python application, including the sample AWS AppConfig helper library.
• Test the application.
• Deploy a new version of the configuration and test the application to see it take effect.

Prerequisites

To complete the steps in this walkthrough, you need the following:

• An AWS account with AWS credentials configured in your command line environment (typically in ~/.aws/credentials).
• Python 3 installed. (The sunset date for Python 2 has passed. It is not supported by the AWS AppConfig helper library.)
• A tool to perform HTTP requests. For example, you can use curl or httpie on the command line. If you prefer a GUI, you can use Postman or your web browser.

Create the AWS AppConfig resources

First, create the AWS AppConfig resources to hold your application’s configuration. These resources include:

• An application, which represents a logical unit of code that provides capabilities to your customers.
• An environment, which is a deployment group (for example, beta or production).
• A configuration profile, which allows AWS AppConfig to access your configuration data.

You can create these resources by launching this AWS CloudFormation template. The template is launched in the us-east-1 AWS Region so make sure your command line environment is configured to use the same Region.

If you prefer to create the resources yourself, follow these steps:

1. Sign in to the AWS Management Console and make sure you are using the same AWS Region as the one configured in your command line environment.
2. In the search box, enter AppConfig, and then open the AWS Systems Manager console.
3. If the AWS AppConfig welcome page appears, choose Create configuration data. Otherwise, choose Create application.
4. In Name, enter DemoApp, and then choose Create application.
5. On the details page, choose Create environment.
6. In Name, enter prod, and then choose Create environment.
7. On the details page, choose Start deployment.
8. Choose Create configuration profile.
   

   Figure 2: Create a configuration profile

9. In Name, enter main.
10. For Configuration source, make sure AWS AppConfig hosted configuration is selected.
11. Under Content, choose JSON, enter the following JSON, and then choose Next. This is the configuration your app will receive from AWS AppConfig.

    {
        "transform_reverse": true,
        "transform_allcaps": false
    }

    

    Figure 3: Choose JSON and enter the configuration as a JSON document

12. On the Add validators page, do not select either option. Choose Create configuration profile.
13. Under Deployment details, from Configuration, choose main.
14. From Hosted configuration version, choose 1.
15. From Deployment strategy, choose AppConfig.AllAtOnce (Quick).
    

    Figure 4: Deployment details

16. Choose Start deployment.

Your JSON document will be available as configuration version 1 when the application requests it.

Create the Python application

Next, create the Python application. As a best practice, create a virtual environment to install the Python libraries. In addition to the AWS AppConfig helper, the solution uses the FastAPI library to provide the API functionality and uvicorn to provide an HTTP server.

Note: These instructions were written with the assumption that python and pip (the Python package installer) point to a Python 3 installation. You might need to use pip3 and python3 instead.

1. Create a folder where you will build the project:

   mkdir appconfig-demo; cd appconfig-demo

2. Create a virtual environment:

   python -m venv .venv

3. Activate the virtual environment:

   source .venv/bin/activate

   Note: If you open other terminal windows or shells, you will need to run this command in them, too.

4. In your editor, create a file with the following contents and save it as requirements.txt in the appconfig-demo folder.

   fastapi
   uvicorn
   sample-helper-aws-appconfig

5. Install the libraries:

   pip install -r requirements.txt

6. In your editor, create another file with the following contents and save it as main.py in the appconfig-demo folder.

   from appconfig_helper import AppConfigHelper
   from fastapi import FastAPI
   
   app = FastAPI()
   
   appconfig = AppConfigHelper(
       "DemoApp",
       "prod",
       "main",
       15,
   )
   
   
   @app.get("/process-string/{input_string}")
   def index(input_string):
       if appconfig.update_config():
           print("Received new configuration")
       output_string = input_string
       if appconfig.config.get("transform_reverse", False):
           output_string = "".join(reversed(output_string))
       if appconfig.config.get("transform_allcaps", False):
           output_string = output_string.upper()
   
       return {
           "output": output_string,
       }
   

This code imports the required libraries, and then creates an AppConfigHelper instance. The first three values passed tell the library which configuration to request from the AWS AppConfig API. These are the application, environment, and profile names you set earlier. The final value is the number of seconds to wait between requesting new configuration updates from the API. Here the value is set to 15 seconds so that you can quickly see the effect of deploying updates. For more information about the parameters you can supply to the library, see the README on GitHub.

The library implements AWS AppConfig best practices when it calls the API. It specifies a client ID and the last-received version of the configuration document. The client ID allows AWS AppConfig to deploy the configuration in intervals according to the deployment strategy in use. The last-received version of the configuration allows the API to notify you quickly if you already have the correct configuration version. If this value was not supplied on the API call, AWS AppConfig returns the entire configuration document in its response, which incurs an additional charge. (If you are familiar with HTTP requests and caching, this is similar to a client making a request with an If-Modified-Since header and the server responding with a 304 Not Modified status code.) For more information, see the Receiving the configuration in the AWS AppConfig User Guide.

The code sets up a handler for the /process-string path on your HTTP API, which takes an input parameter to work on. The handler first calls the update_config() function on the AppConfigHelper instance. If it has been more than 15 seconds since the last check, the library calls the AWS AppConfig API to check for a new configuration.

The handler then checks the values of the two feature flags from the received configuration (which is exposed by the library as the config attribute) and performs the required transformations on the input text. The JSON document was processed by the helper library automatically. Finally, the result is returned so that FastAPI and uvicorn can return it to the requestor.

Test the application

Now start the application and test it to see it reversing, but not uppercasing, the input string, as per the feature flags you configured.

1. Make sure your terminal environment has required credentials and is configured to use the same AWS Region where you created the resources. Make sure you have activated the virtual environment in this terminal (see step 3 in the previous section).
2. Start the web server:

   uvicorn main:app

3. Using curl, httpie, Postman, or your browser, go to http://localhost:8000/process-string/hello%20world.
4. You should receive a JSON response that contains the output "dlrow olleh."

Figure 5: Using a terminal to run the demo application and sending it an HTTP request

Your application has received the configuration and, as requested, is reversing the input but not transforming it to all capitalized letters.

Deploy a configuration update that enables all-caps mode

1. 1. To update the configuration, go the AWS Systems Manager console and choose AWS AppConfig.
   2. Choose the DemoApp application.
   3. Choose the Configuration profiles tab.
      

      Figure 6: Configuration profiles tab for the DemoApp application

   4. Choose the main profile.
   5. Under Hosted configuration versions, choose Create.
   6. On the Create hosted configuration version page, the current content of the configuration is displayed. Change the value of transform_allcaps from false to true and then choose Create hosted configuration version.
      

      Figure 7: Update the JSON configuration document for the transform_allcaps setting

   7. When the main page reloads, choose Start deployment.
   8. On the Start deployment page, choose the prod environment, the new configuration version (2), and the AppConfig.AllAtOnce (Quick) deployment strategy.
   9. Choose Start deployment and then wait for the state to change from Deploying to Complete.

   You can repeat the test in the previous section by loading http://localhost:8000/process-string/hello%20world.

   The output value should now be reversed and in uppercase. If the change does not appear, wait 15 seconds to ensure the library will check for a new configuration version, and try again.

   
   Figure 8: Terminal window showing the application has received the new configuration

   Congratulations! You have just deployed a configuration update for your application. It was picked up and applied without having to be restarted.

   Cleaning up

   Although there are no charges for storing AWS AppConfig resources, you might want to clean up the resources if you’re not going to use them again.

   1. In the AWS Systems Manager console, choose AWS AppConfig, and then navigate to the DemoApp application.
   2. Next to Version, choose Delete, and then choose Delete again to confirm.
   3. Repeat step 2 until there are no hosted configuration versions.
   4. Choose the DemoApp link in the breadcrumb at the top of the page.
   5. Choose the prod environment, choose Delete, and then choose Delete to confirm.
   6. On the Configuration profiles tab, choose the main profile, choose Delete, and then choose Delete to confirm.
   7. Choose Delete application, and then choose Delete to confirm.

   If you used CloudFormation to create the AWS AppConfig resources, open the AWS CloudFormation console, choose the stack you created, and click Delete, then Delete stack.

   Conclusion

   In this post, I showed you how to integrate AWS AppConfig with a Python application using the AWS AppConfig helper library. In addition to dynamically deploying configuration updates to your applications, you can use the code in this blog post to explore other useful features, including syntactic and semantic configuration validation, deployment rate controls, and monitoring your application and rolling back in the event of errors. For more information, see the What Is AWS AppConfig in the AWS AppConfig User Guide.

   About the Author

   

   James Seward is a Solutions Architect at Amazon Web Services. He works with healthcare customers in the UK to help them design and implement solutions in the AWS Cloud. James enjoys cycling through the English countryside and working on his car.