From ddf01205c2778ca51925dfc2cad97ae15f7c377e Mon Sep 17 00:00:00 2001 From: akash1810 Date: Thu, 6 Aug 2026 13:24:34 +0100 Subject: [PATCH 1/2] docs: Provide worked examples for the AWS tag schema --- AWS.md | 9 +-------- aws-tags.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+), 8 deletions(-) create mode 100644 aws-tags.md diff --git a/AWS.md b/AWS.md index cf25a82..60ff172 100644 --- a/AWS.md +++ b/AWS.md @@ -3,14 +3,7 @@ * Provision and manage all AWS resources using infrastructure as code * Prefer to use [CDK](https://github.com/guardian/cdk) to generate CloudFormation. You might find that older projects still use CloudFormation directly; these should be migrated to CDK where possible. * Prefer to [import resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import.html) into CFN over manually configuring them - * Tag resources with: - * `Stack` - the broad umbrella the service sits under e.g. `media-service`. Useful to denote ownership within a shared AWS account. - * `Stage` - the environment, typical values are: - * `PROD` for production - * `CODE` for pre-production - * `INFRA` for infrastructure or singleton resources e.g. [elasticsearch-node-rotation](https://github.com/guardian/elasticsearch-node-rotation) - * `App` - the individual service e.g. `image-loader` - * `gu:repo` - the GitHub repository where the resource's definition can be found + * Resources should be tagged. See [aws-tags.md](./aws-tags.md) for more information. * If a resource needs to be shared across multiple environments, prefer to define it in it's own CFN template as the same resource cannot be defined in multiple templates * Prefer continuous delivery of infrastructure via Riff-Raff over manual deployment * This provides a better audit trail diff --git a/aws-tags.md b/aws-tags.md new file mode 100644 index 0000000..13be640 --- /dev/null +++ b/aws-tags.md @@ -0,0 +1,56 @@ +# AWS Tags + +Most resources in AWS can be [tagged](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/what-are-tags.html). +This document outlines tags used at the Guardian. In short, resources should have the following tags: +- `App` +- `Stack` +- `Stage` +- `gu:repo` + +You can apply your own tags as well. + +## Core tags +The following tags should be applied to all taggable resources. + +### `App` +This tag identifies an individual application. + +For example, `user-api` could be a web service for managing a user's preferences, or `user-cleanup` could be a lambda that runs periodically to remove inactive users. + +### `Stack` +This tag identifies a group of related applications. + +For example, the aforementioned `user-api` and `user-cleanup` would be part of a `user-management` stack. + +Tools that operate across accounts use `Stack` in the following ways: +- [Riff-Raff](https://github.com/guardian/riff-raff) uses `Stack` to derive an individual AWS account. Therefore, we can consider `Stack` as being unique to a single AWS account +- [Anghammarad](https://github.com/guardian/anghammarad) can use `Stack` to route messages to a team for the entire group of applications, which can be easier than adding a mapping for every application individually. + +Tools which operate across account, for example Riff-Raff, use the stack to derive an individual AWS account. +Therefore, we could consider a stack as being unique to a single AWS account. + +> [!NOTE] +> "Stack" is an overloaded term. For example, in some contexts it can mean a CloudFormation stack. +> Indeed, a CloudFormation stack should have a `Stack` tag! + +### `Stage` +This tag identifies the environment. Typical values are: +- `PROD` for production +- `CODE` for pre-production +- `INFRA` for account-wide infrastructure or singleton resources e.g. [elasticsearch-node-rotation](https://github.com/guardian/elasticsearch-node-rotation) + +> [!IMPORTANT] +> The combination of `App`, `Stack`, `Stage` should **uniquely identify** a service. +> For example, there will be one lambda tagged `App=user-cleanup`, `Stack=user-management`, `Stage=PROD` in the entire estate. + +### `gu:repo` +*This tag is automatically set by tooling such as [GuCDK](https://github.com/guardian/cdk) or [Riff-Raff](https://github.com/guardian/riff-raff).* + +This tag identifies the GitHub repository where the resource's infrastructure as code definition can be found. It takes the form `guardian/`. + +## Other common tags +There are some additional tags to consider based on the circumstance. + +### `Owner` +When provisioning a resource in another team's account, the `Owner` tags helps that team know who to contact if needed. +It should be the team name, for example `DevX`. From 8056940fffa5ac76792e3ea2584b319e9904e202 Mon Sep 17 00:00:00 2001 From: akash1810 Date: Tue, 1 Sep 2026 09:52:17 +0100 Subject: [PATCH 2/2] docs: Add a note about CFN behaviour --- aws-tags.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/aws-tags.md b/aws-tags.md index 13be640..50c726c 100644 --- a/aws-tags.md +++ b/aws-tags.md @@ -1,5 +1,9 @@ # AWS Tags +> [!NOTE] +> Resources provisioned using [GuCDK](https://github.com/guardian/cdk) automatically fulfil these requirements. +> When using a YAML/JSON CloudFormation template, resources that are not explicitly tagged will inherit tags from the parent CloudFormation stack. + Most resources in AWS can be [tagged](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/what-are-tags.html). This document outlines tags used at the Guardian. In short, resources should have the following tags: - `App`