| Name | awsrun JSON |
| Version |
3.1.0
JSON |
| download |
| home_page | None |
| Summary | CLI and library to execute commands over one or more AWS or Azure accounts concurrently. |
| upload_time | 2024-07-03 14:54:53 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | Copyright 2019 FMR LLC Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
aws
azure
cli
command runner
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://github.com/fidelity/awsrun/actions/workflows/ci.yml)
[](https://github.com/psf/black)
# awsrun & azurerun
CLI tool and library to concurrently execute user-defined commands across AWS
accounts or Azure subscriptions.
> **Note**
> As of release 3.0.0, installation has changed with the introduction of
> optional dependencies. Previously, `pip install awsrun` would install all
> dependencies needed for `awsrun`, `azurerun`, and all of the bundled
> commands. You **must** now specify the optional dependencies when installing:
> `pip install "awsrun[aws,azure]"`. See Installation for more details.
## Overview
Awsrun/azurerun is both a CLI tool and Python package that can be used to
execute commands concurrently over one or more AWS accounts or Azure
subscriptions. Commands are user-defined Python modules that implement a simple
interface to abstract away the complications of obtaining credentials for Boto3
and Azure SDK sessions—especially when using SAML authentication and/or
cross-account access in AWS. The key features of awsrun/azurerun include the
following:
**Concurrent Account Processing**:
Run a command concurrently across subset or all of your accounts/subscriptions.
A worker pool manages the execution to ensure accounts/subscriptions are
processed quickly, so you don't have to wait for them to be processed one at a
time. Process hundreds of accounts in a few minutes.
**SAML and Cross-Account Access**:
Tired of dealing with AWS temporary STS credentials with SAML and cross-account
authentication? Use any of the included credential plug-ins based on your needs,
or build your own plug-in to provide credentials for your command authors. Don't
use SAML? Define profiles in your AWS credentials file instead. With Azure, the
default credentials are obtained via the Azure CLI or interactively via the browser.
**Built-in Command for AWS CLI & Azure CLI**:
Ever wish you could run the standard AWS CLI tool or Azure CLI tool across
multiple accounts/subscriptions? Now you can using the included
[`aws`](https://fidelity.github.io/awsrun/commands/aws/aws.html) or
[`az`](https://fidelity.github.io/awsrun/commands/azure/az.html) commands. These
commands are simple wrappers for AWS's and Azure's CLI tools respectively, but
with the added benefits of using metadata to select multiple accounts as well as
simplified credential handling.
**User-Defined Commands**:
Build your own commands using the powerful Boto3 SDK or Azure SDK without the
hassle of obtaining sessions and credentials. Thanks to a simple interface,
commands are easy to build and can be integrated directly into the CLI with
custom arguments and help messages.
**Metadata Enriched Accounts**:
Accounts/subscriptions can be enriched with metadata from external sources, such
as a corporate CMBD, via the account loader plug-in mechanism. This enables you
to use metadata to select accounts to process rather than explicitly listing
each account/subscription on the command line. In addition, command authors have
access to this metadata, so it can used while processing an account if needed.
## Screenshots
These examples demonstrate the wide-range of possibilities when building your
own awsrun & azurerun commands. While these commands are included in awsrun,
they use the same command library that you would if building your own. Nothing is
special about these commands other than they are included in the base install of
awsrun. You could have built these yourself.
### awsrun `aws` command
This screencast illustrates the power of awsrun once it has been configured to
your environment using appropriate credential and account loader plug-ins. In
this demo, we use awsrun to gather VPC information. While we could do the same
using only AWS's native CLI, we would be limited to processing one account at a
time. Instead, we'll use awsrun and the built-in
[`aws`](https://fidelity.github.io/awsrun/commands/aws/aws.html) command to
execute an AWS CLI command across multiple accounts concurrently. We'll also
make use of the awsrun's metadata explorer to select accounts for command
execution.
Note: The output has been obfuscated with random account numbers and
identifiers.
### awsrun `last` command
This screenshot demonstrates the use of the
[`last`](https://fidelity.github.io/awsrun/commands/aws/last.html) command to
interactively explore CloudTrail events. Don't have a simple means to view
CloudTrail logs? Tired of using the AWS Console? The `last` command provides a
simple way of viewing events in one or more accounts.
### awsrun `dx_status` command
If you manage AWS Direct Connects to provide connectivity to your on-premise
corporate networks, you might find the
[`dx_status`](https://fidelity.github.io/awsrun/commands/aws/dx_status.html)
command helpful. It provides an overview of Direct Connects contained within an
account. This includes pulling CloudWatch metrics and generating terminal-based
graphs using [sparklines](https://en.wikipedia.org/wiki/Sparkline) and
ASCII-based charts.
## Installation
Python 3.7 or higher is required.
To install only `awsrun`:
$ pip install "awsrun[aws]"
To install only `azurerun`:
$ pip install "awsrun[azure]"
To install both `awsrun` and `azurerun`:
$ pip install "awsrun[aws,azure]"
In all cases, the console scripts `awsrun` and `azurerun` are installed, but
only the dependencies for the specified CSPs are installed.
Some of the bundled commands have additional dependencies. You will be prompted
to install those if you use one of them. Alternatively, you can install all of
those ahead of time:
$ pip install "awsrun[cmds]"
Finally, to install from source with the development dependencies:
$ git clone https://github.com/fidelity/awsrun.git
$ cd awsrun
$ pip install -e ".[aws,azure,cmds,dev]"
## AWS Quick Start
Out of the box, the utility of awsrun is limited as most of its power comes from
the configuration of an [account loader
plug-in](https://fidelity.github.io/awsrun/cli.html#account-plug-ins) (to
simplify the selection of multiple accounts) and a [credential loader
plug-in](https://fidelity.github.io/awsrun/cli.html#credential-plug-ins) (to
simplify access to those accounts). With that said, however, you can still use
it, as it will default to loading credentials from your `$HOME/.aws/credentials`
file. While not convenient when managing hundreds of accounts, it will suffice
to get you started.
Assume you wanted to list the EC2 instances in two accounts: 100200300400
and 200300400100. We can use the built-in
[`aws`](https://fidelity.github.io/awsrun/commands/aws/aws.html) command to
execute any [AWS CLI
command](https://docs.aws.amazon.com/cli/latest/reference/index.html#cli-aws)
across one or more accounts concurrently. Be sure you have followed the
installation instructions in the previous section. Then, create two profiles,
`[100200300400]` and `[200300400100]`, in your local AWS credentials file
`$HOME/.aws/credentials`. If awsrun cannot find a profile for named for the
specific account, it will fallback to the `[default]` profile.
Note: The AWS credentials file is not part of awsrun, but it is used as the
default mechanism to obtain credentials if more [advanced
options](https://fidelity.github.io/awsrun/plugins/creds/aws.html) have not been
configured. For help on the configuration of the AWS credential file, refer to
[AWS CLI Named
Profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html).
With the profiles defined, you can now run the following to list the EC2
instances in both accounts across multiple regions concurrently:
$ awsrun --account 100200300400 --account 200300400100 aws ec2 describe-instances --region us-east-1 --region us-west-2
2 accounts selected:
100200300400, 200300400100
Proceed (y/n)? y
...
If, instead, you want to list lambda functions in those accounts:
$ awsrun --account 100200300400 --account 200300400100 aws lambda list-functions --region us-east-1 --region us-west-2
2 accounts selected:
100200300400, 200300400100
Proceed (y/n)? y
...
There are several other [built-in
commands](https://fidelity.github.io/awsrun/commands/aws/index.html) that have
been included in awsrun. The more interesting ones include the
[`last`](https://fidelity.github.io/awsrun/commands/aws/last.html) command to
inspect CloudTrail events as well as the
[`dx_status`](https://fidelity.github.io/awsrun/commands/aws/dx_status.html)
command to check the status of Direct Connect circuits. Remember, you are
encouraged to build your own custom commands. These have been provided to show
you how to do so.
## Azure Quick Start
Let's list all the Azure VMs in two subscriptions:
00000000-0000-0000-0000-000000000000 and 11111111-1111-1111-1111-111111111111.
We can use the built-in
[`az`](https://fidelity.github.io/awsrun/commands/azure/az.html) command to
execute an [Azure CLI
command](https://docs.microsoft.com/en-us/cli/azure/reference-index?view=azure-cli-latest)
across one or more subscriptions concurrently. Assuming you have already
followed the installation instructions:
$ az login # Use the Azure CLI to obtain credentials
$ azurerun --account 00000000-0000-0000-0000-000000000000 --account 11111111-1111-1111-1111-111111111111 az vm list --output table
2 accounts selected:
00000000-0000-0000-0000-000000000000, 11111111-1111-1111-1111-111111111111
Proceed (y/n)? y
...
Name ResourceGroup Location Zones
----- ----------------- ---------- -----
vm1 rg1 centralus 1
vm2 rg1 eastus2 1
Name ResourceGroup Location Zones
----- ----------------- ---------- -----
vm1 rg2 centralus 1
vm2 rg2 eastus1 1
vm3 rg2 eastus2 1
Out of the box, the utility of azurerun is limited as most of its power comes
from the configuration of an [account loader
plug-in](https://fidelity.github.io/awsrun/cli.html#account-plug-ins) (to
simplify selection of multiple accounts). Using the included
[AzureCLI](https://fidelity.github.io/awsrun/plugins/accts/azure.html) plug-in,
azurerun will use the Azure CLI to obtain a list of subscriptions and metadata
associated with those. Furthermore, assuming you use a naming convention for
your subscriptions, we can parse the name to pull out additional metadata. For
example, if your subscriptions are named "azure-retail-prod" and
"azure-retail-nonprod", then we can use this regexp to add the "bu" and "env"
metadata attributes:
azure-(?P<bu>[^-]+)-(?P<env>.+)
Create the following azurerun configuration file called `.azurerun.yaml` in your
home directory:
Accounts:
plugin: awsrun.plugins.accts.azure.AzureCLI
options:
name_regexp: 'azure-(?P<bu>[^-]+)-(?P<env>.+)'
Now, you can use the metadata filters to specify subscriptions instead of
enumerating them on the azurerun command line. Here are a few examples:
# Let's see what metadata we can use
$ azurerun --metadata
bu
cloudName
env
homeTenantId
id
isDefault
name
state
tenantId
# Run the command over all subscriptions.
$ azurerun az vm list --output table
...
# Run the command over all prod subscriptions.
$ azurerun --include env=prod az vm list --output table
...
# Run the command over all enabled, nonprod subscriptions
$ azurerun --include state=Enabled --include Env=nonprod az vm list --output table
...
There are several other [built-in
commands](https://fidelity.github.io/awsrun/commands/azure/index.html) that have
been included in azurerun. Remember, you are encouraged to build your own custom
commands. These have been provided to show you how to do so.
## Documentation
awsrun includes extensive [documentation](https://fidelity.github.io/awsrun/), which
includes the following:
- The [CLI User Guide](https://fidelity.github.io/awsrun/cli.html#cli-user-guide)
includes basic usage, configuration of awsrun, and how to use the account
loader and credential loader plug-ins to enhance the user experience on the
CLI.
- The [Library User Guide](https://fidelity.github.io/awsrun/#api-usage)
includes pointers to the key documentation required to use awsrun
programmatically instead of via the CLI. All of the awsrun
[modules](https://fidelity.github.io/awsrun/#header-submodules) are also
extensively documented.
- The [How-to Write Your Own
Commands](https://fidelity.github.io/awsrun/commands/#user-defined-commands)
guide provides everything you need to write your own custom awsrun commands.
This is where you'll spend a lot of time once you become familiar with the
capabilities of awsrun.
- The [How-to Write Your Own
Plug-ins](https://fidelity.github.io/awsrun/#user-defined-plug-ins) section
includes pointers to the documentation required to build your own account
loader plug-in and credential plug-in if the included ones are not suitable to
your environment.
## Change Log
### v3.1.0
- Add `URLAccountLoader` plug-in which supports HTTP authentication (basic,
digest, oauth2). This plug-in should be preferred over the existing
`JSONAccountLoader`, `YAMLAccountLoader`, and `CSVAccountLoader` plug-ins,
which will eventually be deprecated.
- Add HTTP POST support to the SAML credential provider plug-in. Thanks to
@RobertShan2000 for the contribution.
### v3.0.0
- **BREAKING CHANGE**: Installation via `pip install awsurn` no longer installs
all of the dependencies for `awsrun`, `azurerun`, and the bundled commands.
Instead, users must now specify which optional dependendencies to install.
See Installation section above for details. Note: while the major version
was bumped, there are no API changes to awsrun. This was bumped from "2"
to "3" solely to bring awareness to the different installation instructions.
- The terminal-based UI for the `last` command, a CloudTrail event viewer,
was rewritten using the amazing Textual TUI framework. With this change,
several new features were added to the command: dark/light modes, mouse
support, filtering events, exporting events, OS clipboard integration,
highlighting of events with errors, ability to toggle layout, as well as
a brand new look and feel. See screenshot above.
- Modernized the python packaging to use `pyproject.toml` instead of the
`setup.py` style of packgaing.
- Thanks to Gábor Lipták for the GitHub actions contributions. This included
adding the new check for PR titles to ensure they adhere to the Conventional
Commits standard.
- Added a CONTRIBUTING document thanks to Brian Warner, a member of our
open-source office at Fidelity.
### v2.5.2
- Resolve all pylint warnings.
- Update `dx_status` for `asciichart` API changes and bump version.
- Allow reuse of `argparse` option flags for command authors that use the same
flag across multiple argparse subcommands. Previously, reuse of option flags
was prohibited across different instances of `argparse.ArgumentParser`.
### v2.5.1
- Fix tag and redeploy pypi artifacts.
### v2.5.0
- `last` command now appends each CloudTrail event line in non-interactive mode
with "ERROR: " and the `errorCode` from the event if present. This allows users
to quickly identify errors (`grep ERROR`). The CloudTrail API does not provide
a means to filter on errors, so it can only be done after retrieving events.
- `last` command TUI now allows users to filter CloudTrail events interactively
via a popup (mapped to 'f' key). Users can specify one or more terms to match
events. Terms are logically OR'd together. A term may be prefixed with `-` to
exclude events matching it. For example, "errorCode -s3" will show only
events that had errors excluding S3 events.
### v2.4.2
- Update `kubectl` wrapper to use latest `v1beta1` Kubernetes API instead of
`v1alpha1` to fix compatibility issues with the latest version of Kubernetes
`kubectl` and latest AWS CLI tool.
### v2.4.1
- Require Python 3.7 or greater in `setup.py`.
### v2.4.0
- Remove Python 3.6 classifier from `setup.py`.
- Update authentication method in `kubectl` wrapper from `aws-iam-authenticator`
to use the AWS CLI command `aws eks get-token`. Users will no longer need
to install the separate `aws-iam-authenticator` helper moving forward.
- Use `KUBECONFIG` environment variable instead of `--kubeconfig` command line
flag when the `kubectl` wrapper command invokes the real `kubectl` command.
This change should be transparent to users of the `kubectl` command.
### v2.3.1
- Add new sample awsrun command, `dx_maint`, that queries the AWS Health API to
display recent and upcoming maintenance events (technically any open events)
on Direct Connects.
- Add new sample azurerun command, `list_udrs`, that displays all User Defined
Routes (UDRs) in an Azure VNET.
### v2.3.0
- Add support for Azure. By default, installation now installs both `awsrun` as
well as `azurerun`. See the quick start for Azure above.
### v2.2.2
- Add a decorator `awsrun.runner.max_thread_limit` that can be used by command
authors to limit the number of concurrent executions. There are some scenarios
where a command author may never want their command run concurrently across
multiple accounts. By default, awsrun uses a thread pool of ten workers, and
users can override, so this gives command authors ability to limit if needed.
### v2.2.1
- Reorganized the documentation. The CLI user guide and reference are now part
of the `awsrun.cli` module documentation. The user guide on writing commands
has been moved to the `awsrun.commands` module. Lots of other minor edits were
made as part of this reorganization. Hopefully, things are easier to find with
the new layout.
### v2.2.0
- Add three new built-in commands:
[`console`](https://fidelity.github.io/awsrun/commands/aws/console.html),
[`dx_status`](https://fidelity.github.io/awsrun/commands/aws/dx_status.html),
and [`last`](https://fidelity.github.io/awsrun/commands/aws/last.html). Console
generates sign-in URLs for the AWS Console using credentials from awsrun.
Dx_status shows the status of Direct Connect circuits (terminal graphs too!).
Last provides an easier way to review CloudTrail events in both an interactive
and non-interactive manner.
- Add the [`cloudwatch`](https://fidelity.github.io/awsrun/cloudwatch.html)
module to simplify the retrieval of CloudWatch metrics using bulk retrieval
for efficiency. This module is used be the new
[`dx_status`](https://fidelity.github.io/awsrun/commands/aws/dx_status.html)
command.
- Update the included built-in commands that iterate over VPCs to filter out
VPCs that have been shared with an account, as opposed to being owned by the
account, as generally that is the behavior one is expecting.
- Remove AWS CLI as a python dependency in `setup.py`. AWS has released v2 of
the AWS CLI, so we should not presume to install v1 via pip installation. In
addition, AWS has stated that the only supported installation of the AWS CLI
v2 is via their own bundled package installers. What does this mean for awsrun
users? Install the AWS CLI on your own if you plan on using the built-in `aws`
command.
- Fonts used in documentation have been updated to use Charter and Fira Mono.
### v2.1.0
- Add a YAML account loader plug-in to complement the CSV and JSON account
loader plug-ins.
- Minor clarification in user guide about the interaction between `--accounts` and
metadata filters (`--include`/`--exclude`).
### v2.0.0
- Initial open source release of awsrun from Fidelity's CloudX Network team. This
version abstracts the Fidelity specific integrations into plug-ins, so others
can take advantage of this tool, which has proven to be valuable for our teams.
Raw data
{
"_id": null,
"home_page": null,
"name": "awsrun",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "aws, azure, cli, command runner",
"author": null,
"author_email": "Pete Kazmier <opensource@fidelity.com>",
"download_url": "https://files.pythonhosted.org/packages/bb/be/55c4f9f806c8bbad0916d9d9a590c4cefa7047cf333d097f36f7ee0a31b1/awsrun-3.1.0.tar.gz",
"platform": null,
"description": "[](https://github.com/fidelity/awsrun/actions/workflows/ci.yml)\n[](https://github.com/psf/black)\n\n# awsrun & azurerun\n\nCLI tool and library to concurrently execute user-defined commands across AWS\naccounts or Azure subscriptions.\n\n> **Note**\n> As of release 3.0.0, installation has changed with the introduction of\n> optional dependencies. Previously, `pip install awsrun` would install all\n> dependencies needed for `awsrun`, `azurerun`, and all of the bundled\n> commands. You **must** now specify the optional dependencies when installing:\n> `pip install \"awsrun[aws,azure]\"`. See Installation for more details.\n\n## Overview\n\nAwsrun/azurerun is both a CLI tool and Python package that can be used to\nexecute commands concurrently over one or more AWS accounts or Azure\nsubscriptions. Commands are user-defined Python modules that implement a simple\ninterface to abstract away the complications of obtaining credentials for Boto3\nand Azure SDK sessions—especially when using SAML authentication and/or\ncross-account access in AWS. The key features of awsrun/azurerun include the\nfollowing:\n\n**Concurrent Account Processing**:\nRun a command concurrently across subset or all of your accounts/subscriptions.\nA worker pool manages the execution to ensure accounts/subscriptions are\nprocessed quickly, so you don't have to wait for them to be processed one at a\ntime. Process hundreds of accounts in a few minutes.\n\n**SAML and Cross-Account Access**:\nTired of dealing with AWS temporary STS credentials with SAML and cross-account\nauthentication? Use any of the included credential plug-ins based on your needs,\nor build your own plug-in to provide credentials for your command authors. Don't\nuse SAML? Define profiles in your AWS credentials file instead. With Azure, the\ndefault credentials are obtained via the Azure CLI or interactively via the browser.\n\n**Built-in Command for AWS CLI & Azure CLI**:\nEver wish you could run the standard AWS CLI tool or Azure CLI tool across\nmultiple accounts/subscriptions? Now you can using the included\n[`aws`](https://fidelity.github.io/awsrun/commands/aws/aws.html) or\n[`az`](https://fidelity.github.io/awsrun/commands/azure/az.html) commands. These\ncommands are simple wrappers for AWS's and Azure's CLI tools respectively, but\nwith the added benefits of using metadata to select multiple accounts as well as\nsimplified credential handling.\n\n**User-Defined Commands**:\nBuild your own commands using the powerful Boto3 SDK or Azure SDK without the\nhassle of obtaining sessions and credentials. Thanks to a simple interface,\ncommands are easy to build and can be integrated directly into the CLI with\ncustom arguments and help messages.\n\n**Metadata Enriched Accounts**:\nAccounts/subscriptions can be enriched with metadata from external sources, such\nas a corporate CMBD, via the account loader plug-in mechanism. This enables you\nto use metadata to select accounts to process rather than explicitly listing\neach account/subscription on the command line. In addition, command authors have\naccess to this metadata, so it can used while processing an account if needed.\n\n## Screenshots\n\nThese examples demonstrate the wide-range of possibilities when building your\nown awsrun & azurerun commands. While these commands are included in awsrun,\nthey use the same command library that you would if building your own. Nothing is\nspecial about these commands other than they are included in the base install of\nawsrun. You could have built these yourself.\n\n### awsrun `aws` command\n\nThis screencast illustrates the power of awsrun once it has been configured to\nyour environment using appropriate credential and account loader plug-ins. In\nthis demo, we use awsrun to gather VPC information. While we could do the same\nusing only AWS's native CLI, we would be limited to processing one account at a\ntime. Instead, we'll use awsrun and the built-in\n[`aws`](https://fidelity.github.io/awsrun/commands/aws/aws.html) command to\nexecute an AWS CLI command across multiple accounts concurrently. We'll also\nmake use of the awsrun's metadata explorer to select accounts for command\nexecution.\n\n\n\nNote: The output has been obfuscated with random account numbers and\nidentifiers.\n\n### awsrun `last` command\n\nThis screenshot demonstrates the use of the\n[`last`](https://fidelity.github.io/awsrun/commands/aws/last.html) command to\ninteractively explore CloudTrail events. Don't have a simple means to view\nCloudTrail logs? Tired of using the AWS Console? The `last` command provides a\nsimple way of viewing events in one or more accounts.\n\n\n\n### awsrun `dx_status` command\n\nIf you manage AWS Direct Connects to provide connectivity to your on-premise\ncorporate networks, you might find the\n[`dx_status`](https://fidelity.github.io/awsrun/commands/aws/dx_status.html)\ncommand helpful. It provides an overview of Direct Connects contained within an\naccount. This includes pulling CloudWatch metrics and generating terminal-based\ngraphs using [sparklines](https://en.wikipedia.org/wiki/Sparkline) and\nASCII-based charts.\n\n\n\n\n\n## Installation\n\nPython 3.7 or higher is required.\n\nTo install only `awsrun`:\n\n $ pip install \"awsrun[aws]\"\n\nTo install only `azurerun`:\n\n $ pip install \"awsrun[azure]\"\n\nTo install both `awsrun` and `azurerun`:\n\n $ pip install \"awsrun[aws,azure]\"\n\nIn all cases, the console scripts `awsrun` and `azurerun` are installed, but\nonly the dependencies for the specified CSPs are installed.\n\nSome of the bundled commands have additional dependencies. You will be prompted\nto install those if you use one of them. Alternatively, you can install all of\nthose ahead of time:\n\n $ pip install \"awsrun[cmds]\"\n\nFinally, to install from source with the development dependencies:\n\n $ git clone https://github.com/fidelity/awsrun.git\n $ cd awsrun\n $ pip install -e \".[aws,azure,cmds,dev]\"\n\n## AWS Quick Start\n\nOut of the box, the utility of awsrun is limited as most of its power comes from\nthe configuration of an [account loader\nplug-in](https://fidelity.github.io/awsrun/cli.html#account-plug-ins) (to\nsimplify the selection of multiple accounts) and a [credential loader\nplug-in](https://fidelity.github.io/awsrun/cli.html#credential-plug-ins) (to\nsimplify access to those accounts). With that said, however, you can still use\nit, as it will default to loading credentials from your `$HOME/.aws/credentials`\nfile. While not convenient when managing hundreds of accounts, it will suffice\nto get you started.\n\nAssume you wanted to list the EC2 instances in two accounts: 100200300400\nand 200300400100. We can use the built-in\n[`aws`](https://fidelity.github.io/awsrun/commands/aws/aws.html) command to\nexecute any [AWS CLI\ncommand](https://docs.aws.amazon.com/cli/latest/reference/index.html#cli-aws)\nacross one or more accounts concurrently. Be sure you have followed the\ninstallation instructions in the previous section. Then, create two profiles,\n`[100200300400]` and `[200300400100]`, in your local AWS credentials file\n`$HOME/.aws/credentials`. If awsrun cannot find a profile for named for the\nspecific account, it will fallback to the `[default]` profile.\n\nNote: The AWS credentials file is not part of awsrun, but it is used as the\ndefault mechanism to obtain credentials if more [advanced\noptions](https://fidelity.github.io/awsrun/plugins/creds/aws.html) have not been\nconfigured. For help on the configuration of the AWS credential file, refer to\n[AWS CLI Named\nProfiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html).\n\nWith the profiles defined, you can now run the following to list the EC2\ninstances in both accounts across multiple regions concurrently:\n\n $ awsrun --account 100200300400 --account 200300400100 aws ec2 describe-instances --region us-east-1 --region us-west-2\n 2 accounts selected:\n\n 100200300400, 200300400100\n\n Proceed (y/n)? y\n ...\n\nIf, instead, you want to list lambda functions in those accounts:\n\n $ awsrun --account 100200300400 --account 200300400100 aws lambda list-functions --region us-east-1 --region us-west-2\n 2 accounts selected:\n\n 100200300400, 200300400100\n\n Proceed (y/n)? y\n ...\n\nThere are several other [built-in\ncommands](https://fidelity.github.io/awsrun/commands/aws/index.html) that have\nbeen included in awsrun. The more interesting ones include the\n[`last`](https://fidelity.github.io/awsrun/commands/aws/last.html) command to\ninspect CloudTrail events as well as the\n[`dx_status`](https://fidelity.github.io/awsrun/commands/aws/dx_status.html)\ncommand to check the status of Direct Connect circuits. Remember, you are\nencouraged to build your own custom commands. These have been provided to show\nyou how to do so.\n\n## Azure Quick Start\n\nLet's list all the Azure VMs in two subscriptions:\n00000000-0000-0000-0000-000000000000 and 11111111-1111-1111-1111-111111111111.\nWe can use the built-in\n[`az`](https://fidelity.github.io/awsrun/commands/azure/az.html) command to\nexecute an [Azure CLI\ncommand](https://docs.microsoft.com/en-us/cli/azure/reference-index?view=azure-cli-latest)\nacross one or more subscriptions concurrently. Assuming you have already\nfollowed the installation instructions:\n\n $ az login # Use the Azure CLI to obtain credentials\n $ azurerun --account 00000000-0000-0000-0000-000000000000 --account 11111111-1111-1111-1111-111111111111 az vm list --output table\n 2 accounts selected:\n\n 00000000-0000-0000-0000-000000000000, 11111111-1111-1111-1111-111111111111\n\n Proceed (y/n)? y\n ...\n Name ResourceGroup Location Zones\n ----- ----------------- ---------- -----\n vm1 rg1 centralus 1\n vm2 rg1 eastus2 1\n\n Name ResourceGroup Location Zones\n ----- ----------------- ---------- -----\n vm1 rg2 centralus 1\n vm2 rg2 eastus1 1\n vm3 rg2 eastus2 1\n\nOut of the box, the utility of azurerun is limited as most of its power comes\nfrom the configuration of an [account loader\nplug-in](https://fidelity.github.io/awsrun/cli.html#account-plug-ins) (to\nsimplify selection of multiple accounts). Using the included\n[AzureCLI](https://fidelity.github.io/awsrun/plugins/accts/azure.html) plug-in,\nazurerun will use the Azure CLI to obtain a list of subscriptions and metadata\nassociated with those. Furthermore, assuming you use a naming convention for\nyour subscriptions, we can parse the name to pull out additional metadata. For\nexample, if your subscriptions are named \"azure-retail-prod\" and\n\"azure-retail-nonprod\", then we can use this regexp to add the \"bu\" and \"env\"\nmetadata attributes:\n\n azure-(?P<bu>[^-]+)-(?P<env>.+)\n\nCreate the following azurerun configuration file called `.azurerun.yaml` in your\nhome directory:\n\n Accounts:\n plugin: awsrun.plugins.accts.azure.AzureCLI\n options:\n name_regexp: 'azure-(?P<bu>[^-]+)-(?P<env>.+)'\n\nNow, you can use the metadata filters to specify subscriptions instead of\nenumerating them on the azurerun command line. Here are a few examples:\n\n # Let's see what metadata we can use\n $ azurerun --metadata\n bu\n cloudName\n env\n homeTenantId\n id\n isDefault\n name\n state\n tenantId\n\n # Run the command over all subscriptions.\n $ azurerun az vm list --output table\n ...\n\n # Run the command over all prod subscriptions.\n $ azurerun --include env=prod az vm list --output table\n ...\n\n # Run the command over all enabled, nonprod subscriptions\n $ azurerun --include state=Enabled --include Env=nonprod az vm list --output table\n ...\n\nThere are several other [built-in\ncommands](https://fidelity.github.io/awsrun/commands/azure/index.html) that have\nbeen included in azurerun. Remember, you are encouraged to build your own custom\ncommands. These have been provided to show you how to do so.\n\n## Documentation\n\nawsrun includes extensive [documentation](https://fidelity.github.io/awsrun/), which\nincludes the following:\n\n- The [CLI User Guide](https://fidelity.github.io/awsrun/cli.html#cli-user-guide)\n includes basic usage, configuration of awsrun, and how to use the account\n loader and credential loader plug-ins to enhance the user experience on the\n CLI.\n\n- The [Library User Guide](https://fidelity.github.io/awsrun/#api-usage)\n includes pointers to the key documentation required to use awsrun\n programmatically instead of via the CLI. All of the awsrun\n [modules](https://fidelity.github.io/awsrun/#header-submodules) are also\n extensively documented.\n\n- The [How-to Write Your Own\n Commands](https://fidelity.github.io/awsrun/commands/#user-defined-commands)\n guide provides everything you need to write your own custom awsrun commands.\n This is where you'll spend a lot of time once you become familiar with the\n capabilities of awsrun.\n\n- The [How-to Write Your Own\n Plug-ins](https://fidelity.github.io/awsrun/#user-defined-plug-ins) section\n includes pointers to the documentation required to build your own account\n loader plug-in and credential plug-in if the included ones are not suitable to\n your environment.\n\n## Change Log\n\n### v3.1.0\n\n- Add `URLAccountLoader` plug-in which supports HTTP authentication (basic,\n digest, oauth2). This plug-in should be preferred over the existing\n `JSONAccountLoader`, `YAMLAccountLoader`, and `CSVAccountLoader` plug-ins,\n which will eventually be deprecated.\n\n- Add HTTP POST support to the SAML credential provider plug-in. Thanks to\n @RobertShan2000 for the contribution.\n\n### v3.0.0\n\n- **BREAKING CHANGE**: Installation via `pip install awsurn` no longer installs\n all of the dependencies for `awsrun`, `azurerun`, and the bundled commands.\n Instead, users must now specify which optional dependendencies to install.\n See Installation section above for details. Note: while the major version\n was bumped, there are no API changes to awsrun. This was bumped from \"2\"\n to \"3\" solely to bring awareness to the different installation instructions.\n\n- The terminal-based UI for the `last` command, a CloudTrail event viewer,\n was rewritten using the amazing Textual TUI framework. With this change,\n several new features were added to the command: dark/light modes, mouse\n support, filtering events, exporting events, OS clipboard integration,\n highlighting of events with errors, ability to toggle layout, as well as\n a brand new look and feel. See screenshot above.\n\n- Modernized the python packaging to use `pyproject.toml` instead of the\n `setup.py` style of packgaing.\n\n- Thanks to G\u00e1bor Lipt\u00e1k for the GitHub actions contributions. This included\n adding the new check for PR titles to ensure they adhere to the Conventional\n Commits standard.\n\n- Added a CONTRIBUTING document thanks to Brian Warner, a member of our\n open-source office at Fidelity.\n\n### v2.5.2\n\n- Resolve all pylint warnings.\n\n- Update `dx_status` for `asciichart` API changes and bump version.\n\n- Allow reuse of `argparse` option flags for command authors that use the same\n flag across multiple argparse subcommands. Previously, reuse of option flags\n was prohibited across different instances of `argparse.ArgumentParser`.\n\n### v2.5.1\n\n- Fix tag and redeploy pypi artifacts.\n\n### v2.5.0\n\n- `last` command now appends each CloudTrail event line in non-interactive mode\n with \"ERROR: \" and the `errorCode` from the event if present. This allows users\n to quickly identify errors (`grep ERROR`). The CloudTrail API does not provide\n a means to filter on errors, so it can only be done after retrieving events.\n\n- `last` command TUI now allows users to filter CloudTrail events interactively\n via a popup (mapped to 'f' key). Users can specify one or more terms to match\n events. Terms are logically OR'd together. A term may be prefixed with `-` to\n exclude events matching it. For example, \"errorCode -s3\" will show only\n events that had errors excluding S3 events.\n\n### v2.4.2\n\n- Update `kubectl` wrapper to use latest `v1beta1` Kubernetes API instead of\n `v1alpha1` to fix compatibility issues with the latest version of Kubernetes\n `kubectl` and latest AWS CLI tool.\n\n### v2.4.1\n\n- Require Python 3.7 or greater in `setup.py`.\n\n### v2.4.0\n\n- Remove Python 3.6 classifier from `setup.py`.\n\n- Update authentication method in `kubectl` wrapper from `aws-iam-authenticator`\n to use the AWS CLI command `aws eks get-token`. Users will no longer need\n to install the separate `aws-iam-authenticator` helper moving forward.\n\n- Use `KUBECONFIG` environment variable instead of `--kubeconfig` command line\n flag when the `kubectl` wrapper command invokes the real `kubectl` command.\n This change should be transparent to users of the `kubectl` command.\n\n### v2.3.1\n\n- Add new sample awsrun command, `dx_maint`, that queries the AWS Health API to\n display recent and upcoming maintenance events (technically any open events)\n on Direct Connects.\n\n- Add new sample azurerun command, `list_udrs`, that displays all User Defined\n Routes (UDRs) in an Azure VNET.\n\n### v2.3.0\n\n- Add support for Azure. By default, installation now installs both `awsrun` as\n well as `azurerun`. See the quick start for Azure above.\n\n### v2.2.2\n\n- Add a decorator `awsrun.runner.max_thread_limit` that can be used by command\n authors to limit the number of concurrent executions. There are some scenarios\n where a command author may never want their command run concurrently across\n multiple accounts. By default, awsrun uses a thread pool of ten workers, and\n users can override, so this gives command authors ability to limit if needed.\n\n### v2.2.1\n\n- Reorganized the documentation. The CLI user guide and reference are now part\n of the `awsrun.cli` module documentation. The user guide on writing commands\n has been moved to the `awsrun.commands` module. Lots of other minor edits were\n made as part of this reorganization. Hopefully, things are easier to find with\n the new layout.\n\n### v2.2.0\n\n- Add three new built-in commands:\n [`console`](https://fidelity.github.io/awsrun/commands/aws/console.html),\n [`dx_status`](https://fidelity.github.io/awsrun/commands/aws/dx_status.html),\n and [`last`](https://fidelity.github.io/awsrun/commands/aws/last.html). Console\n generates sign-in URLs for the AWS Console using credentials from awsrun.\n Dx_status shows the status of Direct Connect circuits (terminal graphs too!).\n Last provides an easier way to review CloudTrail events in both an interactive\n and non-interactive manner.\n\n- Add the [`cloudwatch`](https://fidelity.github.io/awsrun/cloudwatch.html)\n module to simplify the retrieval of CloudWatch metrics using bulk retrieval\n for efficiency. This module is used be the new\n [`dx_status`](https://fidelity.github.io/awsrun/commands/aws/dx_status.html)\n command.\n\n- Update the included built-in commands that iterate over VPCs to filter out\n VPCs that have been shared with an account, as opposed to being owned by the\n account, as generally that is the behavior one is expecting.\n\n- Remove AWS CLI as a python dependency in `setup.py`. AWS has released v2 of\n the AWS CLI, so we should not presume to install v1 via pip installation. In\n addition, AWS has stated that the only supported installation of the AWS CLI\n v2 is via their own bundled package installers. What does this mean for awsrun\n users? Install the AWS CLI on your own if you plan on using the built-in `aws`\n command.\n\n- Fonts used in documentation have been updated to use Charter and Fira Mono.\n\n### v2.1.0\n\n- Add a YAML account loader plug-in to complement the CSV and JSON account\n loader plug-ins.\n\n- Minor clarification in user guide about the interaction between `--accounts` and\n metadata filters (`--include`/`--exclude`).\n\n### v2.0.0\n\n- Initial open source release of awsrun from Fidelity's CloudX Network team. This\n version abstracts the Fidelity specific integrations into plug-ins, so others\n can take advantage of this tool, which has proven to be valuable for our teams.\n",
"bugtrack_url": null,
"license": "Copyright 2019 FMR LLC Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "CLI and library to execute commands over one or more AWS or Azure accounts concurrently.",
"version": "3.1.0",
"project_urls": {
"homepage": "https://github.com/fidelity/awsrun"
},
"split_keywords": [
"aws",
" azure",
" cli",
" command runner"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "35f8c6de188bbb5076eeee2134286ce7cb1b06aa7d84f07cc0a3a90f73fe1adc",
"md5": "2ccc12bf4ac98b9968dcc775bf9dc33d",
"sha256": "6f94830a6735a5a406716617276fb5e392e27d2b4f66b7c1e6dad8b007db637d"
},
"downloads": -1,
"filename": "awsrun-3.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2ccc12bf4ac98b9968dcc775bf9dc33d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 178156,
"upload_time": "2024-07-03T14:54:51",
"upload_time_iso_8601": "2024-07-03T14:54:51.467122Z",
"url": "https://files.pythonhosted.org/packages/35/f8/c6de188bbb5076eeee2134286ce7cb1b06aa7d84f07cc0a3a90f73fe1adc/awsrun-3.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bbbe55c4f9f806c8bbad0916d9d9a590c4cefa7047cf333d097f36f7ee0a31b1",
"md5": "ba65a9ec77af8654fb10dee9da77947e",
"sha256": "59fdba44477f24d4e9b2c6f5751c46fe1e9cf7f6732b5c6f1f50b9361d329733"
},
"downloads": -1,
"filename": "awsrun-3.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ba65a9ec77af8654fb10dee9da77947e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 157895,
"upload_time": "2024-07-03T14:54:53",
"upload_time_iso_8601": "2024-07-03T14:54:53.517417Z",
"url": "https://files.pythonhosted.org/packages/bb/be/55c4f9f806c8bbad0916d9d9a590c4cefa7047cf333d097f36f7ee0a31b1/awsrun-3.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-03 14:54:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fidelity",
"github_project": "awsrun",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "awsrun"
}
