bufplugindocker

Documentation

Overview

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

Index

• Constants
• type BuildOption
  • func WithConfigDirPath(path string) 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)

Constants

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 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 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)
	// 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.