README
¶
Docker Networks
This package provides a simple API to create and manage Docker networks.
Installation
go get github.com/docker/go-sdk/network
Usage
nw, err := network.New(ctx)
if err != nil {
log.Fatalf("failed to create network: %v", err)
}
resp, err := nw.Inspect(ctx)
if err != nil {
log.Fatalf("failed to inspect network: %v", err)
}
fmt.Printf("network: %+v", resp)
inspect, err := network.FindByID(ctx, nw.ID())
if err != nil {
log.Fatalf("failed to find network by id: %v", err)
}
inspect, err = network.FindByName(ctx, nw.Name())
if err != nil {
log.Fatalf("failed to find network by name: %v", err)
}
_, err = network.List(ctx)
if err != nil {
log.Fatalf("failed to list networks: %v", err)
}
_, err = network.List(ctx, network.WithFilters(filters.NewArgs(filters.Arg("driver", "bridge"))))
if err != nil {
log.Fatalf("failed to list networks with filters: %v", err)
}
err = nw.Terminate(ctx)
if err != nil {
log.Fatalf("failed to terminate network: %v", err)
}
Customizing the network
The network created with the New function can be customized using functional options. The following options are available:
WithClient(client client.SDKClient) network.Option: The client to use to create the network. If not provided, the default client will be used.WithName(name string) network.Option: The name of the network.WithDriver(driver string) network.Option: The driver of the network.WithInternal() network.Option: Whether the network is internal.WithEnableIPv6() network.Option: Whether the network is IPv6 enabled.WithAttachable() network.Option: Whether the network is attachable.WithLabels(labels map[string]string) network.Option: The labels of the network.WithIPAM(ipam *network.IPAM) network.Option: The IPAM configuration of the network.
Documentation
¶
Index ¶
- func Cleanup(tb testing.TB, nw TerminableNetwork)
- func CleanupByID(tb testing.TB, id string)
- func FindByID(ctx context.Context, id string, opts ...ListOptions) (network.Summary, error)
- func FindByName(ctx context.Context, name string, opts ...ListOptions) (network.Summary, error)
- func List(ctx context.Context, opts ...ListOptions) ([]network.Summary, error)
- func Version() string
- type InspectOptions
- type ListOptions
- type Network
- func (n *Network) Client() client.SDKClient
- func (n *Network) Driver() string
- func (n *Network) ID() string
- func (n *Network) Inspect(ctx context.Context, opts ...InspectOptions) (client.NetworkInspectResult, error)
- func (n *Network) Name() string
- func (n *Network) Terminate(ctx context.Context) error
- type Option
- type TerminableNetwork
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Cleanup ¶
func Cleanup(tb testing.TB, nw TerminableNetwork)
Cleanup is a helper function that schedules the network to be removed when the test ends. This should be the first call after New in a test before any error check. If network is nil, it's a no-op.
func CleanupByID ¶
CleanupByID is a helper function that schedules the network to be removed, identified by its ID, when the test ends. This should be the first call after New(...) in a test before any error check. If network is nil, it's a no-op. It uses a new docker client to terminate the network, which is automatically closed when the test ends.
func FindByName ¶
FindByName returns a network by its name.
Types ¶
type InspectOptions ¶
type InspectOptions func(opts *inspectOptions) error
InspectOptions is a function that modifies the inspect options.
func WithInspectOptions ¶
func WithInspectOptions(opts client.NetworkInspectOptions) InspectOptions
WithInspectOptions returns an InspectOptions that sets the inspect options.
func WithNoCache ¶
func WithNoCache() InspectOptions
WithNoCache returns an InspectOptions that disables caching the result of the inspection. If passed, the Docker daemon will be queried for the latest information, so it can be used for refreshing the cached result of a previous inspection.
type ListOptions ¶
type ListOptions func(opts *listOptions) error
func WithFilters ¶
func WithFilters(filters dockerclient.Filters) ListOptions
WithFilters sets the filters to be used to filter the networks.
func WithListClient ¶
func WithListClient(client client.SDKClient) ListOptions
WithListClient sets the client to be used to list the networks.
type Network ¶
type Network struct {
// contains filtered or unexported fields
}
Network represents a Docker network.
func New ¶
New creates a new network.
Example ¶
package main
import (
"context"
"fmt"
"github.com/docker/go-sdk/network"
)
func main() {
nw, err := network.New(context.Background())
fmt.Println(err)
fmt.Println(nw.Name() != "")
err = nw.Terminate(context.Background())
fmt.Println(err)
}
Output: <nil> true <nil>
Example (WithClient) ¶
package main
import (
"context"
"fmt"
"github.com/docker/go-sdk/client"
"github.com/docker/go-sdk/network"
)
func main() {
dockerClient, err := client.New(context.Background())
fmt.Println(err)
nw, err := network.New(context.Background(), network.WithClient(dockerClient))
fmt.Println(err)
fmt.Println(nw.Name() != "")
err = nw.Terminate(context.Background())
fmt.Println(err)
}
Output: <nil> <nil> true <nil>
Example (WithOptions) ¶
package main
import (
"context"
"fmt"
"runtime"
"github.com/docker/go-sdk/network"
)
func main() {
name := "test-network"
driver := "bridge"
if runtime.GOOS == "windows" {
driver = "nat"
}
nw, err := network.New(
context.Background(),
network.WithName(name),
network.WithDriver(driver),
network.WithLabels(map[string]string{"test": "test"}),
network.WithAttachable(),
)
fmt.Println(err)
fmt.Println(nw.Name())
fmt.Println(nw.Driver() != "")
err = nw.Terminate(context.Background())
fmt.Println(err)
}
Output: <nil> test-network true <nil>
func (*Network) Inspect ¶
func (n *Network) Inspect(ctx context.Context, opts ...InspectOptions) (client.NetworkInspectResult, error)
Inspect inspects the network, caching the results.
Example ¶
package main
import (
"context"
"fmt"
"github.com/docker/go-sdk/network"
)
func main() {
name := "test-network-inspect"
nw, err := network.New(context.Background(), network.WithName(name))
fmt.Println(err)
inspect, err := nw.Inspect(context.Background())
fmt.Println(err)
fmt.Println(inspect.Network.Name)
err = nw.Terminate(context.Background())
fmt.Println(err)
}
Output: <nil> <nil> test-network-inspect <nil>
Example (WithOptions) ¶
package main
import (
"context"
"fmt"
dockerclient "github.com/moby/moby/client"
"github.com/docker/go-sdk/network"
)
func main() {
name := "test-network-inspect-options"
nw, err := network.New(context.Background(), network.WithName(name))
fmt.Println(err)
inspect, err := nw.Inspect(
context.Background(),
network.WithNoCache(),
network.WithInspectOptions(dockerclient.NetworkInspectOptions{
Verbose: true,
Scope: "local",
}),
)
fmt.Println(err)
fmt.Println(inspect.Network.Name)
err = nw.Terminate(context.Background())
fmt.Println(err)
}
Output: <nil> <nil> test-network-inspect-options <nil>
func (*Network) Terminate ¶
Terminate is used to remove the network. It is usually triggered by as defer function.
Example ¶
package main
import (
"context"
"fmt"
"github.com/docker/go-sdk/network"
)
func main() {
nw, err := network.New(context.Background())
fmt.Println(err)
err = nw.Terminate(context.Background())
fmt.Println(err)
}
Output: <nil> <nil>
type Option ¶
type Option func(*options) error
Option is a function that modifies the options to create a network.
func WithClient ¶
WithClient sets the docker client.
func WithLabels ¶
WithLabels sets the labels of the network.
type TerminableNetwork ¶
TerminableNetwork is a network that can be terminated.
Source Files