Skip to content

Quick Start

Installation

pip3 install balcony
Set your AWS credentials
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_DEFAULT_REGION=us-west-2

Run balcony on Docker

You may choose to run balcony with Docker

Shell Autocompletion

balcony --help

# give your shell as an argument
balcony --show-completion <your-shell>

# run the output on your shell to activate the autocompletion

balcony --help

# give your shell as an argument
balcony --install-completion <your-shell>

# restart your shell

About AWS credentials

balcony uses your shell environment for the AWS credentials

See the active profile with awscli
aws sts get-caller-identity
Set your AWS profile and region
export AWS_PROFILE=default
export AWS_REGION=us-east-1
Set your AWS credentials
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_DEFAULT_REGION=us-west-2

List all available AWS Services

balcony aws

Remember to get --help

balcony --help
balcony aws --help

balcony --help output screenshot

List all Resource Nodes of a Service

balcony aws iam

balcony aws ec2

See the documentation of a Resource Node and its Operations

balcony aws iam Policy -l
# or
balcony aws iam Policy --list
# or to open it on a pager
balcony aws iam Policy -ls

Read a Resource Node

balcony aws iam Policy

# if you are curious to see what's going on
# under the hood, enable the debug messages
balcony aws iam Policy -d
# or
balcony aws iam Policy --debug

Read a Resource Nodes specific operation

balcony aws iam Policy get

balcony aws iam Policy list

Use --paginate, -p option for pagination

Using the --paginate, -p option allows you to paginate the outputs if they're truncated. If you don't set this flag you may get incomplete data.

# Get all instances available on the AWS Account
balcony aws ec2 Instances \
    -js "DescribeInstances[*].Reservations[*].Instances[]" \
    --paginate --debug

Filter generated parameters with UNIX style --pattern matching

Important note on --pattern option

This option only filters the generated api parameters for the given operation.

Because of this --pattern matching is only applied to operations with required parameters.

balcony aws iam Policy --pattern "*service-role/*"

# supports multiple patterns
balcony aws iam Policy --pattern "*service-role/*" --pattern "*prod-*"

Use JMESPath queries for the json data

You can use JMESPath (like jq) to query the output data.

If you are going to use the balcony as a part of your automation scripts, you should use this option to have a more precise output.

balcony aws iam Policy \
    --jmespath-selector "GetPolicy[*].Policy"
# or
balcony aws iam Policy \
    -js "GetPolicy[*].Policy"

Use --format option for customized output

Using the --format option allows you to string format the output json data.

Must be used with -js | --jmespath-selector option because --format option only works with a list of dictionaries of same structure.

Given format string will be applied to each dict in the list, allowing you to use f-strings notation.

# create stop-instances script for running instances
balcony aws ec2 Instances \
    -js "DescribeInstances[*].Reservations[*].Instances[?State.Name=='running'][][]" \
    --format "aws ec2 stop-instances --instance-ids {InstanceId} # {Tags}"

# create delete-policy script
balcony aws iam Policy \
    --jmespath-selector "GetPolicy[*].Policy" \
    --format 'aws iam delete-policy --policy-arn "{Arn}" --version "{DefaultVersionId}"'

Use --output, -o option for writing the output to a file

Using the --output, -o option allows you to save the output data to a file.

# Get all instances available on the AWS Account
balcony aws ec2 Instances \
    -js "DescribeInstances[*].Reservations[*].Instances[]" \
    --paginate --debug \
    --output /tmp/balcony-output.json