bufplugindocker

Documentation

Overview

Package bufplugindocker contains utilities for building Buf plugins using the Docker API.

Index

• Constants
• type BuildOption
  • func WithBuildArgs(args []string) BuildOption
  • func WithCacheFrom(cacheFrom []string) BuildOption
  • func WithConfigDirPath(path string) BuildOption
  • func WithPullParent(pullParent bool) BuildOption
  • func WithTarget(target string) BuildOption
• type BuildResponse
• type Client
  • func NewClient(logger *zap.Logger, options ...ClientOption) (Client, error)
• type ClientOption
  • func WithHost(host string) ClientOption
  • func WithVersion(version string) ClientOption
• type DeleteResponse
• type PushResponse
• type RegistryAuthConfig
  • func (r *RegistryAuthConfig) ToHeader() (string, error)
• type TagResponse

Constants

const (
	// DefaultTarget is the default target architecture for Docker images.
	DefaultTarget = "linux/amd64"
)

const SourceFileAlternatePath = "Dockerfile"

SourceFileAlternatePath is the alternate path for the DockerSource.

const SourceFilePath = "Dockerfile.plugin"

SourceFilePath is the default source file path for the DockerSource.

Types

type BuildOption

type BuildOption func(*buildOptions)

BuildOption defines options for the image build call.

func WithBuildArgs

func WithBuildArgs(args []string) BuildOption

WithBuildArgs allows specifying additional Docker build args.

func WithCacheFrom

func WithCacheFrom(cacheFrom []string) BuildOption

WithCacheFrom is a BuildOption which allows using images published to an OCI registry to be used as cached state during build.

func WithConfigDirPath

func WithConfigDirPath(path string) BuildOption

WithConfigDirPath is a BuildOption which enables node ID persistence to the specified configuration directory. If not set, a new node ID will be generated with each build call.

func WithPullParent

func WithPullParent(pullParent bool) BuildOption

WithPullParent configures whether the build will attempt to pull the latest parent images (FROM ...) prior to build.

func WithTarget

func WithTarget(target string) BuildOption

WithTarget is a BuildOption which sets the target architecture (used for local testing on arm64).

type BuildResponse

type BuildResponse struct {
	// Image contains the Docker image name in the local Docker engine including the tag (i.e. plugins.buf.build/library/some-plugin:<id>, where <id> is a random id).
	// It is created from the bufpluginconfig.Config's Name.IdentityString() and a unique id.
	Image string
	// ImageID specifies the Docker image id in the format <hash_algorithm>:<hash>.
	// Example: sha256:65001659f150f085e0b37b697a465a95cbfd885d9315b61960883b9ac588744e
	ImageID string
}

BuildResponse returns details of a successful image build call.

type Client

type Client interface {
	// Build creates a Docker image for the plugin using the Dockerfile.plugin and plugin config.
	Build(ctx context.Context, dockerfile io.Reader, config *bufpluginconfig.Config, options ...BuildOption) (*BuildResponse, error)
	// Push the Docker image to the remote registry.
	Push(ctx context.Context, image string, auth *RegistryAuthConfig) (*PushResponse, error)
	// Delete removes the Docker image from local Docker Engine.
	Delete(ctx context.Context, image string) (*DeleteResponse, error)
	// Tag creates a Docker image tag from an existing image and plugin config.
	Tag(ctx context.Context, image string, config *bufpluginconfig.Config) (*TagResponse, error)
	// Close releases any resources used by the underlying Docker client.
	Close() error
}

Client is a small abstraction over a Docker API client, providing the basic APIs we need to build plugins. It ensures that we pass the appropriate parameters to build images (i.e. platform 'linux/amd64').

func NewClient

func NewClient(logger *zap.Logger, options ...ClientOption) (Client, error)

NewClient creates a new Client to use to build Docker plugins.

type ClientOption

type ClientOption func(options *clientOptions)

ClientOption defines options for the NewClient call to customize the underlying Docker client.

func WithHost

func WithHost(host string) ClientOption

WithHost allows specifying a Docker engine host to connect to (instead of the default lookup using DOCKER_HOST env var). This makes it suitable for use by parallel tests.

func WithVersion

func WithVersion(version string) ClientOption

WithVersion allows specifying a Docker API client version instead of using the default version negotiation algorithm. This allows tests to implement the Docker engine API using stable URLs.

type DeleteResponse

type DeleteResponse struct{}

DeleteResponse is a placeholder for data to be returned from a successful image delete call.

type PushResponse

type PushResponse struct {
	// Digest specifies the Docker image digest in the format <hash_algorithm>:<hash>.
	// The digest returned from Client.Push differs from the image id returned in Client.Build.
	Digest string
}

PushResponse is a placeholder for data to be returned from a successful image push call.

type RegistryAuthConfig

type RegistryAuthConfig struct {
	Username      string `json:"username,omitempty"`
	Password      string `json:"password,omitempty"`
	Email         string `json:"email,omitempty"`
	ServerAddress string `json:"serveraddress,omitempty"` // domain/ip without a protocol
}

RegistryAuthConfig represents the fields required to authenticate with the Docker Engine API. Ref: https://docs.docker.com/engine/api/v1.41/#section/Authentication

func (*RegistryAuthConfig) ToHeader

func (r *RegistryAuthConfig) ToHeader() (string, error)

ToHeader marshals the auth information as a base64 encoded JSON object. This is suitable for passing to the Docker API as the X-Registry-Auth header.

type TagResponse

type TagResponse struct {
	// Image contains the Docker image name in the local Docker engine including the tag.
	// It is created from the bufpluginconfig.Config's Name.IdentityString() and a unique id.
	Image string
}

TagResponse returns details of a successful image tag call.