Skip to main content

Securely manage runtime configuration

Project description

Takes care of your environment (variables) on AWS.


  • Python 3.4+

  • Some simple dependencies as listed in - boto3, PyYAML, requests, and six.

  • A KMS key in your account aliased as alias/treehugger.

How it works

Treehugger lets you use KMS encrypted environment variables to run your application on EC2. You store the encrypted variables in YAML files alongside your other configuration management, then just get them into the EC2 User Data for an instance. Treehugger can read the variables from user data, decrypt the encrypted ones, and run your application.

For example, say we want to run an application that takes a GITHUB_TOKEN environment variable for talking to GitHub. Since this is sensitive data, we want to store it encrypted and only decrypt it when running the application. You can start by writing a YAML file my_app_vars.yml that contains the variable in its unencrypted form, in a to_encrypt key in a mapping that indicates it should be encrypted:

GITHUB_TOKEN: {to_encrypt: example-token}

The TREEHUGGER_APP and TREEHUGGER_STAGE variables are mandatory and used to provide context to Treehugger. They are used to encrypt the variables using KMS’s Encryption Context feature, giving access control and protection against tampering.

You can encrypt the file by running:

treehugger encrypt-file my_app_vars.yml

It’ll be changed to something like:

GITHUB_TOKEN: {encrypted: AQECAHiVqEdWu6BhwWXkqJrEhgPpuDXA3TC1MPUeQb...}

Note that the plaintext variables are not encrypted, only those marked to_encrypt.

Going forwards you can edit the file with:

treehugger edit my_app_vars.yml

This will decrypt the file into a temporary file, open that in your $EDITOR, then once that finishes encrypt it back in place. This avoids any risk of accidentally committing your decrypted secrets.

For deployment, it’s up to you to get the contents of that file into the User Data of the EC2 instance of the application, underneath the key treehugger.

For example, you could pass the contents of the file as a parameter to a CloudFormation template that puts the value into the UserData property of an AutoScaling Group. For example if passed in as a parameter TreehuggerUserData (with extra indentation):

  Type: AWS::AutoScaling::LaunchConfiguration
        - |

Then on the EC2 instance your application can be started with:

treehugger exec -- /path/to/application

Treehugger will load the User Data as YAML, extract the dictionary under the ‘treehugger’ key, decrypt the variables marked encrypted, put them into the environment, and then replace itself with a copy of the application using execlp.

You can also merge in data from an external source with the key include, for example:

include: s3://bucket-name/filename.yml?versionId=7

Where the value is a URL pointing to another YAML file consisting of environment variables. The file will be fetched, and the keys merged in on top of anything defined locally. Currently only S3 URLs are supported, and the S3 API is used for them; versionId is required to avoid ambiguity.

It’s also possible to set the location of a external source in an environment variable:

TREEHUGGER_DATA='s3://bucket-name/filename.yml?versionId=7' treehugger exec -- /path/to/application

this is useful when using treehugger within containers where UserData is not available. If the TREEHUGGER_DATA environment variable is set, UserData or files will not be read.

N.B. To be sure of the Python you’re using to run Treehugger, you can also run it as a module. For example:

/usr/local/bin/python -m treehugger exec -- /path/to/application


Install and run tox (docs).


Treehugger was created by Niklas Lindblad and is now maintained by Adam Johnson.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

treehugger-3.0.0.tar.gz (16.4 kB view hashes)

Uploaded Source

Built Distribution

treehugger-3.0.0-py3-none-any.whl (14.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page