Added documentation

README-in-development.md

@@ -7,7 +7,7 @@ CLI tools to help with working with Dalmatian
 - An AWS Organisation with at least 1 Account to configure with Dalmatian
 - A user assigned to a group that has an Administrative permission set
 - An S3 bucket to store the Terraform state
-- AWS IAM Identity Center (successor to AWS Single Sign-On) configured with the 
+- AWS IAM Identity Center (successor to AWS Single Sign-On) configured with the
 default identity source.
 
 ## Installation

README.md

@@ -1,149 +1,19 @@
 # Dalmatian Tools
 
-CLI tools to help with working with Dalmatian
+![GitHub Release](https://img.shields.io/github/v/release/dxw/dalmatian-tools)
 
-## Installation
+A collection of administration tools you can use to interact with dxw's Dalmatian hosting platform.
 
-1. Clone this repository locally
-
-1. Install the dependencies
-
-   ```
-   brew bundle install
-   ```
-
-1. Add the dalmatian-tools `bin` directory to your `$PATH`
-
-   To add the ability to run the `dalmatian` command, you will need to add the
-   Dalmatian Tools `bin` directory to your `$PATH` variable
-
-   Find the full path of Dalmatian Tools by changing directory into this
-   repository, and run `pwd`. eg:
-
-   ```
-   $ cd ~/git-clones/dalmatian-tools
-   $ pwd
-   /Users/alex/git-clones/dalmatian-tools
-   ```
-
-   Add this path, plus '/bin' to the '$PATH' variable, by modifying
-   either the `~/.bashrc` or `~/.zshrc` file
-
-   ```bash
-   # ~/.bashrc or ~/.zshrc
-   export PATH="$PATH:/<path-to-dalmatian-tools>/bin"
-   ```
-
-   The easiest way for this to take effect is to close and open your terminal application
-
-   Or you can run `source ~/.bashrc` or `source ~/.zshrc` on all open terminals
-
-1. Login to dalmatian
-
-  Run the `dalmatian login` command
-
-  You can find your AWS Access Key and Secret Key in the AWS console by heading
-  to the [IAM users list](https://console.aws.amazon.com/iamv2/home#/users),
-  choosing your `dalmatian-user-admin`, and selecting the "Security credentials"
-  tab. You will need to create a new Access Key. *Do not close this dialog*
-  until you have successfully logged in, as this is the only time you can view
-  your Secret Key.
-
-  When prompted for your MFA secret, this is _not_ the six numbers from 2FA.
-  Instead, you will need the secret key used to generate this. See below for the
-  FAQ if you don't know how to get this.
-
-  ```
-  $ dalmatian login
-  Note: You must have a Dalmatian Admin account to use Dalmatian Tools
-
-  For added security, your credentials and MFA secret will be
-  encrypted with GPG
-
-  Email associated with GPG key: alex@example.com
-  AWS Access Key ID: XXXXXXXXXXXXXXXXXXXX
-  AWS Secret Access Key:
-  AWS MFA Secret:
-  ==> Checking credentials...
-    User ID: XXXXXXXXXXXXXXXXXXXXX
-    Account: XXXXXXXXXXXX
-    Arn:     arn:aws:iam::XXXXXXXXXXXX:user/dalmatian_admins/<user-name>
-  ==> Saving configuration settings in /Users/alex/.config/dalmatian/config.json ...
-  ==> Storing credentials in /Users/alex/.config/dalmatian/credentials.json.enc ...
-  ==> Attempting MFA...
-  ==> Storing MFA credentials in /Users/alex/.config/dalmatian/mfa_credentials.json
-  ==> Login success!
-  ```
-
-  Once you're signed in you can safely close the AWS Access Key dialog.
-
-## FAQ
-
-### Why am I seeing "oathtool: base32 decoding failed: Base32 string is invalid"
-
-Probably you've entered your 6 digit MFA code rather than the underlying MFA
-secret which is a long alphanumeric string. This secret is available:
-
-- at the time you set up MFA in the AWS Console (Security Credentials | Manage MFA), and
-
-- in 1Password if you're using that software to generate MFA codes. You need to
-  go into 'edit' mode to view. You're looking for the string of letters and
-  numbers after `?secret=`.
-
-If you are using an 'app' such as Google Authenticator on your phone you may not
-be able to access this initial secret without removing your MFA in the AWS
-Console and setting it up afresh.
-
-## Usage
-
-### Help
-
-  `dalmatian -h`
-
-  ```
-  $ dalmatian -h
-  Usage: dalmatian
-    SUBCOMMAND COMMAND     - dalmatian command to run
-    SUBCOMMAND COMMAND -h  - show command help
-      Or:
-    -h                     - help
-    -l
-  ```
-
-### List commands
-
-  `dalmatian -l`
-
-### Shell completion
-**Bash (/bin/bash)**
-
-Add the full path to the `support/bash-completion.sh` script to your `~/.bashrc` file
-
-eg:
-
-```
-# ~/.bashrc
-
-source /path/to/dalmatian-tools/support/bash-completion.sh
-```
-
-**Zsh (/bin/zsh)**
-
-Add the full path to the `support/zsh-completion.sh` script to your `~/.zshrc` file
-
-eg:
-
-```
-# ~/.zshrc
-
-autoload -Uz +X compinit && compinit
-autoload -Uz +X bashcompinit && bashcompinit
-source /path/to/dalmatian-tools/support/zsh-completion.sh
-```
+## Table of Contents
+1. [Installation](./docs/installation.md)
+1. [Usage](./docs/usage.md)
+1. [Shell integration](./docs/shell-integration.md)
+1. [FAQ](./docs/faq.md)
 
 ### Environment Variables
 
-- DALMATIAN_CONFIG_PATH
-  Set a path to dalmatian.yml to override the use of the checkout used by the
+- `DALMATIAN_CONFIG_PATH`
+
+  Set a path to `dalmatian.yml` to override the use of the checkout used by the
   tools by default. Useful if bringing up a service or infrastructure whose
   config hasn't been merged in yet.

docs/faq.md

@@ -0,0 +1,16 @@
+## FAQ
+
+### Why am I seeing "oathtool: base32 decoding failed: Base32 string is invalid"
+
+Probably you've entered your 6 digit MFA code rather than the underlying MFA
+secret which is a long alphanumeric string. This secret is available:
+
+- at the time you set up MFA in the AWS Console (Security Credentials | Manage MFA), and
+
+- in 1Password if you're using that software to generate MFA codes. You need to
+  go into 'edit' mode to view. You're looking for the string of letters and
+  numbers after `?secret=`.
+
+If you are using an 'app' such as Google Authenticator on your phone you may not
+be able to access this initial secret without removing your MFA in the AWS
+Console and setting it up afresh.

docs/installation.md

@@ -0,0 +1,74 @@
+## Installation
+
+1. Clone this repository locally
+
+1. Install the dependencies
+
+   ```
+   brew bundle install
+   ```
+
+1. Add the dalmatian-tools `bin` directory to your `$PATH`
+
+   To add the ability to run the `dalmatian` command, you will need to add the
+   Dalmatian Tools `bin` directory to your `$PATH` variable
+
+   Find the full path of Dalmatian Tools by changing directory into this
+   repository, and run `pwd`. eg:
+
+   ```
+   $ cd ~/git-clones/dalmatian-tools
+   $ pwd
+   /Users/alex/git-clones/dalmatian-tools
+   ```
+
+   Add this path, plus '/bin' to the '$PATH' variable, by modifying
+   either the `~/.bashrc` or `~/.zshrc` file
+
+   ```bash
+   # ~/.bashrc or ~/.zshrc
+   export PATH="$PATH:/<path-to-dalmatian-tools>/bin"
+   ```
+
+   The easiest way for this to take effect is to close and open your terminal application
+
+   Or you can run `source ~/.bashrc` or `source ~/.zshrc` on all open terminals
+
+1. Login to dalmatian
+
+  Run the `dalmatian login` command
+
+  You can find your AWS Access Key and Secret Key in the AWS console by heading
+  to the [IAM users list](https://console.aws.amazon.com/iamv2/home#/users),
+  choosing your `dalmatian-user-admin`, and selecting the "Security credentials"
+  tab. You will need to create a new Access Key. *Do not close this dialog*
+  until you have successfully logged in, as this is the only time you can view
+  your Secret Key.
+
+  When prompted for your MFA secret, this is _not_ the six numbers from 2FA.
+  Instead, you will need the secret key used to generate this. See below for the
+  FAQ if you don't know how to get this.
+
+  ```
+  $ dalmatian login
+  Note: You must have a Dalmatian Admin account to use Dalmatian Tools
+
+  For added security, your credentials and MFA secret will be
+  encrypted with GPG
+
+  Email associated with GPG key: alex@example.com
+  AWS Access Key ID: XXXXXXXXXXXXXXXXXXXX
+  AWS Secret Access Key:
+  AWS MFA Secret:
+  ==> Checking credentials...
+    User ID: XXXXXXXXXXXXXXXXXXXXX
+    Account: XXXXXXXXXXXX
+    Arn:     arn:aws:iam::XXXXXXXXXXXX:user/dalmatian_admins/<user-name>
+  ==> Saving configuration settings in /Users/alex/.config/dalmatian/config.json ...
+  ==> Storing credentials in /Users/alex/.config/dalmatian/credentials.json.enc ...
+  ==> Attempting MFA...
+  ==> Storing MFA credentials in /Users/alex/.config/dalmatian/mfa_credentials.json
+  ==> Login success!
+  ```
+
+  Once you're signed in you can safely close the AWS Access Key dialog.

docs/shell-integration.md

@@ -0,0 +1,27 @@
+## Shell completion
+
+**Bash (/bin/bash)**
+
+Add the full path to the `support/bash-completion.sh` script to your `~/.bashrc` file
+
+eg:
+
+```
+# ~/.bashrc
+
+source /path/to/dalmatian-tools/support/bash-completion.sh
+```
+
+**Zsh (/bin/zsh)**
+
+Add the full path to the `support/zsh-completion.sh` script to your `~/.zshrc` file
+
+eg:
+
+```
+# ~/.zshrc
+
+autoload -Uz +X compinit && compinit
+autoload -Uz +X bashcompinit && bashcompinit
+source /path/to/dalmatian-tools/support/zsh-completion.sh
+```

docs/usage.md

@@ -0,0 +1,96 @@
+## Usage
+
+>[!IMPORTANT]
+>Please note the following documentation is for version 1 of Dalmatian Tools. Version 2 usage documentation is still in early draft
+
+>[!TIP]
+>List all available commands at any time with the handy `-l` option.
+>
+>Most commands include a 'help' option. Add `-h` to your command to see what available options it expects
+
+### `dalmatian login`
+
+The **login** command is used to authenticate Dalmatian Tools with AWS using Single Sign-On.
+
+As dalmatian requires that a number of packages are installed to your system in order to function effectively, the login command will check these exist and install any missing dependencies on your behalf before proceeding.
+
+Logging into Dalmatian Tools is an essential first step in getting setup.
+
+If you haven't already, please read the [installation guide](./installation.md).
+
+### `dalmatian version`
+
+The **version** command allows you to switch operation modes between version 1 (legacy) and version 2.
+
+To switch versions, simply adjust the number value for the `-v` option.
+
+```
+# Switching to Dalmatian version 2
+$ dalmatian version -v 2
+# Switching back to Dalmatian version 1
+$ dalmatian version -v 1
+```
+
+To see what version you are currently using you can simply run
+```
+$ dalmatian version
+```
+
+### `dalmatian certificate`
+
+This collection of tools allow an operator to manipulate certificates within AWS Certificate Manager.
+
+#### `dalmatian certificate list`
+
+This command will query AWS Certificate Manager for all certificates in a particular infrastructure and output a list containing the **ARN**, **Domain name**, and **Status** of each certificate.
+
+```
+$ dalmatian certificate list -i "$infrastructure"
+arn:aws:acm:eu-west-2:xxx:certificate/aaa-aaa-aaa-aaa-aaa my-example-domain.org EXPIRED
+arn:aws:acm:eu-west-2:xxx:certificate/bbb-bbb-bbb-bbb-bbb my-example-domain.net ISSUED
+arn:aws:acm:eu-west-2:xxx:certificate/ccc-ccc-ccc-ccc-ccc my-example-domain.com ISSUED
+```
+
+If you like to filter the output for a specific domain, you can adjust the command slightly and include the domain name as an option
+
+```
+$ dalmatian certificate list -i "$infrastructure" -d "my-example-domain.org"
+arn:aws:acm:eu-west-2:xxx:certificate/aaa-aaa-aaa-aaa-aaa my-example-domain.org EXPIRED
+arn:aws:acm:eu-west-2:xxx:certificate/aaa-aaa-bbb-bbb-bbb my-example-domain.org EXPIRED
+```
+
+If you are registering a new certificate and need to complete DNS validation, you can include both the domain and `-D` as an option to include the DNS records along with each certificate
+
+```
+$ dalmatian certificate list -i "$infrastructure" -d "my-example-domain.org" -D
+arn:aws:acm:eu-west-2:xxx:certificate/aaa-aaa-aaa-aaa-aaa my-example-domain.org EXPIRED
+_c33dc71b006c460ed5ef53b6dcf57040.my-example-domain.org. CNAME _7330c60e670977e371567a560c6c1c05.aaa.acm-validations.aws.
+_4416a7c8eb42f12439788a305cfcd8a5.www.my-example-domain.org. CNAME _86d26d74a9ad4a4d4571f1ed611c2b26.bbb.acm-validations.aws.
+
+arn:aws:acm:eu-west-2:xxx:certificate/aaa-aaa-bbb-bbb-bbb my-example-domain.org EXPIRED
+_c33dc71b006c460ed5ef53b6dcf57040.my-example-domain.org. CNAME _7330c60e670977e371567a560c6c1c05.aaa.acm-validations.aws.
+_4416a7c8eb42f12439788a305cfcd8a5.www.my-example-domain.org. CNAME _86d26d74a9ad4a4d4571f1ed611c2b26.bbb.acm-validations.aws.
+```
+
+#### `dalmatian certificate delete`
+
+This command will allow an operator to delete specific certificates from AWS Certificate Manager in a particular infrastructure.
+
+You can delete certificates that match either a specific ARN, or you can specify a domain name. By specifying a domain name you can delete all certificates that are not in either `PENDING` or `ISSUED` state.
+
+If you are wanting to use an ARN, you may find it useful to first run `dalmatian certificate list` to find the ARN you need.
+
+>[!CAUTION]
+>This is a **destructive** action! You can add `-d` to this command to perform a dry-run and instead will print the commands it _would have_ executed to the output.
+
+To delete a certificate using an ARN
+
+```
+$ dalmatian certificate delete -i "$infrastructure" -c "arn:aws:acm:eu-west-2:xxx:certificate/aaa-aaa-aaa-aaa-aaa"
+```
+
+To delete all certificate for a domain name that are not `PENDING` or `ISSUED`
+
+```
+$ dalmatian certificate delete -i "$infrastructure" -D "my-example-domain.org"
+```