Added Consul module (#2194)

* added consul module

* removed existing examples

* added WithConfigFile and examples. swapped panics with fatalf

* removed more references

* chore: run make lint

* chore: reverse assertion

* chore: fix lint

* docs: use pinned version in docs

---------

Co-authored-by: Manuel de la Peña <mdelapenya@gmail.com>

.github/dependabot.yml

@@ -23,13 +23,6 @@ updates:
         day: sunday
       open-pull-requests-limit: 3
       rebase-strategy: disabled
-    - package-ecosystem: gomod
-      directory: /examples/consul
-      schedule:
-        interval: monthly
-        day: sunday
-      open-pull-requests-limit: 3
-      rebase-strategy: disabled
     - package-ecosystem: gomod
       directory: /examples/nginx
       schedule:
@@ -86,6 +79,13 @@ updates:
         day: sunday
       open-pull-requests-limit: 3
       rebase-strategy: disabled
+    - package-ecosystem: gomod
+      directory: /modules/consul
+      schedule:
+        interval: monthly
+        day: sunday
+      open-pull-requests-limit: 3
+      rebase-strategy: disabled
     - package-ecosystem: gomod
       directory: /modules/couchbase
       schedule:

.github/workflows/ci.yml

@@ -104,7 +104,7 @@ jobs:
       matrix:
         go-version: [1.20.x, 1.x]
         platform: [ubuntu-latest]
-        module: [artemis, cassandra, clickhouse, cockroachdb, compose, couchbase, elasticsearch, gcloud, inbucket, k3s, k6, kafka, localstack, mariadb, minio, mockserver, mongodb, mssql, mysql, nats, neo4j, openldap, postgres, pulsar, rabbitmq, redis, redpanda, vault]
+        module: [artemis, cassandra, clickhouse, cockroachdb, compose, consul, couchbase, elasticsearch, gcloud, inbucket, k3s, k6, kafka, localstack, mariadb, minio, mockserver, mongodb, mssql, mysql, nats, neo4j, openldap, postgres, pulsar, rabbitmq, redis, redpanda, vault]
         exclude:
           - go-version: 1.20.x
             module: compose
@@ -124,7 +124,7 @@ jobs:
     needs: test-modules
     strategy:
       matrix:
-        module: [consul, nginx, toxiproxy]
+        module: [nginx, toxiproxy]
     uses: ./.github/workflows/ci-test-go.yml
     with:
       go-version: "1.20.x"

.vscode/.testcontainers-go.code-workspace

@@ -5,10 +5,6 @@
             "name": "testcontainers-go",
             "path": "../"
         },
-        {
-            "name": "example / consul",
-            "path": "../examples/consul"
-        },
         {
             "name": "example / nginx",
             "path": "../examples/nginx"
@@ -37,6 +33,10 @@
             "name": "module / compose",
             "path": "../modules/compose"
         },
+        {
+            "name": "module / consul",
+            "path": "../modules/consul"
+        },
         {
             "name": "module / couchbase",
             "path": "../modules/couchbase"
@@ -134,4 +134,4 @@
             "path": "../modulegen"
         }
     ]
-}
+}

RELEASING.md

@@ -150,7 +150,6 @@ git add modules/**/go.*
 git commit -m chore: use new version (v0.20.1) in modules and examples
 git tag v0.20.1
 git tag examples/bigtable/v0.20.1
-git tag examples/consul/v0.20.1
 git tag examples/datastore/v0.20.1
 git tag examples/firestore/v0.20.1
 git tag examples/mongodb/v0.20.1
@@ -178,7 +177,6 @@ git commit -m chore: prepare for next minor development cycle (0.21.0)
 git push origin main --tags
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/bigtable/@v/v0.20.1.info
-curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/consul/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/datastore/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/firestore/@v/v0.20.1.info
 curl https://proxy.golang.org/github.com/testcontainers/testcontainers-go/examples/mongodb/@v/v0.20.1.info

docs/modules/consul.md

@@ -0,0 +1,58 @@
+# Consul
+
+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 Consul.
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the Consul module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/modules/consul
+```
+
+## Usage example
+
+<!--codeinclude-->
+[Creating a Consul container](../../modules/consul/examples_test.go) inside_block:runConsulContainer
+<!--/codeinclude-->
+
+## Module reference
+
+The Consul module exposes one entrypoint function to create the Consul container, and this function receives two parameters:
+
+```golang
+func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*ConsulContainer, error)
+```
+
+- `context.Context`, the Go context.
+- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+
+### Container Options
+
+When starting the Consul container, you can pass options in a variadic way to configure it.
+
+#### Image
+
+If you need to set a different Consul Docker image, you can use `testcontainers.WithImage` with a valid Docker image
+for Consul. E.g. `testcontainers.WithImage("docker.io/hashicorp/consul:1.15")`.
+
+{% include "../features/common_functional_options.md" %}
+
+#### Configuration File
+If you need to customize the behavior for the deployed node you can use either `WithConfigString(config string)` or `WithConfigFile(configPath string)`.
+The configuration has to be in JSON format and will be loaded at the node startup.
+
+### Container Methods
+
+The Consul container exposes the following method:
+
+#### ApiEndpoint
+This method returns the connection string to connect to the Consul container API, using the default `8500` port.
+
+<!--codeinclude-->
+[Using ApiEndpoint with the Consul client](../../modules/consul/examples_test.go) inside_block:connectConsul
+<!--/codeinclude-->

mkdocs.yml

@@ -67,6 +67,7 @@ nav:
         - modules/cassandra.md
         - modules/clickhouse.md
         - modules/cockroachdb.md
+        - modules/consul.md
         - modules/couchbase.md
         - modules/elasticsearch.md
         - modules/gcloud.md
@@ -92,7 +93,6 @@ nav:
         - modules/vault.md
     - Examples:
         - examples/index.md
-        - examples/consul.md
         - examples/nginx.md
         - examples/toxiproxy.md
     - System Requirements:

examples/consul/Makefile → modules/consul/Makefile

@@ -3,3 +3,4 @@ include ../../commons-test.mk
 .PHONY: test
 test:
 	$(MAKE) test-consul
+

modules/consul/consul.go

@@ -0,0 +1,88 @@
+package consul
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/wait"
+)
+
+const (
+	defaultHttpApiPort = "8500"
+	defaultBrokerPort  = "8600"
+)
+
+const (
+	DefaultBaseImage = "docker.io/hashicorp/consul:1.15"
+)
+
+// ConsulContainer represents the Consul container type used in the module.
+type ConsulContainer struct {
+	testcontainers.Container
+}
+
+// ApiEndpoint returns host:port for the HTTP API endpoint.
+func (c *ConsulContainer) ApiEndpoint(ctx context.Context) (string, error) {
+	mappedPort, err := c.MappedPort(ctx, defaultHttpApiPort)
+	if err != nil {
+		return "", err
+	}
+
+	hostIP, err := c.Host(ctx)
+	if err != nil {
+		return "", err
+	}
+
+	uri := fmt.Sprintf("%s:%s", hostIP, mappedPort.Port())
+	return uri, nil
+}
+
+// WithConfigString takes in a JSON string of keys and values to define a configuration to be used by the instance.
+func WithConfigString(config string) testcontainers.CustomizeRequestOption {
+	return func(req *testcontainers.GenericContainerRequest) {
+		req.Env["CONSUL_LOCAL_CONFIG"] = config
+	}
+}
+
+// WithConfigFile takes in a path to a JSON file to define a configuration to be used by the instance.
+func WithConfigFile(configPath string) testcontainers.CustomizeRequestOption {
+	return func(req *testcontainers.GenericContainerRequest) {
+		cf := testcontainers.ContainerFile{
+			HostFilePath:      configPath,
+			ContainerFilePath: "/consul/config/node.json",
+			FileMode:          0o755,
+		}
+		req.Files = append(req.Files, cf)
+	}
+}
+
+// RunContainer creates an instance of the Consul container type
+func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*ConsulContainer, error) {
+	containerReq := testcontainers.GenericContainerRequest{
+		ContainerRequest: testcontainers.ContainerRequest{
+			Image: DefaultBaseImage,
+			ExposedPorts: []string{
+				defaultHttpApiPort + "/tcp",
+				defaultBrokerPort + "/tcp",
+				defaultBrokerPort + "/udp",
+			},
+			Env: map[string]string{},
+			WaitingFor: wait.ForAll(
+				wait.ForLog("Consul agent running!"),
+			),
+		},
+		Started: true,
+	}
+
+	for _, opt := range opts {
+		opt.Customize(&containerReq)
+	}
+
+	container, err := testcontainers.GenericContainer(ctx, containerReq)
+	if err != nil {
+		return nil, err
+	}
+
+	return &ConsulContainer{Container: container}, nil
+}