README.md in ami_spec-1.6.0 vs README.md in ami_spec-1.7.0
- old
+ new
@@ -1,10 +1,10 @@
# AmiSpec
[](https://github.com/envato/ami-spec/blob/master/LICENSE.txt)
[](https://badge.fury.io/rb/ami_spec)
-[](https://travis-ci.org/envato/ami-spec)
+[](https://github.com/envato/ami-spec/actions?query=branch%3Amaster+workflow%3Atests)
Acceptance testing your AMIs.
AmiSpec is a RubyGem used to launch an Amazon Machine Image (AMI) and run ServerSpecs against it. It wraps around the AWS API and ServerSpec to spin up, test and tear down instances.
@@ -31,48 +31,85 @@
## CLI Usage
```cli
$ bundle exec ami_spec --help
Options:
- -r, --role=<s> The role to test, this should map to a directory in the spec
- folder
- -a, --ami=<s> The ami ID to run tests against
- -o, --role-ami-file=<s> A file containing comma separated roles and amis. i.e.
- web_server,ami-id.
- -s, --specs=<s> The directory to find ServerSpecs
- -u, --subnet-id=<s> The subnet to start the instance in. If not provided a subnet
- will be chosen from the default VPC
- -k, --key-name=<s> The SSH key name to assign to instances. If not provided a
- temporary key pair will be generated in AWS
- -e, --key-file=<s> The SSH private key file associated to the key_name
- -h, --ssh-user=<s> The user to ssh to the instance as
- -w, --aws-region=<s> The AWS region, defaults to AWS_DEFAULT_REGION environment
- variable
- -i, --aws-instance-type=<s> The ec2 instance type, defaults to t2.micro (default:
- t2.micro)
- -c, --aws-security-groups=<s> Security groups to associate to the launched instances. May be
- specified multiple times. If not provided a temporary security
- group will be generated in AWS
- -p, --aws-public-ip Launch instances with a public IP
- -t, --ssh-retries=<i> The number of times we should try sshing to the ec2 instance
- before giving up. Defaults to 30 (default: 30)
- -g, --tags=<s> Additional tags to add to launched instances in the form of
- comma separated key=value pairs. i.e. Name=AmiSpec (default: )
- -d, --debug Don't terminate instances on exit
- -b, --buildkite Output section separators for buildkite
- -f, --wait-for-rc Wait for oldschool SystemV scripts to run before conducting
- tests. Currently only supports Ubuntu with upstart
- -l, --user-data-file=<s> File path for aws ec2 user data
- -m, --iam-instance-profile-arn=<s> IAM instance profile to use
- --help Show this message
+ -r, --role=<s> The role to test, this should map to a directory in the spec
+ folder
+ -a, --ami=<s> The ami ID to run tests against
+ -o, --role-ami-file=<s> A file containing comma separated roles and amis. i.e.
+ web_server,ami-id.
+ -s, --specs=<s> The directory to find ServerSpecs
+ -u, --subnet-id=<s> The subnet to start the instance in. If not provided a subnet
+ will be chosen from the default VPC
+ -k, --key-name=<s> The SSH key name to assign to instances. If not provided a
+ temporary key pair will be generated in AWS
+ -e, --key-file=<s> The SSH private key file associated to the key_name
+ -h, --ssh-user=<s> The user to ssh to the instance as
+ -w, --aws-region=<s> The AWS region, defaults to AWS_DEFAULT_REGION environment
+ variable
+ -i, --aws-instance-type=<s> The ec2 instance type, defaults to t2.micro (default:
+ t2.micro)
+ -c, --aws-security-groups=<s> Security groups IDs to associate to the launched instances. May be
+ specified multiple times. If not provided a temporary security
+ group will be generated in AWS
+ -n, --allow-any-temporary-security-group The temporary security group will allow SSH connections
+ from any IP address (0.0.0.0/0), otherwise allow the subnet's block
+ -p, --aws-public-ip Launch instances with a public IP
+ -t, --ssh-retries=<i> The number of times we should try sshing to the ec2 instance
+ before giving up. Defaults to 30 (default: 30)
+ -g, --tags=<s> Additional tags to add to launched instances in the form of
+ comma separated key=value pairs. i.e. Name=AmiSpec (default: )
+ -d, --debug Don't terminate instances on exit
+ -b, --buildkite Output section separators for buildkite
+ -f, --wait-for-rc Wait for oldschool SystemV scripts to run before conducting
+ tests. Currently only supports Ubuntu with upstart
+ -l, --user-data-file=<s> File path for aws ec2 user data
+ -m, --iam-instance-profile-arn=<s> IAM instance profile to use
+ --help Show this message
```
AmiSpec will launch an EC2 instance from the given AMI (`--ami`), in a subnet (`--subnet-id`) with a key-pair (`--key-name`)
and try to SSH to it (`--ssh-user` and `--key-file`).
When the instances becomes reachable it will run all Specs inside the role spec directory (`--role` i.e. `my_project/spec/web_server`).
Alternative to the `--ami` and `--role` variables, a file of comma separated roles and AMIs (`ROLE,AMI\n`) can be supplied to `--role-ami-file`.
+
+## ServerSpec test layout
+
+AmiSpec expects the usual ServerSpec configuration layout as generated by "serverspec-init":
+
+ spec/
+ ├── webserver
+ │ └── webserver_spec.rb
+ └── spec_helper.rb
+
+The \*\_spec.rb files under the role (e.g. webserver) contain the ServerSpec
+tests that you want to run. The spec_helper.rb file can be very simple:
+
+ require 'serverspec'
+
+ set :backend, :ssh
+
+Note that the backend *needs* to be :ssh or ami_spec might run the tests on
+your local machine, not in EC2.
+
+## Example usage
+
+To test a custom AMI using a pre-created security group that allows SSH from anywhere:
+
+```cli
+ami_spec --role webserver\
+ --specs spec\
+ --aws-region us-east-1\
+ --ami ami-0123456789abcdef0\
+ --key-name default\
+ --key-file ~/.ssh/default.pem\
+ --ssh-user ubuntu\
+ --aws-public-ip\
+ --aws-security-groups sg-0123456789abcdef0
+```
## Known caveats
### RSpec conditions in examples