awsx is a command-line utility providing helpful commands that the default AWS CLI does not provide. It does not replace the AWS CLI, rather it is meant to work in conjunction with it.
awsx 0.1.0
KAISER+KRAFT EUROPA GmbH
USAGE:
awsx [FLAGS] [OPTIONS] <SUBCOMMAND>
FLAGS:
--dont-update-deployment-metadata
Unless specified, awsx will automatically update a stack-parameter containing deployment metadata with the
latest information for commands that update a stack. If you specify this option, awsx will not update the
deployment metadata.
-h, --help
Prints help information
-V, --version
Prints version information
OPTIONS:
--assume-role-arn <assume-role-arn>
Optional role to assume before executing AWS API calls. This can be used to execute commands in other
accounts, or to separate the actions performable in a single account. If unspecified, no role will be
assumed.
--aws-access-key-id <aws-access-key-id>
AWS Access Key ID to use when authenticating against the AWS API. If left unspecified, the default
credential provider will be used to determine the credentials (via environment variables, instance metadata,
container metadata or AWS profiles). You have to specify --aws-secret-access-key too if you specify this
parameter.
--aws-region <aws-region>
Region the AWS API calls should be performed in. If left unspecified, the region will be determined
automatically, falling back to us-east-1 should it fail.
--aws-secret-access-key <aws-secret-access-key>
AWS Secret Access Key to use when authenticating against the AWS API. If left unspecified, the default
credential provider will be used to determine the credentials (via environment variables, instance metadata,
container metadata or AWS profiles). You have to specify --aws-access-key-id too if you specify this
parameter.
--deployment-metadata-parameter <deployment-metadata-parameter>
Parameter of the stack in which deployment metadata will be stored. This applies to all commands that update
a stack. You can opt-out of metadata updates with the `--dont-update-deployment-metadata` option. [default:
DeploymentMetadata]
--output-format <output-format>
Specify the format of the application output. The default, if left unspecified, depends on whether stdout is
a TTY. If it is, the output will be human readable. If it isn't, the contents will be output in structured
form, specifically JSON. [possible values: human, human-readable, structured, json, yml, yaml]
--s3-bucket-name <s3-bucket-name>
Name of the S3 bucket used for storing templates. Any command that updates a stack template will upload the
template to S3 if this parameter is specified. If the parameter is unspecified, the awsx will try to provide
the template within the API call to AWS, although the template size here is limited to 51,200 bytes
(enforced by the AWS API).
SUBCOMMANDS:
create-stack Create a new stack with given parameters
find-amis-inuse Identify all AMI-IDs that are being used
find-auto-scaling-group Find an auto scaling group based on its tags
find-cloudfront-distribution Find a CloudFront distribution based on its tags
find-db-cluster-snapshot Find a DB cluster snapshot based on its tags
find-db-snapshot Find a DB snapshot based on its tags
find-target-group Find a target group based on its tags
help Prints this message or the help of the given subcommand(s)
identify-new-parameters Show new template parameters not present on the stack
override-parameters Update specified parameters on an existing stack
update-deployed-template Update an existing stack with a new template
verify-changes-compatible Verify that the deployed and local changes are compatible
verify-parameter-file Verify that parameters in a file match a deployed stack
awsx-create-stack 0.1.0
KAISER+KRAFT EUROPA GmbH
Create a new stack with given parameters
USAGE:
awsx create-stack [FLAGS] [OPTIONS] --change-set-name <change-set-name> --stack-name <stack-name> --template-path <template-path>
FLAGS:
--force-create
Force change set creation, even if the parameters supplied do not cover all required parameters exactly, or
if the stack you are trying to deploy. This means that if you force change set creation, the created change
set might be invalid.
-h, --help
Prints help information
-V, --version
Prints version information
OPTIONS:
--change-set-name <change-set-name>
Name for the new change set
--parameter-path <parameter-path>
Path to a JSON parameter file. This file should be structured the same as the AWS CLI expects. The file
shuold contain all parameters required by the template (parameters with defaults can be skipped).
(If you specify this parameter and --parameter-overrides, parameters specified through --parameters will
override parameters provided via the parameter file.)
-p, --parameters <parameters>...
Parameters required by template. Specify as multiple `Key=Value` pairs, where each key has to correspond to
a parameter newly added to the template, i.e. the parameter can not be already defined on the stack.
(If you specify this parameter and --parameter-path, parameters provided here will override parameters
provided via the parameter file.)
--role-arn <role-arn>
IAM Role that AWS CloudFormation assumes when executing the change set
--stack-name <stack-name>
Name of the stack to create
--template-path <template-path>
Path to the new template
IAM permissions required:
- cloudformation:DescribeStacks
- cloudformation:CreateChangeSet
- s3:PutObject
awsx-find-amis-inuse 0.1.0
KAISER+KRAFT EUROPA GmbH
Identify all AMI-IDs that are being used within a region and account. For this the command analyzes all AWS resources
where AMI-IDs can be referenced, and returns a complete list of the AMI-IDs in-use.
USAGE:
awsx find-amis-inuse
FLAGS:
-h, --help
Prints help information
-V, --version
Prints version information
IAM permissions required:
- ec2:DescribeInstances
- ec2:DescribeLaunchTemplates
- ec2:DescribeLaunchTemplateVersions
- autoscaling:DescribeLaunchConfigurations
awsx-find-auto-scaling-group 0.1.0
KAISER+KRAFT EUROPA GmbH
Find an auto scaling group based on its tags
USAGE:
awsx find-auto-scaling-group --tags <tags>...
FLAGS:
-h, --help
Prints help information
-V, --version
Prints version information
OPTIONS:
--tags <tags>...
Filter for auto-scaling groups by their tags. Specify multiple `Key=Value` pairs, separated by spaces, where
each key-value-pair corresponds to a tag assigned to the auto-scaling groups.
IAM permissions required:
- autoscaling:DescribeAutoScalingGroups
awsx-find-cloudfront-distribution 0.1.0
KAISER+KRAFT EUROPA GmbH
Find a CloudFront distribution based on its tags
USAGE:
awsx find-cloudfront-distribution --tags <tags>...
FLAGS:
-h, --help
Prints help information
-V, --version
Prints version information
OPTIONS:
--tags <tags>...
Filter for CloudFront distributions by their tags. Specify multiple `Key=Value` pairs, separated by spaces,
where each key-value-pair corresponds to a tag assigned to the CloudFront distributions.
IAM permissions required:
- cloudfront:ListDistributions
- cloudfront:ListTagsForResource
awsx-find-db-cluster-snapshot 0.1.0
KAISER+KRAFT EUROPA GmbH
Find a DB cluster snapshot based on its tags
USAGE:
awsx find-db-cluster-snapshot [OPTIONS]
FLAGS:
-h, --help
Prints help information
-V, --version
Prints version information
OPTIONS:
--db-cluster-identifier <db-cluster-identifier>
Filter for DB snapshots assigned from a specific DB cluster
--snapshot-type <snapshot-type>
Filter DB snapshots by their type
--tags <tags>...
Filter for DB snapshots by their tags. Specify multiple `Key=Value` pairs, separated by spaces, where each
key-value-pair corresponds to a tag assigned to the DB snapshot.
IAM permissions required:
- rds:DescribeDBClusterSnapshots
- rds:ListTagsForResource
awsx-find-db-snapshot 0.1.0
KAISER+KRAFT EUROPA GmbH
Find a DB snapshot based on its tags
USAGE:
awsx find-db-snapshot [OPTIONS]
FLAGS:
-h, --help
Prints help information
-V, --version
Prints version information
OPTIONS:
--db-instance-identifier <db-instance-identifier>
Filter for DB snapshots assigned from a specific DB instance
--snapshot-type <snapshot-type>
Filter DB snapshots by their type
--tags <tags>...
Filter for DB snapshots by their tags. Specify multiple `Key=Value` pairs, separated by spaces, where each
key-value-pair corresponds to a tag assigned to the DB snapshot.
IAM permissions required:
- rds:DescribeDBSnapshots
- rds:ListTagsForResource
awsx-find-target-group 0.1.0
KAISER+KRAFT EUROPA GmbH
Find a target group based on its tags
USAGE:
awsx find-target-group [OPTIONS]
FLAGS:
-h, --help
Prints help information
-V, --version
Prints version information
OPTIONS:
--load-balancer-arn <load-balancer-arn>
Filter for target groups assigned to a specific load balancer
--tags <tags>...
Filter for target groups by their tags. Specify multiple `Key=Value` pairs, separated by spaces, where each
key-value-pair corresponds to a tag assigned to the target groups.
IAM permissions required:
- elasticloadbalancing:DescribeTargetGroups
- elasticloadbalancing:DescribeTags
awsx-identify-new-parameters 0.1.0
KAISER+KRAFT EUROPA GmbH
Show all new parameters defined on the template, but not present on the stack. This subcommand does not create a change
set, and performs only read-only actions.
USAGE:
awsx identify-new-parameters --stack-name <stack-name> --template-path <template-path>
FLAGS:
-h, --help
Prints help information
-V, --version
Prints version information
OPTIONS:
--stack-name <stack-name>
Name of the stack to update
--template-path <template-path>
Path to the new template
IAM permissions required:
- cloudformation:DescribeStacks
awsx-override-parameters 0.1.0
KAISER+KRAFT EUROPA GmbH
Update specified parameters on an existing stack, without updating the underlying template. Only the specified
parameters will be updated, with all other parameters staying unchanged. NOTE: this will only create a change set that
will not be automatically executed.
USAGE:
awsx override-parameters [OPTIONS] --change-set-name <change-set-name> --stack-name <stack-name>
FLAGS:
-h, --help
Prints help information
-V, --version
Prints version information
OPTIONS:
--change-set-name <change-set-name>
Name for the new change set
--exclude <excludes>...
Exclude parameters based on the patterns provided. All patterns will be compiled into a regex-set, which
will be used to match each parameter key. If a parameter key matches any of the exclude-patterns, the
parameter will not be applied.
(Excludes only apply to parameters passed in via --parameter-path. Parameters provided via --parameter-
overrides will not be affected by this.)
--include <includes>...
Include parameters based on the patterns provided. All patterns will be compiled into a regex-set, which
will be used to match each parameter key. Every parameter key that doesn't match any of the include-patterns
will not be applied.
(Excludes are applied before includes, and you cannot include a parameter that was previously excluded.
Includes only apply to parameters passed in via --parameter-path. Parameters provided via --parameter-
overrides will not be affected by this.)
-p, --parameter-overrides <parameter-overrides>...
Parameters to override. Specify as multiple space-separated `Key=Value` pairs, where each key has to
correspond to an existing parameter on the requested stack.
(If you specify this parameter and --parameter-path, parameters provided here will override parameters
provided via the parameter file.)
--parameter-path <parameter-path>
Path to a JSON parameter file. This file should be structured the same as the AWS CLI expects. The file can
only contain parameters newly added to the template, unless the existing parameters are defined as
`UsePreviousValue=true`.
(If you specify this parameter and --parameter-overrides, parameters specified through --parameters will
override parameters provided via the parameter file.)
--role-arn <role-arn>
IAM Role that AWS CloudFormation assumes when executing the change set
--stack-name <stack-name>
Name of the stack to update
IAM permissions required:
- cloudformation:DescribeStacks
- cloudformation:CreateChangeSet
awsx-update-deployed-template 0.1.0
KAISER+KRAFT EUROPA GmbH
Update an existing stack with a new template, without updating any parameters already defined on the stack. You can and
have to supply parameters that are newly added. NOTE: this will only create a change set that will not be automatically
executed.
USAGE:
awsx update-deployed-template [FLAGS] [OPTIONS] --change-set-name <change-set-name> --stack-name <stack-name> --template-path <template-path>
FLAGS:
--force-create
Force change set creation, even if the parameters supplied do not cover the newly required parameters
exactly, or if the stack you are trying to deploy is not a direct child of the already deployed stack. This
means that if you force change set creation, the created change set might contain parameter changes in
addition to the template changes, and it might overwrite changes that are not part of the template you are
trying to deploy.
-h, --help
Prints help information
--only-new-parameters
By default, specifying parameters (either directly or through a path) will include all the parameters
provided/defined, even if they are already defined on the destination stack. When updating a deployed
template/stack this is not desired, which is why changeset creation fails if not forced in such cases. This
option provides a convenience that whatever parameters are specified, only those are used that are actually
new.
-V, --version
Prints version information
OPTIONS:
--change-set-name <change-set-name>
Name for the new change set
--exclude <excludes>...
Exclude parameters based on the patterns provided. All patterns will be compiled into a regex-set, which
will be used to match each parameter key. If a parameter key matches any of the exclude-patterns, the
parameter will not be applied.
--include <includes>...
Include parameters based on the patterns provided. All patterns will be compiled into a regex-set, which
will be used to match each parameter key. Every parameter key that doesn't match any of the include-patterns
will not be applied.
(Excludes are applied before includes, and you cannot include a parameter that was previously excluded.)
--parameter-defaults-path <parameter-defaults-path>
Path to a JSON parameter file, from which values will be taken if not specified in the regular parameter
file. This file should be structured the same as the AWS CLI expects. If the provided path does not exist,
no error is thrown, instead it will be simply ignored.
--parameter-path <parameter-path>
Path to a JSON parameter file. This file should be structured the same as the AWS CLI expects. The file can
only contain parameters newly added to the template, unless the existing parameters are defined as
`UsePreviousValue=true`.
(If you specify this parameter, you cannot specify --parameters.)
-p, --parameters <parameters>...
New parameters required by template. Specify as multiple `Key=Value` pairs, where each key has to correspond
to a parameter newly added to the template, i.e. the parameter can not be already defined on the stack.
(If you specify this parameter, you cannot specify --parameter-path, --exclude or --include.)
--role-arn <role-arn>
IAM Role that AWS CloudFormation assumes when executing the change set
--stack-name <stack-name>
Name of the stack to update
--template-path <template-path>
Path to the new template
IAM permissions required:
- cloudformation:DescribeStacks
- cloudformation:CreateChangeSet
- s3:PutObject
awsx-verify-changes-compatible 0.1.0
KAISER+KRAFT EUROPA GmbH
Verify that the deployed stack is compatible with the local changes.
USAGE:
awsx verify-changes-compatible [OPTIONS] --stack-name <stack-name>
FLAGS:
-h, --help
Prints help information
-V, --version
Prints version information
OPTIONS:
--git-path <git-path>
Path to git-repository to compare against. The default is to use the current working directory.
--stack-name <stack-name>
Name of the stack to compare against
IAM permissions requried:
- cloudformation:DescribeStacks
awsx-verify-parameter-file 0.1.0
KAISER+KRAFT EUROPA GmbH
Verify that the parameters defined in your parameters file match a currently deployed stack. If your parameter-file has
parameters defined as `UsePreviousValue`, they will be considered equal to whatever is defined on the stack. This
subcommand does not create a change set, and performs only read-only actions.
USAGE:
awsx verify-parameter-file [OPTIONS] --parameter-path <parameter-path> --stack-name <stack-name> --template-path <template-path>
FLAGS:
-h, --help
Prints help information
-V, --version
Prints version information
OPTIONS:
--parameter-defaults-path <parameter-defaults-path>
Path to a JSON parameter file, from which values will be taken if not specified in the regular parameter
file. This file should be structured the same as the AWS CLI expects. If the provided path does not exist,
no error is thrown, instead it will be simply ignored.
--parameter-path <parameter-path>
Path to a JSON parameter file. This file should be structured the same as the AWS CLI expects.
--stack-name <stack-name>
Name of the stack to compare the parameter-file against. You cannot specify this if --template-path has been
specified.
--template-path <template-path>
Path to the template-file to compare the parameter-file against. You cannot specify this if --stack-name has
been specified.
IAM permissions required:
- cloudformation:DescribeStacks
awsx is licensed under the Apache License, Version 2.0, (see LICENSE or https://www.apache.org/licenses/LICENSE-2.0).
awsx internally makes use of various open-source projects. You can find a full list of these projects and their licenses in THIRD_PARTY_LICENSES.md.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in awsx by you, as defined in the Apache-2.0 license, shall be licensed under the Apache License, Version 2.0, without any additional terms or conditions.
We require code submitted to be formatted with Rust's default rustfmt formatter (CI will automatically verified if your code is formatted correctly). We are using unstable rustfmt formatting rules, which requires running the formatter with a nightly toolchain, which you can do as follows:
$ rustup toolchain install nightly
$ cargo +nightly fmt(Building and running awsx itself can and should happen with the stable toolchain.)
Additionally we are also checking whether there are any clippy warnings in your code. You can run clippy locally with:
$ cargo clippy --workspace --lib --bins --tests --all-targets -- -DwarningsThere can be occasions where newer versions of clippy warn about code you haven't touched. In such cases we'll try to get those warnings resolved before merging your changes, or work together with you to get them resolved in your merge request.
This project has no official affiliation with Amazon Web Services, Inc., Amazon.com, Inc., or any of its affiliates. "Amazon Web Services" is a trademark of Amazon.com, Inc. or its affiliates in the United States and/or other countries.