Home

Getting started

fzfaws is super simple to get started once installed. If you haven't installed yet, checkout README for installation instructions. After installation, you'll need to check 2 things and you are ready to rock!

Configure IAM credentials

If you haven't configured your IAM credentials through aws-cli, make sure to get the access key and secret access key with proper permissions from aws console and configure them under your preference.

aws configure

If you don't have aws-cli on the machine, you'll need to configure this manually. Change the following placeholder and run the command. Or alternatively set aws ENV variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_DEFAULT_REGION.

cat << EOF > $HOME/.aws/config
[default]
region = <Your prefered region> # e.g. us-east-1
output = json
EOF

cat << EOF > $HOME/.aws/credentials
[default]
aws_access_key_id = <Your access key>
aws_secret_access_key = <Your secret access key>
EOF

Inform fzfaws the location to look for ssh pem keys

If you store the ssh pem keys under $HOME/.ssh, then you can skip this step. fzfaws can be configured through both ENV variables and a config file. By default, when attempting to ssh into instance through fzfaws, fzfaws will look for key pairs under ~/.ssh. If you store the key pairs somewhere else, make sure to configure it before running fzfaws ec2 ssh.

ENV variable

Use this method if you just want a quick start and tryout fzfaws to see how it works. Otherwise, I suggest to configure the location in the fzfaws configuration file.

# reference home directory using "~"
# e.g. ~/.ssh
export FZFAWS_EC2_KEYPAIRS=<Location for key pairs>

Configuration file

The suggested way to configure fzfaws is through the configuration file, there is a dedicated section in the configuration file to set the key pair location. Checkout customization for detail.

services:
  ec2:
    # use "~" to reference home directory
    keypair: ~/.ssh

Basic usage

For more advanced usage and explanation please visit individual service wiki page.

Getting help

fzfaws doesn't have a man page at this point, you could find help manual by running --help or -h flag. It provides different level of help page as demonstrated below.

fzfaws --help
fzfaws cloudformation --help
fzfaws cloudformation ls --help

Using different profile or region

Sometimes for specific service, you may want to use a different profile or region due to permissions or service locations, fzfaws support any level of configuration of region, profile settings, consult the sample configuration file for more details. You can also override the configuration file by passing in options.

# You can explicitly specify the region to use
fzfaws ec2 ssh --region us-east-2
# You can also pass the flag without argument to select a region through fzf
fzfaw ec2 ssh --region
# Same applies to profile
fzfaws s3 upload --profile

Customization

fzfaws could be configured through both ENV variables and configuration file. I don't suggest customizing it through ENV variables, but if you are interested in that way, you could reference all the ENV variables here.

Run the following command to obtain the configuration file. It will copy the latest configuration file to ~/.config/fzfaws/fzfaws.yml, and it does respect $XDG_CONFIG_HOME.

fzfaws --copy-config

The configuration file contains all the comments and instructions to get you started, if you have any concerns or questions feel free to fire up issues.

The settings priority from lowerest to highest: ENV variable -> Gloabal settings in fzfaws.yml -> Service settings in fzfaws.yml -> Command line options

Docker image

There is also a docker image for fzfaws with some limitations. Reference the image here.

docker pull kazhala/fzfaws:latest

The docker image is not aware of your current aws credentials and thus you need to set the env variable when creating the container.

docker container run -it --rm --name fzfaws \
  -e AWS_ACCESS_KEY_ID=<Your access key> \
  -e AWS_SECRET_ACCESS_KEY=<Your secret access key> \
  -e AWS_DEFAULT_REGION=<Your region> \
  kazhala/fzfaws:latest \
  cloudformation ls

The docker image doesn't come with aws-cli hence you cannot run commands like fzfaws s3 upload --sync which utilise aws-cli under the hood. And because it's a container, it doesn't have any of the files in your system, if you want to upload a file or maybe creating a cloudformation stack, you need to bind mount the directory to the container /root directory. Same applies to ssh pem keys, if you want to use fzfaws ec2 ssh you'll need to bind mount the key directory to /root/.ssh for fzfaws to discover it.

# upload local file to s3 bucket
docker container run -it --rm --name fzfaws \
  -e AWS_ACCESS_KEY_ID=111111 \
  -e AWS_SECRET_ACCESS_KEY=222222 \
  -e AWS_DEFAULT_REGION=ap-southeast-2 \
  -v "$PWD":/root \
  kazhala/fzfaws:latest \
  s3 upload

Extending functionalities

fzfaws has a limited sets of functionalities. There are some functionalities I intentionally left out due to not having a good experience integrating with the general fzfaws flow (linear flow) and some functionalities I may not even be aware of. Feel free to fire up feature request, I'm open to discussion.

To overcome this, fzfaws has ls command for all services it supports. The ls command doesn't provide any actual functionalities, rather it just print information based on the flags and user selection through fzf. You could integrate the ls command into your own script and leveraging aws-cli to achieve the missing functionalities.

# print the selected instance id
fzfaws ec2 ls --instanceid

The ls command is still considered a WIP as it also only contains a limited sets of flags, ideally I would like to add more flags to support more information fetching.

Full Example

Although fzfaws provides option to enable "termination protection" during cloudformation stack creation, it doesn't have the functionality to update this setting once created. Below is a bash example to cover this functionality.

#!/usr/bin/env bash

# exit on failure
set -e

# select and store the name of the stack
selected_stack=$(python3 -m fzfaws cloudformation ls --name)
update_action="--no-enable-termination-protection"

# stop the script if no selection was made
[[ -z "${selected_stack}" ]] && exit 1

case "$1" in
  enable)
    update_action="--enable-termination-protection"
    ;;
  disable)
    update_action="--no-enable-termination-protection"
    ;;
esac

aws cloudformation update-termination-protection "${update_action}" --stack-name "${selected_stack}"
aws cloudformation describe-stacks --stack-name "${selected_stack}"

Obviously there's a lot more functionality that could be achieved, checkout individual service's help manual to consult the ls options, fzfaws [service] ls --help.