Merge pull request #1472 from pccornel/pccornel-ruby-ec2

Cleaned up remaining Ruby code examples for Amazon EC2. Added READMEs

Author: scmacdon

ruby/example_code/README.md

@@ -21,7 +21,7 @@ This folder contains code examples that demonstrate how to use the AWS SDK for R
 
 - As an AWS best practice, grant this code least privilege, or only the 
   permissions required to perform a task. For more information, see 
-  [Grant Least Privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) 
+  [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) 
   in the *AWS Identity and Access Management User Guide*.
 - This code has not been tested in all AWS Regions. Some AWS services are 
   available only in specific AWS Regions. For more information, see the 
@@ -37,7 +37,7 @@ Most of these code example files can be run with very little to no modification.
 ruby s3/create_bucket_snippet.rb
 ```
 
-Most of these files have been refactored into reusable functions that can be copied into your own code. You can then call those functions directly from your own code without modifying the copied function code itself. For example, you could copy the `list_bucket_objects?` function code from the `s3/auth_request_object_keys.rb` file into your own code. You could then adapt the code in the `run_me` function in that same file as a basis to write your own code to call the copied `list_bucket_objects?` function.
+Most of these files have been refactored into reusable functions that can be copied into your own code. You can then call those functions directly from your own code without modifying the copied function code itself. For example, you could copy the `bucket_created?` function code from the `s3/create_bucket_snippet.rb` file into your own code. You could then adapt the code in the `run_me` function in that same file as a basis to write your own code to call the copied `bucket_created?` function.
 
 ## Running the tests
 
@@ -46,7 +46,7 @@ Most of these code example files have accompanying tests that are written to wor
 To use RSpec to run all tests within a file, specify the path to that file, for example:
 
 ```
-rspec s3/tests/test_auth_request_test.rb
+rspec s3/tests/test_create_bucket_snippet.rb
 ```
 
 To explore additional options for using RSpec to run tests, run the `rspec --help` command. 
@@ -56,7 +56,7 @@ Most of these tests are designed to use stubs, to avoid generating unnecessary c
 
 ## Additional information
 
-- [Amazon S3 Developer Guide](https://docs.aws.amazon.com/AmazonS3/latest/dev)
+- [AWS Documentation](https://docs.aws.amazon.com)
 - [AWS SDK for Ruby Documentation](https://docs.aws.amazon.com/sdk-for-ruby)
 - [AWS Tools and SDKs Shared Configuration and Credentials Reference Guide](https://docs.aws.amazon.com/credref/latest/refdocs)
 - [RSpec Documentation](https://rspec.info/documentation)

ruby/example_code/ec2/README.md

@@ -0,0 +1,88 @@
+# AWS SDK for Ruby code examples for Amazon EC2
+
+## Purpose
+
+This folder contains code examples that demonstrate how to use the AWS SDK for Ruby to automate 
+Amazon Elastic Compute Cloud (Amazon EC2).
+
+## Prerequisites
+
+- An AWS account. To create an account, see [How do I create and activate a new AWS account](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/) on the AWS Premium Support website.
+- AWS credentials or an AWS Security Token Service (AWS STS) access token. For details, see 
+  [Configuring the AWS SDK for Ruby](https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-config.html) in the 
+  *AWS SDK for Ruby Developer Guide*.
+- To run the code examples, Ruby version 1.9 or later. For Ruby download and installation instructions, see 
+  [Download Ruby](https://www.ruby-lang.org/en/downloads/) on the Ruby Progamming Language website.
+- To test the code examples, RSpec 3.9 or later. For RSpec download and installation instructions, see the [rspec/rspec](https://github.com/rspec/rspec) repository in GitHub.
+- The AWS SDK for Ruby. For AWS SDK for Ruby download and installation instructions, see 
+  [Install the AWS SDK for Ruby](https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-install.html) in the 
+  *AWS SDK for Ruby Developer Guide*.
+
+## Cautions
+
+- As an AWS best practice, grant this code least privilege, or only the 
+  permissions required to perform a task. For more information, see 
+  [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) 
+  in the *AWS Identity and Access Management User Guide*.
+- This code has not been tested in all AWS Regions. Some AWS services are 
+  available only in specific AWS Regions. For more information, see the 
+  [AWS Regional Services List](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)
+  on the AWS website.
+- Running this code might result in charges to your AWS account.
+
+## Running the code
+
+Most of these code example files can be run with very little to no modification. For example, to use Ruby to run the `ec2-ruby-example-create-instance.rb` file, you can run the file along with the correct command-line arguments. Or you can replace the equivalent hard-coded values in the file with your own values, save the file, and then run the file without any command-line arguments. For example:
+
+```
+# Option 1: Run the file with the correct command-line arguments.
+
+ruby ec2-ruby-example-create-instance.rb ami-0947d2ba12EXAMPLE my-key-pair my-key my-value t2.micro us-east-1 my-user-data.txt
+
+# Option 2: Replace the equivalent hard-coded values in the file with your own values, save the file, and then run the file without any command-line arguments.
+
+ruby ec2-ruby-example-create-instance.rb
+```
+
+To display the list of correct command-line arguments, run the file along with the `-h` or `--help` option, for example:
+
+```
+# Running one of the following:
+
+ruby ec2-ruby-example-create-instance.rb -h
+ruby ec2-ruby-example-create-instance.rb --help
+
+# Displays:
+
+Usage:   ruby ec2-ruby-example-create-instance.rb IMAGE_ID KEY_PAIR_NAME TAG_KEY TAG_VALUE INSTANCE_TYPE REGION [USER_DATA_FILE]
+Example: ruby ec2-ruby-example-create-instance.rb ami-0947d2ba12EXAMPLE my-key-pair my-key my-value t2.micro us-east-1 my-user-data.txt
+```
+
+Most of these files have been refactored into reusable functions that can be copied into your own code. You can then call those functions directly from your own code without modifying the copied function code itself. For example, you could copy the `instance_created?` function code from the `ec2-ruby-example-create-instance.rb` file into your own code. You could then adapt the code in the `run_me` function in that same file as a basis to write your own code to call the copied `instance_created?` function.
+
+## Running the tests
+
+Most of these code example files have accompanying tests that are written to work with RSpec. These tests are in the `tests` folder and contain the same file name as the corresponding code example file, for example `tests/test_ec2-ruby-example-create-instance.rb` contains tests for `ec2-ruby-example-create-instance.rb`.
+
+To use RSpec to run all tests within a file, specify the path to that file, for example:
+
+```
+rspec tests/test_ec2-ruby-example-create-instance.rb
+```
+
+To explore additional options for using RSpec to run tests, run the `rspec --help` command. 
+
+Most of these tests are designed to use stubs, to avoid generating unnecessary costs in an AWS account. For more information, see [Stubbing Client Responses and Errors](https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/stubbing.html) in the *AWS SDK for Ruby Developer Guide*.
+
+
+## Additional information
+
+- [Amazon Elastic Compute Cloud Documentation](https://docs.aws.amazon.com/ec2)
+- [AWS SDK for Ruby Documentation](https://docs.aws.amazon.com/sdk-for-ruby)
+- [AWS Tools and SDKs Shared Configuration and Credentials Reference Guide](https://docs.aws.amazon.com/credref/latest/refdocs)
+- [RSpec Documentation](https://rspec.info/documentation)
+
+---
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0

ruby/example_code/ec2/ec2-ruby-example-manage-instances.rb

@@ -122,7 +122,7 @@ def instance_detailed_monitoring_enabled?(ec2_client, instance_id)
   puts "Detailed monitoring state: #{result.instance_monitorings[0].monitoring.state}"
   return true
 rescue Aws::EC2::Errors::InvalidState
-  puts "The instance is not in a monitorable state. Continuing on..."
+  puts "The instance is not in a monitorable state. Skipping this step."
   return false
 rescue StandardError => e
   puts "Error enabling detailed monitoring: #{e.message}"
@@ -191,25 +191,25 @@ def run_me
   puts 'Attempting to stop the instance. ' \
     'This might take a few minutes...'
   unless instance_stopped?(ec2_client, instance_id)
-    puts 'Cannot stop the instance. Continuing anyway...'
+    puts 'Cannot stop the instance. Skipping this step.'
   end
 
   puts "\nAttempting to restart the instance. " \
     'This might take a few minutes...'
   unless instance_restarted?(ec2_client, instance_id)
-    puts 'Cannot restart the instance. Continuing anyway...'
+    puts 'Cannot restart the instance. Skipping this step.'
   end
 
   puts "\nAttempting to reboot the instance. " \
     'This might take a few minutes...'
   unless instance_rebooted?(ec2_client, instance_id)
-    puts 'Cannot reboot the instance. Continuing anyway...'
+    puts 'Cannot reboot the instance. Skipping this step.'
   end
 
   puts "\nAttempting to enable detailed monitoring for the instance..."
   unless instance_detailed_monitoring_enabled?(ec2_client, instance_id)
     puts 'Cannot enable detailed monitoring for the instance. ' \
-      'Continuing anyway...'
+      'Skipping this step.'
   end
 
   puts "\nInformation about available instances:"