README
¶
Docker Volumes
This package provides a simple API to create and manage Docker volumes.
Installation
go get github.com/docker/go-sdk/volume
Usage
v, err := volume.New(context.Background(), volume.WithName("my-volume-list"), volume.WithLabels(map[string]string{"volume.type": "example-test"}))
if err != nil {
log.Println(err)
return
}
defer func() {
if err := v.Terminate(context.Background()); err != nil {
log.Println(err)
}
}()
fmt.Printf("volume: %+v", vol)
vol, err := volume.FindByID(context.Background(), v.ID())
if err != nil {
log.Println(err)
return
}
fmt.Printf("volume: %+v", vol)
vols, err := volume.List(context.Background(), make(client.Filters).Add("label", "volume.type=example-test"))
if err != nil {
log.Println(err)
return
}
fmt.Println(len(vols))
for _, v := range vols {
fmt.Printf("%s", v.Name)
}
err = v.Terminate(ctx)
if err != nil {
log.Fatalf("failed to terminate volume: %v", err)
}
Customizing the volume
The volume created with the New function can be customized using functional options. The following options are available:
WithClient(client client.SDKClient) volume.Option: The client to use to create the volume. If not provided, the default client will be used.WithName(name string) volume.Option: The name of the volume.WithLabels(labels map[string]string) volume.Option: The labels of the volume.
When terminating a volume, the Terminate function can be customized using functional options. The following options are available:
WithForce() volume.TerminateOption: Whether to force the termination of the volume.
When finding a volume, the FindByID and List functions can be customized using functional options. The following options are available:
WithFindClient(client *client.Client) volume.FindOptions: The client to use to find the volume. If not provided, the default client will be used.WithFilters(filters client.Filters) volume.FindOptions: The filters to use to find the volume. In the case of theFindByIDfunction, this option is ignored.
Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Cleanup ¶
func Cleanup(tb testing.TB, v TerminableVolume)
Cleanup is a helper function that schedules the volume to be removed when the test ends. This should be the first call after New in a test before any error check. If volume is nil, it's a no-op.
func CleanupByID ¶
CleanupByID is a helper function that schedules the volume 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 volume is nil, it's a no-op. It uses a new docker client to terminate the volume, which is automatically closed when the test ends.
Types ¶
type FindOptions ¶
type FindOptions func(opts *findOptions) error
FindOptions is a function that modifies the find options used to find volumes.
func WithFilters ¶
func WithFilters(filters dockerclient.Filters) FindOptions
WithFilters sets the filters to be used to filter the volumes.
func WithFindClient ¶
func WithFindClient(dockerClient client.SDKClient) FindOptions
WithFindClient returns an FindOptions that sets the find client.
type Option ¶
type Option func(*options) error
Option is a function that modifies the options to create a volume.
func WithClient ¶
WithClient sets the docker client.
func WithLabels ¶
WithLabels sets the labels of the volume.
type TerminableVolume ¶
type TerminableVolume interface {
Terminate(ctx context.Context, opts ...TerminateOption) error
}
TerminableVolume is a volume that can be terminated.
type TerminateOption ¶
type TerminateOption func(*terminateOptions) error
type Volume ¶
type Volume struct {
*dockervolume.Volume
// contains filtered or unexported fields
}
Volume represents a Docker volume.
func FindByID ¶
FindByID finds the volume by ID.
Example ¶
package main
import (
"context"
"fmt"
"log"
"github.com/docker/go-sdk/volume"
)
func main() {
v, err := volume.New(context.Background(), volume.WithName("my-volume-id"))
if err != nil {
log.Println(err)
return
}
defer func() {
if err := v.Terminate(context.Background()); err != nil {
log.Println(err)
}
}()
vol, err := volume.FindByID(context.Background(), "my-volume-id")
if err != nil {
log.Println(err)
return
}
fmt.Println(vol.ID())
fmt.Println(vol.Name)
}
Output: my-volume-id my-volume-id
func List ¶
func List(ctx context.Context, opts ...FindOptions) ([]Volume, error)
List lists volumes.
Example ¶
package main
import (
"context"
"fmt"
"log"
"github.com/moby/moby/client"
"github.com/docker/go-sdk/volume"
)
func main() {
v, err := volume.New(context.Background(), volume.WithName("my-volume-list"), volume.WithLabels(map[string]string{"volume.type": "example-test"}))
if err != nil {
log.Println(err)
return
}
defer func() {
if err := v.Terminate(context.Background()); err != nil {
log.Println(err)
}
}()
vols, err := volume.List(context.Background(), volume.WithFilters(make(client.Filters).Add("label", "volume.type=example-test")))
if err != nil {
log.Println(err)
return
}
fmt.Println(len(vols))
for _, v := range vols {
fmt.Println(v.ID())
fmt.Println(v.Name)
}
}
Output: 1 my-volume-list my-volume-list
func New ¶
New creates a new volume. If no name is provided, a random name is generated. If no client is provided, the default client is used.
Example ¶
package main
import (
"context"
"fmt"
"log"
"github.com/docker/go-sdk/volume"
)
func main() {
v, err := volume.New(context.Background(), volume.WithName("my-volume"))
if err != nil {
log.Println(err)
return
}
defer func() {
if err := v.Terminate(context.Background()); err != nil {
log.Println(err)
}
}()
fmt.Println(v.Name)
fmt.Println(v.ID())
}
Output: my-volume my-volume
Source Files