config

Documentation

Overview

Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at

http://aws.amazon.com/apache2.0/

or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Package config handles loading configuration data, warning on missing data, and setting sane defaults.

Configuration Sources

Configuration data is loaded from two sources currently: the environment and a json config file.

Environment Variables:

The environment variables from which configuration values are loaded are documented in the README file which can be found at https://github.com/aws/amazon-ecs-agent#environment-variables.

Config file:

The config file will be loaded from the path stored in the environment key ECS_AGENT_CONFIG_FILE_PATH. It must be a JSON file of the format described by the "Config" struct below.

Index

• Constants
• Variables
• type Conditional
  • func (b Conditional) Enabled() bool
  • func (b Conditional) MarshalJSON() ([]byte, error)
  • func (b *Conditional) UnmarshalJSON(jsonData []byte) error
• type Config
  • func DefaultConfig() Config
  • func NewConfig(ec2client ec2.EC2MetadataClient) (*Config, error)
  • func (cfg *Config) Merge(rhs Config) *Config
  • func (cfg *Config) String() string
• type ConfigReader
• type ContainerInstancePropagateTagsFromType
• type ImagePullBehaviorType
• type PlatformVariables
• type SensitiveRawMessage
  • func NewSensitiveRawMessage(data json.RawMessage) *SensitiveRawMessage
  • func (data SensitiveRawMessage) Contents() json.RawMessage
  • func (data SensitiveRawMessage) GoString() string
  • func (data SensitiveRawMessage) MarshalJSON() ([]byte, error)
  • func (data SensitiveRawMessage) String() string
  • func (data *SensitiveRawMessage) UnmarshalJSON(jsonData []byte) error

Constants

const (
	// http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=docker
	DockerReservedPort    = 2375
	DockerReservedSSLPort = 2376
	// DockerTagSeparator is the charactor used to separate names and tag in docker
	DockerTagSeparator = ":"
	// DefaultDockerTag is the default tag used by docker
	DefaultDockerTag = "latest"

	SSHPort = 22

	// AgentIntrospectionPort is used to serve the metadata about the agent and to query the tasks being managed by the agent.
	AgentIntrospectionPort = 51678

	// AgentCredentialsPort is used to serve the credentials for tasks.
	AgentCredentialsPort = 51679

	// AgentPrometheusExpositionPort is used to expose Prometheus metrics that can be scraped by a Prometheus server
	AgentPrometheusExpositionPort = 51680

	// DefaultClusterName is the name of the default cluster.
	DefaultClusterName = "default"

	// DefaultTaskCleanupWaitDuration specifies the default value for task cleanup duration. It is used to
	// clean up task's containers.
	DefaultTaskCleanupWaitDuration = 3 * time.Hour

	// DefaultPollingMetricsWaitDuration specifies the default value for polling metrics wait duration
	// This is only used when PollMetrics is set to true
	DefaultPollingMetricsWaitDuration = 15 * time.Second

	// DefaultImageCleanupTimeInterval specifies the default value for image cleanup duration. It is used to
	// remove the images pulled by agent.
	DefaultImageCleanupTimeInterval = 30 * time.Minute

	// DefaultNumImagesToDeletePerCycle specifies the default number of images to delete when agent performs
	// image cleanup.
	DefaultNumImagesToDeletePerCycle = 5

	// DefaultNumNonECSContainersToDeletePerCycle specifies the default number of nonecs containers to delete when agent performs
	// nonecs containers cleanup.
	DefaultNumNonECSContainersToDeletePerCycle = 5

	// DefaultImageDeletionAge specifies the default value for minimum amount of elapsed time after an image
	// has been pulled before it can be deleted.
	DefaultImageDeletionAge = 1 * time.Hour

	// DefaultNonECSImageDeletionAge specifies the default value for minimum amount of elapsed time after an image
	// has been created before it can be deleted
	DefaultNonECSImageDeletionAge = 1 * time.Hour

	// DefaultMinSupportedCNIVersion denotes the minimum version of cni spec required
	DefaultMinSupportedCNIVersion = "0.3.0"

	// DefaultTaskMetadataSteadyStateRate is set as 40. This is arrived from our benchmarking
	// results where task endpoint can handle 4000 rps effectively. Here, 100 containers
	// will be able to send out 40 rps.
	DefaultTaskMetadataSteadyStateRate = 40

	// DefaultTaskMetadataBurstRate is set to handle 60 burst requests at once
	DefaultTaskMetadataBurstRate = 60

	//Known cached image names
	CachedImageNamePauseContainer = "amazon/amazon-ecs-pause:0.1.0"
	CachedImageNameAgentContainer = "amazon/amazon-ecs-agent:latest"

	// DefaultNvidiaRuntime is the name of the runtime to pass Nvidia GPUs to containers
	DefaultNvidiaRuntime = "nvidia"
)

const (
	// AgentCredentialsAddress is used to serve the credentials for tasks.
	AgentCredentialsAddress = "" // this is left blank right now for net=bridge

	// DefaultTaskCgroupPrefix is default cgroup prefix for ECS tasks
	DefaultTaskCgroupPrefix = "/ecs"
)

const OSType = "linux"

OSType is the type of operating system where agent is running

Variables

var (
	// DefaultPauseContainerImageName is the name of the pause container image. The linker's
	// load flags are used to populate this value from the Makefile
	DefaultPauseContainerImageName = ""

	// DefaultPauseContainerTag is the tag for the pause container image. The linker's load
	// flags are used to populate this value from the Makefile
	DefaultPauseContainerTag = ""
)

Types

type Conditional

type Conditional int

Conditional makes it possible to understand if a variable was set explicitly or relies on a default setting

const (
	ExplicitlyEnabled Conditional
	ExplicitlyDisabled
	DefaultEnabled
)

func (Conditional) Enabled

func (b Conditional) Enabled() bool

Enabled is a convenience function for when consumers don't care if the value is implicit or explicit

func (Conditional) MarshalJSON

func (b Conditional) MarshalJSON() ([]byte, error)

MarshalJSON is used to serialize the type to json, per the Marshaller interface

func (*Conditional) UnmarshalJSON

func (b *Conditional) UnmarshalJSON(jsonData []byte) error

UnmarshalJSON is used to deserialize json types into Conditional, per the Unmarshaller interface

type Config

type Config struct {
	// DEPRECATED
	// ClusterArn is the Name or full ARN of a Cluster to register into. It has
	// been deprecated (and will eventually be removed) in favor of Cluster
	ClusterArn string `deprecated:"Please use Cluster instead"`
	// Cluster can either be the Name or full ARN of a Cluster. This is the
	// cluster the agent should register this ContainerInstance into. If this
	// value is not set, it will default to "default"
	Cluster string `trim:"true"`
	// APIEndpoint is the endpoint, such as "ecs.us-east-1.amazonaws.com", to
	// make calls against. If this value is not set, it will default to the
	// endpoint for your current AWSRegion
	APIEndpoint string `trim:"true"`
	// DockerEndpoint is the address the agent will attempt to connect to the
	// Docker daemon at. This should have the same value as "DOCKER_HOST"
	// normally would to interact with the daemon. It defaults to
	// unix:///var/run/docker.sock
	DockerEndpoint string
	// AWSRegion is the region to run in (such as "us-east-1"). This value will
	// be inferred from the EC2 metadata service, but if it cannot be found this
	// will be fatal.
	AWSRegion string `missing:"fatal" trim:"true"`

	// ReservedPorts is an array of ports which should be registered as
	// unavailable. If not set, they default to [22,2375,2376,51678].
	ReservedPorts []uint16
	// ReservedPortsUDP is an array of UDP ports which should be registered as
	// unavailable. If not set, it defaults to [].
	ReservedPortsUDP []uint16

	// DataDir is the directory data is saved to in order to preserve state
	// across agent restarts.
	// It is also used to keep the metadata of containers managed by the agent
	DataDir string
	// DataDirOnHost is the directory in the instance from which we mount
	// DataDir to the ecs-agent container and to agent managed containers
	DataDirOnHost string
	// Checkpoint configures whether data should be periodically to a checkpoint
	// file, in DataDir, such that on instance or agent restarts it will resume
	// as the same ContainerInstance. It defaults to false.
	Checkpoint bool

	// EngineAuthType configures what type of data is in EngineAuthData.
	// Supported types, right now, can be found in the dockerauth package: https://godoc.org/github.com/aws/amazon-ecs-agent/agent/dockerclient/dockerauth
	EngineAuthType string `trim:"true"`
	// EngineAuthData contains authentication data. Please see the documentation
	// for EngineAuthType for more information.
	EngineAuthData *SensitiveRawMessage

	// UpdatesEnabled specifies whether updates should be applied to this agent.
	// Default true
	UpdatesEnabled bool
	// UpdateDownloadDir specifies where new agent versions should be placed
	// within the container in order for the external updating process to
	// correctly handle them.
	UpdateDownloadDir string

	// DisableMetrics configures whether task utilization metrics should be
	// sent to the ECS telemetry endpoint
	DisableMetrics bool

	// PollMetrics configures whether metrics are constantly streamed for each container or
	// polled on interval instead.
	PollMetrics bool

	// PollingMetricsWaitDuration configures how long a container should wait before polling metrics
	// again when PollMetrics is set to true
	PollingMetricsWaitDuration time.Duration

	// DisableDockerHealthCheck configures whether container health feature was enabled
	// on the instance
	DisableDockerHealthCheck bool

	// ReservedMemory specifies the amount of memory (in MB) to reserve for things
	// other than containers managed by ECS
	ReservedMemory uint16

	// DockerStopTimeout specifies the amount of time before a SIGKILL is issued to
	// containers managed by ECS
	DockerStopTimeout time.Duration

	// ContainerStartTimeout specifies the amount of time to wait to start a container
	ContainerStartTimeout time.Duration

	// ImagePullInactivityTimeout is here to override the amount of time to wait when pulling and extracting a container
	ImagePullInactivityTimeout time.Duration

	// AvailableLoggingDrivers specifies the logging drivers available for use
	// with Docker.  If not set, it defaults to ["json-file","none"].
	AvailableLoggingDrivers []dockerclient.LoggingDriver

	// PrivilegedDisabled specified whether the Agent is capable of launching
	// tasks with privileged containers
	PrivilegedDisabled bool

	// SELinxuCapable specifies whether the Agent is capable of using SELinux
	// security options
	SELinuxCapable bool

	// AppArmorCapable specifies whether the Agent is capable of using AppArmor
	// security options
	AppArmorCapable bool

	// TaskCleanupWaitDuration specifies the time to wait after a task is stopped
	// until cleanup of task resources is started.
	TaskCleanupWaitDuration time.Duration

	// TaskIAMRoleEnabled specifies if the Agent is capable of launching
	// tasks with IAM Roles.
	TaskIAMRoleEnabled bool

	// DeleteNonECSImagesEnabled specifies if the Agent can delete the cached, unused non-ecs images.
	DeleteNonECSImagesEnabled bool

	// TaskCPUMemLimit specifies if Agent can launch a task with a hierarchical cgroup
	TaskCPUMemLimit Conditional

	// CredentialsAuditLogFile specifies the path/filename of the audit log.
	CredentialsAuditLogFile string

	// CredentialsAuditLogEnabled specifies whether audit logging is disabled.
	CredentialsAuditLogDisabled bool

	// TaskIAMRoleEnabledForNetworkHost specifies if the Agent is capable of launching
	// tasks with IAM Roles when networkMode is set to 'host'
	TaskIAMRoleEnabledForNetworkHost bool

	// TaskENIEnabled specifies if the Agent is capable of launching task within
	// defined EC2 networks
	TaskENIEnabled bool

	// ENITrunkingEnabled specifies if the Agent is enabled to launch awsvpc
	// task with ENI Trunking
	ENITrunkingEnabled bool

	// ImageCleanupDisabled specifies whether the Agent will periodically perform
	// automated image cleanup
	ImageCleanupDisabled bool

	// MinimumImageDeletionAge specifies the minimum time since it was pulled
	// before it can be deleted
	MinimumImageDeletionAge time.Duration

	// NonECSMinimumImageDeletionAge specifies the minimum time since non ecs images created before it can be deleted
	NonECSMinimumImageDeletionAge time.Duration

	// ImageCleanupInterval specifies the time to wait before performing the image
	// cleanup since last time it was executed
	ImageCleanupInterval time.Duration

	// NumImagesToDeletePerCycle specifies the num of image to delete every time
	// when Agent performs cleanup
	NumImagesToDeletePerCycle int

	// NumNonECSContainersToDeletePerCycle specifies the num of NonECS containers to delete every time
	// when Agent performs cleanup
	NumNonECSContainersToDeletePerCycle int

	// ImagePullBehavior specifies the agent's behavior for pulling image and loading
	// local Docker image cache
	ImagePullBehavior ImagePullBehaviorType

	// InstanceAttributes contains key/value pairs representing
	// attributes to be associated with this instance within the
	// ECS service and used to influence behavior such as launch
	// placement.
	InstanceAttributes map[string]string

	// Set if clients validate ssl certificates. Used mainly for testing
	AcceptInsecureCert bool `json:"-"`

	// CNIPluginsPath is the path for the cni plugins
	CNIPluginsPath string

	// PauseContainerTarballPath is the path to the pause container tarball
	PauseContainerTarballPath string

	// PauseContainerImageName is the name for the pause container image.
	// Setting this value to be different from the default will disable loading
	// the image from the tarball; the referenced image must already be loaded.
	PauseContainerImageName string

	// PauseContainerTag is the tag for the pause container image.
	// Setting this value to be different from the default will disable loading
	// the image from the tarball; the referenced image must already be loaded.
	PauseContainerTag string

	// PrometheusMetricsEnabled configures whether Agent metrics should be
	// collected and published to the specified endpoint. This is disabled by
	// default.
	PrometheusMetricsEnabled bool

	// AWSVPCBlockInstanceMetdata specifies if InstanceMetadata endpoint should be blocked
	// for tasks that are launched with network mode "awsvpc" when ECS_AWSVPC_BLOCK_IMDS=true
	AWSVPCBlockInstanceMetdata bool

	// OverrideAWSVPCLocalIPv4Address overrides the local IPv4 address chosen
	// for a task using the `awsvpc` networking mode. Using this configuration
	// will limit you to running one `awsvpc` task at a time. IPv4 addresses
	// must be specified in decimal-octet form and also specify the subnet
	// size (e.g., "169.254.172.42/22").
	OverrideAWSVPCLocalIPv4Address *cnitypes.IPNet

	// AWSVPCAdditionalLocalRoutes allows the specification of routing table
	// entries that will be added in the task's network namespace via the
	// instance bridge interface rather than via the ENI.
	AWSVPCAdditionalLocalRoutes []cnitypes.IPNet

	// ContainerMetadataEnabled specifies if the agent should provide a metadata
	// file for containers.
	ContainerMetadataEnabled bool

	// OverrideAWSLogsExecutionRole is config option used to enable awslogs
	// driver authentication over the task's execution role
	OverrideAWSLogsExecutionRole bool

	// CgroupPath is the path expected by the agent, defaults to
	// '/sys/fs/cgroup'
	CgroupPath string

	// PlatformVariables consists of configuration variables specific to linux/windows
	PlatformVariables PlatformVariables

	// TaskMetadataSteadyStateRate specifies the steady state throttle for the task metadata endpoint
	TaskMetadataSteadyStateRate int

	// TaskMetadataBurstRate specifies the burst rate throttle for the task metadata endpoint
	TaskMetadataBurstRate int

	// SharedVolumeMatchFullConfig is config option used to short-circuit volume validation against a
	// provisioned volume, if false (default). If true, we perform deep comparison including driver options
	// and labels. For comparing shared volume across 2 instances, this should be set to false as docker's
	// default behavior is to match name only, and does not propagate driver options and labels through volume drivers.
	SharedVolumeMatchFullConfig bool

	// NoIID when set to true, specifies that the agent should not register the instance
	// with instance identity document. This is required in order to accomodate scenarios in
	// which ECS agent tries to register the instance where the instance id document is
	// not available or needed
	NoIID bool

	// ContainerInstancePropagateTagsFrom when set to "ec2_instance", agent will call EC2 API to
	// get the tags and register them through RegisterContainerInstance call.
	// When set to "none" (or any other string), no API call will be made.
	ContainerInstancePropagateTagsFrom ContainerInstancePropagateTagsFromType

	// ContainerInstanceTags contains key/value pairs representing
	// tags extracted from config file and will be associated with this instance
	// through RegisterContainerInstance call. Tags with the same keys from DescribeTags
	// API call will be overridden.
	ContainerInstanceTags map[string]string

	// GPUSupportEnabled specifies if the Agent is capable of launching GPU tasks
	GPUSupportEnabled bool
	// ImageCleanupExclusionList is the list of image names customers want to keep for their own use and delete automatically
	ImageCleanupExclusionList []string

	// NvidiaRuntime is the runtime to be used for passing Nvidia GPU devices to containers
	NvidiaRuntime string `trim:"true"`

	// TaskMetadataAZDisabled specifies if availability zone should be disabled in Task Metadata endpoint
	TaskMetadataAZDisabled bool

	// ENIPauseContainerCleanupDelaySeconds specifies how long to wait before cleaning up the pause container after all
	// other containers have stopped.
	ENIPauseContainerCleanupDelaySeconds int

	// CgroupCPUPeriod is config option to set different CFS quota and period values in microsecond, defaults to 100 ms
	CgroupCPUPeriod time.Duration

	// SpotInstanceDrainingEnabled, if true, agent will poll the container instance's metadata endpoint for an ec2 spot
	//   instance termination notice. If EC2 sends a spot termination notice, then agent will set the instance's state
	//   to DRAINING, which gracefully shuts down all running tasks on the instance.
	// If the instance is not spot then the poller will still run but it will never receive a termination notice.
	// Defaults to false.
	// see https://docs.aws.amazon.com/AmazonECS/latest/developerguide/container-instance-draining.html
	SpotInstanceDrainingEnabled bool

	// GMSACapable is the config option to indicate if gMSA is supported.
	// It should be enabled by default only if the container instance is part of a valid active directory domain.
	GMSACapable bool
}

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the default configuration for Linux

func NewConfig

func NewConfig(ec2client ec2.EC2MetadataClient) (*Config, error)

NewConfig returns a config struct created by merging environment variables, a config file, and EC2 Metadata info. The 'config' struct it returns can be used, even if an error is returned. An error is returned, however, if the config is incomplete in some way that is considered fatal.

func (*Config) Merge

func (cfg *Config) Merge(rhs Config) *Config

Merge merges two config files, preferring the ones on the left. Any nil or zero values present in the left that are not present in the right will be overridden

func (*Config) String

func (cfg *Config) String() string

String returns a lossy string representation of the config suitable for human readable display. Consequently, it *should not* return any sensitive information.

type ConfigReader

type ConfigReader interface {
	ReadConfig() *Config
}

type ContainerInstancePropagateTagsFromType

type ContainerInstancePropagateTagsFromType int8

ContainerInstancePropagateTagsFromType is an enum variable type corresponding to different ways to propagate tags, it includes none (default) and ec2_instance.

const (
	// When ContainerInstancePropagateTagsFromNoneType is specified, no DescribeTags
	// API call will be made.
	ContainerInstancePropagateTagsFromNoneType ContainerInstancePropagateTagsFromType = iota

	// When ContainerInstancePropagateTagsFromEC2InstanceType is specified, agent will
	// make DescribeTags API call to get tags remotely.
	ContainerInstancePropagateTagsFromEC2InstanceType
)

type ImagePullBehaviorType

type ImagePullBehaviorType int8

ImagePullBehaviorType is an enum variable type corresponding to different agent pull behaviors including default, always, never and once.

const (
	// ImagePullDefaultBehavior specifies the behavior that if an image pull API call fails,
	// agent tries to start from the Docker image cache anyway, assuming that the image has not changed.
	ImagePullDefaultBehavior ImagePullBehaviorType = iota

	// ImagePullAlwaysBehavior specifies the behavior that if an image pull API call fails,
	// the task fails instead of using cached image.
	ImagePullAlwaysBehavior

	// ImagePullOnceBehavior specifies the behavior that agent will only attempt to pull
	// the same image once, once an image is pulled, local image cache will be used
	// for all the containers.
	ImagePullOnceBehavior

	// ImagePullPreferCachedBehavior specifies the behavior that agent will only attempt to pull
	// the image if there is no cached image.
	ImagePullPreferCachedBehavior
)

type PlatformVariables

type PlatformVariables struct{}

PlatformVariables consists of configuration variables specific to Linux

type SensitiveRawMessage

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

SensitiveRawMessage is a struct to store some data that should not be logged or printed. This struct is a Stringer which will not print its contents with 'String'. It is a json.Marshaler and json.Unmarshaler and will present its actual contents in plaintext when read/written from/to json.

func NewSensitiveRawMessage

func NewSensitiveRawMessage(data json.RawMessage) *SensitiveRawMessage

NewSensitiveRawMessage returns a new encapsulated json.RawMessage or nil if the data is empty. It cannot be accidentally logged via .String/.GoString/%v/%#v

func (SensitiveRawMessage) Contents

func (data SensitiveRawMessage) Contents() json.RawMessage

func (SensitiveRawMessage) GoString

func (data SensitiveRawMessage) GoString() string

func (SensitiveRawMessage) MarshalJSON

func (data SensitiveRawMessage) MarshalJSON() ([]byte, error)

func (SensitiveRawMessage) String

func (data SensitiveRawMessage) String() string

func (*SensitiveRawMessage) UnmarshalJSON

func (data *SensitiveRawMessage) UnmarshalJSON(jsonData []byte) error