<img align="right" src="https://raw.github.com/cliffano/awstaga/main/avatar.jpg" alt="Avatar"/>
[](https://github.com/cliffano/awstaga/actions?query=workflow%3ACI)
[](https://snyk.io/test/github/cliffano/awstaga)
[](https://libraries.io/github/cliffano/awstaga)
[](https://pypi.python.org/pypi/awstaga)
<br/>
Awstaga
-------
Awstaga is a Python CLI for tagging AWS resources defined in a YAML configuration.
This package is intended as a companion for [AWS Tag Editor](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging-resources.html). While AWS Tag Editor is useful for tagging multiple resources in one go, it has no easy way to re-run the tagging since you have to use the AWS console UI, and its resource filtering capability is quite limited, making it hard to select resources with-more-than basic logic.
Using Awstaga, you can easily re-run the tagging by running the CLI again. And with its support of YAML configuration, it allows you to define multiple tagsets which you can reuse and mix and match with the resources, you can construct your own mapping between the resources and the relevant tags and tagsets. You can generate your own YAML configuration using Python scripts, or any other programming language, allowing you to construct a more complex filtering logic.
Installation
------------
pip3 install awstaga
Usage
-----
Create a configuration file, e.g. `awstaga.yaml`:
---
tagsets:
- name: common
tags:
- key: CostCentre
value: FIN-123
- key: Organisation
value: World Enterprise
- key: Description
value: AWS Resource
- name: prod
tags:
- key: EnvType
value: prod
- key: Availability
value: 24x7
- name: nonprod
tags:
- key: EnvType
value: non-prod
- key: Availability
value: on-demand
resources:
- arn: 'arn:aws:ssm:ap-southeast-2:123456789012:document/high-avail'
tags:
- key: Description
value: High availability SSM document
tagsetnames:
- common
- prod
- arn: 'arn:aws:s3:::world-enterprise/development/logo.jpg'
tags:
- key: Description
value: World Enterprise logo
tagsetnames:
- common
- nonprod
And then run `awstaga` CLI and pass the configuration file path:
awstaga --conf-file awstaga.yaml
It will write the log messages to stdout:
[awstaga] INFO Loading configuration file awstaga.yaml
[awstaga] INFO Loading 3 tagset(s)...
[awstaga] INFO Loading 2 resource(s)...
[awstaga] INFO Adding resource arn:aws:ssm:ap-southeast-2:123456789012:document/high-avail to a batch with tags {'CostCentre': 'FIN-123', 'Organisation': 'World Enterprise', 'Description': 'AWS Resource', 'EnvType': 'prod', 'Availability': '24x7', 'Description': 'High availability SSM document'}
[awstaga] INFO Adding resource arn:aws:s3:::world-enterprise/development/logo.jpg to a batch with tags {'CostCentre': 'FIN-123', 'Organisation': 'World Enterprise', 'Description': 'AWS Resource', 'EnvType': 'prod', 'Availability': '24x7', 'Description': 'World Enterprise logo'}
And if the tagging failed (e.g. due to rate exceeded), it will log the following error messages:
[awstaga] ERROR Failed to apply tags to 1 resource(s):
[awstaga] ERROR arn:aws:ssm:ap-southeast-2:123456789012:document/high-avail: 400 - Throttling - Rate exceeded
[awstaga] ERROR arn:aws:s3:::world-enterprise/development/logo.jpg: 400 - Throttling - Rate exceeded
### YAML includes
Awstaga supports YAML includes using , so you can split your configuration into multiple files:
---
tagsets:
- !include include.d/tagset.yaml
resources: !include include.d/resources.yaml
Include files should be put under `include.d/`` folder relative to the configuration file.
The included tagset file `include.d/tagset.yaml`:
---
name: common
tags:
- key: CostCentre
value: FIN-123
- key: Organisation
value: World Enterprise
- key: Description
value: AWS Resource
The included resources file `include.d/resources.yaml`:
---
- arn: 'arn:aws:ssm:ap-southeast-2:123456789012:document/high-avail'
tags:
- key: Description
value: High availability SSM document
tagsetnames:
- common
- prod
- arn: 'arn:aws:s3:::world-enterprise/development/logo.jpg'
tags:
- key: Description
value: World Enterprise logo
tagsetnames:
- common
- nonprod
### Dry run
You can also run Awstaga in dry-run mode by adding `--dry-run` flag:
awstaga --conf-file awstaga.yaml --dry-run
During dry-run mode, Awstaga log messages will be labeled with `[dry-run]`:
[dry-run] [awstaga] INFO Loading configuration file awstaga.yaml
[dry-run] [awstaga] INFO Loading 3 tagset(s)...
[dry-run] [awstaga] INFO Loading 2 resource(s)...
[dry-run] [awstaga] INFO Adding resource arn:aws:ssm:ap-southeast-2:123456789012:document/high-avail to a batch with tags {'CostCentre': 'FIN-123', 'Organisation': 'World Enterprise', 'Description': 'AWS Resource', 'EnvType': 'prod', 'Availability': '24x7', 'Description': 'High availability SSM document'}
### Batch size
In order to optimise the number of API calls, resources with identical tags are put into batches. By default, the batch size is 5.
You can run Awstaga with a custom batch size `--batch-size <number>` flag:
awstaga --conf-file awstaga.yaml --batch-size 10
### Delay
In order to avoid rate exceeded error, you can run Awstaga with a custom delay `--delay <number>` flag:
awstaga --conf-file awstaga.yaml --delay 5
By default, the delay is 2 seconds. The delay is applied between each batch of tagging API calls.
Please note that AWS limits the number of tagging API (`tag_resources`) calls to [maximum of 5 calls per second](https://docs.aws.amazon.com/general/latest/gr/arg.html).
Configuration
-------------
These are the configuration properties that you can use with `awstaga` CLI.
Some example configuration files are available on [examples](examples) folder.
| Property | Type | Description | Example |
|----------|------|-------------|---------|
| `tagsets[]` | Array | A list of one or more tagsets. Any tagset can be associated with any resource, and the resource will include the tags specified in the tagset. | |
| `tagsets[].name` | String | The name of the tagset. | `common` |
| `tagsets[].tags[]` | Array | A list of one or more key-value pair tags within the tagset. | |
| `tagsets[].tags[].key` | String | The tag key. | `CostCentre` |
| `tagsets[].tags[].value` | String | The tag value. | `FIN-123` |
| `resources[]` | Array | A list of one or more AWS resources. Each of the resource has a corresponding list of tags, along with the tags from tagsets. | |
| `resources[].arn` | String | AWS resource [ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html). | `arn:aws:s3:::world-enterprise/development/logo.jpg` |
| `resources[].tags[]` | Array | A list of one or more key-value pair tags of the resource. | |
| `resources[].tags[].key` | String | The tag key. | `Description` |
| `resources[].tags[].value` | String | The tag value. | `Some description` |
| `resources[].tagsetnames[]` | Array | A list of one or more tagset names. All tags within the tagsets specified are included in the resource. | |
Permissions
-----------
The AWS credentials used to run `awstaga` CLI must have [the following permissions](https://docs.aws.amazon.com/ARG/latest/userguide/gettingstarted-prereqs.html):
* Permission to use AWS Resource Groups API
* Permission to tag resources for individual AWS services that you want to tag
Colophon
--------
[Developer's Guide](https://cliffano.github.io/developers_guide.html#python)
Build reports:
* [Lint report](https://cliffano.github.io/awstaga/lint/pylint/index.html)
* [Code complexity report](https://cliffano.github.io/awstaga/complexity/wily/index.html)
* [Unit tests report](https://cliffano.github.io/awstaga/test/pytest/index.html)
* [Test coverage report](https://cliffano.github.io/awstaga/coverage/coverage/index.html)
* [Integration tests report](https://cliffano.github.io/awstaga/test-integration/pytest/index.html)
* [API Documentation](https://cliffano.github.io/awstaga/doc/sphinx/index.html)
Raw data
{
"_id": null,
"home_page": "https://github.com/cliffano/awstaga",
"name": "awstaga",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "awstaga, aws, tag, tagging",
"author": "Cliffano Subagio",
"author_email": "cliffano@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/06/42/f603d2466b0510f1b3dca59e0e9a1ddb420e98f55282510cbc8a48b102aa/awstaga-1.3.0.tar.gz",
"platform": null,
"description": "<img align=\"right\" src=\"https://raw.github.com/cliffano/awstaga/main/avatar.jpg\" alt=\"Avatar\"/>\n\n[](https://github.com/cliffano/awstaga/actions?query=workflow%3ACI)\n[](https://snyk.io/test/github/cliffano/awstaga)\n[](https://libraries.io/github/cliffano/awstaga)\n[](https://pypi.python.org/pypi/awstaga)\n<br/>\n\nAwstaga\n-------\n\nAwstaga is a Python CLI for tagging AWS resources defined in a YAML configuration.\n\nThis package is intended as a companion for [AWS Tag Editor](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging-resources.html). While AWS Tag Editor is useful for tagging multiple resources in one go, it has no easy way to re-run the tagging since you have to use the AWS console UI, and its resource filtering capability is quite limited, making it hard to select resources with-more-than basic logic.\n\nUsing Awstaga, you can easily re-run the tagging by running the CLI again. And with its support of YAML configuration, it allows you to define multiple tagsets which you can reuse and mix and match with the resources, you can construct your own mapping between the resources and the relevant tags and tagsets. You can generate your own YAML configuration using Python scripts, or any other programming language, allowing you to construct a more complex filtering logic.\n\nInstallation\n------------\n\n pip3 install awstaga\n\nUsage\n-----\n\nCreate a configuration file, e.g. `awstaga.yaml`:\n\n ---\n tagsets:\n - name: common\n tags:\n - key: CostCentre\n value: FIN-123\n - key: Organisation\n value: World Enterprise\n - key: Description\n value: AWS Resource\n - name: prod\n tags:\n - key: EnvType\n value: prod\n - key: Availability\n value: 24x7\n - name: nonprod\n tags:\n - key: EnvType\n value: non-prod\n - key: Availability\n value: on-demand\n resources:\n - arn: 'arn:aws:ssm:ap-southeast-2:123456789012:document/high-avail'\n tags:\n - key: Description\n value: High availability SSM document\n tagsetnames:\n - common\n - prod\n - arn: 'arn:aws:s3:::world-enterprise/development/logo.jpg'\n tags:\n - key: Description\n value: World Enterprise logo\n tagsetnames:\n - common\n - nonprod\n\nAnd then run `awstaga` CLI and pass the configuration file path:\n\n awstaga --conf-file awstaga.yaml\n\nIt will write the log messages to stdout:\n\n [awstaga] INFO Loading configuration file awstaga.yaml\n [awstaga] INFO Loading 3 tagset(s)...\n [awstaga] INFO Loading 2 resource(s)...\n [awstaga] INFO Adding resource arn:aws:ssm:ap-southeast-2:123456789012:document/high-avail to a batch with tags {'CostCentre': 'FIN-123', 'Organisation': 'World Enterprise', 'Description': 'AWS Resource', 'EnvType': 'prod', 'Availability': '24x7', 'Description': 'High availability SSM document'}\n [awstaga] INFO Adding resource arn:aws:s3:::world-enterprise/development/logo.jpg to a batch with tags {'CostCentre': 'FIN-123', 'Organisation': 'World Enterprise', 'Description': 'AWS Resource', 'EnvType': 'prod', 'Availability': '24x7', 'Description': 'World Enterprise logo'}\n\nAnd if the tagging failed (e.g. due to rate exceeded), it will log the following error messages:\n\n [awstaga] ERROR Failed to apply tags to 1 resource(s):\n [awstaga] ERROR arn:aws:ssm:ap-southeast-2:123456789012:document/high-avail: 400 - Throttling - Rate exceeded\n [awstaga] ERROR arn:aws:s3:::world-enterprise/development/logo.jpg: 400 - Throttling - Rate exceeded\n\n### YAML includes\n\nAwstaga supports YAML includes using , so you can split your configuration into multiple files:\n\n ---\n tagsets:\n - !include include.d/tagset.yaml\n resources: !include include.d/resources.yaml\n\nInclude files should be put under `include.d/`` folder relative to the configuration file.\n\nThe included tagset file `include.d/tagset.yaml`:\n\n ---\n name: common\n tags:\n - key: CostCentre\n value: FIN-123\n - key: Organisation\n value: World Enterprise\n - key: Description\n value: AWS Resource\n\nThe included resources file `include.d/resources.yaml`:\n\n ---\n - arn: 'arn:aws:ssm:ap-southeast-2:123456789012:document/high-avail'\n tags:\n - key: Description\n value: High availability SSM document\n tagsetnames:\n - common\n - prod\n - arn: 'arn:aws:s3:::world-enterprise/development/logo.jpg'\n tags:\n - key: Description\n value: World Enterprise logo\n tagsetnames:\n - common\n - nonprod\n\n### Dry run\n\nYou can also run Awstaga in dry-run mode by adding `--dry-run` flag:\n\n awstaga --conf-file awstaga.yaml --dry-run\n\nDuring dry-run mode, Awstaga log messages will be labeled with `[dry-run]`:\n\n [dry-run] [awstaga] INFO Loading configuration file awstaga.yaml\n [dry-run] [awstaga] INFO Loading 3 tagset(s)...\n [dry-run] [awstaga] INFO Loading 2 resource(s)...\n [dry-run] [awstaga] INFO Adding resource arn:aws:ssm:ap-southeast-2:123456789012:document/high-avail to a batch with tags {'CostCentre': 'FIN-123', 'Organisation': 'World Enterprise', 'Description': 'AWS Resource', 'EnvType': 'prod', 'Availability': '24x7', 'Description': 'High availability SSM document'}\n\n### Batch size\n\nIn order to optimise the number of API calls, resources with identical tags are put into batches. By default, the batch size is 5.\nYou can run Awstaga with a custom batch size `--batch-size <number>` flag:\n\n awstaga --conf-file awstaga.yaml --batch-size 10\n\n### Delay\n\nIn order to avoid rate exceeded error, you can run Awstaga with a custom delay `--delay <number>` flag:\n\n awstaga --conf-file awstaga.yaml --delay 5\n\nBy default, the delay is 2 seconds. The delay is applied between each batch of tagging API calls.\n\nPlease note that AWS limits the number of tagging API (`tag_resources`) calls to [maximum of 5 calls per second](https://docs.aws.amazon.com/general/latest/gr/arg.html).\n\nConfiguration\n-------------\n\nThese are the configuration properties that you can use with `awstaga` CLI.\nSome example configuration files are available on [examples](examples) folder.\n\n| Property | Type | Description | Example |\n|----------|------|-------------|---------|\n| `tagsets[]` | Array | A list of one or more tagsets. Any tagset can be associated with any resource, and the resource will include the tags specified in the tagset. | |\n| `tagsets[].name` | String | The name of the tagset. | `common` |\n| `tagsets[].tags[]` | Array | A list of one or more key-value pair tags within the tagset. | |\n| `tagsets[].tags[].key` | String | The tag key. | `CostCentre` |\n| `tagsets[].tags[].value` | String | The tag value. | `FIN-123` |\n| `resources[]` | Array | A list of one or more AWS resources. Each of the resource has a corresponding list of tags, along with the tags from tagsets. | |\n| `resources[].arn` | String | AWS resource [ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html). | `arn:aws:s3:::world-enterprise/development/logo.jpg` |\n| `resources[].tags[]` | Array | A list of one or more key-value pair tags of the resource. | |\n| `resources[].tags[].key` | String | The tag key. | `Description` |\n| `resources[].tags[].value` | String | The tag value. | `Some description` |\n| `resources[].tagsetnames[]` | Array | A list of one or more tagset names. All tags within the tagsets specified are included in the resource. | |\n\nPermissions\n-----------\n\nThe AWS credentials used to run `awstaga` CLI must have [the following permissions](https://docs.aws.amazon.com/ARG/latest/userguide/gettingstarted-prereqs.html):\n\n* Permission to use AWS Resource Groups API\n* Permission to tag resources for individual AWS services that you want to tag\n\nColophon\n--------\n\n[Developer's Guide](https://cliffano.github.io/developers_guide.html#python)\n\nBuild reports:\n\n* [Lint report](https://cliffano.github.io/awstaga/lint/pylint/index.html)\n* [Code complexity report](https://cliffano.github.io/awstaga/complexity/wily/index.html)\n* [Unit tests report](https://cliffano.github.io/awstaga/test/pytest/index.html)\n* [Test coverage report](https://cliffano.github.io/awstaga/coverage/coverage/index.html)\n* [Integration tests report](https://cliffano.github.io/awstaga/test-integration/pytest/index.html)\n* [API Documentation](https://cliffano.github.io/awstaga/doc/sphinx/index.html)\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python CLI for tagging AWS resources based on a YAML configuration",
"version": "1.3.0",
"project_urls": {
"Documentation": "https://github.com/cliffano/awstaga",
"Homepage": "https://github.com/cliffano/awstaga",
"Repository": "https://github.com/cliffano/awstaga"
},
"split_keywords": [
"awstaga",
" aws",
" tag",
" tagging"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a537974113724a348f5c1b0c92418acf8ae2f4dc463b49f15fda1948087f7f9d",
"md5": "7342718f79d84a7cbe5706b2b8982350",
"sha256": "06d3d70178841566440b5436cf4c1c518366d68f9a681f8d486e6a26bc4664c4"
},
"downloads": -1,
"filename": "awstaga-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7342718f79d84a7cbe5706b2b8982350",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 12295,
"upload_time": "2024-04-27T05:49:44",
"upload_time_iso_8601": "2024-04-27T05:49:44.256946Z",
"url": "https://files.pythonhosted.org/packages/a5/37/974113724a348f5c1b0c92418acf8ae2f4dc463b49f15fda1948087f7f9d/awstaga-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0642f603d2466b0510f1b3dca59e0e9a1ddb420e98f55282510cbc8a48b102aa",
"md5": "0eeaaeec84cf068abdfda69e1c54b322",
"sha256": "67bfc33ab0a51cd6351ba6175e32025785f9236a4064ea8c4b07adad0327c9b3"
},
"downloads": -1,
"filename": "awstaga-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "0eeaaeec84cf068abdfda69e1c54b322",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 12433,
"upload_time": "2024-04-27T05:49:45",
"upload_time_iso_8601": "2024-04-27T05:49:45.821673Z",
"url": "https://files.pythonhosted.org/packages/06/42/f603d2466b0510f1b3dca59e0e9a1ddb420e98f55282510cbc8a48b102aa/awstaga-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-27 05:49:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cliffano",
"github_project": "awstaga",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "awstaga"
}
JSON
