view release on metacpan or  search on metacpan

lib/AWS/CLIWrapper.pm  view on Meta::CPAN

sub transfer           { shift->_execute('transfer', @_) }
sub translate          { shift->_execute('translate', @_) }
sub verifiedpermissions { shift->_execute('verifiedpermissions', @_) }
sub voice_id           { shift->_execute('voice-id', @_) }
sub vpc_lattice        { shift->_execute('vpc-lattice', @_) }
sub waf                { shift->_execute('waf', @_) }
sub waf_regional       { shift->_execute('waf-regional', @_) }
sub wafv2              { shift->_execute('wafv2', @_) }
sub wellarchitected    { shift->_execute('wellarchitected', @_) }
sub wisdom             { shift->_execute('wisdom', @_) }
sub workdocs           { shift->_execute('workdocs', @_) }
sub worklink           { shift->_execute('worklink', @_) }
sub workmail           { shift->_execute('workmail', @_) }
sub workmailmessageflow { shift->_execute('workmailmessageflow', @_) }
sub workspaces         { shift->_execute('workspaces', @_) }
sub workspaces_web     { shift->_execute('workspaces-web', @_) }
sub xray               { shift->_execute('xray', @_) }

1;

__END__

=encoding utf-8

=head1 NAME

AWS::CLIWrapper - Wrapper module for aws-cli

=head1 SYNOPSIS

    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};
    }

=head1 DESCRIPTION

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)

=head1 METHODS

=over 4

=item B<new>($param:HashRef)

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.

=item B<accessanalyzer>($operation:Str, $param:HashRef, %opt:Hash)

=item B<account>($operation:Str, $param:HashRef, %opt:Hash)

=item B<acm>($operation:Str, $param:HashRef, %opt:Hash)

=item B<acm_pca>($operation:Str, $param:HashRef, %opt:Hash)

=item B<alexaforbusiness>($operation:Str, $param:HashRef, %opt:Hash)

=item B<amp>($operation:Str, $param:HashRef, %opt:Hash)

=item B<amplify>($operation:Str, $param:HashRef, %opt:Hash)

=item B<amplifybackend>($operation:Str, $param:HashRef, %opt:Hash)

=item B<amplifyuibuilder>($operation:Str, $param:HashRef, %opt:Hash)

=item B<apigateway>($operation:Str, $param:HashRef, %opt:Hash)

=item B<apigatewaymanagementapi>($operation:Str, $param:HashRef, %opt:Hash)

=item B<apigatewayv2>($operation:Str, $param:HashRef, %opt:Hash)

=item B<appconfig>($operation:Str, $param:HashRef, %opt:Hash)

=item B<appconfigdata>($operation:Str, $param:HashRef, %opt:Hash)

=item B<appfabric>($operation:Str, $param:HashRef, %opt:Hash)

=item B<appflow>($operation:Str, $param:HashRef, %opt:Hash)

=item B<appintegrations>($operation:Str, $param:HashRef, %opt:Hash)

lib/AWS/CLIWrapper.pm  view on Meta::CPAN

    })

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.

=back

=head1 ENVIRONMENT

=over 4

=item HOME: used by default by /usr/bin/aws utility to find it's credentials (if none are specified)

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.

=item AWS_CLIWRAPPER_TIMEOUT

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.

=item AWS_CLIWRAPPER_CATCH_ERROR_PATTERN

If this variable is set, AWS::CLIWrapper will retry `aws-cli` execution if stdout output
of failed `aws-cli` command matches the pattern. See L<ERROR HANDLING>.

=item AWS_CLIWRAPPER_CATCH_ERROR_RETRIES

How many times to retry command execution if an error was caught. Default is 3.

=item AWS_CLIWRAPPER_CATCH_ERROR_MIN_DELAY

Minimal delay before retrying command execution if an error was caught, in seconds.

Default is 3.

=item AWS_CLIWRAPPER_CATCH_ERROR_MAX_DELAY

Maximal delay before retrying command execution, in seconds. Default is 10.

=item AWS_CONFIG_FILE

=item AWS_ACCESS_KEY_ID

=item AWS_SECRET_ACCESS_KEY

=item AWS_DEFAULT_REGION

See documents of aws-cli.

=back

=head1 ERROR HANDLING

=over 4

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 L<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.

=back 

=head1 AUTHOR

HIROSE Masaaki E<lt>hirose31 _at_ gmail.comE<gt>

=head1 REPOSITORY

L<https://github.com/hirose31/AWS-CLIWrapper>

  git clone git://github.com/hirose31/AWS-CLIWrapper.git

patches and collaborators are welcome.

=head1 SEE ALSO

L<http://aws.amazon.com/cli/>,
L<https://github.com/aws/aws-cli>,
L<http://docs.aws.amazon.com/AWSEC2/latest/APIReference/Welcome.html>,
L<https://github.com/boto/botocore>,

=head1 LICENSE

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut

# for Emacsen
# Local Variables:
# mode: cperl
# cperl-indent-level: 4
# indent-tabs-mode: nil
# coding: utf-8
# End:

# vi: set ts=4 sw=4 sts=0 et ft=perl fenc=utf-8 ff=unix :