From 0debd985e3a5318bd67381bbde81cd5473d7a03d Mon Sep 17 00:00:00 2001 From: ZeljkoBenovic Date: Sun, 19 Nov 2023 00:04:47 +0100 Subject: [PATCH] updated readme --- README.md | 72 +++++++++++++++++++++++++++++----------------------- conf/conf.go | 2 +- 2 files changed, 41 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index c25d8da..f5ec040 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,72 @@ # AWS Commander -A tool used for running bash scripts on AWS EC2 instances, leveraging AWS Systems Manager > Run Command feature. -User can load a bash script or define a single command, that will execute on all instances with defined instance ID. +A tool used for easier automation of the AWS EC2 instances, leveraging AWS Systems Manager - Run Command feature. +Supported scripts: +* One-liner bash command +* Bash script loaded from a local filesystem +* Ansible playbook loaded from a local filesystem + +The command/script/playbook will run across all EC2 instances simultaneously. +EC2 instances, for now, can be selected only by their IDs. Support for selection by tags will be +added in future versions. + ## Prerequisites -* The **AmazonSSMManagedInstanceCore** must be placed on all instances that need to be managed via this tool. -* AWS API credentials defined in *aws credentials* file or as environment variables +* The **AmazonSSMManagedInstanceCore** IAM role, attached on all EC2 instances. +* Authenticated AWS CLI session ## Usage ### AWS credentials -AWS credentials can be pulled from environment variables or from aws credentials file. -To define a which profile from credentials file should be used, set `aws-profile` flag. By default, it is set to `default`. -Environment variables with credentials that can be set: -* `AWS_ACCESS_KEY_ID` - the aws access key id -* `AWS_SECRET_ACCESS_KEY` - the access key secret -* `AWS_SESSION_TOKEN` - the session token (optional) - +AWS access must be authenticated via `aws cli`. ### General Parameters -* `aws-profile` - AWS profile as defined in *aws credentials* file. Default: `default` -* `aws-zone` - AWS zone in which EC2 instances reside. Default: `eu-central-1` -* `instances` - instance IDs, separated by comma (,). This is a mandatory flag. -* `log-level` - the level of logging output (info, debug, error). Default: `info` -* `output` - a file name to write the output result of a command/script. Default: `console output` -* `mode` - switch between modes - Bash script or Ansible playbook. Default: `bash` +* `log-level` - the level of logging output (`info`, `debug`, `error`). Default: `info` +* `mode` - commands running mode (`bash`, `ansible`) Default: `bash` +* `profile` - AWS profile as defined in *aws credentials* file. +* `region` - AWS region in which EC2 instances reside. +* `ids` - instance IDs, separated by comma (`,`). This is a mandatory flag. +* `max-wait` - maximum wait time in seconds to run the command Default: `30` +* `max-exec` - maximum wait time in seconds to get command result Default: `300` ### Running Bash scripts * `cmd` - one-liner bash command that will be executed on EC2 instances. * `script` - the location of bash script file that will run on EC2 instances. -* `mode` - for running bash scripts `mode` can be omitted as the default value is `bash` - -If both `cmd` and `script` flags are defined, `script` will take precedence, and `cmd` will be disregarded. +* `mode` - for running Bash script or oneliner `mode` can be omitted or set to `bash` #### Example ```bash +# AWS authentication +aws sso login --profile test-account + +# oneliner aws-commander -instances i-0bf9c273c67f684a0,i-011c9b3e3607a63b5,i-0e53e37f7b34517f5,i-0f02ca10faf8f349e -cmd "cd /tmp && ls -lah" -aws-profile test-account + +# or bash script +aws-commander -instances i-0bf9c273c67f684a0,i-011c9b3e3607a63b5,i-0e53e37f7b34517f5,i-0f02ca10faf8f349e -script ./script.sh -aws-profile test-account ``` ### Running Ansible Playbook * `playbook` - the location of Ansible playbook that will be executed on EC2 instances. +* `ansible-url` - the URL locaction of the Ansible playbook +* `extra-vars` - comma delimited, key value pairs of Ansible variables * `dryrun` - when set to true, Ansible playbook will run and the output will be shown, but - no data will be changed. + no data will be changed. Default: `false` * `mode` - for running Ansible playbook `mode` must be set to `ansible` -#### Ansible prerequisites -Every EC2 instance, that should run Ansible playbook, must have Ansible already installed. -If Ansible is not installed, the deployment will fail. -You can use `bash` mode to simply install Ansible from your OS package manager before running the playbook. - #### Example ```bash -## if Ansible is not installed on host - install Ansible -aws-commander -instances i-0bf9c273c67f684a0,i-011c9b3e3607a63b5,i-0e53e37f7b34517f5,i-0f02ca10faf8f349e -cmd "sudo apt install -y ansible" -aws-profile test-account -aws-zone us-west-2 -## run playbook -aws-commander -instances i-0bf9c273c67f684a0,i-011c9b3e3607a63b5,i-0e53e37f7b34517f5,i-0f02ca10faf8f349e -mode ansible -playbook scripts/nodes-restart.yaml -aws-profile test-account -aws-zone us-west-2 +# AWS authentication +aws sso login + +# run local playbook +aws-commander -instances i-0bf9c273c67f684a0,i-011c9b3e3607a63b5,i-0e53e37f7b34517f5,i-0f02ca10faf8f349e -mode ansible -playbook scripts/init.yaml -extra-vars foo=bar,faz=baz + +# or from url +aws-commander -instances i-0bf9c273c67f684a0,i-011c9b3e3607a63b5,i-0e53e37f7b34517f5,i-0f02ca10faf8f349e -mode ansible -ansible-url https://example.com/init.yaml -extra-vars foo=bar,faz=baz ``` #### Missing features -Currently, running the Ansible playbook from a remote location via URL / S3 is not supported. -It will be supported in the future release. +* Select EC2 instances using instance tags diff --git a/conf/conf.go b/conf/conf.go index b88d0a9..84d4c04 100644 --- a/conf/conf.go +++ b/conf/conf.go @@ -103,7 +103,7 @@ func (c *Config) processFlags() { flag.Int64Var(&c.CommandExecMaxWait, "max-exec", c.CommandExecMaxWait, "maximum command execution time in seconds", ) - flag.BoolVar(&c.AnsibleDryRun, "dry-run", c.AnsibleDryRun, + flag.BoolVar(&c.AnsibleDryRun, "dryrun", c.AnsibleDryRun, "run ansible in dry-run mode", ) flag.StringVar(&c.AnsibleExtraVars, "extra-vars", c.AnsibleExtraVars,