Merge branch 'main' into james/oss-3364-bump-gcp-sdk

Author: james00012

docs/_docs/01_getting-started/testing-terragrunt.md

@@ -5,7 +5,7 @@ category: getting-started
 excerpt: >-
   Learn how to test Terragrunt configurations with Terratest.
 tags: ["terragrunt", "testing", "quick-start"]
-order: 104
+order: 105
 nav_title: Documentation
 nav_title_link: /docs/
 ---
@@ -27,15 +27,17 @@ For testing a single Terragrunt unit, use the `terraform` package with `Terrafor
 func TestTerragruntModule(t *testing.T) {
     t.Parallel()
 
+    ctx := t.Context()
+
     terraformOptions := terraform.WithDefaultRetryableErrors(t, &terraform.Options{
         TerraformDir:    "../examples/my-module",
         TerraformBinary: "terragrunt",
     })
 
-    defer terraform.Destroy(t, terraformOptions)
-    terraform.Apply(t, terraformOptions)
+    defer terraform.DestroyContext(t, ctx, terraformOptions)
+    terraform.ApplyContext(t, ctx, terraformOptions)
 
-    output := terraform.Output(t, terraformOptions, "my_output")
+    output := terraform.OutputContext(t, ctx, terraformOptions, "my_output")
     assert.Equal(t, "expected_value", output)
 }
 ```
@@ -48,17 +50,19 @@ For testing a stack of units with dependencies, use the dedicated `terragrunt` p
 func TestStack(t *testing.T) {
     t.Parallel()
 
+    ctx := t.Context()
+
     testFolder, err := files.CopyTerragruntFolderToTemp("../live/prod", t.Name())
     require.NoError(t, err)
 
     options := &terragrunt.Options{
         TerragruntDir: testFolder,
     }
 
-    defer terragrunt.DestroyAll(t, options)
-    terragrunt.ApplyAll(t, options)
+    defer terragrunt.DestroyAllContext(t, ctx, options)
+    terragrunt.ApplyAllContext(t, ctx, options)
 
-    exitCode := terragrunt.PlanAllExitCode(t, options)
+    exitCode := terragrunt.PlanAllExitCodeContext(t, ctx, options)
     require.Equal(t, 0, exitCode)
 }
 ```

docs/_docs/02_testing-best-practices/cleanup.md

@@ -18,11 +18,13 @@ always cleanup after themselves so you don't leave a bunch of resources lying ar
 For example, if your test runs `terraform apply`, you should run `terraform destroy` at the end to clean up:
 
 ```go
+ctx := t.Context()
+
 // Ensure cleanup always runs
-defer terraform.Destroy(t, options)
+defer terraform.DestroyContext(t, ctx, options)
 
 // Deploy
-terraform.Apply(t, options)
+terraform.ApplyContext(t, ctx, options)
 
 // Validate
 checkServerWorks(t, options)

docs/_docs/02_testing-best-practices/debugging-interleaved-test-output.md

@@ -69,13 +69,12 @@ You can install any binary using one of the following methods:
 
 ### Manual installation
 
-To install the binary manually, download the version that matches your platform and place it somewhere on your `PATH`.
-For example to install version 0.13.13 of `terratest_log_parser`:
+To install the binary manually, download the version that matches your platform and place it somewhere on your `PATH`:
 
 ```bash
-# This example assumes a linux 64bit machine
+# This example assumes a linux 64bit machine and installs the latest release.
 # Use curl to download the binary
-curl --location --silent --fail --show-error -o terratest_log_parser https://github.com/gruntwork-io/terratest/releases/download/v0.13.13/terratest_log_parser_linux_amd64
+curl --location --silent --fail --show-error -o terratest_log_parser https://github.com/gruntwork-io/terratest/releases/latest/download/terratest_log_parser_linux_amd64
 # Make the downloaded binary executable
 chmod +x terratest_log_parser
 # Finally, we place the downloaded binary to a place in the PATH
@@ -89,13 +88,13 @@ install](https://pkg.go.dev/cmd/go#hdr-Compile_and_install_packages_and_dependen
 with `go install`, point `go install` to the repo and path where the main code for each relevant command lives. For
 example, you can install the terratest log parser binary with:
 
-```
+```bash
 go install github.com/gruntwork-io/terratest/cmd/terratest_log_parser@latest
 ```
 
 Similarly, to install `pick-instance-type`, you can run:
 
-```
+```bash
 go install github.com/gruntwork-io/terratest/cmd/pick-instance-type@latest
 ```
 
@@ -105,5 +104,5 @@ You can also use [the gruntwork-installer utility](https://github.com/gruntwork-
 binaries, which will do the above steps and automatically select the right binary for your platform:
 
 ```bash
-gruntwork-install --binary-name 'terratest_log_parser' --repo 'https://github.com/gruntwork-io/terratest' --tag 'v0.13.13'
+gruntwork-install --binary-name 'terratest_log_parser' --repo 'https://github.com/gruntwork-io/terratest' --tag 'v1.0.0'
 ```

docs/_docs/02_testing-best-practices/error-handling.md

@@ -10,11 +10,11 @@ nav_title: Documentation
 nav_title_link: /docs/
 ---
 
-Just about every method `foo` in Terratest comes in two versions: `foo` and `fooE` (e.g., `terraform.Apply` and
-`terraform.ApplyE`).
+Just about every method `foo` in Terratest comes in two versions: `foo` and `fooE` (e.g., `terraform.ApplyContext` and
+`terraform.ApplyContextE`).
 
-- `foo`: The base method takes a `t *testing.T` as an argument. If the method hits any errors, it calls `t.Fatal` to
-  fail the test.
+- `foo`: The base method takes a `t *testing.T` and a `context.Context` as arguments. If the method hits any errors,
+  it calls `t.Fatal` to fail the test.
 
 - `fooE`: Methods that end with the capital letter `E` always return an `error` as the last argument and never call
   `t.Fatal` themselves. This allows you to decide how to handle errors.
@@ -23,25 +23,28 @@ You will use the base method name most of the time, as it allows you to keep you
 `if err != nil` checks all over the place:
 
 ```go
-terraform.Init(t, terraformOptions)
-terraform.Apply(t, terraformOptions)
-url := terraform.Output(t, terraformOptions, "url")
+ctx := t.Context()
+terraform.InitContext(t, ctx, terraformOptions)
+terraform.ApplyContext(t, ctx, terraformOptions)
+url := terraform.OutputContext(t, ctx, terraformOptions, "url")
 ```
 
-In the code above, if `Init`, `Apply`, or `Output` hits an error, the method will call `t.Fatal` and fail the test
-immediately, which is typically the behavior you want. However, if you are _expecting_ an error and don't want it to
-cause a test failure, use the method name that ends with a capital `E`:
+In the code above, if `InitContext`, `ApplyContext`, or `OutputContext` hits an error, the method will call `t.Fatal`
+and fail the test immediately, which is typically the behavior you want. However, if you are _expecting_ an error and
+don't want it to cause a test failure, use the method name that ends with a capital `E`:
 
 ```go
-if _, err := terraform.InitE(t, terraformOptions); err != nil {
+ctx := t.Context()
+
+if _, err := terraform.InitContextE(t, ctx, terraformOptions); err != nil {
   // Do something with err
 }
 
-if _, err := terraform.ApplyE(t, terraformOptions); err != nil {
+if _, err := terraform.ApplyContextE(t, ctx, terraformOptions); err != nil {
   // Do something with err
 }
 
-url, err := terraform.OutputE(t, terraformOptions, "url")
+url, err := terraform.OutputContextE(t, ctx, terraformOptions, "url")
 if err != nil {
   // Do something with err
 }

docs/_docs/02_testing-best-practices/idempotent.md

@@ -15,11 +15,14 @@ A Terraform configuration is idempotent when a second apply results in 0 changes
 1.  What you define in Terraform is exactly what is being deployed. 
 1.  Detection of bugs in Terraform resources and providers that might affect your configuration.
 
-You can use Terratest's `terraform.ApplyAndIdempotent()` function to both apply your Terraform configuration and test its
-idempotency.
+You can use Terratest's `terraform.ApplyAndIdempotentContext()` function to both apply your Terraform configuration and
+test its idempotency.
 
 ```go
-terraform.ApplyAndIdempotent(t, terraformOptions)
+ctx := t.Context()
+
+defer terraform.DestroyContext(t, ctx, terraformOptions)
+terraform.ApplyAndIdempotentContext(t, ctx, terraformOptions)
 ```
 
 If a second apply of your Terraform configuration results in changes then your test will fail.

docs/_docs/02_testing-best-practices/namespacing.md

@@ -20,12 +20,12 @@ a unique name to ensure that:
 For example, when deploying AWS infrastructure with Terraform, that typically means exposing variables that allow you
 to configure auto scaling group names, security group names, IAM role names, and any other names that must be unique.
 
-You can use Terratest's `random.UniqueId()` function to generate identifiers that are short enough to use in resource
+You can use Terratest's `random.UniqueID()` function to generate identifiers that are short enough to use in resource
 names (just 6 characters) but random enough to make it unlikely that you'll have a conflict.
 
 ```go
-uniqueId := random.UniqueId()
-instanceName := fmt.Sprintf("terratest-http-example-%s", uniqueId)
+uniqueID := random.UniqueID()
+instanceName := fmt.Sprintf("terratest-http-example-%s", uniqueID)
 
 terraformOptions := &terraform.Options {
   TerraformDir: "../examples/terraform-http-example",
@@ -34,5 +34,5 @@ terraformOptions := &terraform.Options {
   },
 }
 
-terraform.Apply(t, terraformOptions)
+terraform.ApplyContext(t, t.Context(), terraformOptions)
 ```

docs/_docs/02_testing-best-practices/picking-instance-types.md

@@ -10,56 +10,53 @@ nav_title: Documentation
 nav_title_link: /docs/
 ---
 
-It's common to want to test infrastructure code that deploys [EC2 instances](https://aws.amazon.com/ec2/) into AWS. 
+It's common to want to test infrastructure code that deploys [EC2 instances](https://aws.amazon.com/ec2/) into AWS.
 There are many different [instance types](https://aws.amazon.com/ec2/instance-types/), but not all instance types
-are available in all [regions or availability zones 
-(AZs)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). For example, 
+are available in all [regions or availability zones
+(AZs)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). For example,
 `t3.micro` is sometimes available only in newer AZs, while `t2.micro` is sometimes only available in older AZs. If you
 are testing code that needs to deploy a "small" instance across many regions, this can make it tricky to know which
 region to pick.
 
 To help work around this problem, Terratest includes:
 
-1. [`GetRecommendedInstanceType`](#getrecommendedinstancetype): A Go function that helps you pick a recommended instance type.
+1. [`GetRecommendedInstanceTypeContext`](#getrecommendedinstancetypecontext): A Go function that helps you pick a recommended instance type.
 1. [`pick-instance-type`](#pick-instance-type): A CLI tool that helps you pick a recommended instance type.
 
 
 
 
-## `GetRecommendedInstanceType`
+## `GetRecommendedInstanceTypeContext`
 
-`GetRecommendedInstanceType` takes in an AWS region and a list of EC2 instance types and returns the first instance 
-type in the list that is available in all Availability Zones (AZs) in the given region. If there's no
-instance available in all AZs, this function exits with an error. 
+`GetRecommendedInstanceTypeContext` takes in an AWS region and a list of EC2 instance types and returns the first
+instance type in the list that is available in all Availability Zones (AZs) in the given region. If there's no
+instance available in all AZs, this function exits with an error.
 
 Example usage:
 
 ```go
-aws.GetRecommendedInstanceType(t, "eu-west-1", []string{"t2.micro", "t3.micro"})
-// As of July, 2020, returns "t2.micro"
+ctx := t.Context()
 
-aws.GetRecommendedInstanceType(t, "ap-northeast-2", []string{"t2.micro", "t3.micro"})
-// As of July, 2020, returns "t3.micro"
-```   
+aws.GetRecommendedInstanceTypeContext(t, ctx, "eu-west-1", []string{"t2.micro", "t3.micro"})
+aws.GetRecommendedInstanceTypeContext(t, ctx, "ap-northeast-2", []string{"t2.micro", "t3.micro"})
+```
 
 
 
 ## `pick-instance-type`
 
-`pick-instance-type` is a CLI tool that you can download from the [Terratest releases 
-page](https://github.com/gruntwork-io/terratest/releases) (click "Assets" under any release). It takes in an AWS 
-region and a list of EC2 instance types and prints to `stdout` the first instance type in the list that is available in 
+`pick-instance-type` is a CLI tool that you can download from the [Terratest releases
+page](https://github.com/gruntwork-io/terratest/releases) (click "Assets" under any release). It takes in an AWS
+region and a list of EC2 instance types and prints to `stdout` the first instance type in the list that is available in
 all Availability Zones (AZs) in the given region. If there's no instance available in all AZs, `pick-instance-type`
 exits with an error.
 
 Example usage:
 
 ```bash
-# Data below is from July, 2020
-
 $ pick-instance-type eu-west-1 t2.micro t3.micro
 t2.micro
 
 $ pick-instance-type ap-northeast-2 t2.micro t3.micro
 t3.micro
-```   
+```

docs/_docs/04_community/contributing.md

@@ -47,9 +47,9 @@ We accept different types of contributions for each of these two types of helper
 These are helper functions that integrate with various DevOps tools—e.g., Terraform, Docker, Packer, and
 Kubernetes—that you can use to deploy infrastructure in your automated tests. Examples:
 
-* `terraform.InitAndApply`: run `terraform init` and `terraform apply`.
-* `packer.BuildArtifacts`: run `packer build`.
-* `shell.RunCommandAndGetOutput`: run an arbitrary shell command and return `stdout` and `stderr` as a string.
+* `terraform.InitAndApplyContext`: run `terraform init` and `terraform apply`.
+* `packer.BuildArtifactsContext`: run `packer build`.
+* `shell.RunCommandContextAndGetOutput`: run an arbitrary shell command and return `stdout` and `stderr` as a string.
 
 Here are the guidelines for contributions with external tools:
 
@@ -66,10 +66,10 @@ Here are the guidelines for contributions with external tools:
 These are helper functions for creating, destroying, and validating infrastructure directly via API calls or SDKs.
 Examples:
 
-* `http_helper.HttpGetWithRetry`: make an HTTP request, retrying until you get a certain expected response.
-* `ssh.CheckSshCommand`: SSH to a server and execute a command.
-* `aws.CreateS3Bucket`: create an S3 bucket.
-* `aws.GetPrivateIpsOfEc2Instances`:  use the AWS APIs to fetch IPs of some EC2 instances.
+* `http_helper.HTTPGetWithRetryContext`: make an HTTP request, retrying until you get a certain expected response.
+* `ssh.CheckSSHCommandContext`: SSH to a server and execute a command.
+* `aws.CreateS3BucketContext`: create an S3 bucket.
+* `aws.GetPrivateIpsOfEc2InstancesContext`: use the AWS APIs to fetch IPs of some EC2 instances.
 
 The number of possible such helpers is nearly infinite, so to avoid Terratest becoming a gigantic, sprawling library
 we ask that contributions for new infrastructure helpers are limited to:
@@ -81,8 +81,8 @@ we ask that contributions for new infrastructure helpers are limited to:
 1. **Complexity**: we ask that you only contribute infrastructure and validation helpers for code that is relatively
    complex to do from scratch. For example, a helper that merely wraps an existing function in the AWS or GCP SDK is
    not a great choice, as the wrapper isn't contributing much value, but is bloating the Terratest API. On the other
-   hand, helpers that expose simple APIs for complex logic are great contributions: `ssh.CheckSshCommand` is a great
-   example of this, as it provides a simple one-line interface for dozens of lines of complicated SSH logic.
+   hand, helpers that expose simple APIs for complex logic are great contributions: `ssh.CheckSSHCommandContext` is a
+   great example of this, as it provides a simple one-line interface for dozens of lines of complicated SSH logic.
 
 1. **Popularity**: Terratest should only contain helpers for common use cases that come up again and again in the
    course of testing. We don't want to bloat the library with lots of esoteric helpers for rarely used tools, so
@@ -262,7 +262,7 @@ MINOR, and PATCH versions on each release to indicate any incompatibilities.
 
 ### Developing For Azure
 
-Azure supports multliple cloud environments. In order to properly register the correct environment for you test code, you need to use the Azure SDK Client Factory.
+Azure supports multiple cloud environments. In order to properly register the correct environment for you test code, you need to use the Azure SDK Client Factory.
 
 #### Azure SDK Client Factory
 

examples/terraform-asg-scp-example/README.md

@@ -22,12 +22,14 @@ When a test fails, it is often important to be able to quickly get to logs and c
 You can use terratest to help with this task by specifying `RemoteFileSpecification` structs that describe which files you want to copy from your instances:
 
 ```go
+ctx := t.Context()
+
 logstashSpec := aws.RemoteFileSpecification{
 	SshUser:sshUserName,
 	UseSudo:true,
 	KeyPair:keyPair,
 	LocalDestinationDir:filepath.Join("/tmp", "logs", t.Name(), "logstash"),
-	AsgNames: strings.Split(strings.Replace(terraform.OutputRequired(t, terraformOptions, "logstash_server_asg_names"), "\n", "", -1), ","),
+	AsgNames: strings.Split(strings.Replace(terraform.OutputRequiredContext(t, ctx, terraformOptions, "logstash_server_asg_names"), "\n", "", -1), ","),
 	RemotePathToFileFilter: map[string][]string {
 		"/var/log/logstash":{"*"},
 		"/etc/logstash/conf.d" : {"*"},
@@ -37,12 +39,12 @@ logstashSpec := aws.RemoteFileSpecification{
 
 Once you've described what files you want, grabbing them from ASGs is simple with:
 ```go
-aws.FetchFilesFromAllAsgsE(t, awsRegion, logstashSpec)
+aws.FetchFilesFromAsgsPContextE(t, ctx, awsRegion, &logstashSpec)
 ```
 
 or directly from EC2 instances with:
 ```go
-aws.FetchFilesFromInstance(t, awsRegion, sshUserName, keyPair, appServerInstanceId, true, appServerConfig, filepath.Join("/tmp", "logs", t.Name(), "app_server"), []string{"*.yml", "caFile", "*.key", "*.pem"})
+aws.FetchFilesFromInstanceContext(t, ctx, awsRegion, sshUserName, keyPair, appServerInstanceId, true, appServerConfig, filepath.Join("/tmp", "logs", t.Name(), "app_server"), []string{"*.yml", "caFile", "*.key", "*.pem"})
 ```
 
 Finally, to put all of this together, in your go test you could do something like: