diff --git a/README-in-development.md b/README-in-development.md index b8969fe..0e91f7e 100644 --- a/README-in-development.md +++ b/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 diff --git a/README.md b/README.md index 2f59c9a..745208e 100644 --- a/README.md +++ b/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://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/ - ==> 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. diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..e818626 --- /dev/null +++ b/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. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..42b2926 --- /dev/null +++ b/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://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/ + ==> 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. diff --git a/docs/shell-integration.md b/docs/shell-integration.md new file mode 100644 index 0000000..40cd359 --- /dev/null +++ b/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 +``` diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..4b9ac43 --- /dev/null +++ b/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" +```