docs: the auto attachment of an EC2 to a default private hosted zone (#…

…129)

docs/configure/auto-attachment.md

@@ -0,0 +1,35 @@
+---
+description: "Automatically attach your EC2 to a default Route53 Private Hosted Zone"
+icon: material/connection
+status: new
+---
+
+# Auto Attachment of your EC2
+
+Your EC2 can automatically be attached to a default Route53 Private Hosted Zone (PHZ) called `dns53`.
+
+```sh
+dns53 --auto-attach
+```
+
+For this to work as intended, `dns53` handles two attachment scenarios, removing the need for any PHZ management. 👍
+
+## You are the first Auto Attachment
+
+Congratulations, you beat everyone else in your team or organisation and auto-attached your EC2 to the default `dns53` PHZ. `dns53` will:
+
+1. Create the new `dns53` PHZ and associate the launched EC2 VPC with it.
+1. Broadcasts your EC2 as expected, using a custom domain name if provided.
+1. Tidies everything up when you exit.
+
+## Auto Attachment has already happened
+
+If someone in your team, or organisation, was super keen and already auto-attached their EC2 to the default `dns53` PHZ, your attachment will be slightly different. `dns53` will:
+
+1. Check if your launched EC2 is within a VPC associated with the PHZ. If not, it will create a new association.
+1. Broadcasts your EC2 as expected, using a custom domain name if provided.
+1. Tidies everything up when you exit.
+
+## A 10,000-foot view
+
+![Auto Attachment Flow](../static/auto-attachment-flow.png)

docs/configure/exposing-tags.md

@@ -1,7 +1,6 @@
 ---
 description: "Expand your domain name customisation options by exposing your EC2 instance tags"
 icon: material/tag-outline
-status: new
 ---
 
 # Exposing EC2 Instance Tags

docs/configure/iam.md

@@ -1,24 +1,36 @@
 ---
 description: "Understand what Identity Access Management (IAM) permissions are needed for dns53 to run"
 icon: material/shield-lock-outline
+status: new
 ---
 
 # IAM Permissions
 
-Limited access to Route53 and EC2 is required for `dns53` to work. Your IAM persona must have the following permissions granted:
+Access to Route53 and EC2 is required for `dns53` to work. Your IAM persona must have the following permissions granted:
 
 ```json
 {
   "Version": "2012-10-17",
   "Statement": [
     {
       "Effect": "Allow",
-      "Action": ["route53:GetHostedZone", "route53:ChangeResourceRecordSets"],
+      "Action": [
+        "route53:AssociateVPCWithHostedZone",
+        "route53:ChangeResourceRecordSets",
+        "route53:DeleteHostedZone",
+        "route53:DisassociateVPCFromHostedZone",
+        "route53:GetHostedZone"
+      ],
       "Resource": "arn:aws:route53:::hostedzone/*"
     },
     {
       "Effect": "Allow",
-      "Action": ["route53:ListHostedZonesByVPC", "ec2:DescribeVpcs"],
+      "Action": [
+        "ec2:DescribeVpcs",
+        "route53:CreateHostedZone",
+        "route53:ListHostedZonesByName",
+        "route53:ListHostedZonesByVPC"
+      ],
       "Resource": "*"
     },
     {

docs/configure/list-tags.md

@@ -1,7 +1,6 @@
 ---
 description: "Generate a cheat sheet on how to include EC2 instance tags within your custom domain name"
 icon: material/tag-search-outline
-status: new
 ---
 
 # List Available EC2 Instance Tags

docs/install.md → docs/install/binary.md

@@ -2,11 +2,11 @@
 icon: material/package-variant-closed
 ---
 
-# Install
+# Installing the Binary
 
-There are many different ways to install dns53. You can install the binary using either a supported package manager, manually, or by compiling the source yourself.
+You can use various package managers to install the `dns53` binary. Take your pick.
 
-## Installing the binary
+## Package Managers
 
 ### Homebrew
 
@@ -35,7 +35,7 @@ sudo apt update
 sudo apt install -y dns53
 ```
 
-You may need to install the `ca-certificates` package if you encounter [trust issues](https://gemfury.com/help/could-not-verify-ssl-certificate/) with regards to the gemfury certificate:
+You may need to install the `ca-certificates` package if you encounter [trust issues](https://gemfury.com/help/could-not-verify-ssl-certificate/) with regard to the Gemfury certificate:
 
 ```sh
 sudo apt update && sudo apt install -y ca-certificates
@@ -98,53 +98,26 @@ To install the latest version using a bash script:
 curl https://raw.githubusercontent.com/purpleclay/dns53/main/scripts/install | bash
 ```
 
-A specific version can be downloaded by using the `-v` flag. By default the script uses `sudo`, which can be turned off by using the `--no-sudo` flag.
+Download a specific version using the `-v` flag. The script uses `sudo` by default but can be disabled through the `--no-sudo` flag.
 
 ```sh
 curl https://raw.githubusercontent.com/purpleclay/dns53/main/scripts/install | bash -s -- -v v0.1.0 --no-sudo
 ```
 
-### Manually
+## Manual Download of Binary
 
-Binary downloads of dns53 can be found on the [Releases](https://github.com/purpleclay/dns53/releases) page. Unpack the dns53 binary and add it to your `PATH`.
+Head over to the [Releases](https://github.com/purpleclay/dns53/releases) page on GitHub and download any release artefact. Unpack the `dns53` binary and add it to your `PATH`.
 
-## Compiling from source
+## Verifying a Binary with Cosign
 
-dns53 is written using [Go 1.18+](https://go.dev/doc/install) and should be installed along with [go-task](https://taskfile.dev/#/installation), as it is preferred over using make.
-
-Then clone the code from GitHub:
-
-```sh
-git clone https://github.com/purpleclay/dns53.git
-cd dns53
-```
-
-Build dns53:
-
-```sh
-task
-```
-
-And check that everything works:
-
-```sh
-./dns53 version
-```
-
-## Verifying Artefacts
-
-All verification is carried out using cosign and it must be [installed](https://docs.sigstore.dev/cosign/installation) before proceeding.
-
-### Binaries
-
-All binaries can be verified using the checksum file, which has been signed using cosign.
+All binaries can be verified using [cosign](https://github.com/sigstore/cosign).
 
 1. Download the checksum files that need to be verified:
 
    ```sh
-   curl -sL https://github.com/purpleclay/dns53/releases/download/v0.1.0/checksums.txt -O
-   curl -sL https://github.com/purpleclay/dns53/releases/download/v0.1.0/checksums.txt.sig -O
-   curl -sL https://github.com/purpleclay/dns53/releases/download/v0.1.0/checksums.txt.pem -O
+   curl -sL https://github.com/purpleclay/dns53/releases/download/v0.8.0/checksums.txt -O
+   curl -sL https://github.com/purpleclay/dns53/releases/download/v0.8.0/checksums.txt.sig -O
+   curl -sL https://github.com/purpleclay/dns53/releases/download/v0.8.0/checksums.txt.pem -O
    ```
 
 1. Verify the signature of the checksum file:
@@ -158,7 +131,3 @@ All binaries can be verified using the checksum file, which has been signed usin
    ```sh
    sha256sum --ignore-missing -c checksums.txt
    ```
-
-!!!warning "Don't mix versions"
-
-    For checksum verification to work, all artefacts must be downloaded from the same release

docs/install/source.md

@@ -0,0 +1,24 @@
+---
+icon: material/file-code-outline
+---
+
+# Compiling from Source
+
+Download both [Go 1.19+](https://go.dev/doc/install) and [go-task](https://taskfile.dev/#/installation). Then clone the code from GitHub:
+
+```sh
+git clone https://github.com/purpleclay/dns53.git
+cd dns53
+```
+
+Build:
+
+```sh
+task
+```
+
+And check that everything works:
+
+```sh
+./dns53 version
+```

docs/license.md

@@ -0,0 +1,25 @@
+---
+icon: material/file-key-outline
+---
+
+MIT License
+
+Copyright (c) 2022 Purple Clay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/reference/cli/dns53.md

@@ -19,6 +19,7 @@ dns53 [command]
 ## Flags
 
 ```text
+    --auto-attach          automatically create and attach a record set to a default private hosted zone
     --domain-name string   assign a custom domain name when generating a record set
 -h, --help                 help for dns53
     --phz-id string        an ID of a Route53 private hosted zone to use when generating a record set

mkdocs.yml

@@ -33,12 +33,16 @@ theme:
 nav:
   - Home: index.md
   - Getting Started:
-      - Installation: install.md
       - Broadcast your EC2: configure/broadcast-ec2.md
       - Custom Domain: configure/custom-domain.md
+      - EC2 Auto Attachment: configure/auto-attachment.md
       - Expose EC2 Tags: configure/exposing-tags.md
       - List EC2 Tags: configure/list-tags.md
       - IAM: configure/iam.md
+      - License: license.md
+      - Installation:
+          - Binary: install/binary.md
+          - From Source: install/source.md
   - Reference:
       - Templating: reference/templating.md
       - CLI: