AWS::CLIWrapper - Wrapper module for aws-cli
use AWS::CLIWrapper; my $aws = AWS::CLIWrapper->new( region => 'us-west-1', ); my $res = $aws->ec2( 'describe-instances' => { instance_ids => ['i-XXXXX', 'i-YYYYY'], }, timeout => 18, # optional. default is 30 seconds ); if ($res) { for my $rs ( @{ $res->{Reservations} }) { for my $is (@{ $rs->{Instances} }) { print $is->{InstanceId},"\n"; } } } else { warn $AWS::CLIWrapper::Error->{Code}; warn $AWS::CLIWrapper::Error->{Message}; }
AWS::CLIWrapper is wrapper module for aws-cli (recommend: awscli >= 1.0.0, requires: >= 0.40.0).
AWS::CLIWrapper is a just wrapper module, so you can do everything what you can do with aws-cli.
See note below about making sure AWS credentials are accessible (especially under crond)
Constructor of AWS::CLIWrapper. Acceptable AWS CLI params are:
region region_name:Str profile profile_name:Str endpoint_url endpoint_url:Str
Additionally, the these params can be used to control the wrapper behavior:
nofork Truthy to avoid forking when executing `aws` timeout `aws` execution timeout croak_on_error Truthy to croak() with the error message when `aws` exits with non-zero code catch_error_pattern Regexp pattern to match for error handling. catch_error_retries Retries for handling errors. catch_error_min_delay Minimal delay before retrying `aws` call when an error was caught. catch_error_max_delay Maximal delay before retrying `aws` call.
See below for more detailed explanation.
AWS::CLIWrapper provides methods same as services of aws-cli. Please refer to `aws help`.
First arg "operation" is same as operation of aws-cli. Please refer to `aws SERVICE help`.
Second arg "param" is same as command line option of aws-cli. Please refer to `aws SERVICE OPERATION help`.
Key of param is string that trimmed leading "--" and replaced "-" to "_" for command line option (--instance-ids -> instance_ids). Value of param is SCALAR or ARRAYREF or HASHREF.
You can specify (boolean) parameter by $AWS::CLIWrapper::true or $AWS::CLIWrapper::false.
(boolean)
$AWS::CLIWrapper::true
$AWS::CLIWrapper::false
my $res = $aws->ec2('assign-private-ip-addresses', { network_interface_id => $eni_id, private_ip_addresses => [ $private_ip_1, $private_ip_2 ], allow_reassignment => $AWS::CLIWrapper::true, })
Special case: several OPERATIONs take a single arg. For example "aws s3api get-object ... output_file". In this case, You can specify below using output_file key:
output_file
my $res = $aws->s3api('get-object', { bucket => 'my-bucket', key => 'blahblahblah', output_file => '/path/to/output/file', })
Special case: s3 OPERATION takes one or two arguments in addition to options. For example "aws s3 cp LocalPath s3://S3Path". Pass an extra ARRAYREF to the s3 method in this case:
my $res = $aws->s3('cp', ['LocalPath', 's3://S3Path'], { exclude => '*.bak', })
Special case: s3 OPERATION can take --include and --exclude option multiple times. For example "aws s3 sync --exclude 'foo' --exclude 'bar' LocalPath s3://S3Path", Pass ARRAYREF as value of include or exclude in this case:
include
exclude
my $res = $aws->s3('sync', ['LocalPath', 's3://S3Path'], { exclude => ['foo', 'bar'], })
Third arg "opt" is optional. Available key/values are below:
timeout => Int Maximum time the "aws" command is allowed to run before aborting. default is 30 seconds, unless overridden with AWS_CLIWRAPPER_TIMEOUT environment variable. nofork => Int (>0) Call IPC::Cmd::run vs. IPC::Cmd::run_forked (mostly useful if/when in perl debugger). Note: 'timeout', if used with 'nofork', will merely cause an alarm and return. ie. 'run' will NOT kill the awscli command like 'run_forked' will. croak_on_error => Int (>0) When set to a truthy value, this will make AWS::CLIWrapper to croak() with error message when `aws` command exits with non-zero status. Default behavior is to set $AWS::CLIWrapper::Error and return. catch_error_pattern => RegExp When defined, this option will enable catching `aws-cli` errors matching this pattern and retrying `aws-cli` command execution. Environment variable AWS_CLIWRAPPER_CATCH_ERROR_PATTERN takes precedence over this option, if both are defined. Default is undef. catch_error_retries => Int (>= 0) When defined, this option will set the number of retries to make when `aws-cli` error was caught with catch_error_pattern, before giving up. Environment variable AWS_CLIWRAPPER_CATCH_ERROR_RETRIES takes precedence over this option, if both are defined. 0 (zero) retries is a valid way to turn off error catching via environment variable in certain scenarios. Negative values are invalid and will be reset to default. Default is 3. catch_error_min_delay => Int (>= 0) When defined, this option will set the minimum delay in seconds before attempting a retry of failed `aws-cli` execution when the error was caught. Environment variable AWS_CLIWRAPPER_CATCH_ERROR_MIN_DELAY takes precedence over this option, if both are defined. 0 (zero) is a valid value. Negative values are invalid and will be reset to default. Default is 3. catch_error_max_delay => Int (>= 0) When defined, this option will set the maximum delay in seconds before attempting a retry of failed `aws-cli` execution. Environment variable AWS_CLIWRAPPER_CATCH_ERROR_MAX_DELAY takes precedence over this option, if both are defined. 0 (zero) is a valid value. Negative values are invalid and will be reset to default. If catch_error_min_delay is greater than catch_error_max_delay, both are set to catch_error_min_delay value. Default is 10.
Special note: cron on Linux will often have a different HOME "/" instead of "/root" - set $ENV{'HOME'} to use the default credentials or specify $ENV{'AWS_CONFIG_FILE'} directly.
If this variable is set, this value will be used instead of default timeout (30 seconds) for every invocation of `aws-cli` that does not have a timeout value provided in the options argument of the called function.
If this variable is set, AWS::CLIWrapper will retry `aws-cli` execution if stdout output of failed `aws-cli` command matches the pattern. See "ERROR HANDLING".
How many times to retry command execution if an error was caught. Default is 3.
Minimal delay before retrying command execution if an error was caught, in seconds.
Default is 3.
Maximal delay before retrying command execution, in seconds. Default is 10.
See documents of aws-cli.
By default, when `aws-cli` exits with an error code (> 0), AWS::CLIWrapper will set the error code and message to $AWS::CLIWrapper::Error (and optionally croak), thus relaying the error to calling code. While this approach is beneficial 99% of the time, in some use cases `aws-cli` execution fails for a temporary reason unrelated to both calling code and AWS::CLIWrapper, and can be safely retried after a short delay.
One of this use cases is executing `aws-cli` on AWS EC2 instances, where `aws-cli` retrieves its configuration and credentials from the API exposed to the EC2 instance; at certain times these credentials may be rotated and calling `aws-cli` at exactly the right moment will cause it to fail with `Unable to locate credentials` error.
To prevent this kind of errors from failing the calling code, AWS::CLIWrapper allows configuring an RegExp pattern and retry `aws-cli` execution if it fails with an error matching the configured pattern.
The error catching pattern, as well as other configuration, can be defined either as AWS::CLIWrapper options in the code, or as respective environment variables (see ENVIRONMENT).
The actual delay before retrying a failed `aws-cli` execution is computed as a random value of seconds between catch_error_min_delay (default 3) and catch_error_max_delay (default 10). Backoff is not supported at this moment.
HIROSE Masaaki <hirose31 _at_ gmail.com>
https://github.com/hirose31/AWS-CLIWrapper
git clone git://github.com/hirose31/AWS-CLIWrapper.git
patches and collaborators are welcome.
http://aws.amazon.com/cli/, https://github.com/aws/aws-cli, http://docs.aws.amazon.com/AWSEC2/latest/APIReference/Welcome.html, https://github.com/boto/botocore,
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install AWS::CLIWrapper, copy and paste the appropriate command in to your terminal.
cpanm
cpanm AWS::CLIWrapper
CPAN shell
perl -MCPAN -e shell install AWS::CLIWrapper
For more information on module installation, please visit the detailed CPAN module installation guide.