Merge pull request #7345 from ministryofjustice/upd/tweaks-to-user-docs

Minor updates to user docs - concepts

.github/workflows/test-url-links.yml

@@ -0,0 +1,30 @@
+---
+  name: check for broken links
+
+  on:
+    pull_request: 
+      paths:
+        - "source/**"
+    schedule:
+      - cron: '3 7 * * TUE'
+
+  permissions: {}
+  jobs:
+    check-links:
+      name: Test
+      runs-on: ubuntu-latest
+      permissions:
+        contents: read
+      steps:
+        - name: Checkout
+          id: checkout
+          uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+
+        - name: Lychee
+          id: lychee
+          uses: lycheeverse/lychee-action@2b973e86fc7b1f6b36a93795fe2c9c6ae1118621 # v1.10.0
+          env:
+            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          with:
+            args: --verbose --no-progress './**/*.md' './**/*.html' './**/*.erb' --config config/lychee.toml
+            fail: true

architecture-decision-record/0006-use-a-multi-account-strategy-for-applications.md

@@ -12,7 +12,7 @@ In the Modernisation Platform, we want to reduce the blast radius and increase t
 
 ## Decision
 
-We've decided to use a multi-account strategy, split by application. We have a complete write-up as part of our [environments concept](https://user-guide.modernisation-platform.service.justice.gov.uk/concepts/environments/).
+We've decided to use a multi-account strategy, split by application. We have a complete write-up as part of our [environments concept](https://user-guide.modernisation-platform.service.justice.gov.uk/#environments-aws-accounts).
 
 ## Consequences
 

architecture-decision-record/0009-use-secrets-manager-for-secrets.md

@@ -16,7 +16,7 @@ There are also other well known industry solutions such as [HashiCorp Vault](htt
 
 We've decided to use [Secrets Manager](https://aws.amazon.com/secrets-manager/) for our secrets storage.
 
-Parameter store can be used to store non secret parameters if needed for environment specific configuration, but the first choice should be using an app_variables.json like [here](https://github.com/ministryofjustice/modernisation-platform-environments/blob/main/terraform/environments/sprinkler/app_variables.json)
+Parameter store can be used to store non secret parameters if needed for environment specific configuration, but the first choice should be using an [`application_variables.json` such as this](https://github.com/ministryofjustice/modernisation-platform-environments/blob/main/terraform/environments/sprinkler/application_variables.json)
 
 ## Consequences
 

config/lychee.toml

@@ -0,0 +1,46 @@
+#############################  Display  #############################
+
+# Verbose program output
+# Accepts log level: "error", "warn", "info", "debug", "trace"
+verbose = "info"
+
+# Don't show interactive progress bar while checking links.
+no_progress = true
+
+#############################  Cache  ###############################
+
+# Enable link caching. This can be helpful to avoid checking the same links on
+# multiple runs.
+cache = true
+
+# Discard all cached requests older than this duration.
+max_cache_age = "2d"
+
+#############################  Requests  ############################
+
+# User agent to send with each request.
+user_agent = "curl/7.83. 1"
+
+# Website timeout from connect to response finished.
+timeout = 2
+
+# Minimum wait time in seconds between retries of failed requests.
+retry_wait_time = 2
+
+# Comma-separated list of accepted status codes for valid links.
+# Supported values are:
+accept = ["200", "401", "403", "429"]
+#############################  Exclusions  ##########################
+
+# Exclude URLs and mail addresses from checking (supports regex).
+exclude = [
+    '^https://github\.com/ministryofjustice/[\w-]+/settings/.*', 
+    '^https://github\.com/ministryofjustice/modernisation-platform-security',
+    '^https://github\.com/ministryofjustice/deployment-tgw',
+    '^https://moj-digital-tools.pagerduty.com',
+]
+
+# Exclude all private IPs from checking.
+# Equivalent to setting `exclude_private`, `exclude_link_local`, and
+# `exclude_loopback` to true.
+exclude_all_private = true

source/concepts/environments/auto-nuke.html.md.erb

@@ -1,7 +1,7 @@
 ---
 owner_slack: "#modernisation-platform"
 title: Auto-nuke and redeploy development environments on weekly basis
-last_reviewed_on: 2024-06-20
+last_reviewed_on: 2024-06-28
 review_in: 6 months
 ---
 
@@ -18,31 +18,31 @@ review_in: 6 months
 
 ## Feature description
 
-This feature automatically nukes and optionally recreates development environments on weekly basis. This is useful for environments with the sandbox permission, which allow users provisioning resources directly through the AWS web console as opposite to using terraform. In such cases, the auto-nuke will make sure the resources created manually will be cleared on weekly basis. If requested, the resources defined in terraform will then be recreated.
+This feature automatically destroys all resources in development environments on a weekly basis, and provides a utitily to recreate resources in these environments. This is useful for environments with the sandbox permission, which allow users to provision resources directly through the AWS web console alongside infrastructure as code (IaC). In such cases, the auto-nuke will make ensure the manually created resources will be regularly removed. If requested, resources defined in terraform can then be recreated.
 
 Every Sunday:
 
-- At 10.00pm the awsnuke.yml workflow is triggered. This workflow nukes all the configured development environments using the AWS Nuke tool (https://github.com/rebuy-de/aws-nuke).
-- At 12.00 noon the nuke-redeploy.yml workflow is triggered. If requested, this workflow redeploys the nuked environment using terraform apply.
+- At 22:00 the [awsnuke.yml workflow](https://github.com/ministryofjustice/modernisation-platform-environments/blob/main/.github/workflows/awsnuke.yml) is triggered. This workflow nukes all the configured development environments using the [AWS Nuke tool](https://github.com/rebuy-de/aws-nuke).
+- At 12:00 the [nuke-redeploy.yml workflow](https://github.com/ministryofjustice/modernisation-platform-environments/blob/main/.github/workflows/nuke-redeploy.yml) is triggered. If requested, this workflow redeploys IaC into the nuked environment using `terraform apply`.
 
-A sketch of the algorithm is as follows:
+An outline of the 'nuke' algorithm is as follows:
 
-- For every account in a dynamically generated list of all sandbox accounts
-- Assume the role MemberInfrastructureAccess under the account ID
-- Nuke the resources under the account ID
-- (Optionally) Perform terraform apply in order to recreate all resources from terraform
+- For every account in a dynamically generated list of all sandbox accounts:
+   - Assume the [`MemberInfrastructureAccess` role](https://github.com/ministryofjustice/modernisation-platform/blob/ab3eb5a6a8e6253afc9db794362034ba4ae1cd94/terraform/environments/bootstrap/member-bootstrap/iam.tf#L266) under the account ID
+   - Nuke the resources under the account ID
+   - (Optionally) Perform terraform apply in order to recreate all resources from terraform
 
 ## Configuration
 
 Auto-nuke consumes the following dynamically generated Github secrets stored in the Modernisation Platorm Environments repository:
 
-- `MODERNISATION_PLATFORM_AUTONUKE_BLOCKLIST`: Account aliases to always exclude from auto-nuke. This takes precedence over all other configuration options. Due to the destructive nature of the tool, AWS-Nuke (https://github.com/rebuy-de/aws-nuke) requires at least one Account ID in the configured blocklist. Our blocklist contains all production. preproduction and core accounts.
+- `MODERNISATION_PLATFORM_AUTONUKE_BLOCKLIST`: Account aliases to always exclude from auto-nuke. This takes precedence over all other configuration options. Due to the destructive nature of the tool, [AWS-Nuke](https://github.com/rebuy-de/aws-nuke) requires at least one account ID in the configured blocklist. Our blocklist contains all production, preproduction, and core accounts.
 
 - `MODERNISATION_PLATFORM_AUTONUKE`: Account aliases of sandbox accounts to be auto-nuked on weekly basis.
 
 - `MODERNISATION_PLATFORM_AUTONUKE_REBUILD`: Accounts to be rebuilt after auto-nuke runs. This secret is consumed by the `nuke-redeploy.yml` workflow.
 
-The `nuke-config-template.txt` is populated with account and blocklist information during the runtime of the `awsnuke.yml` workflow, to produce a valid aws-nuke configuration file.
+The [`nuke-config-template.txt`](https://github.com/ministryofjustice/modernisation-platform-environments/blob/main/scripts/nuke-config-template.txt) is populated with account and blocklist information during the runtime of the `awsnuke.yml` workflow, to produce a valid aws-nuke configuration file.
 
 ### When new sandbox development environment is onboarded
 
@@ -67,8 +67,8 @@ Eg:
 
 Valid values are:
 
-`include` = nukes but doesn’t rebuild (default option if nothing added)
-`exclude` = doesn’t nuke or rebuild
-`rebuild` = nukes and rebuilds
+- `include` = nukes but doesn’t rebuild (default option if nothing added)
+- `exclude` = doesn’t nuke or rebuild
+- `rebuild` = nukes and rebuilds
 
 Please contact us in [#ask-modernisation-platform](https://mojdt.slack.com/archives/C01A7QK5VM1) channel for details.

source/concepts/environments/instance-scheduling.html.md.erb

@@ -1,7 +1,7 @@
 ---
 owner_slack: "#modernisation-platform"
 title: Instance Scheduling - automatically stop non-production instances overnight
-last_reviewed_on: 2024-03-15
+last_reviewed_on: 2024-06-28
 review_in: 6 months
 ---
 
@@ -18,9 +18,9 @@ review_in: 6 months
 
 ## Feature description
 
-This feature automatically stops non-production EC2 and RDS instances overnight, in order to save on AWS costs and reduce environmental impact. Stopped instances don't incur charges, but Elastic IP addresses or EBS volumes attached to those instances do.
+This feature automatically stops non-production EC2 and RDS instances overnight and over each weekend, in order to save on AWS costs and reduce environmental impact. Stopped instances don't incur charges, but Elastic IP addresses or EBS volumes attached to those instances do.
 
-The instances will be automatically stopped every weekday at 9pm night and started at 6am in the morning. By default, this includes every EC2 and RDS instance in every non-production environment (development, test, pre-production) without requiring any configuration from the end user. Users can customise the default behaviour by attaching the `instance-scheduling` tag to EC2 and RDS instances with one of the following values:
+The instances will be [automatically stopped each weekday at 21:00 and started at 06:00 each weekday morning](https://github.com/ministryofjustice/modernisation-platform/blob/main/terraform/environments/core-shared-services/instance-scheduler-lambda-function.tf), which includes shut down on Friday night and startup on Monday morning. By default, this includes every EC2 and RDS instance in every non-production environment (development, test, preproduction) without requiring any configuration from the end user. Users can customise the default behaviour by attaching the `instance-scheduling` tag to EC2 and RDS instances with one of the following values:
 
 - `default` - Automatically stop the instance overnight and start it in the morning. Absence of the `instance-scheduling` tag will have the same effect.
 - `skip-scheduling` - Skip auto scheduling for the instance
@@ -44,15 +44,15 @@ Ordering instances and automatically stopping them on public holidays is not sup
 
 For those teams that require the shutdown & startup of ec2 & rds resources in a specific order or at different times, the option exists to make use of github workflows & cron schedules to stop & start services.
 
-- These workflows can be run from the application source github via the use of oidc for authenticaiton to the Modernisation Platform - see https://user-guide.modernisation-platform.service.justice.gov.uk/user-guide/deploying-your-application.html#deploying-your-application. It is recommended to hold the AWS account number for the member account as a github secret, especially if the repo is public.
+- These workflows can be run from the application source github [via the use of oidc for authentication to the Modernisation Platform](https://user-guide.modernisation-platform.service.justice.gov.uk/user-guide/deploying-your-application.html#deploying-your-application). It is recommended to hold the AWS account number for the member account as a github secret, especially if the repo is public.
 
-- An example of how to use a github workflow to meet this requirement can be found here - https://github.com/ministryofjustice/modernisation-platform-configuration-management/blob/main/.github/workflows/flexible-instance-stop-start.yml. Note that the workflow uses a separate script to run the AWS CLI commands for shutdown & startup. These can be easily reused & customised to meet specific needs. 
+- An example of how to use a github workflow to meet this requirement can be [found here](https://github.com/ministryofjustice/modernisation-platform-configuration-management/blob/main/.github/workflows/flexible-instance-stop-start.yml). Note that the workflow uses [a separate script](https://github.com/ministryofjustice/modernisation-platform-configuration-management/blob/main/scripts/flexistopstart.sh) to run the AWS CLI commands for shutdown & startup. These can be easily reused & customised to meet specific needs. 
 
 - EC2 or RDS resources that are stopped or started in this manner must have the `skip-scheduling` tag added as described above.
 
 - Note that there are some restrictions that come with using github schedules - most importantly that github themselves do not guarantee execution of the action at the specified time. Actions can be delayed at busy times or even dropped entirely so it is recommended to avoid schedules running on-the-hour or half-hour.
 
-Further information regarding github schedule events can be found here - https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
+Further information regarding github schedule events can be [found here](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule).
 
 ## References