feat: forward host ports to a container using an SSH tunnel

[mdelapenya]

• chore: start a foundational package for interacting with Docker networks
• feat: add an SSH tunnel forwarding a host port to a container

What does this PR do?

This PR defines a new field in the container request struct, so that users can define which host ports are needed to be exposed to a given container.

If set, an internal SSHD server container will be spun before the container, forwarding each exposed host port to the container using an SSH tunnel.

All this logic will happen thanks to the lifecycle container hooks:

1. if the container declares host ports, we will define a new container lifecycle hook:

• after the container is ready, we will expose the host ports using a SSH tunnel.
• before the container is terminates, we will stop the sshd container.

2. we'll take the first network of the container to attach the sshd container to it
3. the IP fo the SSHD container in that network will be passed as extra-hosts of the container, so that the host.testcontainers.internal key will land in the container's /etc/hosts file (Linux).

As part of this PR we are adding an internal/core/network package to start adding core, network-related logic in it. This is needed because we need to get the Docker network of the container to pass it to the SSHD container.

Why is it important?

At the moment it's not possible for a container to access a port in the host, which is handy for multiple use cases (please see #2212)

Related issues

• Closes [Feature] Add withAccessToHost option to access to host from containers #2212
• Superseded and Closes [draft] feat(portforward): Add SSHD module + Ability to port forward #2467
• Relates chore: include common CMD used across all libraries sshd-docker#7
• Relates (java) chore: use new sshd:1.2.0 image testcontainers-java#8574
• Relates (.NET) chore: Use new sshd:1.2.0 image testcontainers-dotnet#1160
• Relates (node) Use new sshd:1.2.0 image testcontainers-node#758

Follow-ups

This PR is in draft for one single reason: I'm pushing this branch to receive feedback from the community. I do not want to add any new library for the SSH tunnel, just using the plain stdlib. I see it not very friendly to use it and would like to have more eyes on this feature.

Both Java and .Net use a library to forward the port, and in Go I'd like to avoid that.

At the same time, there is a TODO in the code, as we are adding the network to the sshd container with a functional option that is an exact clone of the network.WithNetwork. If we use it, then a circular dependency will appear, which is not desired. This demonstrates that our efforts for refactoring the API with a more decoupled API is in the right direction.

One final follow-up is to consider starting just one SSHD container per test session, ala Ryuk: at the moment, there is one sshd container per container request. I think we can start this way, make progress, and move to that approach once needed. Thoughts?

[netlify]

✅ Deploy Preview for testcontainers-go ready!

Name	Link
🔨 Latest commit	52d386b
🔍 Latest deploy log	https://app.netlify.com/sites/testcontainers-go/deploys/66292801639a9c00083254e8
😎 Deploy Preview	https://deploy-preview-2471--testcontainers-go.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[codefromthecrypt]

Thanks for the start!

some comments about where context can be propagated to facilitate an incoming context with deadline (I use one all the time with tc). Also, some notes about a logic problem I think.

Finally, if anything is replicating logic from another project, maybe worthwhile citing it even if in the same org, as not all maintainers will know to look in the java side for congruence or practice updates.

[codefromthecrypt]

the edge case where sshdFirstNetwork == "" .. is this ok here? If not, I would early exit if len(req.Networks) == 0 a lot higher in this function, as it also reduces indentation and breaks apart some other logic

[codefromthecrypt]

nit: not sure about style in this project, but functions like this are easier to unit test if they are not anonymous.

[JulienBreux]

A big thanks from Microcks team 🙏🏻

[mdelapenya]

A big thanks from Microcks team 🙏🏻

🙇 I need to focus on this task, as I found a blocker here: I cannot see the communication being produced between the container and the exposed port in the host. The code is trying to mimic what the Java team is doing:

• add an extra-hosts to the container with the IP of the sshd server
• get the first network of the given container and connect the sshd container to it
• create a ssh client to the sshd server, using the mapped port of the sshd server for the well-known 22.

I verified that it's possible to telnet from the container to the sshd server (port 22) using host.testcontainers.internal with success, but the other extreme of the communication (reaching the port) is not.

Could anybody give this PR a try and help if possible?

[codefromthecrypt]

@joonas-fi I noticed you are doing something similar in your holepunch-client. Though maybe you aren't using testcontainers, yet. If you have some time to spare to help folks get container port forwarding working, much oblidged! https://github.com/function61/holepunch-client/blob/master/cmd/holepunch/client.go

[mdelapenya]

@codefromthecrypt @JulienBreux could you give this one a try? 🙏 I think it's ready for review

[JulienBreux]

@codefromthecrypt @JulienBreux could you give this one a try? 🙏 I think it's ready for review

Let's go to testing at 2 PM today.

[JulienBreux]

Hey @mdelapenya 👋🏻

Actually, I use this file to test, and it works well. 🎉 🎉 🎉

Design explanation :

1. Create a local HTTP server http://127.0.0.1:7171.
2. Create a TC "alpine" with HostAccessPorts: []int{7171}.
3. Exec a CMD curl -s -L http://host.testcontainers.internal:7171/ from the TC "alpine".

https://gist.github.com/JulienBreux/3892189373cb246c180a0d8d2d1928c7

[codefromthecrypt]

probably just me, but I struggled on this in k3s (wanting a pod to call a service on my host). 1000x thanks if someone has a gist or contributes an integration test to the k3s module for this.

[JulienBreux]

Hi @codefromthecrypt,

Do you've a reproducible architecture? I need to test more.
Thanks!

[codefromthecrypt]

@JulienBreux (cc @salaboy as he probably is interested in this)

So, I was testing coredns dnstap plugin (wanting to have traffic flow out to a listener I setup in the go test). However, since the PR here is about http and should work similar, I've a rough test below (pasted into k3s_test.go). I'm not sure I need an external name, but with or without it, I get "bad address" from alpine.

const (
	expectedResponse = "Hello, World!"
)

func Test_WithHostPortAccess(t *testing.T) {
	ctx := context.Background()

	port, err := getFreePort()
	if err != nil {
		t.Fatal(err)
	}
	portString := fmt.Sprintf("%d", port)

	// Create a local HTTP server
	server := http.Server{Addr: ":" + portString, Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, expectedResponse)
	})}
	go server.ListenAndServe()
	defer server.Close()

	k3sContainer, err := k3s.RunContainer(ctx,
		testcontainers.WithImage("docker.io/rancher/k3s:v1.27.1-k3s1"),
		testcontainers.WithHostPortAccess(port),
	)
	if err != nil {
		t.Fatal(err)
	}

	// Clean up the container
	defer func() {
		if err := k3sContainer.Terminate(ctx); err != nil {
			t.Fatal(err)
		}
	}()

	kubeConfigYaml, err := k3sContainer.GetKubeConfig(ctx)
	if err != nil {
		t.Fatal(err)
	}

	restcfg, err := clientcmd.RESTConfigFromKubeConfig(kubeConfigYaml)
	if err != nil {
		t.Fatal(err)
	}

	k8s, err := kubernetes.NewForConfig(restcfg)
	if err != nil {
		t.Fatal(err)
	}

	// Create a CNAME httptest pointing to host.testcontainers.internal
	service := &corev1.Service{
		ObjectMeta: metav1.ObjectMeta{
			Name: "httptest",
		},
		Spec: corev1.ServiceSpec{
			Type:         corev1.ServiceTypeExternalName,
			ExternalName: "host.testcontainers.internal",
		},
	}
	services := k8s.CoreV1().Services("default")
	if _, err = services.Create(ctx, service, metav1.CreateOptions{}); err != nil {
		t.Fatal(err)
	}

	// Block until the service is ready to avoid race conditions
	if err = kwait.PollUntilContextCancel(ctx, time.Second, true, func(ctx context.Context) (bool, error) {
		if s, err := services.Get(ctx, service.Name, metav1.GetOptions{}); err != nil {
			return false, err
		} else if s.Spec.Type != service.Spec.Type || s.Spec.ExternalName != service.Spec.ExternalName {
			return false, fmt.Errorf("unexpected service spec: %v", s.Spec)
		}
		return true, nil
	}); err != nil {
		t.Fatal(err)
	}

	// Create a pod that attempts to access the host's http service using wget
	pod := &corev1.Pod{
		ObjectMeta: metav1.ObjectMeta{
			Name: "test-pod",
		},
		Spec: corev1.PodSpec{
			Containers: []corev1.Container{
				{
					Name:    "alpine",
					Image:   "alpine:3.17",
					Command: []string{"wget", "-qO-", fmt.Sprintf("http://%s:%d", service.Name, port)},
				},
			},
			RestartPolicy: corev1.RestartPolicyNever,
		},
	}

	pods := k8s.CoreV1().Pods("default")
	if _, err = pods.Create(ctx, pod, metav1.CreateOptions{}); err != nil {
		t.Fatal(err)
	}

	// Wait for the wget to complete
	if err = kwait.PollUntilContextCancel(ctx, time.Second, true, func(ctx context.Context) (bool, error) {
		pod, err := pods.Get(ctx, "test-pod", metav1.GetOptions{})
		if err != nil {
			return false, err
		}

		for _, status := range pod.Status.ContainerStatuses {
			if status.State.Terminated != nil {
				return true, nil
			}
		}

		return false, nil
	}); err != nil {
		t.Fatal(err)
	}

	// Check the logs of the Pod to ensure that we read the expected response
	logs, err := pods.GetLogs("test-pod", &corev1.PodLogOptions{}).DoRaw(ctx)
	if err != nil {
		t.Fatal(err)
	}
	if !strings.Contains(string(logs), expectedResponse) {
		t.Fatalf("wget did not return the expected response, got: %s", logs)
	}
}

// getFreePort asks the kernel for a free open port that is ready to use.
func getFreePort() (int, error) {
	addr, err := net.ResolveTCPAddr("tcp", "localhost:0")
	if err != nil {
		return 0, err
	}

	l, err := net.ListenTCP("tcp", addr)
	if err != nil {
		return 0, err
	}
	defer l.Close()
	return l.Addr().(*net.TCPAddr).Port, nil
}

FYI I am running docker via colima start --cpu 4 --memory 8 --network-address, not docker desktop or otherwise. Also, I'm moving to singapore this weekend, so won't be able to revise this, but anyone has license to this if they want to make a PR out of it.