docker

Documentation

Index

• Constants
• func EngineSpecRequiresDocker(t testing.TB, engineSpec *models.SpecConfig)
• func MaybeNeedDocker(t testing.TB, needDocker bool)
• func MustHaveDocker(t testing.TB)
• func NewCustomDockerError(code bacerrors.ErrorCode, message string) bacerrors.Error
• func NewDockerError(err error) (bacErr bacerrors.Error)
• func NewDockerImageError(err error, image string) (bacErr bacerrors.Error)
• func NewManifestCache(cfg types.DockerManifestCache) cache.Cache[ImageManifest]
• type Client
  • func NewDockerClient() (*Client, error)
  • func (c *Client) FindContainer(ctx context.Context, label string, value string) (string, error)
  • func (c *Client) FollowLogs(ctx context.Context, id string) (stdout, stderr io.Reader, err error)
  • func (c *Client) GetOutputStream(ctx context.Context, id string, since string, follow bool) (io.ReadCloser, error)
  • func (c *Client) HostGatewayIP(ctx context.Context) (net.IP, error)
  • func (c *Client) ImageDistribution(ctx context.Context, image string, creds config_legacy.DockerCredentials) (*ImageManifest, error)
  • func (c *Client) ImagePlatforms(ctx context.Context, image string, dockerCreds config_legacy.DockerCredentials) ([]v1.Platform, error)
  • func (c *Client) IsInstalled(ctx context.Context) bool
  • func (c *Client) PullImage(ctx context.Context, img string, dockerCreds config_legacy.DockerCredentials) error
  • func (c *Client) RemoveContainer(ctx context.Context, id string) error
  • func (c *Client) RemoveObjectsWithLabel(ctx context.Context, labelName, labelValue string) error
  • func (c *Client) SupportedPlatforms(ctx context.Context) ([]v1.Platform, error)
• type ImageManifest

Constants

const (
	ContainerNotFound = "ContainerNotFound"
	ImageNotFound     = "ImageNotFound"
	ImageInvalid      = "ImageInvalid"
	NotFound          = "NotFound"
	Conflict          = "Conflict"
	Unauthorized      = "Unauthorized"
	Forbidden         = "Forbidden"
	DataLoss          = "DataLoss"
	Deadline          = "Deadline"
	Cancelled         = "Cancelled"
	Unavailable       = "Unavailable"
	SystemError       = "SystemError"
	NotImplemented    = "NotImplemented"
	UnknownError      = "UnknownError"
)

Docker-specific error codes

const (
	BridgeNetworkUnattached = "BridgeNetworkUnattached"
	ContainerNotRunning     = "ContainerNotRunning"
	ImageDigestMismatch     = "ImageDigestMismatch"
)

Custom Docker error codes

const Component = "Docker"

Functions

func EngineSpecRequiresDocker

func EngineSpecRequiresDocker(t testing.TB, engineSpec *models.SpecConfig)

EngineSpecRequiresDocker will skip the test if the test is running in an environment that cannot support cross-platform Docker images, and the passed model.EngineSpec type is model.EngineDocker

func MaybeNeedDocker

func MaybeNeedDocker(t testing.TB, needDocker bool)

MaybeNeedDocker will skip the test if the test is running in an environment that cannot support cross-platform Docker images, and the passed boolean flag is true.

func MustHaveDocker

func MustHaveDocker(t testing.TB)

MustHaveDocker will skip the test if the test is running in an environment that cannot support cross-platform Docker images.

func NewCustomDockerError

func NewCustomDockerError(code bacerrors.ErrorCode, message string) bacerrors.Error

func NewDockerError

func NewDockerError(err error) (bacErr bacerrors.Error)

func NewDockerImageError

func NewDockerImageError(err error, image string) (bacErr bacerrors.Error)

func NewManifestCache

func NewManifestCache(cfg types.DockerManifestCache) cache.Cache[ImageManifest]

Types

type Client

type Client struct {
	tracing.TracedClient
}

func NewDockerClient

func NewDockerClient() (*Client, error)

func (*Client) FindContainer

func (c *Client) FindContainer(ctx context.Context, label string, value string) (string, error)

func (*Client) FollowLogs

func (c *Client) FollowLogs(ctx context.Context, id string) (stdout, stderr io.Reader, err error)

func (*Client) GetOutputStream

func (c *Client) GetOutputStream(ctx context.Context, id string, since string, follow bool) (io.ReadCloser, error)

func (*Client) HostGatewayIP

func (c *Client) HostGatewayIP(ctx context.Context) (net.IP, error)

func (*Client) ImageDistribution

func (c *Client) ImageDistribution(
	ctx context.Context, image string, creds config_legacy.DockerCredentials,
) (*ImageManifest, error)

ImageDistribution fetches the details for the specified image by asking docker to fetch the distribution manifest from the remote registry. This manifest will contain information on the digest along with the details of the platform that the image supports.

It is worth noting that if the call is made to the docker hub, the digest retrieved may not appear accurate when compared to the hub website but this is expected as the non-platform-specific digest is not displayed on the docker hub. This digest is safe however as both manual and programmatic pulls do the correct thing in retrieving the correct image for the platform.

cf:

• https://github.com/moby/moby/issues/40636)
• https://github.com/docker/roadmap/issues/262

When a docker image is available on only a single platform, the digest shown will be the digest pointing directly at the manifest for that image on that platform (as shown by the docker hub). Where multiple platforms are available, the digest is pointing to a top level document describing all of the different platform manifests available.

In either case, `docker pull` will do the correct thing and download the image for your platform. For example:

$ docker manifest inspect bitnami/rabbitmq@sha256:0be0d2a2 ...

"manifests": [ {
	  "digest": "sha256:959a02013e8ab5538167f9....",
	  "platform": { "architecture": "amd64", "os": "linux" }
	},
	{
	  "digest": "sha256:11ee2c7e9e69e3a8311a19....",
	  "platform": { "architecture": "arm64", "os": "linux"}
	}]

$ docker pull bitnami/rabbitmq@sha256:0be0d2a2 ... $ docker image ls bitnami/rabbitmq ... 48603925e10c

The digest 486039 can be found in manifest sha256:11ee2c7e which is the manifest for the current authors machine.

$ docker manifest inspect bitnami/rabbitmq@sha256:11ee2c7e

  "config": {
	   "size": 7383,
	   "digest": "sha256:48603925e10c01936ea4258f...."
  }

This is the image that will finally be installed.

func (*Client) ImagePlatforms

func (c *Client) ImagePlatforms(ctx context.Context, image string, dockerCreds config_legacy.DockerCredentials) ([]v1.Platform, error)

func (*Client) IsInstalled

func (c *Client) IsInstalled(ctx context.Context) bool

func (*Client) PullImage

func (c *Client) PullImage(ctx context.Context, img string, dockerCreds config_legacy.DockerCredentials) error

func (*Client) RemoveContainer

func (c *Client) RemoveContainer(ctx context.Context, id string) error

func (*Client) RemoveObjectsWithLabel

func (c *Client) RemoveObjectsWithLabel(ctx context.Context, labelName, labelValue string) error

func (*Client) SupportedPlatforms

func (c *Client) SupportedPlatforms(ctx context.Context) ([]v1.Platform, error)

type ImageManifest

type ImageManifest struct {
	// We only ever expect the digest to be the `algorithm:hash`
	Digest    digest.Digest
	Platforms []v1.Platform
}