From 5c0381cb972dee853913b13f41770171f2744fc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20de=20la=20Pe=C3=B1a?= Date: Thu, 25 Apr 2024 12:02:10 +0200 Subject: [PATCH] docs: document the SSHd tunnel (#2514) * docs: document the SSHd tunnel * chore: add functional option for customising modules and host ports --- docs/features/common_functional_options.md | 12 +++++++ docs/features/networking.md | 38 ++++++++++++++++++++++ options.go | 11 +++++++ options_test.go | 33 +++++++++++++++++++ port_forwarding.go | 2 ++ port_forwarding_test.go | 4 +++ 6 files changed, 100 insertions(+) diff --git a/docs/features/common_functional_options.md b/docs/features/common_functional_options.md index 1572bb461b..d7a23c8559 100644 --- a/docs/features/common_functional_options.md +++ b/docs/features/common_functional_options.md @@ -25,6 +25,18 @@ If you need to either pass additional environment variables to a container or ov postgres, err = postgresModule.RunContainer(ctx, testcontainers.WithEnv(map[string]string{"POSTGRES_INITDB_ARGS": "--no-sync"})) ``` +#### WithHostPortAccess + +- Not available until the next release of testcontainers-go :material-tag: main + +If you need to access a port that is already running in the host, you can use `testcontainers.WithHostPortAccess` for example: + +```golang +postgres, err = postgresModule.RunContainer(ctx, testcontainers.WithHostPortAccess(8080)) +``` + +To understand more about this feature, please read the [Exposing host ports to the container](/features/networking/#exposing-host-ports-to-the-container) documentation. + #### WithLogConsumers - Since testcontainers-go :material-tag: v0.28.0 diff --git a/docs/features/networking.md b/docs/features/networking.md index 9eb86e8da2..2eb6ef2812 100644 --- a/docs/features/networking.md +++ b/docs/features/networking.md @@ -47,6 +47,44 @@ It is normally advisable to use `Host` and `MappedPort` together when constructi !!! info Setting the `TC_HOST` environment variable overrides the host of the docker daemon where the container port is exposed. For example, `TC_HOST=172.17.0.1`. +## Exposing host ports to the container + +- Not available until the next release of testcontainers-go :material-tag: main + +In some cases it is necessary to make a network connection from a container to a socket that is listening on the host machine. Natively, Docker has limited support for this model across platforms. Testcontainers, however, makes this possible, allowing your code to access services running on the host machine. + +In this example, assume that `freePorts` is an slice of ports on our test host machine where different servers (e.g. a web application) are running. + +We can simply create a container and expose these ports to the container using the `ContainerRequest` struct: + + +[Exposing the host ports](../../port_forwarding_test.go) inside_block:hostAccessPorts + + +!!!warning + Note that the server/s listening on those ports on the host must have been started before the container is created. + +From a container's perspective, the hostname will be `host.testcontainers.internal` and the port will be the same value as any in the `freePorts` slice. _Testcontainers for Go_ exposes the host internal name as the `testcontainers.HostInternal` constant, so you can use it to build the address to connect to the host on the exposed port. + + +[Accessing the exposed host port from a container](../../port_forwarding_test.go) inside_block:wgetHostInternal + + +In the above example we are executing an HTTP request from the command line inside the given container to the host machine. + +### How it works + +When you expose a host port to a container, _Testcontainers for Go_ creates an SSHD server companion container, which will be used to forward the traffic from the container to the host machine. This is done by creating a tunnel between the container and the host machine through the SSHD server container. + +You can find more information about this SSHD server container on its Github repository: [https://github.com/testcontainers/sshd-docker](https://github.com/testcontainers/sshd-docker). + + +[SSHD Server Docker Image](../../port_forwarding.go) inside_block:hubSshdImage + + +!!!important + At this moment, each container request will use a new SSHD server container. This means that if you create multiple containers with exposed host ports, each one will have its own SSHD server container. + ## Docker's host networking mode From [Docker documentation](https://docs.docker.com/network/drivers/host/): diff --git a/options.go b/options.go index 391d3e1a82..39d9fc7a13 100644 --- a/options.go +++ b/options.go @@ -74,6 +74,17 @@ func WithHostConfigModifier(modifier func(hostConfig *container.HostConfig)) Cus } } +// WithHostPortAccess allows to expose the host ports to the container +func WithHostPortAccess(ports ...int) CustomizeRequestOption { + return func(req *GenericContainerRequest) { + if req.HostAccessPorts == nil { + req.HostAccessPorts = []int{} + } + + req.HostAccessPorts = append(req.HostAccessPorts, ports...) + } +} + // WithImage sets the image for a container func WithImage(image string) CustomizeRequestOption { return func(req *GenericContainerRequest) { diff --git a/options_test.go b/options_test.go index bbd4a944d5..465e18ade5 100644 --- a/options_test.go +++ b/options_test.go @@ -210,3 +210,36 @@ func TestWithEnv(t *testing.T) { }) } } + +func TestWithHostPortAccess(t *testing.T) { + tests := []struct { + name string + req *testcontainers.GenericContainerRequest + hostPorts []int + expect []int + }{ + { + name: "add to existing", + req: &testcontainers.GenericContainerRequest{ + ContainerRequest: testcontainers.ContainerRequest{ + HostAccessPorts: []int{1, 2}, + }, + }, + hostPorts: []int{3, 4}, + expect: []int{1, 2, 3, 4}, + }, + { + name: "add to nil", + req: &testcontainers.GenericContainerRequest{}, + hostPorts: []int{3, 4}, + expect: []int{3, 4}, + }, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + opt := testcontainers.WithHostPortAccess(tc.hostPorts...) + opt.Customize(tc.req) + require.Equal(t, tc.expect, tc.req.HostAccessPorts) + }) + } +} diff --git a/port_forwarding.go b/port_forwarding.go index 14cead708f..98c2e45154 100644 --- a/port_forwarding.go +++ b/port_forwarding.go @@ -14,7 +14,9 @@ import ( ) const ( + // hubSshdImage { image string = "testcontainers/sshd:1.2.0" + // } // HostInternal is the internal hostname used to reach the host from the container, // using the SSHD container as a bridge. HostInternal string = "host.testcontainers.internal" diff --git a/port_forwarding_test.go b/port_forwarding_test.go index ebcb207134..aa08159afd 100644 --- a/port_forwarding_test.go +++ b/port_forwarding_test.go @@ -73,11 +73,13 @@ func TestExposeHostPorts(t *testing.T) { } req := testcontainers.GenericContainerRequest{ + // hostAccessPorts { ContainerRequest: testcontainers.ContainerRequest{ Image: "alpine:3.17", HostAccessPorts: freePorts, Cmd: []string{"top"}, }, + // } Started: true, } @@ -128,11 +130,13 @@ func TestExposeHostPorts(t *testing.T) { } func httpRequest(t *testing.T, c testcontainers.Container, port int) (int, string) { + // wgetHostInternal { code, reader, err := c.Exec( context.Background(), []string{"wget", "-q", "-O", "-", fmt.Sprintf("http://%s:%d", testcontainers.HostInternal, port)}, tcexec.Multiplexed(), ) + // } if err != nil { t.Fatal(err) }