From 77ea973671b56af56f1b313a6cb5aa7deba8edb8 Mon Sep 17 00:00:00 2001 From: Ryan Brooks Date: Mon, 13 Jan 2025 17:10:20 +0000 Subject: [PATCH 01/11] =?UTF-8?q?=E2=9C=8D=EF=B8=8F=20Initial=20draft=20of?= =?UTF-8?q?=20tagging=20standards?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is a work in progress initial draft of the tagging standards for AWS, based on https://github.com/LBHackney-IT/aws-tags-lbh and https://docs.google.com/document/d/1iWsgVYWXAbZQZDYP4PJ-Gv74rFRQUSdDC_XHHSiliXk/edit?pli=1&tab=t.0. --- docs/technical-standards/Readme.md | 3 ++ .../Reference/_category_.json | 4 ++ .../Reference/hosting-standards/Readme.md | 6 +++ .../Reference/hosting-standards/tagging.md | 46 +++++++++++++++++++ docusaurus.config.js | 6 +++ sidebars.js | 1 + 6 files changed, 66 insertions(+) create mode 100644 docs/technical-standards/Readme.md create mode 100644 docs/technical-standards/Reference/_category_.json create mode 100644 docs/technical-standards/Reference/hosting-standards/Readme.md create mode 100644 docs/technical-standards/Reference/hosting-standards/tagging.md diff --git a/docs/technical-standards/Readme.md b/docs/technical-standards/Readme.md new file mode 100644 index 0000000..70f830f --- /dev/null +++ b/docs/technical-standards/Readme.md @@ -0,0 +1,3 @@ +# Technical standards + +These technical standards are the baseline operating requirements for systems and services in Hackney. diff --git a/docs/technical-standards/Reference/_category_.json b/docs/technical-standards/Reference/_category_.json new file mode 100644 index 0000000..d997d2a --- /dev/null +++ b/docs/technical-standards/Reference/_category_.json @@ -0,0 +1,4 @@ +{ + "collapsible": false, + "collapsed": false, +} diff --git a/docs/technical-standards/Reference/hosting-standards/Readme.md b/docs/technical-standards/Reference/hosting-standards/Readme.md new file mode 100644 index 0000000..ab91917 --- /dev/null +++ b/docs/technical-standards/Reference/hosting-standards/Readme.md @@ -0,0 +1,6 @@ +--- +sidebar_position: 1 +--- +# Hosting standards + +Hosting standards apply to everything we host at Hackney, whether it's built in-house, developed externally, or an off-the-shelf product. If we're hosting it in one of our cloud platforms, e.g. AWS, these standards apply diff --git a/docs/technical-standards/Reference/hosting-standards/tagging.md b/docs/technical-standards/Reference/hosting-standards/tagging.md new file mode 100644 index 0000000..d91fe73 --- /dev/null +++ b/docs/technical-standards/Reference/hosting-standards/tagging.md @@ -0,0 +1,46 @@ +# Tagging + +We will tag all AWS objects, so we know they have a purpose and have a defined owner to manage cost, maintenance and support. + +## What must be in place + +1. All objects in our cloud hosting providers (primarily AWS) must be tagged in line with the requirements set out below. + +## Monitoring + +The user creating the object will be notified when an object is untagged with increasing urgency. + +## Resolution/Escalation if the baseline isn't met + +1. Creation of untagged objects will be prevented by technical controls where possible. +2. Newly created untagged objects will be forcefully and automatically shutdown/disabled if they remain untagged for 7 calendar days. +3. Existing untagged objects will not be editable until the mandatory tags have been added. + +## Tags to use + +To ensure we can consistently search for, and report on, the tags we use, you should use the following tags. In all cases, only use acronyms if you’re confident that someone from another part of the council would understand them. If in doubt, avoid acronyms and use the full term. + +### Mandatory tags + +- `Application`: The full name of the application or service. This should match the name used in the Service Catalogue, e.g. `Repairs Hub`, `Common Fate`. +- `Team`: In the form `: `. This is the team responsible for the operation of the service. +- `Environment`: The name of the environment, must be one of `dev`, `stg`, `prod` or `mgmt`[^environment-tags-source]. + +### Optional tags + +- `AutomationBuildUrl`: URL of the automation build, must be a valid URL. +- `AutomationTool`: The tool used for Infrastructure as Code, e.g. `Terraform` or `Serverless Framework`. +- `Confidentiality`: Data confidentiality of the infrastructure. Only applicable to infrastructure which holds data, e.g. EC2, RDS, EBS, DynamoDB, Glue, and S3. Must be one of `Internal`, `Restricted`, or `Public`[^confidentiality-tags-source]. +- `OOOShutdown`: Whether to shut an EC2 instance down out of hours. Must be `true` or `false`. + +### FIXME(remove) Tags we're no longer using + +- Department (maybe useful, it's a fixed list) +- BackupPolicy (should be inferred from environment, as they seem to match) +- Phase +- Stack +- Patch Group +- Project + +[^confidentiality-tags-source]: https://github.com/LBHackney-IT/aws-tags-lbh/blob/main/variables.tf#L83 +[^environment-tags-source]: https://github.com/LBHackney-IT/aws-tags-lbh/blob/main/variables.tf#L150 diff --git a/docusaurus.config.js b/docusaurus.config.js index 5bf3ce0..2830810 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -86,6 +86,12 @@ const config = { position: 'left', label: 'Ways of working', }, + { + type: 'docSidebar', + sidebarId: 'technicalStandards', + position: 'left', + label: 'Technical standards', + }, { type: 'docSidebar', sidebarId: 'architecturePillars', diff --git a/sidebars.js b/sidebars.js index bf6b0e1..5fb6972 100644 --- a/sidebars.js +++ b/sidebars.js @@ -19,6 +19,7 @@ const sidebars = { frontendDevelopment: [{type: 'autogenerated', dirName: 'frontend-development'}], apiSpecifications: [{type: 'autogenerated', dirName: 'api-specifications'}], productPlaybook: [{type: 'autogenerated', dirName: 'Product-Playbook'}], + technicalStandards: [{type: 'autogenerated', dirName: 'technical-standards'}], }; export default sidebars; From a39b180f08105e8b71c43383edb01c112347f433 Mon Sep 17 00:00:00 2001 From: Ryan Brooks Date: Tue, 14 Jan 2025 11:04:53 +0000 Subject: [PATCH 02/11] updated following discussions with Stuart & Anna in Cloud Engineering --- .../Reference/hosting-standards/tagging.md | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/technical-standards/Reference/hosting-standards/tagging.md b/docs/technical-standards/Reference/hosting-standards/tagging.md index d91fe73..66c9a77 100644 --- a/docs/technical-standards/Reference/hosting-standards/tagging.md +++ b/docs/technical-standards/Reference/hosting-standards/tagging.md @@ -23,24 +23,28 @@ To ensure we can consistently search for, and report on, the tags we use, you sh ### Mandatory tags - `Application`: The full name of the application or service. This should match the name used in the Service Catalogue, e.g. `Repairs Hub`, `Common Fate`. -- `Team`: In the form `: `. This is the team responsible for the operation of the service. +- `TeamEmail`: The email address of the team responsible for the operation of the service. Must be a valid email group, not an individual. - `Environment`: The name of the environment, must be one of `dev`, `stg`, `prod` or `mgmt`[^environment-tags-source]. ### Optional tags - `AutomationBuildUrl`: URL of the automation build, must be a valid URL. -- `AutomationTool`: The tool used for Infrastructure as Code, e.g. `Terraform` or `Serverless Framework`. +- `BackupPolicy`: The backup policy to apply to the resource. If present must be one of `Dev`, `Stg`, `Preprod`, `Prod`, `Mgmt`. - `Confidentiality`: Data confidentiality of the infrastructure. Only applicable to infrastructure which holds data, e.g. EC2, RDS, EBS, DynamoDB, Glue, and S3. Must be one of `Internal`, `Restricted`, or `Public`[^confidentiality-tags-source]. -- `OOOShutdown`: Whether to shut an EC2 instance down out of hours. Must be `true` or `false`. +weekend_shutdown +ooh_shutdown + ### FIXME(remove) Tags we're no longer using -- Department (maybe useful, it's a fixed list) -- BackupPolicy (should be inferred from environment, as they seem to match) -- Phase -- Stack -- Patch Group -- Project +- `AutomationTool`: The tool used for Infrastructure as Code, e.g. `Terraform` or `Serverless Framework`. +- `Department` (maybe useful, it's a fixed list) +- `Phase` +- `Stack` +- `Patch Group` +- `Project` +- `OOOShutdown` (has been superceded) +- `Team` (replaced by TeamEmail) [^confidentiality-tags-source]: https://github.com/LBHackney-IT/aws-tags-lbh/blob/main/variables.tf#L83 [^environment-tags-source]: https://github.com/LBHackney-IT/aws-tags-lbh/blob/main/variables.tf#L150 From 7f268839cc8a4f28fdf0f50c0c6d55f3b5996d5a Mon Sep 17 00:00:00 2001 From: Ryan Brooks Date: Tue, 14 Jan 2025 11:22:35 +0000 Subject: [PATCH 03/11] Refactor to give precedence to the mandatory tags --- .../Reference/hosting-standards/tagging.md | 23 ++++++++----------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/docs/technical-standards/Reference/hosting-standards/tagging.md b/docs/technical-standards/Reference/hosting-standards/tagging.md index 66c9a77..b6292ae 100644 --- a/docs/technical-standards/Reference/hosting-standards/tagging.md +++ b/docs/technical-standards/Reference/hosting-standards/tagging.md @@ -4,19 +4,7 @@ We will tag all AWS objects, so we know they have a purpose and have a defined o ## What must be in place -1. All objects in our cloud hosting providers (primarily AWS) must be tagged in line with the requirements set out below. - -## Monitoring - -The user creating the object will be notified when an object is untagged with increasing urgency. - -## Resolution/Escalation if the baseline isn't met - -1. Creation of untagged objects will be prevented by technical controls where possible. -2. Newly created untagged objects will be forcefully and automatically shutdown/disabled if they remain untagged for 7 calendar days. -3. Existing untagged objects will not be editable until the mandatory tags have been added. - -## Tags to use +1. All objects in our cloud hosting providers (primarily AWS) *must* be tagged in line with the requirements set out below. To ensure we can consistently search for, and report on, the tags we use, you should use the following tags. In all cases, only use acronyms if you’re confident that someone from another part of the council would understand them. If in doubt, avoid acronyms and use the full term. @@ -34,6 +22,15 @@ To ensure we can consistently search for, and report on, the tags we use, you sh weekend_shutdown ooh_shutdown +## Monitoring + +The user creating the object will be notified when an object is untagged with increasing urgency. + +## Resolution/Escalation if the baseline isn't met + +1. Creation of untagged objects will be prevented by technical controls where possible. +2. Newly created untagged objects will be forcefully and automatically shutdown/disabled if they remain untagged for 7 calendar days. +3. Existing untagged objects will not be editable until the mandatory tags have been added. ### FIXME(remove) Tags we're no longer using From 6d5f39083acf73f94da1b786cfeb766cb04ed15f Mon Sep 17 00:00:00 2001 From: Ryan Brooks Date: Wed, 15 Jan 2025 11:18:06 +0000 Subject: [PATCH 04/11] Pin Tech Standards home to top of section nav Because it's the landing page for this section of the documentation --- docs/technical-standards/Readme.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/technical-standards/Readme.md b/docs/technical-standards/Readme.md index 70f830f..af48cdf 100644 --- a/docs/technical-standards/Readme.md +++ b/docs/technical-standards/Readme.md @@ -1,3 +1,6 @@ +--- +sidebar_position: 0 +--- # Technical standards These technical standards are the baseline operating requirements for systems and services in Hackney. From c1a770a17b258679348f8133f86aa5d7610cd4f9 Mon Sep 17 00:00:00 2001 From: Ryan Brooks Date: Wed, 15 Jan 2025 11:19:37 +0000 Subject: [PATCH 05/11] Update tagging requirements followind discussion with @acanbym and @stonest --- .../Reference/hosting-standards/tagging.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/docs/technical-standards/Reference/hosting-standards/tagging.md b/docs/technical-standards/Reference/hosting-standards/tagging.md index b6292ae..5f32b45 100644 --- a/docs/technical-standards/Reference/hosting-standards/tagging.md +++ b/docs/technical-standards/Reference/hosting-standards/tagging.md @@ -19,8 +19,9 @@ To ensure we can consistently search for, and report on, the tags we use, you sh - `AutomationBuildUrl`: URL of the automation build, must be a valid URL. - `BackupPolicy`: The backup policy to apply to the resource. If present must be one of `Dev`, `Stg`, `Preprod`, `Prod`, `Mgmt`. - `Confidentiality`: Data confidentiality of the infrastructure. Only applicable to infrastructure which holds data, e.g. EC2, RDS, EBS, DynamoDB, Glue, and S3. Must be one of `Internal`, `Restricted`, or `Public`[^confidentiality-tags-source]. -weekend_shutdown -ooh_shutdown +- `Department`: The service area this system serves. +- `WeekendShutdown`: If present, regardless of the value provided the resource will be shut down over the weekend. +- `OOHShutdown`: If present, regardless of the value provided the resource will be shut down out of working hours. ## Monitoring @@ -32,16 +33,9 @@ The user creating the object will be notified when an object is untagged with in 2. Newly created untagged objects will be forcefully and automatically shutdown/disabled if they remain untagged for 7 calendar days. 3. Existing untagged objects will not be editable until the mandatory tags have been added. -### FIXME(remove) Tags we're no longer using +## More information -- `AutomationTool`: The tool used for Infrastructure as Code, e.g. `Terraform` or `Serverless Framework`. -- `Department` (maybe useful, it's a fixed list) -- `Phase` -- `Stack` -- `Patch Group` -- `Project` -- `OOOShutdown` (has been superceded) -- `Team` (replaced by TeamEmail) +See the [How to tag your infrastructure](../../How-to%20guides/tagging.md) guide. [^confidentiality-tags-source]: https://github.com/LBHackney-IT/aws-tags-lbh/blob/main/variables.tf#L83 [^environment-tags-source]: https://github.com/LBHackney-IT/aws-tags-lbh/blob/main/variables.tf#L150 From 666ee3abdf6c6e0e38e4d5cf8d4af5e7e13f9a2e Mon Sep 17 00:00:00 2001 From: Ryan Brooks Date: Wed, 15 Jan 2025 11:20:33 +0000 Subject: [PATCH 06/11] Force category sidebar to remain expanded This saves users from needing to open the tree. We may reconsider this is we get lots of content, but for now it's unneccessary --- .../Reference/hosting-standards/_category_.json | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 docs/technical-standards/Reference/hosting-standards/_category_.json diff --git a/docs/technical-standards/Reference/hosting-standards/_category_.json b/docs/technical-standards/Reference/hosting-standards/_category_.json new file mode 100644 index 0000000..d997d2a --- /dev/null +++ b/docs/technical-standards/Reference/hosting-standards/_category_.json @@ -0,0 +1,4 @@ +{ + "collapsible": false, + "collapsed": false, +} From d459b3c2d803d3ec4fcbcb7680f4cf6a2b50b9cb Mon Sep 17 00:00:00 2001 From: Ryan Brooks Date: Wed, 15 Jan 2025 11:23:14 +0000 Subject: [PATCH 07/11] Add AWS tagging how to guide --- .../How-to guides/_category_.json | 4 +++ .../How-to guides/tagging.md | 33 +++++++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 docs/technical-standards/How-to guides/_category_.json create mode 100644 docs/technical-standards/How-to guides/tagging.md diff --git a/docs/technical-standards/How-to guides/_category_.json b/docs/technical-standards/How-to guides/_category_.json new file mode 100644 index 0000000..d997d2a --- /dev/null +++ b/docs/technical-standards/How-to guides/_category_.json @@ -0,0 +1,4 @@ +{ + "collapsible": false, + "collapsed": false, +} diff --git a/docs/technical-standards/How-to guides/tagging.md b/docs/technical-standards/How-to guides/tagging.md new file mode 100644 index 0000000..990bef2 --- /dev/null +++ b/docs/technical-standards/How-to guides/tagging.md @@ -0,0 +1,33 @@ +# How to tag your infrastructure + +This guide shows you how to configure tagging to meet the [tagging standard](../Reference/hosting-standards/tagging.md) using infrastructure as code. + +## Terraform + +TODO + +## Serverless Framework + +In order to add tagging to AWS resources managed by Serverless Framework: + +1. Install the `serverless-plugin-resource-tagging` Node module, e.g. `npm install serverless-plugin-resource-tagging` or `yarn add serverless-plugin-resource-tagging`. +2. Add the plugin to the `plugins` list in `serverless.yml` in your project and add the tags under `stackTags`, e.g.: + ```yaml + provider: + # ... + stackTags: + Application: "Developer Playbook" + TeamEmail: "developers@hackney.gov.uk" + Environment: "production" + + # For CircleCI + AutomationBuildUrl: ${env:CIRCLE_BUILD_URL} + + # For GitHub Actions + AutomationBuildUrl: ${env:GITHUB_SERVER_URL}/${env:GITHUB_REPOSITORY}/actions/runs/${env:GITHUB_RUN_ID} + + plugins: + - serverless-plugin-resource-tagging + ``` + +Refer to the [tagging standard](../Reference/hosting-standards/tagging.md) for a full list of mandatory and optional tags. From cf1c9217bfb7d1dc981eee275b2ccc812ecbe221 Mon Sep 17 00:00:00 2001 From: Ryan Brooks Date: Wed, 15 Jan 2025 12:19:06 +0000 Subject: [PATCH 08/11] Add Terraform/HCL syntax highlighting --- docusaurus.config.js | 1 + 1 file changed, 1 insertion(+) diff --git a/docusaurus.config.js b/docusaurus.config.js index 2830810..257b032 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -168,6 +168,7 @@ const config = { copyright: `Copyright © ${new Date().getFullYear()} London Borough of Hackney Council. The data published here is free to re-use under the Open Government Licence.`, }, prism: { + additionalLanguages: ['hcl'], theme: prismThemes.github, darkTheme: prismThemes.dracula, }, From 35481817feb0c86da985a15c698bf6df9d3349aa Mon Sep 17 00:00:00 2001 From: Ryan Brooks Date: Wed, 15 Jan 2025 12:19:18 +0000 Subject: [PATCH 09/11] Add Terraform tagging how-to --- .../How-to guides/tagging.md | 53 ++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/docs/technical-standards/How-to guides/tagging.md b/docs/technical-standards/How-to guides/tagging.md index 990bef2..0968cb4 100644 --- a/docs/technical-standards/How-to guides/tagging.md +++ b/docs/technical-standards/How-to guides/tagging.md @@ -4,7 +4,58 @@ This guide shows you how to configure tagging to meet the [tagging standard](.. ## Terraform -TODO +To add consistent tags to every resource created by a particular provider within a repo, use [the `default_tags` block in your terraform provider block](https://www.hashicorp.com/blog/default-tags-in-the-terraform-aws-provider). This will cascade any tags you specify to all resources created by terraform. For example: + +```hcl +provider "aws" { + region = "eu-west-2" + default_tags { + tags = { + Application = "Developer Playbook" + TeamEmail = "developers@hackney.gov.uk" + Environment = "production" + } + } +} +``` + +See how we use this in [LBHackney-IT/ce-dns](https://github.com/LBHackney-IT/ce-dns/blob/main/providers.tf) for a real-world example, including passing variables into the tag block. + +### Dynamic tags in Terraform + +Tags such as `AutomationBuildUrl` change every time we run the build in CI. Terraform doesn't support reading environment variables directly in the provider, so we need to pass these in as Terraform variables. + +Here's an example for how to add `AutomationBuildUrl`: + +1. Create a variable to hold the value in `variables.tf`: + > ℹ️ We use snake_case for variable names to match the Terraform convention + ```hcl + variable "automation_build_url" { + description = "The URL of the CI build that deployed or modified this infrastructure" + type = string + nullable = false + } + ``` + +2. Use the environment variable in `providers.tf` where you're defining your tags: + ```hcl + provider "aws" { + default_tags { + # ... + AutomationBuildUrl: var.automation_build_url + } + ``` + +3. Then reference the environment variables in `tfvars/production.tfvars`, `tfvars/staging.tfvars`, and any other environments you have. + - For CircleCI this will look like: + ```hcl + automation_build_url = $CIRCLE_BUILD_URL + ``` + - For GitHub Actions this will look like: + + ```hcl + automation_build_url = ${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID} + ``` ## Serverless Framework From d68e5caee21334e3a6bbeecf7032446e2b08c78c Mon Sep 17 00:00:00 2001 From: Ryan Brooks Date: Wed, 15 Jan 2025 12:27:34 +0000 Subject: [PATCH 10/11] Update docs/technical-standards/How-to guides/tagging.md Co-authored-by: Stuart Stone <10559951+stonest@users.noreply.github.com> --- docs/technical-standards/How-to guides/tagging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/technical-standards/How-to guides/tagging.md b/docs/technical-standards/How-to guides/tagging.md index 0968cb4..ac1163f 100644 --- a/docs/technical-standards/How-to guides/tagging.md +++ b/docs/technical-standards/How-to guides/tagging.md @@ -42,7 +42,7 @@ Here's an example for how to add `AutomationBuildUrl`: provider "aws" { default_tags { # ... - AutomationBuildUrl: var.automation_build_url + AutomationBuildUrl = var.automation_build_url } ``` From d8c423cca208e595d7ea3429652d2155da8adb25 Mon Sep 17 00:00:00 2001 From: Ryan Brooks Date: Wed, 15 Jan 2025 13:59:45 +0000 Subject: [PATCH 11/11] Use expanded acronym for improved readability --- docs/technical-standards/Reference/hosting-standards/tagging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/technical-standards/Reference/hosting-standards/tagging.md b/docs/technical-standards/Reference/hosting-standards/tagging.md index 5f32b45..4e26bde 100644 --- a/docs/technical-standards/Reference/hosting-standards/tagging.md +++ b/docs/technical-standards/Reference/hosting-standards/tagging.md @@ -21,7 +21,7 @@ To ensure we can consistently search for, and report on, the tags we use, you sh - `Confidentiality`: Data confidentiality of the infrastructure. Only applicable to infrastructure which holds data, e.g. EC2, RDS, EBS, DynamoDB, Glue, and S3. Must be one of `Internal`, `Restricted`, or `Public`[^confidentiality-tags-source]. - `Department`: The service area this system serves. - `WeekendShutdown`: If present, regardless of the value provided the resource will be shut down over the weekend. -- `OOHShutdown`: If present, regardless of the value provided the resource will be shut down out of working hours. +- `OutOfHoursShutdown`: If present, regardless of the value provided the resource will be shut down out of working hours. ## Monitoring