feat: add network driver options

[Wielewout]

What does this PR do?

Used the field Options in network.CreateOptions (docker).
Also added a DriverOptions field to the (deprecated) NetworkRequest since we convert from CreateOptions to NetworkRequest and then back to CreateOptions in the docker provider.

Why is it important?

This gives more control over network creation.

For example it allows to set a container interface prefix with com.docker.network.container_iface_prefix.
This can give stability to the interface names when needing to inject one in the config (before the container is running) when the container attaches to multiple networks.
Without it there is no way of predicting which interface (eth0, eth1, ...) would correspond with which network.

Related issues

• Closes [Feature]: Network Driver Options #3301

[netlify]

✅ Deploy Preview for testcontainers-go ready!

Name	Link
🔨 Latest commit	7b5f68c
🔍 Latest deploy log	https://app.netlify.com/projects/testcontainers-go/deploys/68da272ba64b3e0008b03042
😎 Deploy Preview	https://deploy-preview-3302--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 project configuration.

[coderabbitai]

Summary by CodeRabbit

• New Features

  • Added support for specifying driver-specific options when creating networks, providing finer control over network behavior.

• Documentation

  • Updated networking documentation with guidance on configuring driver options during network creation, including usage examples.

Walkthrough

Adds support for network driver options by introducing WithDriverOptions(map[string]string), extending NetworkRequest with DriverOptions, documenting the option, and wiring these options into Docker network creation via the Options field.

Changes

Cohort / File(s)	Summary
Networking API updates network.go, network/network.go	Adds DriverOptions map[string]string to NetworkRequest. Introduces WithDriverOptions(options map[string]string) and maps options into NetworkRequest during New.
Docker integration docker.go	Passes driver options to Docker by assigning nc.Options from req.DriverOptions in CreateNetwork.
Documentation docs/features/networking.md	Documents the new WithDriverOptions(map[string]string) network option alongside existing customizers.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor Dev as Developer
  participant NET as network.New
  participant Builder as NetworkRequest Builder
  participant DockerCli as Docker Client
  participant Engine as Docker Engine

  Dev->>NET: New(..., WithDriverOptions(map[string]string))
  NET->>Builder: Apply options
  Builder->>Builder: Set DriverOptions on NetworkRequest
  Builder->>DockerCli: CreateNetwork(req) with Options = DriverOptions
  DockerCli->>Engine: POST /networks/create { Options: {...} }
  Engine-->>DockerCli: NetworkID
  DockerCli-->>Dev: Result

  note over Builder,DockerCli: New/changed: propagate DriverOptions into Docker Options

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I nudge the nets with careful hops,
A sprinkle of options, carrot-tops.
Drivers purr with tuned finesse,
Interfaces named, no random mess.
With tidy flags my whiskers twitch—
Networks spin up without a hitch. 🐇✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title “feat: add network driver options” concisely and accurately summarizes the primary change introduced by the pull request, namely the addition of support for network driver options in Testcontainers. It clearly reflects the main feature without extraneous information or ambiguity, allowing a teammate to understand the intent at a glance.
Linked Issues Check	✅ Passed	The change set fully implements the objectives of issue #3301 by adding a WithDriverOptions network customizer, introducing the DriverOptions field on NetworkRequest, and mapping those options through CreateNetwork to Docker’s network creation API, thereby fulfilling the requested feature for driver-specific network options.
Out of Scope Changes Check	✅ Passed	All modifications in docker.go, network.go, network/network.go, and the documentation are directly related to introducing and supporting driver options and there are no unrelated or extraneous changes.
Description Check	✅ Passed	The pull request description directly explains the modifications made—using the Options field in network.CreateOptions and adding a DriverOptions field to NetworkRequest—along with the rationale for enabling custom driver options such as com.docker.network.container_iface_prefix. It stays on topic and aligns with the changes in the code.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

• Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
• Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

network/network.go (1)

100-107: Merge driver options when multiple customizers apply.

Right now each call to WithDriverOptions replaces the entire map. That breaks composition if a library and a caller both want to add their own driver options—the later call wipes out the earlier one. Please merge into the existing map (initializing when nil) so multiple customizers can cooperate.

 func WithDriverOptions(options map[string]string) CustomizeNetworkOption {
 	return func(original *network.CreateOptions) error {
-		original.Options = options
+		if len(options) == 0 {
+			return nil
+		}
+		if original.Options == nil {
+			original.Options = make(map[string]string, len(options))
+		}
+		maps.Copy(original.Options, options)
 
 		return nil
 	}
 }

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7eb93bb and 7b5f68c.

📒 Files selected for processing (4)

• docker.go (1 hunks)
• docs/features/networking.md (1 hunks)
• network.go (1 hunks)
• network/network.go (2 hunks)

[mdelapenya]

LGTM! Before merging, I'd suggest we add a test for this, although the code is pretty simply: it just passes the options to the Docker type.

[Wielewout]

LGTM! Before merging, I'd suggest we add a test for this, although the code is pretty simply: it just passes the options to the Docker type.

@mdelapenya The only way to test that I see currently is to use the driver option com.docker.network.container_iface_prefix to set a custom interface name (e.g. test_if). We then create a small go application which provides all the interface names over http (GET /interfaces) and put it in a container. If test_if0 is among the interface names, the test passes. Any thoughts?

(I'm not immediately sure when I'll find some time to try this out)