Merge branch 'main' into james/oss-3454-aws-pagination

Author: james00012

README.md

@@ -35,7 +35,7 @@ Starting with v1.0.0, Terratest follows [semantic versioning](https://semver.org
 only happen in major releases (e.g. v2.0.0).
 
 Symbols renamed or replaced in v1 are kept with `// Deprecated:` annotations pointing at the new name; removals happen
-in v2. Migrating from v0.x: see [`MIGRATION.md`](./MIGRATION.md).
+in v2. Migrating from v0.x: see the [v1 migration guide](https://terratest.gruntwork.io/docs/migrating-to-v1/overview/).
 
 ## More info
 

docs/_docs/01_getting-started/quick-start.md

@@ -16,7 +16,7 @@ custom_js:
 
 Terratest uses the Go testing framework. To use Terratest, you need to install:
 
-- [Go](https://golang.org/) (requires version >=1.21.1)
+- [Go](https://golang.org/) (requires version >=1.26)
 
 ## Setting up your project
 

docs/_docs/03_migrating-to-v1/azure.md

@@ -5,7 +5,7 @@ category: migrating-to-v1
 excerpt: >-
   Migrate Azure tests from Terratest pre-v1 to v1.0.0.
 tags: ["azure", "migration", "v1"]
-order: 300
+order: 301
 nav_title: Documentation
 nav_title_link: /docs/
 ---
@@ -84,7 +84,7 @@ Once imports are updated, expect three follow-on edits per file:
 
 Four client factories were renamed to drop the redundant `New` (a
 `Create*New*Client` reads as redundant). The old names remain as deprecated
-aliases for one minor release; please update at your convenience.
+aliases for the v1 line; please update at your convenience.
 
 | Old name | New name |
 | --- | --- |

docs/_docs/03_migrating-to-v1/overview.md

@@ -0,0 +1,170 @@
+---
+layout: collection-browser-doc
+title: Overview
+category: migrating-to-v1
+excerpt: >-
+  Summary of breaking changes in Terratest v1.0.0 and where to look first.
+tags: ["migration", "v1"]
+order: 300
+nav_title: Documentation
+nav_title_link: /docs/
+---
+
+Terratest v1.0.0 is the first stable release. Once you are on v1, breaking
+changes to the public API only happen in major releases (e.g. v2.0.0), per
+[semver](https://semver.org/). Renamed or replaced symbols stay around as
+deprecated aliases inside v1; full removal is deferred to v2.
+
+This page is the orientation map for v0.x to v1.0.0. It tells you what
+shape the changes take and where to look; the per-service guides hold the
+mechanical details.
+
+## Prerequisites
+
+- **Go 1.26 or newer.** v1.0.0 raised the minimum.
+- After upgrading, run `go mod tidy` from the directory that holds your
+  test module's `go.mod`. The AWS, Azure, and GCP SDK pins all moved.
+
+## Function naming conventions
+
+Most public Terratest helpers come in up to four variants. Knowing which
+to call is the most common source of confusion when reading v1 godoc:
+
+| Suffix | Takes `context.Context` | On error |
+| --- | --- | --- |
+| `Foo` | no | calls `t.Fatal` (fails the test) |
+| `FooE` | no | returns `error` to the caller |
+| `FooContext` | yes | calls `t.Fatal` |
+| `FooContextE` | yes | returns `error` |
+
+Two independent suffixes:
+
+- **`E` suffix.** Long-standing Terratest convention. Use the bare name
+  (`Apply`) when you want any failure to fail the test, and the `E`
+  variant (`ApplyE`) when you want the error back to assert on it or
+  retry.
+- **`Context` suffix.** Added in v1. Takes an explicit `context.Context`
+  as the second argument so callers can plumb timeouts, cancellation,
+  and tracing through. The non-`Context` variants are now deprecated
+  in favor of their `*Context*` counterparts.
+
+The preferred v1 call is `FooContext` (or `FooContextE`). For example,
+prefer `terraform.ApplyContext(t, ctx, opts)` over
+`terraform.Apply(t, opts)`.
+
+A small number of helpers do not yet expose all four variants (some
+packages added `Context` and dropped the bare `Foo` form, others have
+not grown a `Context` variant at all). Trust godoc and the deprecation
+warnings over the table when they disagree.
+
+## Migrating to the `Context` variants
+
+The Context migration is the single largest source of deprecation
+warnings you will see when upgrading. It touches nearly every helper
+package: `terraform`, `helm`, `dns-helper`, `http-helper`, `packer`,
+`docker`, `ssh`, `oci`, `k8s`, `aws`, `azure`, `gcp`. The non-`Context`
+variants compile and behave the same as before; they just emit a
+`// Deprecated:` godoc warning.
+
+Mechanical migration:
+
+```go
+// Before
+out := terraform.Apply(t, options)
+out, err := terraform.ApplyE(t, options)
+
+// After
+ctx := context.Background() // or context.WithTimeout(...) for cancellation
+out := terraform.ApplyContext(t, ctx, options)
+out, err := terraform.ApplyContextE(t, ctx, options)
+```
+
+The `*Context*` variants always take `(t, ctx, ...originalArgs)`. If
+you do not need cancellation or timeouts, `context.Background()` gives
+you the same behavior as the deprecated wrapper. When `t` is
+`*testing.T` (Go 1.24+), `t.Context()` is an even better default
+because it ties the context lifetime to the test.
+
+You can do this incrementally. The deprecated wrappers will keep
+working for the entire v1 line; they only disappear in v2.
+
+## What changed by service
+
+### Azure
+
+The largest set of breaking changes by far. The whole `modules/azure`
+package was moved from the archived `services/...` SDK to the actively
+maintained `sdk/resourcemanager/...` SDK, plus a handful of naming
+cleanups. Updating imports and the resulting compile errors is the bulk
+of the work; per-service tables and a search-and-replace cheatsheet are
+in [Azure modules](./azure/).
+
+### AWS
+
+`modules/aws/s3.go` migrated off the deprecated
+`s3/manager` package onto `s3/transfermanager`. Four exported functions
+that returned `*manager.Uploader` now return `*transfermanager.Client`:
+`NewS3Uploader`, `NewS3UploaderE`, `NewS3UploaderContext`, and
+`NewS3UploaderContextE`. The call shape moves from
+`uploader.Upload(ctx, &s3.PutObjectInput{...})` to
+`client.UploadObject(ctx, &transfermanager.UploadObjectInput{...})`,
+with the input/output types under
+`github.com/aws/aws-sdk-go-v2/feature/s3/transfermanager`.
+
+Every direct `github.com/aws/aws-*` dependency was bumped to the
+versions current at the v1.0.0 cut. If your tests import the AWS SDKs
+directly, expect to run `go mod tidy` and resolve a small number of
+type renames at the SDK level.
+
+### GCP
+
+`modules/gcp/pubsub.go` moved from `cloud.google.com/go/pubsub` (v1) to
+`cloud.google.com/go/pubsub/v2`. The wrapper functions in `modules/gcp`
+are unchanged in shape, but callers that drove the underlying client
+directly need to switch from `client.Topic("name")` /
+`client.Subscription("name")` handles to `TopicAdminClient` /
+`SubscriptionAdminClient` calls that take fully qualified resource
+names (`projects/<id>/topics/<name>`).
+
+A new family of `*WithClient` helpers was added across `modules/gcp`
+(compute, oslogin, region, pubsub, storage, cloudbuild, gcr) so tests
+can inject a pre-built SDK client. This parallels the Azure
+`*WithClient` change and is purely additive.
+
+### Kubernetes
+
+`GetKubernetesClientFromOptionsContextE` now logs the kubeconfig load
+error before falling back to `rest.InClusterConfig()`; previously the
+fallback was silent.
+
+This was a silent-failure footgun: a typo in
+`KubectlOptions.ConfigPath` would send tests against the test runner's
+in-cluster identity (potentially a different cluster) with no signal
+that anything had happened. v1 surfaces the error in the test log, and
+adds an explicit `KubectlOptions.InClusterAuth = true` opt-in that
+skips kubeconfig loading entirely for callers who want fully explicit
+auth.
+
+## Other deprecations you can defer
+
+A large set of legacy spellings picked up Go-idiomatic replacements in
+v1, all preserved as deprecated aliases. Most follow common acronym
+casing (`Id` → `ID`, `Ip` → `IP`, `Json` → `JSON`, `Url` → `URL`,
+`Ssh` → `SSH`, `Gcp` → `GCP`); a few drop redundant prefixes (Azure's
+`CreateNew*Client*` becomes `Create*Client*`); and a few rename for
+clarity (e.g. `SaveAmiId` / `LoadAmiId` became
+`SaveArtifactID` / `LoadArtifactID` to reflect that the helpers are
+not AMI-specific).
+
+You do not need to track these one by one. Run `go vet` or
+`staticcheck` against your test module after upgrading; the deprecated
+aliases all carry `// Deprecated:` annotations and the linter will
+list them with the replacement to use. Aliases stay for the v1 line
+and are removed in v2.
+
+## Need help
+
+Open an issue on the [Terratest
+repo](https://github.com/gruntwork-io/terratest/issues) with a snippet
+of the failing code and the relevant module label. If you spot a gap
+in this guide, send a PR against `docs/_docs/03_migrating-to-v1/`.

docs/_docs/04_community/contributing.md

@@ -256,9 +256,9 @@ go test -timeout 30m -run "<TEST_NAME>"
 This repo follows the principles of [Semantic Versioning](http://semver.org/). You can find each new release,
 along with the changelog, in the [Releases Page](https://github.com/gruntwork-io/terratest/releases).
 
-During initial development, the major version will be 0 (e.g., `0.x.y`), which indicates the code does not yet have a
-stable API. Once we hit `1.0.0`, we will make every effort to maintain a backwards compatible API and use the MAJOR,
-MINOR, and PATCH versions on each release to indicate any incompatibilities.
+Starting with `1.0.0`, breaking changes to the public API only happen in major releases. Symbols renamed or replaced
+inside the v1 line are kept as `// Deprecated:` aliases so test code that compiled against an earlier v1.x.y release
+will keep compiling against later ones; full removal is deferred to v2.
 
 ### Developing For Azure
 

modules/azure/availabilityset.go

@@ -106,6 +106,10 @@ func CheckAvailabilitySetContainsVMWithClient(ctx context.Context, client *armco
 		return false, err
 	}
 
+	if resp.Properties == nil {
+		return false, NewNotFoundError("Virtual Machine", vmName, avsName)
+	}
+
 	for _, vm := range resp.Properties.VirtualMachines {
 		if vm.ID == nil {
 			continue
@@ -171,6 +175,10 @@ func GetAvailabilitySetVMNamesInCapsWithClient(ctx context.Context, client *armc
 
 	vms := []string{}
 
+	if resp.Properties == nil {
+		return vms, nil
+	}
+
 	for _, vm := range resp.Properties.VirtualMachines {
 		if vm.ID == nil {
 			continue

modules/azure/client_factory.go

@@ -489,9 +489,9 @@ func CreateSQLServerClient(subscriptionID string) (*armsql.ServersClient, error)
 	return CreateSQLServerClientContext(context.Background(), subscriptionID)
 }
 
-// CreateSQLMangedInstanceClientContext is a helper function that will create and setup a sql managed instance client.
+// CreateSQLManagedInstanceClientContext is a helper function that will create and setup a sql managed instance client.
 // The ctx parameter supports cancellation and timeouts.
-func CreateSQLMangedInstanceClientContext(_ context.Context, subscriptionID string) (*armsql.ManagedInstancesClient, error) {
+func CreateSQLManagedInstanceClientContext(_ context.Context, subscriptionID string) (*armsql.ManagedInstancesClient, error) {
 	clientFactory, err := getArmSQLClientFactory(subscriptionID)
 	if err != nil {
 		return nil, err
@@ -500,16 +500,26 @@ func CreateSQLMangedInstanceClientContext(_ context.Context, subscriptionID stri
 	return clientFactory.NewManagedInstancesClient(), nil
 }
 
-// CreateSQLMangedInstanceClient is a helper function that will create and setup a sql managed instance client.
+// CreateSQLManagedInstanceClient is a helper function that will create and setup a sql managed instance client.
 //
-// Deprecated: Use [CreateSQLMangedInstanceClientContext] instead.
-func CreateSQLMangedInstanceClient(subscriptionID string) (*armsql.ManagedInstancesClient, error) {
-	return CreateSQLMangedInstanceClientContext(context.Background(), subscriptionID)
+// Deprecated: Use [CreateSQLManagedInstanceClientContext] instead.
+func CreateSQLManagedInstanceClient(subscriptionID string) (*armsql.ManagedInstancesClient, error) {
+	return CreateSQLManagedInstanceClientContext(context.Background(), subscriptionID)
 }
 
-// CreateSQLMangedDatabasesClientContext is a helper function that will create and setup a sql managed databases client.
+// Deprecated: Use [CreateSQLManagedInstanceClientContext] instead.
+func CreateSQLMangedInstanceClientContext(ctx context.Context, subscriptionID string) (*armsql.ManagedInstancesClient, error) { //nolint:revive,staticcheck // preserving deprecated function name
+	return CreateSQLManagedInstanceClientContext(ctx, subscriptionID)
+}
+
+// Deprecated: Use [CreateSQLManagedInstanceClient] instead.
+func CreateSQLMangedInstanceClient(subscriptionID string) (*armsql.ManagedInstancesClient, error) { //nolint:revive,staticcheck // preserving deprecated function name
+	return CreateSQLManagedInstanceClient(subscriptionID)
+}
+
+// CreateSQLManagedDatabasesClientContext is a helper function that will create and setup a sql managed databases client.
 // The ctx parameter supports cancellation and timeouts.
-func CreateSQLMangedDatabasesClientContext(_ context.Context, subscriptionID string) (*armsql.ManagedDatabasesClient, error) {
+func CreateSQLManagedDatabasesClientContext(_ context.Context, subscriptionID string) (*armsql.ManagedDatabasesClient, error) {
 	clientFactory, err := getArmSQLClientFactory(subscriptionID)
 	if err != nil {
 		return nil, err
@@ -518,11 +528,21 @@ func CreateSQLMangedDatabasesClientContext(_ context.Context, subscriptionID str
 	return clientFactory.NewManagedDatabasesClient(), nil
 }
 
-// CreateSQLMangedDatabasesClient is a helper function that will create and setup a sql managed databases client.
+// CreateSQLManagedDatabasesClient is a helper function that will create and setup a sql managed databases client.
 //
-// Deprecated: Use [CreateSQLMangedDatabasesClientContext] instead.
-func CreateSQLMangedDatabasesClient(subscriptionID string) (*armsql.ManagedDatabasesClient, error) {
-	return CreateSQLMangedDatabasesClientContext(context.Background(), subscriptionID)
+// Deprecated: Use [CreateSQLManagedDatabasesClientContext] instead.
+func CreateSQLManagedDatabasesClient(subscriptionID string) (*armsql.ManagedDatabasesClient, error) {
+	return CreateSQLManagedDatabasesClientContext(context.Background(), subscriptionID)
+}
+
+// Deprecated: Use [CreateSQLManagedDatabasesClientContext] instead.
+func CreateSQLMangedDatabasesClientContext(ctx context.Context, subscriptionID string) (*armsql.ManagedDatabasesClient, error) { //nolint:revive,staticcheck // preserving deprecated function name
+	return CreateSQLManagedDatabasesClientContext(ctx, subscriptionID)
+}
+
+// Deprecated: Use [CreateSQLManagedDatabasesClient] instead.
+func CreateSQLMangedDatabasesClient(subscriptionID string) (*armsql.ManagedDatabasesClient, error) { //nolint:revive,staticcheck // preserving deprecated function name
+	return CreateSQLManagedDatabasesClient(subscriptionID)
 }
 
 // getArmSQLClientFactory gets an arm sql client factory

modules/azure/sql_managedinstance.go

@@ -67,7 +67,7 @@ func GetManagedInstanceContext(t testing.TestingT, ctx context.Context, resGroup
 // GetManagedInstanceContextE retrieves the SQL managed instance object for the given subscription.
 // The ctx parameter supports cancellation and timeouts.
 func GetManagedInstanceContextE(ctx context.Context, subscriptionID string, resGroupName string, managedInstanceName string) (*armsql.ManagedInstance, error) {
-	sqlmiClient, err := CreateSQLMangedInstanceClientContext(ctx, subscriptionID)
+	sqlmiClient, err := CreateSQLManagedInstanceClientContext(ctx, subscriptionID)
 	if err != nil {
 		return nil, err
 	}
@@ -117,7 +117,7 @@ func GetManagedInstanceDatabaseContext(t testing.TestingT, ctx context.Context,
 // GetManagedInstanceDatabaseContextE retrieves the SQL managed database object for the given subscription.
 // The ctx parameter supports cancellation and timeouts.
 func GetManagedInstanceDatabaseContextE(ctx context.Context, subscriptionID string, resGroupName string, managedInstanceName string, databaseName string) (*armsql.ManagedDatabase, error) {
-	sqlmiDBClient, err := CreateSQLMangedDatabasesClientContext(ctx, subscriptionID)
+	sqlmiDBClient, err := CreateSQLManagedDatabasesClientContext(ctx, subscriptionID)
 	if err != nil {
 		return nil, err
 	}

modules/gcp/compute.go

@@ -425,12 +425,22 @@ func (i *Instance) SetLabelsContextE(t testing.TestingT, ctx context.Context, la
 	return i.SetLabelsWithClient(ctx, service, labels)
 }
 
-// SetLabelsWithClient adds the tags to the given Compute Instance using the supplied *compute.Service.
-// Prefer this variant in unit tests where the service is backed by an httptest fake server
-// (see compute_unit_test.go for the pattern).
+// SetLabelsWithClient merges the given labels into the instance's existing labels using the
+// supplied *compute.Service. Keys present in labels overwrite existing values; other labels
+// are preserved. Prefer this variant in unit tests where the service is backed by an httptest
+// fake server (see compute_unit_test.go for the pattern).
 // The ctx parameter supports cancellation and timeouts.
 func (i *Instance) SetLabelsWithClient(ctx context.Context, service *compute.Service, labels map[string]string) error {
-	req := compute.InstancesSetLabelsRequest{Labels: labels, LabelFingerprint: i.LabelFingerprint}
+	merged := make(map[string]string, len(i.Labels)+len(labels))
+	for k, v := range i.Labels {
+		merged[k] = v
+	}
+
+	for k, v := range labels {
+		merged[k] = v
+	}
+
+	req := compute.InstancesSetLabelsRequest{Labels: merged, LabelFingerprint: i.LabelFingerprint}
 
 	if _, err := service.Instances.SetLabels(i.projectID, ZoneURLToZone(i.Zone), i.Name, &req).Context(ctx).Do(); err != nil {
 		return fmt.Errorf("Instances.SetLabels(%s) got error: %w", i.Name, err)