testcontainers::Network::Builder Class Reference

A copyable builder for a richer user-defined network: driver, internal / attachable / IPv6 flags, IPAM address pools, driver options, and labels. More...

#include <testcontainers/Network.hpp>

Public Member Functions
Builder &	with_name (std::string name)
Builder &	with_driver (std::string driver)
Builder &	with_internal (bool internal=true)
Builder &	with_attachable (bool attachable=true)
Builder &	with_enable_ipv6 (bool enable=true)
Builder &	with_subnet (std::string cidr)
	IPAM subnet in CIDR form, e.g. "172.31.250.0/24".
Builder &	with_gateway (std::string ip)
	IPAM gateway address (requires a subnet to take effect).
Builder &	with_ipam_pool (NetworkIpamPool pool)
	Add an IPAM address pool (an IPAM.Config entry: subnet, allocation range, gateway, auxiliary addresses; empty fields are omitted).
Builder &	with_option (std::string key, std::string value)
	Add a driver option (Options). Add several to set multiple options.
Builder &	with_label (std::string key, std::string value)
	Add a network label (Labels).
Builder &	with_reuse (bool reuse=true)
	Enable network reuse.
Network	create () const
	Create the network from the configured options, returning the handle.

Detailed Description

A copyable builder for a richer user-defined network: driver, internal / attachable / IPv6 flags, IPAM address pools, driver options, and labels.

Defined in std types only (no Boost/json leak through the header).

The with_* setters mutate in place and return *this by reference; a single unqualified overload chains on both a named lvalue and a temporary. create() assembles the spec, runs the Reaper hook, and creates the network.

Member Function Documentation

with_name()

Builder & testcontainers::Network::Builder::with_name ( std::string name )

inline

with_driver()

Builder & testcontainers::Network::Builder::with_driver ( std::string driver )

inline

with_internal()

Builder & testcontainers::Network::Builder::with_internal ( bool internal = true )

inline

with_attachable()

Builder & testcontainers::Network::Builder::with_attachable ( bool attachable = true )

inline

with_enable_ipv6()

Builder & testcontainers::Network::Builder::with_enable_ipv6 ( bool enable = true )

inline

with_subnet()

Builder & testcontainers::Network::Builder::with_subnet ( std::string cidr )

inline

IPAM subnet in CIDR form, e.g. "172.31.250.0/24".

with_gateway()

Builder & testcontainers::Network::Builder::with_gateway ( std::string ip )

inline

IPAM gateway address (requires a subnet to take effect).

with_ipam_pool()

Builder & testcontainers::Network::Builder::with_ipam_pool ( NetworkIpamPool pool )

inline

Add an IPAM address pool (an IPAM.Config entry: subnet, allocation range, gateway, auxiliary addresses; empty fields are omitted).

Pools land after the with_subnet/with_gateway shorthand pool when that is set. More than one IPv4 pool needs a driver that supports it — the Linux bridge driver takes one IPv4 pool, plus one IPv6 pool with with_enable_ipv6.

with_option()

Builder & testcontainers::Network::Builder::with_option ( std::string key, std::string value )

inline

Add a driver option (Options). Add several to set multiple options.

with_label()

Builder & testcontainers::Network::Builder::with_label ( std::string key, std::string value )

inline

Add a network label (Labels).

The testcontainers session labels are always merged in by create() for Ryuk reaping.

with_reuse()

Builder & testcontainers::Network::Builder::with_reuse ( bool reuse = true )

inline

Enable network reuse.

When reuse is also enabled globally (testcontainers.reuse.enable=true in ~/.testcontainers.properties or TESTCONTAINERS_REUSE_ENABLE=true), create() first looks for an existing network with this exact name whose reuse-hash label matches this configuration and ADOPTS it instead of creating a new one; either way the returned handle is persistent (it does NOT remove the network on destruction, and the network is NOT Ryuk-reaped, so it survives across runs — clean up externally, e.g. docker network rm after a label=org.testcontainers.reuse.hash sweep). Requires with_name (a generated name would never match across runs). If the name is already taken by a network with a DIFFERENT configuration, create() throws instead of making a same-named duplicate (Docker does not enforce unique network names, and a duplicate makes joining by name ambiguous). When reuse is not enabled globally this is a no-op: create() behaves exactly like a normal (session-labeled, reaped) network.

create()

Network testcontainers::Network::Builder::create

(

)

const

Create the network from the configured options, returning the handle.

With with_reuse active this is find-or-create (see there).