Warning

There is no "stable" version. This tool is under development. The only version by the moment is 0.4.0.

cloudsnake 🐍

Wrapping some awscli commands with beautiful TUI

Build with ❤ in Python

Table of Contents generated with DocToc

• Why cloudsnake
• Badges
• Available implementations
• Examples
  • Connect to the EC2 instance using SSM
    • Example
  • Connect to the RDS instance using IAM authentication db token
    • Download the cert
    • Connect to the instance
    • Example
• Installation
  • Using pip
  • Using pipx with virtualenv (recommended)
  • Local install
• Uninstall
  • Using pip
  • Using pipx
• Local development
  • Local run with poetry
  • Run & install pre-commit
  • Testing
• TO DO
• Improvements
  • Positional flags
    • Actually
    • Wants
• TOP LINKS
• Poetry commands
• Cloudsnake commands
• License

Why cloudsnake

The main intention of this tool is to continue improving my python skills, get to know the AWS boto3 SDK better, and learn how to create a CLI using typer, rich, and textual. The tool tries to implement some commands from the official AWS cli (aws cli), adding my own logic and with highlights (pretty print json output/table with typer/rich).

Important

Do not try to use part of this code in a productive app as it is currently untested. (visit #TO DO section). I also don't know if this is the best way to use any of the tools that the application uses (boto3, typer, rich...), that is why any PR is welcome, it will be appreciated so I can continue improving my skills.

Important

In the end, the purpose of this tool is also to be able to facilitate the day to day, creating tools that help me to operate the platform. For example, to quickly connect to EC2, RDS...etc.

Badges

Code
CI/CD
Package
Meta
Linter

Available implementations

• Connect to EC2 instances using SSM. You can pass the instance id (--target) or use the interactive menu (--with-instance-selector)

• Connect to the RDS instances using IAM db authentication.

See examples in the next section

Examples

For the examples, you need to be authenticated to AWS account using your local credentials.

In your terminal, set the corresponding AWS_PROFILE=MyProfile if not using the default. (~/.aws/credentials)

Connect to the EC2 instance using SSM

cloudsnake ssm start-session --with-instance-selector # will print all your instances in a terminal menu
cloudsnake ssm start-session --target i-XXXXXX  # connect to the instance specifying the target id

Example

Connect to the RDS instance using IAM authentication db token

Please follow this instructions to setup your RDS IAM authentication.

Download the cert

By default, cloudsnake forces to use TLS/SSL connections.

cloudsnake rds download-cert --save-path /tmp

Other region:

cloudsnake --region us-east-1 download-cert --save-path /tmp

Connect to the instance

Example for the region eu-west-1:

cloudsnake rds connect -h XXXXX.XXXXXX.eu-west-1.rds.amazonaws.com -u ADMIN --cert /tmp/rds-cert-eu-west-1.pem

Example

Installation

Using pip

pip3 install cloudsnake

Warning

Probably your system will not allow this installation method due to a broken system package.

Example error

Error:

error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try 'pacman -S
python-xyz', where xyz is the package you are trying to
install.
If you wish to install a non-Arch-packaged Python package,
create a virtual environment using 'python -m venv path/to/venv'.
Then use path/to/venv/bin/python and path/to/venv/bin/pip.

If you wish to install a non-Arch packaged Python application,
it may be easiest to use 'pipx install xyz', which will manage a
virtual environment for you. Make sure you have python-pipx
installed via pacman.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

Using pipx with virtualenv (recommended)

Install pipx with your system package manager (apt, dnf, pacman...).

pipx install cloudsnake

Local install

git clone https://github.com/containerscrew/cloudsnake.git
cd cloudsnake
make pipx-local-install

Uninstall

Using pip

pip3 uninstall cloudsnake

Using pipx

pipx uninstall cloudsnake

Local development

Local run with poetry

git clone https://github.com/containerscrew/cloudsnake.git
cd cloudsnake
make update
make run

Run & install pre-commit

make pre-commit-install
make run-pre-commit

Testing

git clone https://github.com/containerscrew/cloudsnake.git
cd cloudsnake
make run-tests

TO DO

• Documentation with docstrings
• Add more tests with pytest and boto3 mock
• Remove @classmethod
• Ruff linter
• Cliff: changelog
• Pipelines with github actions. Automatic publish new version to pypip
• Other...

Improvements

Positional flags

Actually

cloudsnake --log-level debug --region us-east-1 --profile default ec2 describe-instance

Wants

cloudsnake ec2 describe-instances --log-level debug --region us-east-1 --profile default --other-specific-flags-for-this-subdommand

TOP LINKS

links.md

Poetry commands

poetry.md

Cloudsnake commands

cloudsnake --help
cloudsnake ec2 describe-instances --filters "Name=instance-state-name,Values=running" --query 'Reservations[*].Instances[*].{Instance:InstanceId,VpcId:VpcId,AZ:Placement.AvailabilityZone,Name:Tags[?Key==`Name`]|[0].Value}' --output json
cloudsnake ec2 describe-instances --filters "Name=instance-state-name,Values=running" --output json
cloudsnake ec2 describe-instances --filters "Name=instance-state-name,Values=running" --query 'Reservations[*].Instances[*].{InstanceName:Tags[?Key==`Name`]|[0].Value}' --output json
cloudsnake ec2 describe-instances  --filters "Name=instance-state-name,Values=running" --query 'Reservations[*].Instances[*].Tags[?Key==`Name`].Value[][]'
cloudsnake rds describe-db-instances --query 'DBInstances[*].DBInstanceIdentifier'
cloudsnake ssm start-session --with-instance-selector
cloudsnake ssm start-session --target i-xxxxxxx

License

cloudsnake is distributed under the terms of the MIT license.