api

package
v1.14.1 Latest Latest
Warning

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

Go to latest
Published: Mar 6, 2017 License: Apache-2.0, BSD-2-Clause, BSD-3-Clause, + 4 more Imports: 19 Imported by: 621

Documentation

Index

Constants

View Source
const (
	UnrecognizedTransportProtocolErrorName = "UnrecognizedTransportProtocol"
	UnparseablePortErrorName               = "UnparsablePort"
)
View Source
const DOCKER_MINIMUM_MEMORY = 4 * 1024 * 1024 // 4MB
View Source
const INSTANCE_TYPE_CHANGED_ERROR_MESSAGE = "Container instance type changes are not supported."
View Source
const OSType = "linux"

Variables

This section is empty.

Functions

func IsInstanceTypeChangedError added in v1.3.1

func IsInstanceTypeChangedError(err awserr.Error) bool

func PortBindingFromDockerPortBinding

func PortBindingFromDockerPortBinding(dockerPortBindings map[docker.Port][]docker.PortBinding) ([]PortBinding, NamedError)

PortBindingFromDockerPortBinding constructs a PortBinding slice from a docker NetworkSettings.Ports map.

Types

type Container

type Container struct {
	// Name is the name of the container specified in the task definition
	Name string
	// Image is the image name specified in the task definition
	Image string
	// ImageID is the local ID of the image used in the container
	ImageID string

	Command                []string
	CPU                    uint `json:"Cpu"`
	Memory                 uint
	Links                  []string
	VolumesFrom            []VolumeFrom  `json:"volumesFrom"`
	MountPoints            []MountPoint  `json:"mountPoints"`
	Ports                  []PortBinding `json:"portMappings"`
	Essential              bool
	EntryPoint             *[]string
	Environment            map[string]string           `json:"environment"`
	Overrides              ContainerOverrides          `json:"overrides"`
	DockerConfig           DockerConfig                `json:"dockerConfig"`
	RegistryAuthentication *RegistryAuthenticationData `json:"registryAuthentication"`

	// DesiredStatus represents the state where the container should go.  Generally the desired status is informed by the
	// ECS backend as a result of either API calls made to ECS or decisions made by the ECS service scheduler, though the
	// agent may also set the DesiredStatus if a different "essential" container in the task exits.  The DesiredStatus is
	// almost always either ContainerRunning or ContainerStopped.  Do not access DesiredStatus directly.  Instead,
	// use `GetDesiredStatus` and `SetDesiredStatus`.
	// TODO DesiredStatus should probably be private with appropriately written setter/getter.  When this is done, we need
	// to ensure that the UnmarshalJSON is handled properly so that the state storage continues to work.
	DesiredStatus ContainerStatus `json:"desiredStatus"`

	// KnownStatus represents the state where the container is.  Do not access KnownStatus directly.  Instead, use
	// `GetKnownStatus` and `SetKnownStatus`.
	// TODO KnownStatus should probably be private with appropriately written setter/getter.  When this is done, we need
	// to ensure that the UnmarshalJSON is handled properly so that the state storage continues to work.
	KnownStatus ContainerStatus

	// RunDependencies is a list of containers that must be run before
	// this one is created
	RunDependencies []string
	// 'Internal' containers are ones that are not directly specified by task definitions, but created by the agent
	IsInternal bool

	// AppliedStatus is the status that has been "applied" (e.g., we've called Pull, Create, Start, or Stop) but we don't
	// yet know that the application was successful.
	AppliedStatus ContainerStatus
	// ApplyingError is an error that occured trying to transition the container to its desired state
	// It is propagated to the backend in the form 'Name: ErrorString' as the 'reason' field.
	ApplyingError *DefaultNamedError

	// SentStatus represents the last KnownStatus that was sent to the ECS SubmitContainerStateChange API.
	// TODO SentStatus should probably be private with appropriately written setter/getter.  When this is done, we need
	// to ensure that the UnmarshalJSON is handled properly so that the state storage continues to work.
	SentStatus ContainerStatus

	KnownExitCode     *int
	KnownPortBindings []PortBinding

	// Not upstream; todo move this out into a wrapper type
	StatusLock sync.Mutex
	// contains filtered or unexported fields
}

Container is the internal representation of a container in the ECS agent

func (*Container) DesiredTerminal

func (c *Container) DesiredTerminal() bool

func (*Container) GetDesiredStatus added in v1.12.2

func (c *Container) GetDesiredStatus() ContainerStatus

func (*Container) GetKnownStatus added in v1.12.2

func (c *Container) GetKnownStatus() ContainerStatus

func (*Container) GetSentStatus added in v1.14.1

func (c *Container) GetSentStatus() ContainerStatus

GetSentStatus safely returns the SentStatus of the container

func (*Container) KnownTerminal

func (c *Container) KnownTerminal() bool

func (*Container) Overridden

func (c *Container) Overridden() *Container

Overriden returns

func (*Container) SetDesiredStatus added in v1.12.2

func (c *Container) SetDesiredStatus(status ContainerStatus)

func (*Container) SetKnownStatus added in v1.12.2

func (c *Container) SetKnownStatus(status ContainerStatus)

func (*Container) SetSentStatus added in v1.14.1

func (c *Container) SetSentStatus(status ContainerStatus)

SetSentStatus safely sets the SentStatus of the container

func (*Container) String

func (c *Container) String() string

type ContainerOverrides

type ContainerOverrides struct {
	Command *[]string `json:"command"`
}

ContainerOverrides are overrides applied to the container

func (*ContainerOverrides) UnmarshalJSON

func (overrides *ContainerOverrides) UnmarshalJSON(b []byte) error

This custom unmarshaller is needed because the json sent to us as a string rather than a fully typed object. We support both formats in the hopes that one day everything will be fully typed Note: the `json:",string"` tag DOES NOT apply here; it DOES NOT work with struct types, only ints/floats/etc. We're basically doing that though We also intentionally fail if there are any keys we were unable to unmarshal into our struct

type ContainerOverridesCopy

type ContainerOverridesCopy ContainerOverrides

A type alias that doesn't have a custom unmarshaller so we can unmarshal into something without recursing

type ContainerStateChange

type ContainerStateChange struct {
	// TaskArn is the unique identifier for the task
	TaskArn string
	// ContainerName is the name of the container
	ContainerName string
	// Status is the status to send
	Status ContainerStatus

	// Reason may contain details of why the container stopped
	Reason string
	// ExitCode is the exit code of the container, if available
	ExitCode *int
	// PortBindings are the details of the host ports picked for the specified
	// container ports
	PortBindings []PortBinding

	// Container is a pointer to the container involved in the state change that gives the event handler a hook into
	// storing what status was sent.  This is used to ensure the same event is handled only once.
	Container *Container
}

ContainerStateChange represents a state change that needs to be sent to the SubmitContainerStateChange API

func (*ContainerStateChange) String added in v1.3.1

func (c *ContainerStateChange) String() string

type ContainerStatus

type ContainerStatus int32

ContainerStatus is an enumeration of valid states in the container lifecycle

const (
	// ContainerStatusNone is the zero state of a container; this container has not completed pull
	ContainerStatusNone ContainerStatus = iota
	// ContainerPulled represents a container which has had the image pulled
	ContainerPulled
	// ContainerCreated represents a container that has been created
	ContainerCreated
	// ContainerRunning represents a container that has started
	ContainerRunning
	// ContainerStopped represents a container that has stopped
	ContainerStopped

	// ContainerZombie is an "impossible" state that is used as the maximum
	ContainerZombie
)

func (*ContainerStatus) BackendRecognized added in v1.1.0

func (cs *ContainerStatus) BackendRecognized() bool

func (*ContainerStatus) MarshalJSON

func (cs *ContainerStatus) MarshalJSON() ([]byte, error)

func (ContainerStatus) String

func (cs ContainerStatus) String() string

func (*ContainerStatus) TaskStatus

func (cs *ContainerStatus) TaskStatus() TaskStatus

func (ContainerStatus) Terminal

func (cs ContainerStatus) Terminal() bool

func (*ContainerStatus) UnmarshalJSON

func (cs *ContainerStatus) UnmarshalJSON(b []byte) error

type DefaultNamedError added in v1.1.0

type DefaultNamedError struct {
	Err  string `json:"error"`
	Name string `json:"name"`
}

NamedError is a wrapper type for 'error' which adds an optional name and provides a symetric marshal/unmarshal

func NewNamedError added in v1.1.0

func NewNamedError(err error) *DefaultNamedError

NewNamedError creates a NamedError.

func (*DefaultNamedError) Error added in v1.1.0

func (err *DefaultNamedError) Error() string

Error implements error

func (*DefaultNamedError) ErrorName added in v1.1.0

func (err *DefaultNamedError) ErrorName() string

ErrorName implements NamedError

type DockerClientConfigError added in v1.1.0

type DockerClientConfigError struct {
	// contains filtered or unexported fields
}

func (*DockerClientConfigError) Error added in v1.1.0

func (err *DockerClientConfigError) Error() string

func (*DockerClientConfigError) ErrorName added in v1.1.0

func (err *DockerClientConfigError) ErrorName() string

type DockerConfig added in v1.5.0

type DockerConfig struct {
	Config     *string `json:"config"`
	HostConfig *string `json:"hostConfig"`
	Version    *string `json:"version"`
}

DockerConfig represents additional metadata about a container to run. It's remodeled from the `ecsacs` api model file. Eventually it should not exist once this remodeling is refactored out.

type DockerContainer

type DockerContainer struct {
	DockerID   string `json:"DockerId"`
	DockerName string // needed for linking

	Container *Container
}

DockerContainer is a mapping between containers-as-docker-knows-them and containers-as-we-know-them. This is primarily used in DockerState, but lives here such that tasks and containers know how to convert themselves into Docker's desired config format

func (*DockerContainer) String

func (dc *DockerContainer) String() string

type ECRAuthData added in v1.7.0

type ECRAuthData struct {
	EndpointOverride string `json:"endpointOverride"`
	Region           string `json:"region"`
	RegistryID       string `json:"registryId"`
}

ECRAuthData is the authentication details for ECR specifying the region, registryID, and possible endpoint override

type ECSClient

type ECSClient interface {
	// RegisterContainerInstance calculates the appropriate resources, creates
	// the default cluster if necessary, and returns the registered
	// ContainerInstanceARN if successful. Supplying a non-empty container
	// instance ARN allows a container instance to update its registered
	// resources.
	RegisterContainerInstance(existingContainerInstanceArn string, attributes []string) (string, error)
	// SubmitTaskStateChange sends a state change and returns an error
	// indicating if it was submitted
	SubmitTaskStateChange(change TaskStateChange) error
	// SubmitContainerStateChange sends a state change and returns an error
	// indicating if it was submitted
	SubmitContainerStateChange(change ContainerStateChange) error
	// DiscoverPollEndpoint takes a ContainerInstanceARN and returns the
	// endpoint at which this Agent should contact ACS
	DiscoverPollEndpoint(containerInstanceArn string) (string, error)
	// DiscoverTelemetryEndpoint takes a ContainerInstanceARN and returns the
	// endpoint at which this Agent should contact Telemetry Service
	DiscoverTelemetryEndpoint(containerInstanceArn string) (string, error)
}

ECSClient is an interface over the ECSSDK interface which abstracts away some details around constructing the request and reading the response down to the parts the agent cares about. For example, the ever-present 'Cluster' member is abstracted out so that it may be configured once and used throughout transparently.

type ECSSDK added in v1.1.0

ECSSDK is an interface that specifies the subset of the AWS Go SDK's ECS client that the Agent uses. This interface is meant to allow injecting a mock for testing.

type ECSSubmitStateSDK added in v1.4.0

type ECSSubmitStateSDK interface {
	SubmitContainerStateChange(*ecs.SubmitContainerStateChangeInput) (*ecs.SubmitContainerStateChangeOutput, error)
	SubmitTaskStateChange(*ecs.SubmitTaskStateChangeInput) (*ecs.SubmitTaskStateChangeOutput, error)
}

type EmptyHostVolume

type EmptyHostVolume struct {
	HostPath string `json:"hostPath"`
}

EmptyHostVolume represents a volume without a specified host path

func (*EmptyHostVolume) SourcePath

func (e *EmptyHostVolume) SourcePath() string

SourcePath returns the generated host path for the volume

type FSHostVolume

type FSHostVolume struct {
	FSSourcePath string `json:"sourcePath"`
}

FSHostVolume is a simple type of HostVolume which references an arbitrary location on the host as the Volume.

func (*FSHostVolume) SourcePath

func (fs *FSHostVolume) SourcePath() string

SourcePath returns the path on the host filesystem that should be mounted

type HostConfigError added in v1.1.0

type HostConfigError struct {
	// contains filtered or unexported fields
}

func (*HostConfigError) Error added in v1.1.0

func (err *HostConfigError) Error() string

func (*HostConfigError) ErrorName added in v1.1.0

func (err *HostConfigError) ErrorName() string

type HostVolume

type HostVolume interface {
	SourcePath() string
}

HostVolume is an interface for something that may be used as the host half of a docker volume mount

type MountPoint

type MountPoint struct {
	SourceVolume  string `json:"sourceVolume"`
	ContainerPath string `json:"containerPath"`
	ReadOnly      bool   `json:"readOnly"`
}

MountPoint describes the in-container location of a Volume and references that Volume by name.

type NamedError added in v1.1.0

type NamedError interface {
	error
	ErrorName() string
}

type PortBinding

type PortBinding struct {
	// ContainerPort is the port inside the container
	ContainerPort uint16
	// HostPort is the port exposed on the host
	HostPort uint16
	// BindIP is the IP address to which the port is bound
	BindIP string `json:"BindIp"`
	// Protocol is the protocol of the port
	Protocol TransportProtocol
}

PortBinding represents a port binding for a container

type RegistryAuthenticationData added in v1.7.0

type RegistryAuthenticationData struct {
	Type        string       `json:"type"`
	ECRAuthData *ECRAuthData `json:"ecrAuthData"`
}

RegistryAuthenticationData is the authentication data sent by the ECS backend. Currently, the only supported authentication data is for ECR.

type Resource

type Resource struct {
	Name        string
	Type        string
	DoubleValue float64
	LongValue   int64
}

Resource is an on-host resource

type Task

type Task struct {
	// Arn is the unique identifer for the task
	Arn string
	// Overrides are the overrides applied to a task
	Overrides TaskOverrides `json:"-"`
	// Family is the name of the task definition family
	Family string
	// Version is the version of the task definition
	Version string
	// Containers are the containers for the task
	Containers []*Container
	// Volumes are the volumes for the task
	Volumes []TaskVolume `json:"volumes"`

	// DesiredStatus represents the state where the task should go.  Generally the desired status is informed by the ECS
	// backend as a result of either API calls made to ECS or decisions made by the ECS service scheduler.  The
	// DesiredStatus is almost always either TaskRunning or TaskStopped.  Do not access DesiredStatus directly.  Instead,
	// use `UpdateStatus`, `UpdateDesiredStatus`, `SetDesiredStatus`, and `SetDesiredStatus`.
	// TODO DesiredStatus should probably be private with appropriately written setter/getter.  When this is done, we need
	// to ensure that the UnmarshalJSON is handled properly so that the state storage continues to work.
	DesiredStatus TaskStatus

	// KnownStatus represents the state where the task is.  This is generally the minimum of equivalent status types for
	// the containers in the task; if one container is at ContainerRunning and another is at ContainerPulled, the task
	// KnownStatus would be TaskPulled.  Do not access KnownStatus directly.  Instead, use `UpdateStatus`,
	// `UpdateKnownStatusAndTime`,  and `GetKnownStatus`.
	// TODO KnownStatus should probably be private with appropriately written setter/getter.  When this is done, we need
	// to ensure that the UnmarshalJSON is handled properly so that the state storage continues to work.
	KnownStatus TaskStatus

	// KnownStatusTime captures the time when the KnownStatus was last updated.  Do not access KnownStatusTime directly,
	// instead use `GetKnownStatusTime`.
	KnownStatusTime time.Time `json:"KnownTime"`

	// SentStatus represents the last KnownStatus that was sent to the ECS SubmitTaskStateChange API.
	// TODO(samuelkarp) SentStatus needs a lock and setters/getters.
	// TODO SentStatus should probably be private with appropriately written setter/getter.  When this is done, we need
	// to ensure that the UnmarshalJSON is handled properly so that the state storage continues to work.
	SentStatus TaskStatus

	StartSequenceNumber int64
	StopSequenceNumber  int64
	// contains filtered or unexported fields
}

Task is the internal representation of a task in the ECS agent

func RemoveFromTaskArray

func RemoveFromTaskArray(arr []*Task, ndx int) []*Task

RemoveFromTaskArray removes the element at ndx from an array of task pointers, arr. If the ndx is out of bounds, it returns arr unchanged.

func TaskFromACS added in v1.0.0

func TaskFromACS(acsTask *ecsacs.Task, envelope *ecsacs.PayloadMessage) (*Task, error)

TaskFromACS translates ecsacs.Task to api.Task by first marshaling the recieved ecsacs.Task to json and unmrashaling it as api.Task

func (*Task) ContainerByName

func (task *Task) ContainerByName(name string) (*Container, bool)

ContainerByName returns the *Container for the given name

func (*Task) DockerConfig

func (task *Task) DockerConfig(container *Container) (*docker.Config, *DockerClientConfigError)

DockerConfig converts the given container in this task to the format of GoDockerClient's 'Config' struct

func (*Task) DockerHostConfig

func (task *Task) DockerHostConfig(container *Container, dockerContainerMap map[string]*DockerContainer) (*docker.HostConfig, *HostConfigError)

func (*Task) GetCredentialsId added in v1.11.0

func (task *Task) GetCredentialsId() string

func (*Task) GetDesiredStatus added in v1.13.0

func (task *Task) GetDesiredStatus() TaskStatus

func (*Task) GetKnownStatus added in v1.9.0

func (task *Task) GetKnownStatus() TaskStatus

GetKnownStatus gets the KnownStatus of the task

func (*Task) GetKnownStatusTime added in v1.9.0

func (task *Task) GetKnownStatusTime() time.Time

GetKnownStatusTime gets the KnownStatusTime of the task

func (*Task) GetSentStatus added in v1.14.1

func (task *Task) GetSentStatus() TaskStatus

GetSentStatus safely returns the SentStatus of the task

func (*Task) HostVolumeByName

func (task *Task) HostVolumeByName(name string) (HostVolume, bool)

HostVolumeByName returns the task Volume for the given a volume name in that task. The second return value indicates the presense of that volume

func (*Task) Overridden

func (task *Task) Overridden() *Task

Overridden returns a copy of the task with all container's overridden and itself overridden as well

func (*Task) PostUnmarshalTask

func (task *Task) PostUnmarshalTask(credentialsManager credentials.Manager)

PostUnmarshalTask is run after a task has been unmarshalled, but before it has been run. It is possible it will be subsequently called after that and should be able to handle such an occurrence appropriately (e.g. behave idempotently).

func (*Task) SetCredentialsId added in v1.11.0

func (task *Task) SetCredentialsId(id string)

func (*Task) SetDesiredStatus added in v1.13.0

func (task *Task) SetDesiredStatus(status TaskStatus)

func (*Task) SetKnownStatus added in v1.1.0

func (task *Task) SetKnownStatus(status TaskStatus)

func (*Task) SetSentStatus added in v1.14.1

func (task *Task) SetSentStatus(status TaskStatus)

SetSentStatus safely sets the SentStatus of the task

func (*Task) String

func (t *Task) String() string

func (*Task) UpdateDesiredStatus added in v1.1.0

func (task *Task) UpdateDesiredStatus()

func (*Task) UpdateKnownStatusAndTime added in v1.9.0

func (task *Task) UpdateKnownStatusAndTime(status TaskStatus)

UpdateKnownStatusAndTime updates the KnownStatus and KnownStatusTime of the task

func (*Task) UpdateMountPoints

func (task *Task) UpdateMountPoints(cont *Container, vols map[string]string)

UpdateMountPoints updates the mount points of volumes that were created without specifying a host path. This is used as part of the empty host volume feature.

func (*Task) UpdateStatus added in v1.1.0

func (task *Task) UpdateStatus() bool

UpdateStatus updates a task's known and desired statuses to be compatible with all of its containers It will return a bool indicating if there was a change

type TaskOverrides

type TaskOverrides struct{}

TaskOverrides are the overrides applied to a task

type TaskStateChange added in v1.1.0

type TaskStateChange struct {
	// TaskArn is the unique identifier for the task
	TaskArn string
	// Status is the status to send
	Status TaskStatus
	// Reason may contain details of why the task stopped
	Reason string

	// Task is a pointer to the task involved in the state change that gives the event handler a hook into storing
	// what status was sent.  This is used to ensure the same event is handled only once.
	Task *Task
}

TaskStateChange represents a state change that needs to be sent to the SubmitTaskStateChange API

func (*TaskStateChange) String added in v1.3.1

func (t *TaskStateChange) String() string

type TaskStatus

type TaskStatus int32

TaskStatus is an enumeration of valid states in the task lifecycle

const (
	// TaskStatusNone is the zero state of a task; this task has been received but no further progress has completed
	TaskStatusNone TaskStatus = iota
	// TaskPulled represents a task which has had all its container images pulled, but not all have yet progressed passed pull
	TaskPulled
	// TaskCreated represents a task which has had all its containers created
	TaskCreated
	// TaskRunning represents a task which has had all its containers started
	TaskRunning
	// TaskStopped represents a task in which all containers are stopped
	TaskStopped
)

func (*TaskStatus) BackendRecognized added in v1.1.0

func (ts *TaskStatus) BackendRecognized() bool

func (*TaskStatus) BackendStatus added in v1.0.0

func (ts *TaskStatus) BackendStatus() string

Mapping task status in the agent to that in the backend

func (*TaskStatus) ContainerStatus

func (ts *TaskStatus) ContainerStatus() ContainerStatus

func (*TaskStatus) MarshalJSON

func (ts *TaskStatus) MarshalJSON() ([]byte, error)

func (TaskStatus) String

func (ts TaskStatus) String() string

func (TaskStatus) Terminal

func (ts TaskStatus) Terminal() bool

func (*TaskStatus) UnmarshalJSON

func (ts *TaskStatus) UnmarshalJSON(b []byte) error

type TaskVolume

type TaskVolume struct {
	Name   string `json:"name"`
	Volume HostVolume
}

TaskVolume is a definition of all the volumes available for containers to reference within a task. It must be named.

func (*TaskVolume) MarshalJSON

func (tv *TaskVolume) MarshalJSON() ([]byte, error)

func (*TaskVolume) UnmarshalJSON

func (tv *TaskVolume) UnmarshalJSON(b []byte) error

UnmarshalJSON for TaskVolume determines the name and volume type, and unmarshals it into the appropriate HostVolume fulfilling interfaces

type TransportProtocol added in v1.2.0

type TransportProtocol int32

TransportProtocol is an enumeration of valid transport protocols

const (
	// TransportProtocolTCP represents TCP
	TransportProtocolTCP TransportProtocol = iota
	// TransportProtocolUDP represents UDP
	TransportProtocolUDP
)

func NewTransportProtocol added in v1.2.0

func NewTransportProtocol(protocol string) (TransportProtocol, error)

NewTransportProtocol returns a TransportProtocol from a string in the task

func (*TransportProtocol) MarshalJSON added in v1.2.0

func (tp *TransportProtocol) MarshalJSON() ([]byte, error)

func (*TransportProtocol) String added in v1.2.0

func (tp *TransportProtocol) String() string

func (*TransportProtocol) UnmarshalJSON added in v1.2.0

func (tp *TransportProtocol) UnmarshalJSON(b []byte) error

UnmarshalJSON for TransportProtocol determines whether to use TCP or UDP, setting TCP as the zero-value but treating other unrecognized values as errors

type VolumeFrom

type VolumeFrom struct {
	SourceContainer string `json:"sourceContainer"`
	ReadOnly        bool   `json:"readOnly"`
}

VolumeFrom is a volume which references another container as its source.

Notes

Bugs

  • On Windows, volumes with names that differ only by case will collide

Directories

Path Synopsis
Package testutils contains files that are used in tests but not elsewhere and thus can be excluded from the final executable.
Package testutils contains files that are used in tests but not elsewhere and thus can be excluded from the final executable.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL