api

package
v2.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 31, 2022 License: Apache-2.0 Imports: 8 Imported by: 85

Documentation

Index

Constants

View Source 
const (
	// STARTING indicates that stack is being deployed
	STARTING string = "Starting"
	// RUNNING indicates that stack is deployed and services are running
	RUNNING string = "Running"
	// UPDATING indicates that some stack resources are being recreated
	UPDATING string = "Updating"
	// REMOVING indicates that stack is being deleted
	REMOVING string = "Removing"
	// UNKNOWN indicates unknown stack state
	UNKNOWN string = "Unknown"
	// FAILED indicates that stack deployment failed
	FAILED string = "Failed"
)
View Source 
const (
	// RecreateDiverged to recreate services which configuration diverges from compose model
	RecreateDiverged = "diverged"
	// RecreateForce to force service container being recreated
	RecreateForce = "force"
	// RecreateNever to never recreate existing service containers
	RecreateNever = "never"
)
View Source 
const (
	// ContainerEventLog is a ContainerEvent of type log. Line is set
	ContainerEventLog = iota
	// ContainerEventAttach is a ContainerEvent of type attach. First event sent about a container
	ContainerEventAttach
	// ContainerEventStopped is a ContainerEvent of type stopped.
	ContainerEventStopped
	// ContainerEventExit is a ContainerEvent of type exit. ExitCode is set
	ContainerEventExit
	// UserCancel user cancelled compose up, we are stopping containers
	UserCancel
)
View Source 
const (
	// ProjectLabel allow to track resource related to a compose project
	ProjectLabel = "com.docker.compose.project"
	// ServiceLabel allow to track resource related to a compose service
	ServiceLabel = "com.docker.compose.service"
	// ConfigHashLabel stores configuration hash for a compose service
	ConfigHashLabel = "com.docker.compose.config-hash"
	// ContainerNumberLabel stores the container index of a replicated service
	ContainerNumberLabel = "com.docker.compose.container-number"
	// VolumeLabel allow to track resource related to a compose volume
	VolumeLabel = "com.docker.compose.volume"
	// NetworkLabel allow to track resource related to a compose network
	NetworkLabel = "com.docker.compose.network"
	// WorkingDirLabel stores absolute path to compose project working directory
	WorkingDirLabel = "com.docker.compose.project.working_dir"
	// ConfigFilesLabel stores absolute path to compose project configuration files
	ConfigFilesLabel = "com.docker.compose.project.config_files"
	// EnvironmentFileLabel stores absolute path to compose project env file set by `--env-file`
	EnvironmentFileLabel = "com.docker.compose.project.environment_file"
	// OneoffLabel stores value 'True' for one-off containers created by `compose run`
	OneoffLabel = "com.docker.compose.oneoff"
	// SlugLabel stores unique slug used for one-off container identity
	SlugLabel = "com.docker.compose.slug"
	// ImageDigestLabel stores digest of the container image used to run service
	ImageDigestLabel = "com.docker.compose.image"
	// DependenciesLabel stores service dependencies
	DependenciesLabel = "com.docker.compose.depends_on"
	// VersionLabel stores the compose tool version used to run application
	VersionLabel = "com.docker.compose.version"
)
View Source 
const (
	//ExitCodeLoginRequired exit code when command cannot execute because it requires cloud login
	// This will be used by VSCode to detect when creating context if the user needs to login first
	ExitCodeLoginRequired = 5
)

Variables

View Source 
var (
	// ErrNotFound is returned when an object is not found
	ErrNotFound = errors.New("not found")
	// ErrAlreadyExists is returned when an object already exists
	ErrAlreadyExists = errors.New("already exists")
	// ErrForbidden is returned when an operation is not permitted
	ErrForbidden = errors.New("forbidden")
	// ErrUnknown is returned when the error type is unmapped
	ErrUnknown = errors.New("unknown")
	// ErrLoginFailed is returned when login failed
	ErrLoginFailed = errors.New("login failed")
	// ErrLoginRequired is returned when login is required for a specific action
	ErrLoginRequired = errors.New("login required")
	// ErrNotImplemented is returned when a backend doesn't implement
	// an action
	ErrNotImplemented = errors.New("not implemented")
	// ErrUnsupportedFlag is returned when a backend doesn't support a flag
	ErrUnsupportedFlag = errors.New("unsupported flag")
	// ErrCanceled is returned when the command was canceled by user
	ErrCanceled = errors.New("canceled")
	// ErrParsingFailed is returned when a string cannot be parsed
	ErrParsingFailed = errors.New("parsing failed")
	// ErrWrongContextType is returned when the caller tries to get a context
	// with the wrong type
	ErrWrongContextType = errors.New("wrong context type")
)
View Source 
var ComposeVersion string

ComposeVersion is the compose tool version as declared by label VersionLabel

Functions

func IsAlreadyExistsError 

func IsAlreadyExistsError(err error) bool

IsAlreadyExistsError returns true if the unwrapped error is ErrAlreadyExists

func IsErrCanceled 

func IsErrCanceled(err error) bool

IsErrCanceled returns true if the unwrapped error is ErrCanceled

func IsErrNotImplemented 

func IsErrNotImplemented(err error) bool

IsErrNotImplemented returns true if the unwrapped error is ErrNotImplemented

func IsErrParsingFailed 

func IsErrParsingFailed(err error) bool

IsErrParsingFailed returns true if the unwrapped error is ErrParsingFailed

func IsErrUnsupportedFlag 

func IsErrUnsupportedFlag(err error) bool

IsErrUnsupportedFlag returns true if the unwrapped error is ErrUnsupportedFlag

func IsForbiddenError 

func IsForbiddenError(err error) bool

IsForbiddenError returns true if the unwrapped error is ErrForbidden

func IsNotFoundError 

func IsNotFoundError(err error) bool

IsNotFoundError returns true if the unwrapped error is ErrNotFound

func IsUnknownError 

func IsUnknownError(err error) bool

IsUnknownError returns true if the unwrapped error is ErrUnknown

Types

type BuildOptions 

type BuildOptions struct {
	// Pull always attempt to pull a newer version of the image
	Pull bool
	// Progress set type of progress output ("auto", "plain", "tty")
	Progress string
	// Args set build-time args
	Args types.MappingWithEquals
	// NoCache disables cache use
	NoCache bool
	// Quiet make the build process not output to the console
	Quiet bool
	// Services passed in the command line to be built
	Services []string
	// Ssh authentications passed in the command line
	SSHs []types.SSHKey
}

BuildOptions group options of the Build API

type ContainerEvent 

type ContainerEvent struct {
	Type      int
	Container string
	Service   string
	Line      string
	// ContainerEventExit only
	ExitCode   int
	Restarting bool
}

ContainerEvent notify an event has been collected on source container implementing Service

type ContainerEventListener 

type ContainerEventListener func(event ContainerEvent)

ContainerEventListener is a callback to process ContainerEvent from services

type ContainerProcSummary 

type ContainerProcSummary struct {
	ID        string
	Name      string
	Processes [][]string
	Titles    []string
}

ContainerProcSummary holds container processes top data

type ContainerSummary 

type ContainerSummary struct {
	ID         string
	Name       string
	Command    string
	Project    string
	Service    string
	State      string
	Health     string
	ExitCode   int
	Publishers PortPublishers
}

ContainerSummary hold high-level description of a container

type ConvertOptions 

type ConvertOptions struct {
	// Format define the output format used to dump converted application model (json|yaml)
	Format string
	// Output defines the path to save the application model
	Output string
}

ConvertOptions group options of the Convert API

type CopyOptions 

type CopyOptions struct {
	Source      string
	Destination string
	All         bool
	Index       int
	FollowLink  bool
	CopyUIDGID  bool
}

CopyOptions group options of the cp API

type CreateOptions 

type CreateOptions struct {
	// Services defines the services user interacts with
	Services []string
	// Remove legacy containers for services that are not defined in the project
	RemoveOrphans bool
	// Ignore legacy containers for services that are not defined in the project
	IgnoreOrphans bool
	// Recreate define the strategy to apply on existing containers
	Recreate string
	// RecreateDependencies define the strategy to apply on dependencies services
	RecreateDependencies string
	// Inherit reuse anonymous volumes from previous container
	Inherit bool
	// Timeout set delay to wait for container to gracelfuly stop before sending SIGKILL
	Timeout *time.Duration
	// QuietPull makes the pulling process quiet
	QuietPull bool
}

CreateOptions group options of the Create API

type DownOptions 

type DownOptions struct {
	// RemoveOrphans will cleanup containers that are not declared on the compose model but own the same labels
	RemoveOrphans bool
	// Project is the compose project used to define this app. Might be nil if user ran `down` just with project name
	Project *types.Project
	// Timeout override container stop timeout
	Timeout *time.Duration
	// Images remove image used by services. 'all': Remove all images. 'local': Remove only images that don't have a tag
	Images string
	// Volumes remove volumes, both declared in the `volumes` section and anonymous ones
	Volumes bool
}

DownOptions group options of the Down API

type Event 

type Event struct {
	Timestamp  time.Time
	Service    string
	Container  string
	Status     string
	Attributes map[string]string
}

Event is a container runtime event served by Events API

func (Event) String 

func (e Event) String() string

type EventsOptions 

type EventsOptions struct {
	Services []string
	Consumer func(event Event) error
}

EventsOptions group options of the Events API

type ImageSummary 

type ImageSummary struct {
	ID            string
	ContainerName string
	Repository    string
	Tag           string
	Size          int64
}

ImageSummary holds container image description

type ImagesOptions 

type ImagesOptions struct {
	Services []string
}

ImagesOptions group options of the Images API

type Interceptor 

type Interceptor func(ctx context.Context, project *types.Project)

Interceptor allow to customize the compose types.Project before the actual Service method is executed

type KillOptions 

type KillOptions struct {
	// Services passed in the command line to be killed
	Services []string
	// Signal to send to containers
	Signal string
}

KillOptions group options of the Kill API

type ListOptions 

type ListOptions struct {
	All bool
}

ListOptions group options of the ls API

type LogConsumer 

type LogConsumer interface {
	Log(service, container, message string)
	Status(container, msg string)
	Register(container string)
}

LogConsumer is a callback to process log messages from services

type LogOptions 

type LogOptions struct {
	Services   []string
	Tail       string
	Since      string
	Until      string
	Follow     bool
	Timestamps bool
}

LogOptions defines optional parameters for the `Log` API

type PauseOptions 

type PauseOptions struct {
	// Services passed in the command line to be started
	Services []string
}

PauseOptions group options of the Pause API

type PortOptions 

type PortOptions struct {
	Protocol string
	Index    int
}

PortOptions group options of the Port API

type PortPublisher 

type PortPublisher struct {
	URL           string
	TargetPort    int
	PublishedPort int
	Protocol      string
}

PortPublisher hold status about published port

type PortPublishers 

type PortPublishers []PortPublisher

PortPublishers is a slice of PortPublisher

func (PortPublishers) Len 

func (p PortPublishers) Len() int

Len implements sort.Interface

func (PortPublishers) Less 

func (p PortPublishers) Less(i, j int) bool

Less implements sort.Interface

func (PortPublishers) Swap 

func (p PortPublishers) Swap(i, j int)

Swap implements sort.Interface

type PsOptions 

type PsOptions struct {
	All      bool
	Services []string
}

PsOptions group options of the Ps API

type PullOptions 

type PullOptions struct {
	Quiet          bool
	IgnoreFailures bool
}

PullOptions group options of the Pull API

type PushOptions 

type PushOptions struct {
	IgnoreFailures bool
}

PushOptions group options of the Push API

type RemoveOptions 

type RemoveOptions struct {
	// DryRun just list removable resources
	DryRun bool
	// Volumes remove anonymous volumes
	Volumes bool
	// Force don't ask to confirm removal
	Force bool
	// Services passed in the command line to be removed
	Services []string
}

RemoveOptions group options of the Remove API

type RestartOptions 

type RestartOptions struct {
	// Timeout override container restart timeout
	Timeout *time.Duration
	// Services passed in the command line to be restarted
	Services []string
}

RestartOptions group options of the Restart API

type RunOptions 

type RunOptions struct {
	Name              string
	Service           string
	Command           []string
	Entrypoint        []string
	Detach            bool
	AutoRemove        bool
	Tty               bool
	Interactive       bool
	WorkingDir        string
	User              string
	Environment       []string
	Labels            types.Labels
	Privileged        bool
	UseNetworkAliases bool
	NoDeps            bool
	// QuietPull makes the pulling process quiet
	QuietPull bool
	// used by exec
	Index int
}

RunOptions group options of the Run API

type Service 

type Service interface {
	// Build executes the equivalent to a `compose build`
	Build(ctx context.Context, project *types.Project, options BuildOptions) error
	// Push executes the equivalent ot a `compose push`
	Push(ctx context.Context, project *types.Project, options PushOptions) error
	// Pull executes the equivalent of a `compose pull`
	Pull(ctx context.Context, project *types.Project, opts PullOptions) error
	// Create executes the equivalent to a `compose create`
	Create(ctx context.Context, project *types.Project, opts CreateOptions) error
	// Start executes the equivalent to a `compose start`
	Start(ctx context.Context, projectName string, options StartOptions) error
	// Restart restarts containers
	Restart(ctx context.Context, projectName string, options RestartOptions) error
	// Stop executes the equivalent to a `compose stop`
	Stop(ctx context.Context, projectName string, options StopOptions) error
	// Up executes the equivalent to a `compose up`
	Up(ctx context.Context, project *types.Project, options UpOptions) error
	// Down executes the equivalent to a `compose down`
	Down(ctx context.Context, projectName string, options DownOptions) error
	// Logs executes the equivalent to a `compose logs`
	Logs(ctx context.Context, projectName string, consumer LogConsumer, options LogOptions) error
	// Ps executes the equivalent to a `compose ps`
	Ps(ctx context.Context, projectName string, options PsOptions) ([]ContainerSummary, error)
	// List executes the equivalent to a `docker stack ls`
	List(ctx context.Context, options ListOptions) ([]Stack, error)
	// Convert translate compose model into backend's native format
	Convert(ctx context.Context, project *types.Project, options ConvertOptions) ([]byte, error)
	// Kill executes the equivalent to a `compose kill`
	Kill(ctx context.Context, project string, options KillOptions) error
	// RunOneOffContainer creates a service oneoff container and starts its dependencies
	RunOneOffContainer(ctx context.Context, project *types.Project, opts RunOptions) (int, error)
	// Remove executes the equivalent to a `compose rm`
	Remove(ctx context.Context, project string, options RemoveOptions) error
	// Exec executes a command in a running service container
	Exec(ctx context.Context, project string, opts RunOptions) (int, error)
	// Copy copies a file/folder between a service container and the local filesystem
	Copy(ctx context.Context, project string, options CopyOptions) error
	// Pause executes the equivalent to a `compose pause`
	Pause(ctx context.Context, project string, options PauseOptions) error
	// UnPause executes the equivalent to a `compose unpause`
	UnPause(ctx context.Context, project string, options PauseOptions) error
	// Top executes the equivalent to a `compose top`
	Top(ctx context.Context, projectName string, services []string) ([]ContainerProcSummary, error)
	// Events executes the equivalent to a `compose events`
	Events(ctx context.Context, project string, options EventsOptions) error
	// Port executes the equivalent to a `compose port`
	Port(ctx context.Context, project string, service string, port int, options PortOptions) (string, int, error)
	// Images executes the equivalent of a `compose images`
	Images(ctx context.Context, projectName string, options ImagesOptions) ([]ImageSummary, error)
}

Service manages a compose project

type ServiceProxy 

type ServiceProxy struct {
	BuildFn              func(ctx context.Context, project *types.Project, options BuildOptions) error
	PushFn               func(ctx context.Context, project *types.Project, options PushOptions) error
	PullFn               func(ctx context.Context, project *types.Project, opts PullOptions) error
	CreateFn             func(ctx context.Context, project *types.Project, opts CreateOptions) error
	StartFn              func(ctx context.Context, projectName string, options StartOptions) error
	RestartFn            func(ctx context.Context, projectName string, options RestartOptions) error
	StopFn               func(ctx context.Context, projectName string, options StopOptions) error
	UpFn                 func(ctx context.Context, project *types.Project, options UpOptions) error
	DownFn               func(ctx context.Context, projectName string, options DownOptions) error
	LogsFn               func(ctx context.Context, projectName string, consumer LogConsumer, options LogOptions) error
	PsFn                 func(ctx context.Context, projectName string, options PsOptions) ([]ContainerSummary, error)
	ListFn               func(ctx context.Context, options ListOptions) ([]Stack, error)
	ConvertFn            func(ctx context.Context, project *types.Project, options ConvertOptions) ([]byte, error)
	KillFn               func(ctx context.Context, project string, options KillOptions) error
	RunOneOffContainerFn func(ctx context.Context, project *types.Project, opts RunOptions) (int, error)
	RemoveFn             func(ctx context.Context, project string, options RemoveOptions) error
	ExecFn               func(ctx context.Context, project string, opts RunOptions) (int, error)
	CopyFn               func(ctx context.Context, project string, options CopyOptions) error
	PauseFn              func(ctx context.Context, project string, options PauseOptions) error
	UnPauseFn            func(ctx context.Context, project string, options PauseOptions) error
	TopFn                func(ctx context.Context, projectName string, services []string) ([]ContainerProcSummary, error)
	EventsFn             func(ctx context.Context, project string, options EventsOptions) error
	PortFn               func(ctx context.Context, project string, service string, port int, options PortOptions) (string, int, error)
	ImagesFn             func(ctx context.Context, projectName string, options ImagesOptions) ([]ImageSummary, error)
	// contains filtered or unexported fields
}

ServiceProxy implements Service by delegating to implementation functions. This allows lazy init and per-method overrides

func NewServiceProxy 

func NewServiceProxy() *ServiceProxy

NewServiceProxy produces a ServiceProxy

func (*ServiceProxy) Build 

func (s *ServiceProxy) Build(ctx context.Context, project *types.Project, options BuildOptions) error

Build implements Service interface

func (*ServiceProxy) Convert 

func (s *ServiceProxy) Convert(ctx context.Context, project *types.Project, options ConvertOptions) ([]byte, error)

Convert implements Service interface

func (*ServiceProxy) Copy 

func (s *ServiceProxy) Copy(ctx context.Context, project string, options CopyOptions) error

Copy implements Service interface

func (*ServiceProxy) Create 

func (s *ServiceProxy) Create(ctx context.Context, project *types.Project, options CreateOptions) error

Create implements Service interface

func (*ServiceProxy) Down 

func (s *ServiceProxy) Down(ctx context.Context, project string, options DownOptions) error

Down implements Service interface

func (*ServiceProxy) Events 

func (s *ServiceProxy) Events(ctx context.Context, project string, options EventsOptions) error

Events implements Service interface

func (*ServiceProxy) Exec 

func (s *ServiceProxy) Exec(ctx context.Context, project string, options RunOptions) (int, error)

Exec implements Service interface

func (*ServiceProxy) Images 

func (s *ServiceProxy) Images(ctx context.Context, project string, options ImagesOptions) ([]ImageSummary, error)

Images implements Service interface

func (*ServiceProxy) Kill 

func (s *ServiceProxy) Kill(ctx context.Context, project string, options KillOptions) error

Kill implements Service interface

func (*ServiceProxy) List 

func (s *ServiceProxy) List(ctx context.Context, options ListOptions) ([]Stack, error)

List implements Service interface

func (*ServiceProxy) Logs 

func (s *ServiceProxy) Logs(ctx context.Context, projectName string, consumer LogConsumer, options LogOptions) error

Logs implements Service interface

func (*ServiceProxy) Pause 

func (s *ServiceProxy) Pause(ctx context.Context, project string, options PauseOptions) error

Pause implements Service interface

func (*ServiceProxy) Port 

func (s *ServiceProxy) Port(ctx context.Context, project string, service string, port int, options PortOptions) (string, int, error)

Port implements Service interface

func (*ServiceProxy) Ps 

func (s *ServiceProxy) Ps(ctx context.Context, project string, options PsOptions) ([]ContainerSummary, error)

Ps implements Service interface

func (*ServiceProxy) Pull 

func (s *ServiceProxy) Pull(ctx context.Context, project *types.Project, options PullOptions) error

Pull implements Service interface

func (*ServiceProxy) Push 

func (s *ServiceProxy) Push(ctx context.Context, project *types.Project, options PushOptions) error

Push implements Service interface

func (*ServiceProxy) Remove 

func (s *ServiceProxy) Remove(ctx context.Context, project string, options RemoveOptions) error

Remove implements Service interface

func (*ServiceProxy) Restart 

func (s *ServiceProxy) Restart(ctx context.Context, projectName string, options RestartOptions) error

Restart implements Service interface

func (*ServiceProxy) RunOneOffContainer 

func (s *ServiceProxy) RunOneOffContainer(ctx context.Context, project *types.Project, options RunOptions) (int, error)

RunOneOffContainer implements Service interface

func (*ServiceProxy) Start 

func (s *ServiceProxy) Start(ctx context.Context, projectName string, options StartOptions) error

Start implements Service interface

func (*ServiceProxy) Stop 

func (s *ServiceProxy) Stop(ctx context.Context, projectName string, options StopOptions) error

Stop implements Service interface

func (*ServiceProxy) Top 

func (s *ServiceProxy) Top(ctx context.Context, project string, services []string) ([]ContainerProcSummary, error)

Top implements Service interface

func (*ServiceProxy) UnPause 

func (s *ServiceProxy) UnPause(ctx context.Context, project string, options PauseOptions) error

UnPause implements Service interface

func (*ServiceProxy) Up 

func (s *ServiceProxy) Up(ctx context.Context, project *types.Project, options UpOptions) error

Up implements Service interface

func (*ServiceProxy) WithInterceptor 

func (s *ServiceProxy) WithInterceptor(interceptors ...Interceptor) *ServiceProxy

WithInterceptor configures Interceptor to be applied to Service method execution

func (*ServiceProxy) WithService 

func (s *ServiceProxy) WithService(service Service) *ServiceProxy

WithService configure proxy to use specified Service as delegate

type ServiceStatus 

type ServiceStatus struct {
	ID         string
	Name       string
	Replicas   int
	Desired    int
	Ports      []string
	Publishers []PortPublisher
}

ServiceStatus hold status about a service

type Stack 

type Stack struct {
	ID          string
	Name        string
	Status      string
	ConfigFiles string
	Reason      string
}

Stack holds the name and state of a compose application/stack

type StartOptions 

type StartOptions struct {
	// Attach to container and forward logs if not nil
	Attach LogConsumer
	// AttachTo set the services to attach to
	AttachTo []string
	// CascadeStop stops the application when a container stops
	CascadeStop bool
	// ExitCodeFrom return exit code from specified service
	ExitCodeFrom string
	// Wait won't return until containers reached the running|healthy state
	Wait bool
}

StartOptions group options of the Start API

type StopOptions 

type StopOptions struct {
	// Timeout override container stop timeout
	Timeout *time.Duration
	// Services passed in the command line to be stopped
	Services []string
}

StopOptions group options of the Stop API

type UpOptions 

type UpOptions struct {
	Create CreateOptions
	Start  StartOptions
}

UpOptions group options of the Up API

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.