| Name | ssm-ps-template JSON |
| Version |
2.4.1
JSON |
| download |
| home_page | |
| Summary | CLI for rendering configuration templates with SSM Parameter Store as a data source |
| upload_time | 2023-06-21 18:19:56 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.9 |
| license | Copyright (c) 2023 Gavin M. Roy All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
aws
ssm
parameter store
templating
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# SSM Parameter Store Template
Command line application to render templates with data from SSM Parameter Store
[](https://codecov.io/gh/gmr/ssm-ps-template)
## Installation
The `ssm-ps-template` application is available via the [Python Package Index](https://pypi.org/project/ssm-ps-template/) and can be installed with pip:
```bash
pip install ssm-ps-template
```
## Templating
The application uses [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/) for the templating engine. All functionality available to Jinja2 templates by default are exposed in the application.
### Using Prefixes
The application has a default prefix of `/` that is prepended to parameter names that do not start with a leading slash (`/`).
This functionality allows you to group your variables under a path prefix like `/my-application/settings` and then only refer to the individual key values like `password` instead of referencing the full path of `/my-application/settings/password`.
If you reference a parameter name with a leading slash it will not prepend the prefix to the parameter name.
### Getting Parameter Store Values
The application exposes `get_parameter(name: str, default: typing.Optional[str] = None)` in templates to access the values in SSM Parameter Store.
In the following example we assume there are Parameter Store values for the keys `/my-application/foo` and `/my-application/bar` and that the application is called with a prefix of `/my-appliction`:
```yaml
foo: {{ get_parameter('/my-application/foo') }}
bar: {{ get_parameter('/my-application/bar') }}
```
Will render as:
```yaml
foo: bar
baz: qux
```
Additionally, there is another function exposed `get_parameters_by_path(path: str, default: typing.Optional[dict] = None)` which will return a dictionary for the specified path.
The following example will iterate over the results:
```yaml
{% for key, value in get_parameters_by_path('settings/', {}).items() %}
{{ key }}: {{ value }}
{% endfor %}
```
Or you can use Jinja filters to convert them to YAML:
```yaml
{{ get_parameters_by_path('settings/') | path_to_dict | toyaml | indent(2, first=True) }}
```
For values in ParameterStore that are stored as `StringList`, they are automatically transformed as a list of strings. Given the following value:
| Key | Value |
|-------------------------------|----------------------------------|
| `/my-application/connections` | `amqp://server1, amqp://server2` |
And the following template:
```yaml
Connections:
{% for connection in get_parameter('/my-application/connections', []) %}
- {{ connection }}
```
The following would be rendered:
```yaml
Connections:
- amqp://server1
- amqp://server2
```
### Performance Considerations
The parameter names are gathered in a pre-processing step to minimize calls to SSM Parameter Store.
## Configuration
The configuration file provides the ability to specify multiple templates, override AWS configuration, and change logging levels:
### Top-Level Configuration Directives
| Directive | Description |
|-----------------------|----------------------------------------------------------------------------------------------------------------------------------|
| `templates` | An array of template directives as detailed in the next table. |
| `endpoint_url` | Specify an endpoint URL to use to override the default URL used to contact SSM Parameter Store |
| `profile` | Specify the AWS profile to use. If unspecified will default to the `AWS_DEFAULT_PROFILE` environment variable or is unspecified |
| `region` | Specify the AWS region to use. If unspecified it will default to the `AWS_DEFAULT_REGION` environment variable or is unspecified |
| `replace_underscores` | Replace underscores with dashes when asking for values from SSM Parameter Store |
| `verbose` | Turn debug logging on. Possible values are `true` and `false` |
### Template Configuration Directives
The `templates` directive in the configuration is an array of objects:
| Directive | Description |
|---------------|--------------------------------------------------------------------------------------|
| `source` | The source file of the template |
| `destination` | The destination path to write the rendered template to |
| `prefix` | The prefix to prepend variables with if they do not start with a forward-slash (`/`) |
| `user` | An optional username or uid to set as the owner of the rendered file |
| `group` | An optional group or gid to set as the group of the rendered file |
| `mode` | Optional file mode and permissions set using chmod |
If there are parent directories in the `destination` path that do not exist, they will be created.
### Extended Templating Functionality
In addition to the base functionality exposed by Jinja2, the following Python functions have been added:
| Function | Definition |
|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| `get_parameter` | Get a string value from SSM Parameter Store |
| `get_parameters_by_path` | Get a dictionary value from SSM Parameter Store |
| `urlparse` | The [`urllib.parse.urlparse`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlparse) function from the Python standard library. |
| `parse_qs` | The [`urllib.parse.parse_qs`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.parse_qs) function from the Python standard library. |
| `unquote` | The [`urllib.parse.unquote`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.unquote) function from the Python standard library. |
The following filters are added:
| Filter | Description |
|-------------------------|--------------------------------------------------------------------------------------------------------------|
| `dashes_to_underscores` | Recursively replaces dashes with underscores in keys in data structures returned by `get_parameters_by_path` |
| `fromjson` | Convert a JSON blob to a data structure |
| `fromyaml` | Convert a YAML blob to a data structure |
| `path_to_dict` | Converts a dict with forward-slash delimited keys (`/`) to a nested dict using the `/` as the key delimiter |
| `toyaml` | Converts a dictionary value to YAML |
The following variables are exposed:
| Variable | Definition |
|-----------|-------------------------------------------------------------------------------------------------------------------------|
| `environ` | The [`os.environ`](https://docs.python.org/3/library/os.html#os.environ) dictionary for accessing environment variables |
### Configuration File Format
The application supports JSON, TOML, or YAML for configuration. The following example is in YAML:
### Example Configuration File
```yaml
templates:
- source: /etc/ssm-templates/nginx-example
destination: /etc/nginx/sites-available/example
prefix: /namespaced/application/nginx/
- source: /etc/ssm-templates/postgres-example
destination: /etc/postgresql/14/main/postgresql.conf
prefix: /namespaced/application/postgres/
user: postgres
group: postgres
mode: 0600
profile: default
region: us-east-1
verbose: false
```
## Command Line Usage
```sh
usage: ssm-ps-template [-h] [--aws-profile AWS_PROFILE] [--aws-region AWS_REGION] [--endpoint-url ENDPOINT_URL] [--prefix PREFIX] [--replace-underscores]
[--verbose] [--version]
config
Command line application to render templates with data from SSM Parameter Store
positional arguments:
config
optional arguments:
-h, --help show this help message and exit
--aws-profile AWS_PROFILE
AWS Profile (default: None)
--aws-region AWS_REGION
AWS Region (default: None)
--endpoint-url ENDPOINT_URL
Specify an endpoint URL to use when contacting SSM Parameter Store. (default: None)
--prefix PREFIX Default SSM Key Prefix (default: /)
--replace-underscores
Replace underscores in variable names to dashes when looking for values in SSM (default: False)
--verbose
--version show program's version number and exit
```
Note that the default SSM prefix can also be set with the `PARAMS_PREFIX` environment variable and
the endpoint URL setting cn be set with the `SSM_ENDPOINT_URL` environment variable.
Raw data
{
"_id": null,
"home_page": "",
"name": "ssm-ps-template",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "aws,ssm,parameter store,templating",
"author": "",
"author_email": "\"Gavin M. Roy\" <gavinmroy@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0d/c3/1355961b74492fa8061553c9f69ca864f85213ee64c6049a0a8b231899dd/ssm-ps-template-2.4.1.tar.gz",
"platform": null,
"description": "# SSM Parameter Store Template\n\nCommand line application to render templates with data from SSM Parameter Store\n\n[](https://codecov.io/gh/gmr/ssm-ps-template)\n\n## Installation\n\nThe `ssm-ps-template` application is available via the [Python Package Index](https://pypi.org/project/ssm-ps-template/) and can be installed with pip:\n\n```bash\npip install ssm-ps-template\n```\n\n## Templating\n\nThe application uses [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/) for the templating engine. All functionality available to Jinja2 templates by default are exposed in the application.\n\n### Using Prefixes\n\nThe application has a default prefix of `/` that is prepended to parameter names that do not start with a leading slash (`/`).\n\nThis functionality allows you to group your variables under a path prefix like `/my-application/settings` and then only refer to the individual key values like `password` instead of referencing the full path of `/my-application/settings/password`.\n\nIf you reference a parameter name with a leading slash it will not prepend the prefix to the parameter name.\n\n### Getting Parameter Store Values\n\nThe application exposes `get_parameter(name: str, default: typing.Optional[str] = None)` in templates to access the values in SSM Parameter Store.\n\nIn the following example we assume there are Parameter Store values for the keys `/my-application/foo` and `/my-application/bar` and that the application is called with a prefix of `/my-appliction`:\n\n```yaml\nfoo: {{ get_parameter('/my-application/foo') }}\nbar: {{ get_parameter('/my-application/bar') }}\n```\n\nWill render as:\n\n```yaml\nfoo: bar\nbaz: qux\n```\n\nAdditionally, there is another function exposed `get_parameters_by_path(path: str, default: typing.Optional[dict] = None)` which will return a dictionary for the specified path.\n\nThe following example will iterate over the results:\n\n```yaml\n{% for key, value in get_parameters_by_path('settings/', {}).items() %}\n {{ key }}: {{ value }}\n{% endfor %}\n```\n\nOr you can use Jinja filters to convert them to YAML:\n\n```yaml\n{{ get_parameters_by_path('settings/') | path_to_dict | toyaml | indent(2, first=True) }}\n```\n\nFor values in ParameterStore that are stored as `StringList`, they are automatically transformed as a list of strings. Given the following value:\n\n| Key | Value |\n|-------------------------------|----------------------------------|\n| `/my-application/connections` | `amqp://server1, amqp://server2` |\n\nAnd the following template:\n\n```yaml\nConnections:\n{% for connection in get_parameter('/my-application/connections', []) %}\n - {{ connection }}\n```\n\nThe following would be rendered:\n\n```yaml\nConnections:\n - amqp://server1\n - amqp://server2\n```\n\n### Performance Considerations\n\nThe parameter names are gathered in a pre-processing step to minimize calls to SSM Parameter Store.\n\n## Configuration\n\nThe configuration file provides the ability to specify multiple templates, override AWS configuration, and change logging levels:\n\n### Top-Level Configuration Directives\n\n| Directive | Description |\n|-----------------------|----------------------------------------------------------------------------------------------------------------------------------|\n| `templates` | An array of template directives as detailed in the next table. |\n| `endpoint_url` | Specify an endpoint URL to use to override the default URL used to contact SSM Parameter Store |\n| `profile` | Specify the AWS profile to use. If unspecified will default to the `AWS_DEFAULT_PROFILE` environment variable or is unspecified |\n| `region` | Specify the AWS region to use. If unspecified it will default to the `AWS_DEFAULT_REGION` environment variable or is unspecified |\n| `replace_underscores` | Replace underscores with dashes when asking for values from SSM Parameter Store |\n| `verbose` | Turn debug logging on. Possible values are `true` and `false` |\n\n### Template Configuration Directives\n\nThe `templates` directive in the configuration is an array of objects:\n\n| Directive | Description |\n|---------------|--------------------------------------------------------------------------------------|\n| `source` | The source file of the template |\n| `destination` | The destination path to write the rendered template to |\n| `prefix` | The prefix to prepend variables with if they do not start with a forward-slash (`/`) |\n| `user` | An optional username or uid to set as the owner of the rendered file |\n| `group` | An optional group or gid to set as the group of the rendered file |\n| `mode` | Optional file mode and permissions set using chmod |\n\nIf there are parent directories in the `destination` path that do not exist, they will be created.\n\n### Extended Templating Functionality\n\nIn addition to the base functionality exposed by Jinja2, the following Python functions have been added:\n\n| Function | Definition |\n|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|\n| `get_parameter` | Get a string value from SSM Parameter Store |\n| `get_parameters_by_path` | Get a dictionary value from SSM Parameter Store |\n| `urlparse` | The [`urllib.parse.urlparse`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlparse) function from the Python standard library. |\n| `parse_qs` | The [`urllib.parse.parse_qs`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.parse_qs) function from the Python standard library. |\n| `unquote` | The [`urllib.parse.unquote`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.unquote) function from the Python standard library. |\n\nThe following filters are added:\n\n| Filter | Description |\n|-------------------------|--------------------------------------------------------------------------------------------------------------|\n| `dashes_to_underscores` | Recursively replaces dashes with underscores in keys in data structures returned by `get_parameters_by_path` |\n| `fromjson` | Convert a JSON blob to a data structure |\n| `fromyaml` | Convert a YAML blob to a data structure |\n| `path_to_dict` | Converts a dict with forward-slash delimited keys (`/`) to a nested dict using the `/` as the key delimiter |\n| `toyaml` | Converts a dictionary value to YAML |\n\nThe following variables are exposed:\n\n| Variable | Definition |\n|-----------|-------------------------------------------------------------------------------------------------------------------------|\n| `environ` | The [`os.environ`](https://docs.python.org/3/library/os.html#os.environ) dictionary for accessing environment variables |\n\n### Configuration File Format\n\nThe application supports JSON, TOML, or YAML for configuration. The following example is in YAML:\n\n### Example Configuration File\n\n```yaml\ntemplates:\n - source: /etc/ssm-templates/nginx-example\n destination: /etc/nginx/sites-available/example\n prefix: /namespaced/application/nginx/\n - source: /etc/ssm-templates/postgres-example\n destination: /etc/postgresql/14/main/postgresql.conf\n prefix: /namespaced/application/postgres/\n user: postgres\n group: postgres\n mode: 0600\nprofile: default\nregion: us-east-1\nverbose: false\n```\n\n## Command Line Usage\n\n```sh\nusage: ssm-ps-template [-h] [--aws-profile AWS_PROFILE] [--aws-region AWS_REGION] [--endpoint-url ENDPOINT_URL] [--prefix PREFIX] [--replace-underscores]\n [--verbose] [--version]\n config\n\nCommand line application to render templates with data from SSM Parameter Store\n\npositional arguments:\n config\n\noptional arguments:\n -h, --help show this help message and exit\n --aws-profile AWS_PROFILE\n AWS Profile (default: None)\n --aws-region AWS_REGION\n AWS Region (default: None)\n --endpoint-url ENDPOINT_URL\n Specify an endpoint URL to use when contacting SSM Parameter Store. (default: None)\n --prefix PREFIX Default SSM Key Prefix (default: /)\n --replace-underscores\n Replace underscores in variable names to dashes when looking for values in SSM (default: False)\n --verbose\n --version show program's version number and exit\n```\n\nNote that the default SSM prefix can also be set with the `PARAMS_PREFIX` environment variable and\nthe endpoint URL setting cn be set with the `SSM_ENDPOINT_URL` environment variable.\n",
"bugtrack_url": null,
"license": "Copyright (c) 2023 Gavin M. Roy All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ",
"summary": "CLI for rendering configuration templates with SSM Parameter Store as a data source",
"version": "2.4.1",
"project_urls": {
"Bug Tracker": "https://github.com/gmr/ssm-ps-template/issues",
"Homepage": "https://github.com/gmr/ssm-ps-template"
},
"split_keywords": [
"aws",
"ssm",
"parameter store",
"templating"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "215baf0884fe28061e4ca674ae1e0cf6548122bba288f215399d7ad20b6bcb1a",
"md5": "e4886261b72cffd4ca6dc76ceab603a2",
"sha256": "884b0cc076ab1092163259852f3f703f5b3c67d1476af3137f531a2d527cbc07"
},
"downloads": -1,
"filename": "ssm_ps_template-2.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e4886261b72cffd4ca6dc76ceab603a2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 12555,
"upload_time": "2023-06-21T18:19:54",
"upload_time_iso_8601": "2023-06-21T18:19:54.795130Z",
"url": "https://files.pythonhosted.org/packages/21/5b/af0884fe28061e4ca674ae1e0cf6548122bba288f215399d7ad20b6bcb1a/ssm_ps_template-2.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0dc31355961b74492fa8061553c9f69ca864f85213ee64c6049a0a8b231899dd",
"md5": "8e7e61774ac923fe004afa0352bee0d3",
"sha256": "2b2d08753888bf407cf5c80fd99e3cab944490d86e72bd6c956def213c39a80b"
},
"downloads": -1,
"filename": "ssm-ps-template-2.4.1.tar.gz",
"has_sig": false,
"md5_digest": "8e7e61774ac923fe004afa0352bee0d3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 16362,
"upload_time": "2023-06-21T18:19:56",
"upload_time_iso_8601": "2023-06-21T18:19:56.163461Z",
"url": "https://files.pythonhosted.org/packages/0d/c3/1355961b74492fa8061553c9f69ca864f85213ee64c6049a0a8b231899dd/ssm-ps-template-2.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-21 18:19:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gmr",
"github_project": "ssm-ps-template",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ssm-ps-template"
}
