CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-spotify--docker-client

A comprehensive Docker client library for Java applications providing programmatic Docker API access with container lifecycle management, image operations, and Docker Swarm support.

—

Pending
Overview
Eval results
Files

networks.mddocs/

Network Management

This document covers Docker network operations including network creation, configuration, container connectivity, and network inspection.

Network Listing and Inspection

Listing Networks

import com.spotify.docker.client.DockerClient;
import com.spotify.docker.client.messages.Network;

// List all networks
List<Network> networks = docker.listNetworks();

// Filter by network ID
List<Network> specific = docker.listNetworks(
    ListNetworksParam.byNetworkId("network-id")
);

// Filter by network name
List<Network> named = docker.listNetworks(
    ListNetworksParam.byNetworkName("my-network")
);

// Filter by driver
List<Network> bridgeNetworks = docker.listNetworks(
    ListNetworksParam.withDriver("bridge")
);

// Filter by type
List<Network> customNetworks = docker.listNetworks(
    ListNetworksParam.customNetworks()
);

List<Network> builtinNetworks = docker.listNetworks(
    ListNetworksParam.builtInNetworks()
);

// Filter by labels
List<Network> labeledNetworks = docker.listNetworks(
    ListNetworksParam.withLabel("environment", "production")
);

Network Inspection

// Inspect specific network
Network network = docker.inspectNetwork("network-id-or-name");

System.out.println("Network ID: " + network.id());
System.out.println("Name: " + network.name());
System.out.println("Driver: " + network.driver());
System.out.println("Scope: " + network.scope());
System.out.println("Internal: " + network.internal());
System.out.println("IPv6 Enabled: " + network.enableIpv6());

// Network labels
Map<String, String> labels = network.labels();
System.out.println("Labels: " + labels);

// Driver options
Map<String, String> options = network.options();
System.out.println("Driver Options: " + options);

// IPAM configuration
Ipam ipam = network.ipam();
if (ipam != null) {
    System.out.println("IPAM Driver: " + ipam.driver());
    System.out.println("IPAM Config: " + ipam.config());
}

// Connected containers
Map<String, AttachedNetwork> containers = network.containers();
for (Map.Entry<String, AttachedNetwork> entry : containers.entrySet()) {
    AttachedNetwork attached = entry.getValue();
    System.out.println("Container: " + entry.getKey());
    System.out.println("  Name: " + attached.name());
    System.out.println("  Endpoint ID: " + attached.endpointId());
    System.out.println("  MAC Address: " + attached.macAddress());
    System.out.println("  IPv4 Address: " + attached.ipv4Address());
    System.out.println("  IPv6 Address: " + attached.ipv6Address());
}

Network Creation

Basic Network Creation

import com.spotify.docker.client.messages.*;

// Create simple bridge network
NetworkConfig config = NetworkConfig.builder()
    .name("my-network")
    .driver("bridge")
    .build();

NetworkCreation creation = docker.createNetwork(config);
System.out.println("Created network ID: " + creation.id());

Advanced Network Configuration

// IPAM configuration for custom IP addressing
IpamConfig ipamConfig = IpamConfig.builder()
    .subnet("172.20.0.0/16")
    .ipRange("172.20.240.0/20")
    .gateway("172.20.0.1")
    .auxAddress(Map.of("host1", "172.20.1.5"))
    .build();

Ipam ipam = Ipam.builder()
    .driver("default")
    .config(ipamConfig)
    .options(Map.of("foo", "bar"))
    .build();

// Network configuration with all options
NetworkConfig networkConfig = NetworkConfig.builder()
    .name("production-network")
    .driver("bridge")
    .checkDuplicate(true)
    .internal(false)
    .enableIpv6(false)
    .ipam(ipam)
    .options(Map.of(
        "com.docker.network.bridge.enable_icc", "true",
        "com.docker.network.bridge.enable_ip_masquerade", "true",
        "com.docker.network.bridge.host_binding_ipv4", "0.0.0.0",
        "com.docker.network.bridge.name", "docker0",
        "com.docker.network.driver.mtu", "1500"
    ))
    .labels(Map.of(
        "environment", "production",
        "team", "backend",
        "project", "webapp"
    ))
    .build();

NetworkCreation creation = docker.createNetwork(networkConfig);

Overlay Network for Swarm

// Create overlay network for Docker Swarm
NetworkConfig overlayConfig = NetworkConfig.builder()
    .name("swarm-overlay")
    .driver("overlay")
    .attachable(true)  // Allow standalone containers to attach
    .scope("swarm")
    .labels(Map.of("purpose", "swarm-communication"))
    .build();

NetworkCreation swarmNetwork = docker.createNetwork(overlayConfig);

Host and None Networks

// Host network (containers share host network stack)
NetworkConfig hostConfig = NetworkConfig.builder()
    .name("host-network")
    .driver("host")
    .build();

// None network (containers have no networking)
NetworkConfig noneConfig = NetworkConfig.builder()
    .name("isolated-network") 
    .driver("null")
    .build();

Container Network Connectivity

Connecting Containers to Networks

// Connect container to network (simple)
docker.connectToNetwork("network-id", "container-id");

// Connect with specific configuration
NetworkConnection connection = NetworkConnection.builder()
    .containerId("container-id")
    .endpointConfig(EndpointConfig.builder()
        .ipamConfig(EndpointIpamConfig.builder()
            .ipv4Address("172.20.0.10")
            .ipv6Address("2001:db8::10")
            .build())
        .aliases("web-server", "api")
        .build())
    .build();

docker.connectToNetwork("network-id", connection);

Advanced Endpoint Configuration

EndpointConfig endpointConfig = EndpointConfig.builder()
    // Static IP assignment
    .ipamConfig(EndpointIpamConfig.builder()
        .ipv4Address("172.20.0.100")
        .build())
    
    // Network aliases
    .aliases("web", "www", "frontend")
    
    // Links (legacy)
    .links("database:db", "cache:redis")
    
    // Driver options
    .driverOpts(Map.of("com.example.option", "value"))
    
    .build();

NetworkConnection connection = NetworkConnection.builder()
    .containerId("container-id")
    .endpointConfig(endpointConfig)
    .build();

docker.connectToNetwork("production-network", connection);

Disconnecting Containers

// Disconnect container from network
docker.disconnectFromNetwork("container-id", "network-id");

// Force disconnect (even if container is running)
docker.disconnectFromNetwork("container-id", "network-id", true);

Network Configuration in Container Creation

Container with Custom Networks

// Create container with network configuration
NetworkingConfig networkingConfig = NetworkingConfig.builder()
    .endpointsConfig(Map.of(
        "my-network", EndpointConfig.builder()
            .ipamConfig(EndpointIpamConfig.builder()
                .ipv4Address("172.20.0.50")
                .build())
            .aliases("api-server")
            .build()
    ))
    .build();

ContainerConfig config = ContainerConfig.builder()
    .image("nginx:latest")
    .networkingConfig(networkingConfig)
    .build();

ContainerCreation container = docker.createContainer(config);

Host Configuration for Networking

HostConfig hostConfig = HostConfig.builder()
    // Network mode
    .networkMode("my-network")  // or "bridge", "host", "none", "container:name"
    
    // Port bindings
    .portBindings(Map.of(
        "80/tcp", List.of(
            PortBinding.of("0.0.0.0", "8080"),
            PortBinding.of("127.0.0.1", "8081")
        ),
        "443/tcp", List.of(PortBinding.of("0.0.0.0", "8443"))
    ))
    
    // Publish all exposed ports
    .publishAllPorts(false)
    
    // DNS configuration
    .dns("8.8.8.8", "1.1.1.1")
    .dnsOptions("timeout:3")
    .dnsSearch("example.com", "internal.local")
    
    // Extra hosts (/etc/hosts entries)
    .extraHosts("host.docker.internal:host-gateway", "api.local:172.20.0.10")
    
    // Legacy container links
    .links("database:db", "redis:cache")
    
    .build();

ContainerConfig config = ContainerConfig.builder()
    .image("nginx:latest")
    .hostConfig(hostConfig)
    .build();

Network Removal

Removing Networks

// Remove network by ID or name
docker.removeNetwork("network-id-or-name");

// Safe removal with error handling
public void safeRemoveNetwork(DockerClient docker, String networkId) {
    try {
        // First disconnect all containers
        Network network = docker.inspectNetwork(networkId);
        for (String containerId : network.containers().keySet()) {
            try {
                docker.disconnectFromNetwork(containerId, networkId);
                System.out.println("Disconnected container: " + containerId);
            } catch (DockerException e) {
                System.err.println("Failed to disconnect container " + containerId + ": " + e.getMessage());
            }
        }
        
        // Then remove the network
        docker.removeNetwork(networkId);
        System.out.println("Removed network: " + networkId);
        
    } catch (DockerException e) {
        System.err.println("Failed to remove network: " + e.getMessage());
    }
}

Network Filtering Parameters

ListNetworksParam Options

// Filter by network ID
ListNetworksParam.byNetworkId("network-id")

// Filter by network name
ListNetworksParam.byNetworkName("my-network")

// Filter by driver type
ListNetworksParam.withDriver("bridge")
ListNetworksParam.withDriver("overlay") 
ListNetworksParam.withDriver("macvlan")

// Filter by network type
ListNetworksParam.withType(Network.Type.BUILTIN)
ListNetworksParam.withType(Network.Type.CUSTOM)

// Convenience filters
ListNetworksParam.builtInNetworks()
ListNetworksParam.customNetworks()

// Filter by labels
ListNetworksParam.withLabel("environment")
ListNetworksParam.withLabel("team", "backend")

// Custom filters
ListNetworksParam.filter("scope", "local")
ListNetworksParam.filter("type", "custom")

Network Types and Drivers

Bridge Networks

// Default bridge network
NetworkConfig bridgeConfig = NetworkConfig.builder()
    .name("custom-bridge")
    .driver("bridge")
    .options(Map.of(
        "com.docker.network.bridge.name", "br-custom",
        "com.docker.network.bridge.enable_icc", "true",
        "com.docker.network.bridge.enable_ip_masquerade", "true",
        "com.docker.network.bridge.host_binding_ipv4", "0.0.0.0",
        "com.docker.network.driver.mtu", "1500"
    ))
    .build();

Overlay Networks

// Overlay network for multi-host communication
NetworkConfig overlayConfig = NetworkConfig.builder()
    .name("multi-host-overlay")
    .driver("overlay")
    .options(Map.of(
        "encrypted", "true"  // Enable overlay encryption
    ))
    .labels(Map.of("purpose", "cross-host"))
    .build();

MACVLAN Networks

// MACVLAN network for direct physical network access
NetworkConfig macvlanConfig = NetworkConfig.builder()
    .name("macvlan-network")
    .driver("macvlan")
    .options(Map.of(
        "parent", "eth0",  // Parent interface
        "macvlan_mode", "bridge"
    ))
    .ipam(Ipam.builder()
        .driver("default")
        .config(IpamConfig.builder()
            .subnet("192.168.1.0/24")
            .gateway("192.168.1.1")
            .build())
        .build())
    .build();

Complete Network Management Example

public class NetworkManagementExample {
    
    public void demonstrateNetworkManagement(DockerClient docker) 
            throws DockerException, InterruptedException {
        
        // 1. Create a custom network for a multi-tier application
        System.out.println("Creating application network...");
        
        IpamConfig ipamConfig = IpamConfig.builder()
            .subnet("172.25.0.0/16")
            .gateway("172.25.0.1")
            .build();
            
        NetworkConfig appNetworkConfig = NetworkConfig.builder()
            .name("webapp-network")
            .driver("bridge")
            .ipam(Ipam.builder()
                .driver("default")
                .config(ipamConfig)
                .build())
            .labels(Map.of(
                "project", "webapp",
                "environment", "development"
            ))
            .build();
            
        NetworkCreation appNetwork = docker.createNetwork(appNetworkConfig);
        String networkId = appNetwork.id();
        System.out.println("Created network: " + networkId);
        
        try {
            // 2. Create containers for different tiers
            
            // Database container
            ContainerConfig dbConfig = ContainerConfig.builder()
                .image("postgres:13")
                .env("POSTGRES_DB=myapp", "POSTGRES_USER=user", "POSTGRES_PASSWORD=pass")
                .exposedPorts("5432/tcp")
                .build();
                
            ContainerCreation dbContainer = docker.createContainer(dbConfig, "webapp-db");
            
            // Connect database to network with specific IP
            EndpointConfig dbEndpoint = EndpointConfig.builder()
                .ipamConfig(EndpointIpamConfig.builder()
                    .ipv4Address("172.25.0.10")
                    .build())
                .aliases("database", "db", "postgres")
                .build();
                
            docker.connectToNetwork(networkId, NetworkConnection.builder()
                .containerId(dbContainer.id())
                .endpointConfig(dbEndpoint)
                .build());
                
            // Web application container  
            ContainerConfig webConfig = ContainerConfig.builder()
                .image("nginx:latest")
                .exposedPorts("80/tcp")
                .build();
                
            ContainerCreation webContainer = docker.createContainer(webConfig, "webapp-web");
            
            // Connect web server to network
            EndpointConfig webEndpoint = EndpointConfig.builder()
                .ipamConfig(EndpointIpamConfig.builder()
                    .ipv4Address("172.25.0.20")
                    .build())
                .aliases("web", "frontend", "www")
                .build();
                
            docker.connectToNetwork(networkId, NetworkConnection.builder()
                .containerId(webContainer.id())
                .endpointConfig(webEndpoint)
                .build());
            
            // 3. Start containers
            docker.startContainer(dbContainer.id());
            docker.startContainer(webContainer.id());
            
            System.out.println("Started database container: " + dbContainer.id());
            System.out.println("Started web container: " + webContainer.id());
            
            // 4. Inspect the network to see connected containers
            Network network = docker.inspectNetwork(networkId);
            System.out.println("Network inspection:");
            System.out.println("  Name: " + network.name());
            System.out.println("  Driver: " + network.driver());
            System.out.println("  Subnet: " + network.ipam().config().get(0).subnet());
            
            System.out.println("Connected containers:");
            for (Map.Entry<String, AttachedNetwork> entry : network.containers().entrySet()) {
                AttachedNetwork attached = entry.getValue();
                System.out.println("  Container: " + attached.name());
                System.out.println("    IP: " + attached.ipv4Address());
                System.out.println("    Endpoint ID: " + attached.endpointId());
            }
            
            // 5. Test connectivity between containers
            testContainerConnectivity(docker, webContainer.id(), "database", 5432);
            
            // 6. Demonstrate network isolation
            demonstrateNetworkIsolation(docker);
            
        } finally {
            // 7. Cleanup
            cleanupNetworkDemo(docker, networkId);
        }
    }
    
    private void testContainerConnectivity(DockerClient docker, String containerId, 
                                         String targetHost, int port) 
            throws DockerException, InterruptedException {
        
        System.out.println("Testing connectivity from container to " + targetHost + ":" + port);
        
        ExecCreation exec = docker.execCreate(containerId,
            new String[]{"nc", "-z", "-v", targetHost, String.valueOf(port)},
            DockerClient.ExecCreateParam.attachStdout(),
            DockerClient.ExecCreateParam.attachStderr());
            
        try (LogStream output = docker.execStart(exec.id())) {
            String result = output.readFully();
            System.out.println("Connectivity test result: " + result);
        }
    }
    
    private void demonstrateNetworkIsolation(DockerClient docker) 
            throws DockerException, InterruptedException {
        
        System.out.println("Demonstrating network isolation...");
        
        // Create isolated network
        NetworkConfig isolatedConfig = NetworkConfig.builder()
            .name("isolated-network")
            .driver("bridge")
            .internal(true)  // No external connectivity
            .build();
            
        NetworkCreation isolated = docker.createNetwork(isolatedConfig);
        
        // Create container in isolated network
        ContainerConfig config = ContainerConfig.builder()
            .image("alpine:latest")
            .cmd("sleep", "30")
            .build();
            
        ContainerCreation container = docker.createContainer(config);
        docker.connectToNetwork(isolated.id(), container.id());
        docker.startContainer(container.id());
        
        // Test that container cannot reach external hosts
        ExecCreation exec = docker.execCreate(container.id(),
            new String[]{"ping", "-c", "1", "8.8.8.8"},
            DockerClient.ExecCreateParam.attachStdout(),
            DockerClient.ExecCreateParam.attachStderr());
            
        try (LogStream output = docker.execStart(exec.id())) {
            String result = output.readFully();
            System.out.println("Isolation test (should fail): " + result);
        }
        
        // Cleanup isolated demo
        docker.stopContainer(container.id(), 5);
        docker.removeContainer(container.id());
        docker.removeNetwork(isolated.id());
    }
    
    private void cleanupNetworkDemo(DockerClient docker, String networkId) {
        try {
            // Stop and remove containers
            List<Container> containers = docker.listContainers(
                DockerClient.ListContainersParam.allContainers());
                
            for (Container container : containers) {
                if (container.names().stream().anyMatch(name -> name.contains("webapp-"))) {
                    try {
                        docker.stopContainer(container.id(), 5);
                        docker.removeContainer(container.id());
                        System.out.println("Removed container: " + container.id());
                    } catch (DockerException e) {
                        System.err.println("Error removing container: " + e.getMessage());
                    }
                }
            }
            
            // Remove network
            docker.removeNetwork(networkId);
            System.out.println("Removed network: " + networkId);
            
        } catch (DockerException | InterruptedException e) {
            System.err.println("Cleanup error: " + e.getMessage());
        }
    }
}

Network Security and Best Practices

Secure Network Configuration

// Create secure production network
NetworkConfig secureConfig = NetworkConfig.builder()
    .name("secure-production")
    .driver("bridge")
    .internal(false)  // Allow external access only as needed
    .options(Map.of(
        // Disable inter-container communication by default
        "com.docker.network.bridge.enable_icc", "false",
        // Enable IP masquerading for outbound traffic
        "com.docker.network.bridge.enable_ip_masquerade", "true"
    ))
    .labels(Map.of(
        "security.level", "high",
        "environment", "production"
    ))
    .build();

NetworkCreation secureNetwork = docker.createNetwork(secureConfig);

Network Segmentation

public void createNetworkSegmentation(DockerClient docker) 
        throws DockerException, InterruptedException {
    
    // Frontend network (public-facing)
    NetworkConfig frontendConfig = NetworkConfig.builder()
        .name("frontend-network")
        .driver("bridge")
        .labels(Map.of("tier", "frontend", "access", "public"))
        .build();
        
    // Backend network (internal only)
    NetworkConfig backendConfig = NetworkConfig.builder()
        .name("backend-network")
        .driver("bridge")
        .internal(true)  // No external access
        .labels(Map.of("tier", "backend", "access", "internal"))
        .build();
        
    // Database network (highly restricted)
    NetworkConfig dbConfig = NetworkConfig.builder()
        .name("database-network")
        .driver("bridge")
        .internal(true)
        .options(Map.of(
            "com.docker.network.bridge.enable_icc", "false"
        ))
        .labels(Map.of("tier", "database", "access", "restricted"))
        .build();
    
    docker.createNetwork(frontendConfig);
    docker.createNetwork(backendConfig);
    docker.createNetwork(dbConfig);
}

The network management system provides comprehensive control over container connectivity with support for custom addressing, service discovery, network isolation, and multi-host communication for scalable Docker deployments.

Install with Tessl CLI

npx tessl i tessl/maven-com-spotify--docker-client

docs

client-configuration.md

containers.md

images.md

index.md

networks.md

swarm.md

volumes.md

tile.json