diff --git a/docs/conf.py b/docs/conf.py index 71072b0..ea10a18 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -69,7 +69,7 @@ else: # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = "en" # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. diff --git a/docs/configuration.md b/docs/configuration.md index 4eb8ca2..3f0842a 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,4 +1,4 @@ -## Configuration +# Configuration This tool uses [boto3](https://boto3.amazonaws.com/) under the hood which supports [a number of different ways](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html) of providing your AWS credentials. @@ -8,7 +8,7 @@ You can set the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment vari You can also use the `--access-key=`, `--secret-key=`, `--session-token` and `--auth` options documented below. -### Common command options +## Common command options All of the `s3-credentials` commands also accept the following options for authenticating against AWS: diff --git a/docs/contributing.md b/docs/contributing.md index 30d1918..7fd853b 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,4 +1,4 @@ -## Contributing +# Contributing To contribute to this tool, first checkout the code. Then create a new virtual environment: @@ -22,7 +22,7 @@ Any changes to the generated policies require an update to the README using [Cog cog -r README.md -### Integration tests +## Integration tests The main tests all use stubbed interfaces to AWS, so will not make any outbound API calls. diff --git a/docs/create.md b/docs/create.md index e36bede..2ad5789 100644 --- a/docs/create.md +++ b/docs/create.md @@ -1,4 +1,4 @@ -## Creating S3 credentials +# Creating S3 credentials The `s3-credentials create` command is the core feature of this tool. Pass it one or more S3 bucket names, specify a policy (read-write, read-only or write-only) and it will return AWS credentials that can be used to access those buckets. @@ -69,7 +69,7 @@ The `create` command has a number of options: - `--dry-run`: Output details of AWS changes that would have been made without applying them. - `--user-permissions-boundary`: Custom [permissions boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) to use for users created by this tool. The default is to restrict those users to only interacting with S3, taking the `--read-only` option into account. Use `none` to create users without any permissions boundary at all. -### Changes that will be made to your AWS account +## Changes that will be made to your AWS account How the tool works varies depending on if you are creating temporary or permanent credentials. @@ -89,7 +89,7 @@ For temporary credentials: You can run the `create` command with the `--dry-run` option to see a summary of changes that would be applied, including details of generated policy documents, without actually applying those changes. -### Using a custom policy +## Using a custom policy The policy documents applied by this tool [are listed here](policy-documents.md). diff --git a/docs/other-commands.md b/docs/other-commands.md index 0c6c868..52b3a95 100644 --- a/docs/other-commands.md +++ b/docs/other-commands.md @@ -1,6 +1,6 @@ -## Other commands +# Other commands -### policy +## policy You can use the `s3-credentials policy` command to generate the JSON policy document that would be used without applying it. The command takes one or more required bucket names and a subset of the options available on the `create` command: @@ -18,7 +18,7 @@ With none of these options it defaults to a read-write policy. ... ``` -### whoami +## whoami To see which user you are authenticated as: @@ -36,7 +36,7 @@ s3-credentials whoami --auth auth.json "Arn": "arn:aws:iam::462092780466:user/s3.read-only.static.niche-museums.com" } ``` -### list-users +## list-users To see a list of all users that exist for your AWS account: @@ -48,7 +48,7 @@ Add `--nl` to collapse these to single lines as valid newline-delimited JSON. Add `--csv` or `--tsv` to get back CSV or TSV data. -### list-buckets +## list-buckets Shows a list of all buckets in your AWS account. @@ -146,7 +146,7 @@ A bucket with `public_access_block` might look like this: } ``` -### list-bucket +## list-bucket To list the contents of a bucket, use `list-bucket`: @@ -173,7 +173,7 @@ You can use the `--prefix myprefix/` option to list only keys that start with a The commmand accepts the same `--nl`, `--csv` and `--tsv` options as `list-users`. -### list-user-policies +## list-user-policies To see a list of inline policies belonging to users: @@ -208,7 +208,7 @@ You can pass any number of usernames here. If you don't specify a username the t s3-credentials list-user-policies -### list-roles +## list-roles The `list-roles` command lists all of the roles available for the authenticated account. @@ -325,7 +325,7 @@ Add `--nl` to collapse these to single lines as valid newline-delimited JSON. Add `--csv` or `--tsv` to get back CSV or TSV data. -### delete-user +## delete-user In trying out this tool it's possible you will create several different user accounts that you later decide to clean up. @@ -342,7 +342,7 @@ User: s3.read-write.simonw-test-bucket-10 ``` You can pass it multiple usernames to delete multiple users at a time. -### put-object +## put-object You can upload a file to a key in an S3 bucket using `s3-credentials put-object`: @@ -359,7 +359,7 @@ The `Content-Type` on the uploaded object will be automatically set based on the echo "

Hello World

" | \ s3-credentials put-object my-bucket hello.html - --content-type "text/html" -### get-object +## get-object To download a file from a bucket use `s3-credentials get-object`: @@ -370,7 +370,7 @@ This defaults to outputting the downloaded file to the terminal. You can instead s3-credentials get-object my-bucket hello.txt -o /path/to/hello.txt -### set-cors-policy and get-cors-policy +## set-cors-policy and get-cors-policy You can set the [CORS policy](https://docs.aws.amazon.com/AmazonS3/latest/userguide/cors.html) for a bucket using the `set-cors-policy` command. S3 CORS policies are set at the bucket level - they cannot be set for individual items. diff --git a/docs/policy-documents.md b/docs/policy-documents.md index a98a51c..edd893a 100644 --- a/docs/policy-documents.md +++ b/docs/policy-documents.md @@ -1,8 +1,8 @@ -## Policy documents +# Policy documents The IAM policies generated by this tool for a bucket called `my-s3-bucket` would look like this: -### read-write (default) +## read-write (default) -### --read-only +## `--read-only` -### --write-only +## `--write-only` -### --prefix my-prefix/ +## `--prefix my-prefix/` -### --prefix my-prefix/ --read-only +## `--prefix my-prefix/ --read-only` -### --prefix my-prefix/ --write-only +## `--prefix my-prefix/ --write-only`