Merge branch 'main' into rootless-docker

* main: (22 commits)
  docs: document the Go version (testcontainers#1246)
  chore(deps): bump github.com/aws/aws-sdk-go-v2/config (testcontainers#1222)
  chore(deps): bump golang.org/x/sys from 0.7.0 to 0.8.0 (testcontainers#1202)
  chore(deps): bump github.com/stretchr/testify from 1.8.2 to 1.8.3 (testcontainers#1232)
  chore(deps): bump cloud.google.com/go/spanner in /examples/spanner (testcontainers#1226)
  chore: Removes the refercence about docker 22.06 from the docker-compose docs and updates the replace directive for the compose module. (testcontainers#1243)
  chore(deps): bump go.mongodb.org/mongo-driver in /examples/mongodb (testcontainers#1233)
  chore(deps): bump google.golang.org/api from 0.123.0 to 0.124.0 in /examples (testcontainers#1244)
  chore(deps): bump github.com/aws/aws-sdk-go-v2/service/s3 (testcontainers#1241)
  chore(deps): bump github.com/aws/aws-sdk-go in /modules/localstack (testcontainers#1242)
  added NATS JetStream example (testcontainers#1190)
  chore(deps): bump github.com/imdario/mergo from 0.3.12 to 0.3.15 (testcontainers#1204)
  chore(deps): bump cloud.google.com/go/firestore in /examples/firestore (testcontainers#1216)
  chore(deps): bump k8s.io/client-go from 0.22.5 to 0.27.2 in /modules/k3s (testcontainers#1211)
  chore(deps): bump go.mongodb.org/mongo-driver in /examples/mongodb (testcontainers#1092)
  chore(deps): bump github.com/neo4j/neo4j-go-driver/v5 in /modules/neo4j (testcontainers#1206)
  chore(deps): bump github.com/twmb/franz-go in /modules/redpanda (testcontainers#1201)
  chore(deps): bump google.golang.org/api from 0.121.0 to 0.123.0 in /examples (testcontainers#1229)
  chore(deps): bump github.com/stretchr/testify from 1.8.2 to 1.8.3 (testcontainers#1228)
  ...

.github/dependabot.yml

@@ -42,6 +42,12 @@ updates:
         interval: monthly
       open-pull-requests-limit: 3
       rebase-strategy: disabled
+    - package-ecosystem: gomod
+      directory: /examples/nats
+      schedule:
+        interval: monthly
+      open-pull-requests-limit: 3
+      rebase-strategy: disabled
     - package-ecosystem: gomod
       directory: /examples/nginx
       schedule:
@@ -84,6 +90,12 @@ updates:
         interval: monthly
       open-pull-requests-limit: 3
       rebase-strategy: disabled
+    - package-ecosystem: gomod
+      directory: /modules/k3s
+      schedule:
+        interval: monthly
+      open-pull-requests-limit: 3
+      rebase-strategy: disabled
     - package-ecosystem: gomod
       directory: /modules/localstack
       schedule:

.github/workflows/module-k3s.yml

@@ -0,0 +1,56 @@
+name: K3s module pipeline
+
+on:
+  push:
+    paths-ignore:
+    - 'mkdocs.yml'
+    - 'docs/**'
+    - 'README.md'
+  pull_request:
+    paths-ignore:
+    - 'mkdocs.yml'
+    - 'docs/**'
+    - 'README.md'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  test-k3s:
+    strategy:
+      matrix:
+        go-version: [1.19.x, 1.x]
+    runs-on: "ubuntu-latest"
+    steps:
+
+      - name: Set up Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: ${{ matrix.go-version }}
+        id: go
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v3
+
+      - name: modVerify
+        working-directory: ./modules/k3s
+        run: go mod verify
+
+      - name: modTidy
+        working-directory: ./modules/k3s
+        run: make tools-tidy
+
+      - name: gotestsum
+        working-directory: ./modules/k3s
+        run: make test-unit
+
+      - name: Run checker
+        run: |
+          ./scripts/check_environment.sh
+
+      - name: Test Summary
+        uses: test-summary/action@4ee9ece4bca777a38f05c8fc578ac2007fe266f7
+        with:
+          paths: "**/TEST-k3s*.xml"
+        if: always()

.github/workflows/nats-example.yml

@@ -0,0 +1,56 @@
+name: nats example pipeline
+
+on:
+  push:
+    paths-ignore:
+    - 'mkdocs.yml'
+    - 'docs/**'
+    - 'README.md'
+  pull_request:
+    paths-ignore:
+    - 'mkdocs.yml'
+    - 'docs/**'
+    - 'README.md'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  test-nats:
+    strategy:
+      matrix:
+        go-version: [1.19.x, 1.x]
+    runs-on: "ubuntu-latest"
+    steps:
+
+      - name: Set up Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: ${{ matrix.go-version }}
+        id: go
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v3
+
+      - name: modVerify
+        working-directory: ./examples/nats
+        run: go mod verify
+
+      - name: modTidy
+        working-directory: ./examples/nats
+        run: make tools-tidy
+
+      - name: gotestsum
+        working-directory: ./examples/nats
+        run: make test-unit
+
+      - name: Run checker
+        run: |
+          ./scripts/check_environment.sh
+
+      - name: Test Summary
+        uses: test-summary/action@4ee9ece4bca777a38f05c8fc578ac2007fe266f7
+        with:
+          paths: "**/TEST-nats*.xml"
+        if: always()

docs/examples/nats.md

@@ -0,0 +1,23 @@
+# Nats
+
+## Introduction
+
+The Testcontainers module for nats.
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the nats module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/examples/nats
+```
+
+## Usage example
+
+<!--codeinclude-->
+[Creating a nats container](../../examples/nats/nats.go)
+<!--/codeinclude-->
+
+<!--codeinclude-->
+[Test for a nats container](../../examples/nats/nats_test.go)
+<!--/codeinclude-->

docs/features/docker_compose.md

@@ -15,15 +15,16 @@ go get github.com/testcontainers/testcontainers-go/modules/compose
 
 !!!warning
 
-	Given the version includes the Compose dependency, and the Docker folks added [a replace directive until the upcoming Docker 22.06 release is out](https://github.com/docker/compose/issues/9946#issuecomment-1288923912),
-	we were forced to add it too, causing consumers of _Testcontainers for Go_ to add the following replace directive to their `go.mod` files.
-	We expect this to be removed in the next releases of _Testcontainers for Go_.
+	Given the version includes the Compose dependency, and the Docker folks added a replace directive in their [go.mod](https://github.com/docker/compose/blob/v2/go.mod#L175-L188),
+	we were forced to add it as well. As a result, users of _Testcontainers for Go_ need to add the following replace directive to their `go.mod` files.
 
 	```
 	replace (
 
 		github.com/cucumber/godog => github.com/laurazard/godog v0.0.0-20220922095256-4c4b17abdae7
 
+		golang.org/x/oauth2 => golang.org/x/oauth2 v0.1.0
+
 		// For k8s dependencies, we use a replace directive, to prevent them being
 		// upgraded to the version specified in containerd, which is not relevant to the
 		// version needed.

docs/modules/k3s.md

@@ -0,0 +1,81 @@
+# K3s
+
+Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+## Introduction
+
+The Testcontainers module for K3s.
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the K3s module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/modules/k3s
+```
+
+## Usage example
+
+<!--codeinclude-->
+[Test for a K3s container](../../modules/k3s/k3s_test.go) inside_block: k3sRunContainer
+<!--/codeinclude-->
+
+## Module reference
+
+The K3s module exposes one entrypoint function to create the K3s container, and this function receives two parameters:
+
+```golang
+func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*K3sContainer, error)
+```
+
+- `context.Context`, the Go context.
+- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+
+
+### Container Ports
+These are the ports used by the K3s container:
+<!--codeinclude-->
+[Container Ports](../../modules/k3s/k3s.go) inside_block:containerPorts
+<!--/codeinclude-->
+
+### Container Options
+
+When starting the K3s container, you can pass options in a variadic way to configure it.
+
+#### Image
+
+If you need to set a different K3s Docker image, you can use `testcontainers.WithImage` with a valid Docker image
+for K3s. E.g. `testcontainers.WithImage("docker.io/rancher/k3s:v1.27.1-k3s1")`.
+
+#### Wait Strategies
+
+If you need to set a different wait strategy for K3s, you can use `testcontainers.WithWaitStrategy` with a valid wait strategy
+for K3s.
+
+!!!info
+    The default deadline for the wait strategy is 60 seconds.
+
+At the same time, it's possible to set a wait strategy and a custom deadline with `testcontainers.WithWaitStrategyAndDeadline`.
+
+#### Docker type modifiers
+
+If you need an advanced configuration for K3s, you can leverage the following Docker type modifiers:
+
+- `testcontainers.WithConfigModifier`
+- `testcontainers.WithHostConfigModifier`
+- `testcontainers.WithEndpointSettingsModifier`
+
+Please read the [Create containers: Advanced Settings](../features/creating_container.md#advanced-settings) documentation for more information.
+
+### Container Methods
+
+The K3s container exposes the following methods:
+
+#### GetKubeConfig
+
+The `GetKubeConfig` method returns the K3s cluster's `kubeconfig`, including the server URL, to be used for connecting
+to the Kubernetes Rest Client API using a Kubernetes client. It'll be returned in the format of `[]bytes`.
+
+<!--codeinclude-->
+[Get KubeConifg](../../modules/k3s/k3s_test.go) inside_block:GetKubeConfig
+<!--/codeinclude-->

docs/system_requirements/docker.md

@@ -0,0 +1,11 @@
+# General Docker requirements
+
+Testcontainers requires a Docker-API compatible container runtime. 
+During development, Testcontainers is actively tested against recent versions of Docker on Linux, as well as against Docker Desktop on Mac and Windows. 
+These Docker environments are automatically detected and used by Testcontainers without any additional configuration being necessary.
+
+It is possible to configure Testcontainers to work for other Docker setups, such as a remote Docker host or Docker alternatives. 
+However, these are not actively tested in the main development workflow, so not all Testcontainers features might be available and additional manual configuration might be necessary. Please see the [Docker host detection](../features/configuration.md#docker-host-detection) section for more information.
+
+If you have further questions about configuration details for your setup or whether it supports running Testcontainers-based tests, 
+please contact the Testcontainers team and other users from the Testcontainers community on [Slack](https://slack.testcontainers.org/).

docs/system_requirements/index.md

@@ -1,13 +1,7 @@
-# General Docker requirements
+# Go version
 
-## Overview
+From the [Go Release Policy](https://go.dev/doc/devel/release#policy):
 
-Testcontainers requires a Docker-API compatible container runtime. 
-During development, Testcontainers is actively tested against recent versions of Docker on Linux, as well as against Docker Desktop on Mac and Windows. 
-These Docker environments are automatically detected and used by Testcontainers without any additional configuration being necessary.
+> Each major Go release is supported until there are two newer major releases. For example, Go 1.5 was supported until the Go 1.7 release, and Go 1.6 was supported until the Go 1.8 release. We fix critical problems, including critical security problems, in supported releases as needed by issuing minor revisions (for example, Go 1.6.1, Go 1.6.2, and so on).
 
-It is possible to configure Testcontainers to work for other Docker setups, such as a remote Docker host or Docker alternatives. 
-However, these are not actively tested in the main development workflow, so not all Testcontainers features might be available and additional manual configuration might be necessary. Please see the [Docker host detection](../features/configuration.md#docker-host-detection) section for more information.
-
-If you have further questions about configuration details for your setup or whether it supports running Testcontainers-based tests, 
-please contact the Testcontainers team and other users from the Testcontainers community on [Slack](https://slack.testcontainers.org/).
+_Testcontainers for Go_ is tested against those two latest Go releases, therefore we recommend using any of them. You could check what versions are actually supported by looking at the [GitHub Action](../../.github/workflows/ci.yml) configuration, under the `test.strategy.matrix.go-version` key.

examples/bigtable/go.mod

@@ -5,7 +5,7 @@ go 1.19
 require (
 	cloud.google.com/go/bigtable v1.18.1
 	github.com/testcontainers/testcontainers-go v0.20.1
-	google.golang.org/api v0.121.0
+	google.golang.org/api v0.124.0
 	google.golang.org/grpc v1.55.0
 	gotest.tools/gotestsum v1.10.0
 )
@@ -38,12 +38,12 @@ require (
 	github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
 	github.com/golang/protobuf v1.5.3 // indirect
 	github.com/google/go-cmp v0.5.9 // indirect
-	github.com/google/s2a-go v0.1.3 // indirect
+	github.com/google/s2a-go v0.1.4 // indirect
 	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
 	github.com/google/uuid v1.3.0 // indirect
 	github.com/googleapis/enterprise-certificate-proxy v0.2.3 // indirect
 	github.com/googleapis/gax-go/v2 v2.8.0 // indirect
-	github.com/imdario/mergo v0.3.12 // indirect
+	github.com/imdario/mergo v0.3.15 // indirect
 	github.com/klauspost/compress v1.15.9 // indirect
 	github.com/magiconair/properties v1.8.7 // indirect
 	github.com/mattn/go-colorable v0.1.12 // indirect
@@ -60,11 +60,11 @@ require (
 	go.opencensus.io v0.24.0 // indirect
 	golang.org/x/crypto v0.1.0 // indirect
 	golang.org/x/mod v0.9.0 // indirect
-	golang.org/x/net v0.9.0 // indirect
-	golang.org/x/oauth2 v0.7.0 // indirect
-	golang.org/x/sync v0.1.0 // indirect
-	golang.org/x/sys v0.7.0 // indirect
-	golang.org/x/term v0.7.0 // indirect
+	golang.org/x/net v0.10.0 // indirect
+	golang.org/x/oauth2 v0.8.0 // indirect
+	golang.org/x/sync v0.2.0 // indirect
+	golang.org/x/sys v0.8.0 // indirect
+	golang.org/x/term v0.8.0 // indirect
 	golang.org/x/text v0.9.0 // indirect
 	golang.org/x/tools v0.7.0 // indirect
 	golang.org/x/xerrors v0.0.0-20220907171357-04be3eba64a2 // indirect