UNPKG

25.1 kBTypeScriptView Raw
1import * as iam from '@aws-cdk/aws-iam';
2import * as secretsmanager from '@aws-cdk/aws-secretsmanager';
3import * as ssm from '@aws-cdk/aws-ssm';
4import * as cdk from '@aws-cdk/core';
5import { Construct } from 'constructs';
6import { TaskDefinition } from './base/task-definition';
7import { ContainerImage } from './container-image';
8import { CfnTaskDefinition } from './ecs.generated';
9import { EnvironmentFile, EnvironmentFileConfig } from './environment-file';
10import { LinuxParameters } from './linux-parameters';
11import { LogDriver, LogDriverConfig } from './log-drivers/log-driver';
12import { Construct as CoreConstruct } from '@aws-cdk/core';
13/**
14 * Specify the secret's version id or version stage
15 */
16export interface SecretVersionInfo {
17 /**
18 * version id of the secret
19 *
20 * @default - use default version id
21 */
22 readonly versionId?: string;
23 /**
24 * version stage of the secret
25 *
26 * @default - use default version stage
27 */
28 readonly versionStage?: string;
29}
30/**
31 * A secret environment variable.
32 */
33export declare abstract class Secret {
34 /**
35 * Creates an environment variable value from a parameter stored in AWS
36 * Systems Manager Parameter Store.
37 */
38 static fromSsmParameter(parameter: ssm.IParameter): Secret;
39 /**
40 * Creates a environment variable value from a secret stored in AWS Secrets
41 * Manager.
42 *
43 * @param secret the secret stored in AWS Secrets Manager
44 * @param field the name of the field with the value that you want to set as
45 * the environment variable value. Only values in JSON format are supported.
46 * If you do not specify a JSON field, then the full content of the secret is
47 * used.
48 */
49 static fromSecretsManager(secret: secretsmanager.ISecret, field?: string): Secret;
50 /**
51 * Creates a environment variable value from a secret stored in AWS Secrets
52 * Manager.
53 *
54 * @param secret the secret stored in AWS Secrets Manager
55 * @param versionInfo the version information to reference the secret
56 * @param field the name of the field with the value that you want to set as
57 * the environment variable value. Only values in JSON format are supported.
58 * If you do not specify a JSON field, then the full content of the secret is
59 * used.
60 */
61 static fromSecretsManagerVersion(secret: secretsmanager.ISecret, versionInfo: SecretVersionInfo, field?: string): Secret;
62 /**
63 * The ARN of the secret
64 */
65 abstract readonly arn: string;
66 /**
67 * Whether this secret uses a specific JSON field
68 */
69 abstract readonly hasField?: boolean;
70 /**
71 * Grants reading the secret to a principal
72 */
73 abstract grantRead(grantee: iam.IGrantable): iam.Grant;
74}
75export interface ContainerDefinitionOptions {
76 /**
77 * The image used to start a container.
78 *
79 * This string is passed directly to the Docker daemon.
80 * Images in the Docker Hub registry are available by default.
81 * Other repositories are specified with either repository-url/image:tag or repository-url/image@digest.
82 * TODO: Update these to specify using classes of IContainerImage
83 */
84 readonly image: ContainerImage;
85 /**
86 * The name of the container.
87 *
88 * @default - id of node associated with ContainerDefinition.
89 */
90 readonly containerName?: string;
91 /**
92 * The command that is passed to the container.
93 *
94 * If you provide a shell command as a single string, you have to quote command-line arguments.
95 *
96 * @default - CMD value built into container image.
97 */
98 readonly command?: string[];
99 /**
100 * The minimum number of CPU units to reserve for the container.
101 *
102 * @default - No minimum CPU units reserved.
103 */
104 readonly cpu?: number;
105 /**
106 * Specifies whether networking is disabled within the container.
107 *
108 * When this parameter is true, networking is disabled within the container.
109 *
110 * @default false
111 */
112 readonly disableNetworking?: boolean;
113 /**
114 * A list of DNS search domains that are presented to the container.
115 *
116 * @default - No search domains.
117 */
118 readonly dnsSearchDomains?: string[];
119 /**
120 * A list of DNS servers that are presented to the container.
121 *
122 * @default - Default DNS servers.
123 */
124 readonly dnsServers?: string[];
125 /**
126 * A key/value map of labels to add to the container.
127 *
128 * @default - No labels.
129 */
130 readonly dockerLabels?: {
131 [key: string]: string;
132 };
133 /**
134 * A list of strings to provide custom labels for SELinux and AppArmor multi-level security systems.
135 *
136 * @default - No security labels.
137 */
138 readonly dockerSecurityOptions?: string[];
139 /**
140 * The ENTRYPOINT value to pass to the container.
141 *
142 * @see https://docs.docker.com/engine/reference/builder/#entrypoint
143 *
144 * @default - Entry point configured in container.
145 */
146 readonly entryPoint?: string[];
147 /**
148 * The environment variables to pass to the container.
149 *
150 * @default - No environment variables.
151 */
152 readonly environment?: {
153 [key: string]: string;
154 };
155 /**
156 * The environment files to pass to the container.
157 *
158 * @see https://docs.aws.amazon.com/AmazonECS/latest/developerguide/taskdef-envfiles.html
159 *
160 * @default - No environment files.
161 */
162 readonly environmentFiles?: EnvironmentFile[];
163 /**
164 * The secret environment variables to pass to the container.
165 *
166 * @default - No secret environment variables.
167 */
168 readonly secrets?: {
169 [key: string]: Secret;
170 };
171 /**
172 * Time duration (in seconds) to wait before giving up on resolving dependencies for a container.
173 *
174 * @default - none
175 */
176 readonly startTimeout?: cdk.Duration;
177 /**
178 * Time duration (in seconds) to wait before the container is forcefully killed if it doesn't exit normally on its own.
179 *
180 * @default - none
181 */
182 readonly stopTimeout?: cdk.Duration;
183 /**
184 * Specifies whether the container is marked essential.
185 *
186 * If the essential parameter of a container is marked as true, and that container fails
187 * or stops for any reason, all other containers that are part of the task are stopped.
188 * If the essential parameter of a container is marked as false, then its failure does not
189 * affect the rest of the containers in a task. All tasks must have at least one essential container.
190 *
191 * If this parameter is omitted, a container is assumed to be essential.
192 *
193 * @default true
194 */
195 readonly essential?: boolean;
196 /**
197 * A list of hostnames and IP address mappings to append to the /etc/hosts file on the container.
198 *
199 * @default - No extra hosts.
200 */
201 readonly extraHosts?: {
202 [name: string]: string;
203 };
204 /**
205 * The health check command and associated configuration parameters for the container.
206 *
207 * @default - Health check configuration from container.
208 */
209 readonly healthCheck?: HealthCheck;
210 /**
211 * The hostname to use for your container.
212 *
213 * @default - Automatic hostname.
214 */
215 readonly hostname?: string;
216 /**
217 * The amount (in MiB) of memory to present to the container.
218 *
219 * If your container attempts to exceed the allocated memory, the container
220 * is terminated.
221 *
222 * At least one of memoryLimitMiB and memoryReservationMiB is required for non-Fargate services.
223 *
224 * @default - No memory limit.
225 */
226 readonly memoryLimitMiB?: number;
227 /**
228 * The soft limit (in MiB) of memory to reserve for the container.
229 *
230 * When system memory is under heavy contention, Docker attempts to keep the
231 * container memory to this soft limit. However, your container can consume more
232 * memory when it needs to, up to either the hard limit specified with the memory
233 * parameter (if applicable), or all of the available memory on the container
234 * instance, whichever comes first.
235 *
236 * At least one of memoryLimitMiB and memoryReservationMiB is required for non-Fargate services.
237 *
238 * @default - No memory reserved.
239 */
240 readonly memoryReservationMiB?: number;
241 /**
242 * Specifies whether the container is marked as privileged.
243 * When this parameter is true, the container is given elevated privileges on the host container instance (similar to the root user).
244 *
245 * @default false
246 */
247 readonly privileged?: boolean;
248 /**
249 * When this parameter is true, the container is given read-only access to its root file system.
250 *
251 * @default false
252 */
253 readonly readonlyRootFilesystem?: boolean;
254 /**
255 * The user name to use inside the container.
256 *
257 * @default root
258 */
259 readonly user?: string;
260 /**
261 * The working directory in which to run commands inside the container.
262 *
263 * @default /
264 */
265 readonly workingDirectory?: string;
266 /**
267 * The log configuration specification for the container.
268 *
269 * @default - Containers use the same logging driver that the Docker daemon uses.
270 */
271 readonly logging?: LogDriver;
272 /**
273 * Linux-specific modifications that are applied to the container, such as Linux kernel capabilities.
274 * For more information see [KernelCapabilities](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_KernelCapabilities.html).
275 *
276 * @default - No Linux parameters.
277 */
278 readonly linuxParameters?: LinuxParameters;
279 /**
280 * The number of GPUs assigned to the container.
281 *
282 * @default - No GPUs assigned.
283 */
284 readonly gpuCount?: number;
285 /**
286 * The port mappings to add to the container definition.
287 * @default - No ports are mapped.
288 */
289 readonly portMappings?: PortMapping[];
290 /**
291 * The inference accelerators referenced by the container.
292 * @default - No inference accelerators assigned.
293 */
294 readonly inferenceAcceleratorResources?: string[];
295 /**
296 * A list of namespaced kernel parameters to set in the container.
297 *
298 * @default - No system controls are set.
299 * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-taskdefinition-systemcontrol.html
300 * @see https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_systemcontrols
301 */
302 readonly systemControls?: SystemControl[];
303}
304/**
305 * The properties in a container definition.
306 */
307export interface ContainerDefinitionProps extends ContainerDefinitionOptions {
308 /**
309 * The name of the task definition that includes this container definition.
310 *
311 * [disable-awslint:ref-via-interface]
312 */
313 readonly taskDefinition: TaskDefinition;
314}
315/**
316 * A container definition is used in a task definition to describe the containers that are launched as part of a task.
317 */
318export declare class ContainerDefinition extends CoreConstruct {
319 private readonly props;
320 /**
321 * The Linux-specific modifications that are applied to the container, such as Linux kernel capabilities.
322 */
323 readonly linuxParameters?: LinuxParameters;
324 /**
325 * The mount points for data volumes in your container.
326 */
327 readonly mountPoints: MountPoint[];
328 /**
329 * The list of port mappings for the container. Port mappings allow containers to access ports
330 * on the host container instance to send or receive traffic.
331 */
332 readonly portMappings: PortMapping[];
333 /**
334 * The data volumes to mount from another container in the same task definition.
335 */
336 readonly volumesFrom: VolumeFrom[];
337 /**
338 * An array of ulimits to set in the container.
339 */
340 readonly ulimits: Ulimit[];
341 /**
342 * An array dependencies defined for container startup and shutdown.
343 */
344 readonly containerDependencies: ContainerDependency[];
345 /**
346 * Specifies whether the container will be marked essential.
347 *
348 * If the essential parameter of a container is marked as true, and that container
349 * fails or stops for any reason, all other containers that are part of the task are
350 * stopped. If the essential parameter of a container is marked as false, then its
351 * failure does not affect the rest of the containers in a task.
352 *
353 * If this parameter is omitted, a container is assumed to be essential.
354 */
355 readonly essential: boolean;
356 /**
357 * The name of this container
358 */
359 readonly containerName: string;
360 /**
361 * Whether there was at least one memory limit specified in this definition
362 */
363 readonly memoryLimitSpecified: boolean;
364 /**
365 * The name of the task definition that includes this container definition.
366 */
367 readonly taskDefinition: TaskDefinition;
368 /**
369 * The environment files for this container
370 */
371 readonly environmentFiles?: EnvironmentFileConfig[];
372 /**
373 * The log configuration specification for the container.
374 */
375 readonly logDriverConfig?: LogDriverConfig;
376 /**
377 * Whether this container definition references a specific JSON field of a secret
378 * stored in Secrets Manager.
379 */
380 readonly referencesSecretJsonField?: boolean;
381 /**
382 * The name of the image referenced by this container.
383 */
384 readonly imageName: string;
385 /**
386 * The inference accelerators referenced by this container.
387 */
388 private readonly inferenceAcceleratorResources;
389 /**
390 * The configured container links
391 */
392 private readonly links;
393 private readonly imageConfig;
394 private readonly secrets?;
395 private readonly environment;
396 /**
397 * Constructs a new instance of the ContainerDefinition class.
398 */
399 constructor(scope: Construct, id: string, props: ContainerDefinitionProps);
400 /**
401 * This method adds a link which allows containers to communicate with each other without the need for port mappings.
402 *
403 * This parameter is only supported if the task definition is using the bridge network mode.
404 * Warning: The --link flag is a legacy feature of Docker. It may eventually be removed.
405 */
406 addLink(container: ContainerDefinition, alias?: string): void;
407 /**
408 * This method adds one or more mount points for data volumes to the container.
409 */
410 addMountPoints(...mountPoints: MountPoint[]): void;
411 /**
412 * This method mounts temporary disk space to the container.
413 *
414 * This adds the correct container mountPoint and task definition volume.
415 */
416 addScratch(scratch: ScratchSpace): void;
417 /**
418 * This method adds one or more port mappings to the container.
419 */
420 addPortMappings(...portMappings: PortMapping[]): void;
421 /**
422 * This method adds an environment variable to the container.
423 */
424 addEnvironment(name: string, value: string): void;
425 /**
426 * This method adds one or more resources to the container.
427 */
428 addInferenceAcceleratorResource(...inferenceAcceleratorResources: string[]): void;
429 /**
430 * This method adds one or more ulimits to the container.
431 */
432 addUlimits(...ulimits: Ulimit[]): void;
433 /**
434 * This method adds one or more container dependencies to the container.
435 */
436 addContainerDependencies(...containerDependencies: ContainerDependency[]): void;
437 /**
438 * This method adds one or more volumes to the container.
439 */
440 addVolumesFrom(...volumesFrom: VolumeFrom[]): void;
441 /**
442 * This method adds the specified statement to the IAM task execution policy in the task definition.
443 */
444 addToExecutionPolicy(statement: iam.PolicyStatement): void;
445 /**
446 * Returns the host port for the requested container port if it exists
447 */
448 findPortMapping(containerPort: number, protocol: Protocol): PortMapping | undefined;
449 /**
450 * The inbound rules associated with the security group the task or service will use.
451 *
452 * This property is only used for tasks that use the awsvpc network mode.
453 */
454 get ingressPort(): number;
455 /**
456 * The port the container will listen on.
457 */
458 get containerPort(): number;
459 /**
460 * Render this container definition to a CloudFormation object
461 *
462 * @param _taskDefinition [disable-awslint:ref-via-interface] (unused but kept to avoid breaking change)
463 */
464 renderContainerDefinition(_taskDefinition?: TaskDefinition): CfnTaskDefinition.ContainerDefinitionProperty;
465}
466/**
467 * The health check command and associated configuration parameters for the container.
468 */
469export interface HealthCheck {
470 /**
471 * A string array representing the command that the container runs to determine if it is healthy.
472 * The string array must start with CMD to execute the command arguments directly, or
473 * CMD-SHELL to run the command with the container's default shell.
474 *
475 * For example: [ "CMD-SHELL", "curl -f http://localhost/ || exit 1" ]
476 */
477 readonly command: string[];
478 /**
479 * The time period in seconds between each health check execution.
480 *
481 * You may specify between 5 and 300 seconds.
482 *
483 * @default Duration.seconds(30)
484 */
485 readonly interval?: cdk.Duration;
486 /**
487 * The number of times to retry a failed health check before the container is considered unhealthy.
488 *
489 * You may specify between 1 and 10 retries.
490 *
491 * @default 3
492 */
493 readonly retries?: number;
494 /**
495 * The optional grace period within which to provide containers time to bootstrap before
496 * failed health checks count towards the maximum number of retries.
497 *
498 * You may specify between 0 and 300 seconds.
499 *
500 * @default No start period
501 */
502 readonly startPeriod?: cdk.Duration;
503 /**
504 * The time period in seconds to wait for a health check to succeed before it is considered a failure.
505 *
506 * You may specify between 2 and 60 seconds.
507 *
508 * @default Duration.seconds(5)
509 */
510 readonly timeout?: cdk.Duration;
511}
512/**
513 * The ulimit settings to pass to the container.
514 *
515 * NOTE: Does not work for Windows containers.
516 */
517export interface Ulimit {
518 /**
519 * The type of the ulimit.
520 *
521 * For more information, see [UlimitName](https://docs.aws.amazon.com/cdk/api/latest/typescript/api/aws-ecs/ulimitname.html#aws_ecs_UlimitName).
522 */
523 readonly name: UlimitName;
524 /**
525 * The soft limit for the ulimit type.
526 */
527 readonly softLimit: number;
528 /**
529 * The hard limit for the ulimit type.
530 */
531 readonly hardLimit: number;
532}
533/**
534 * Type of resource to set a limit on
535 */
536export declare enum UlimitName {
537 CORE = "core",
538 CPU = "cpu",
539 DATA = "data",
540 FSIZE = "fsize",
541 LOCKS = "locks",
542 MEMLOCK = "memlock",
543 MSGQUEUE = "msgqueue",
544 NICE = "nice",
545 NOFILE = "nofile",
546 NPROC = "nproc",
547 RSS = "rss",
548 RTPRIO = "rtprio",
549 RTTIME = "rttime",
550 SIGPENDING = "sigpending",
551 STACK = "stack"
552}
553/**
554 * The details of a dependency on another container in the task definition.
555 *
556 * @see https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDependency.html
557 */
558export interface ContainerDependency {
559 /**
560 * The container to depend on.
561 */
562 readonly container: ContainerDefinition;
563 /**
564 * The state the container needs to be in to satisfy the dependency and proceed with startup.
565 * Valid values are ContainerDependencyCondition.START, ContainerDependencyCondition.COMPLETE,
566 * ContainerDependencyCondition.SUCCESS and ContainerDependencyCondition.HEALTHY.
567 *
568 * @default ContainerDependencyCondition.HEALTHY
569 */
570 readonly condition?: ContainerDependencyCondition;
571}
572export declare enum ContainerDependencyCondition {
573 /**
574 * This condition emulates the behavior of links and volumes today.
575 * It validates that a dependent container is started before permitting other containers to start.
576 */
577 START = "START",
578 /**
579 * This condition validates that a dependent container runs to completion (exits) before permitting other containers to start.
580 * This can be useful for nonessential containers that run a script and then exit.
581 */
582 COMPLETE = "COMPLETE",
583 /**
584 * This condition is the same as COMPLETE, but it also requires that the container exits with a zero status.
585 */
586 SUCCESS = "SUCCESS",
587 /**
588 * This condition validates that the dependent container passes its Docker health check before permitting other containers to start.
589 * This requires that the dependent container has health checks configured. This condition is confirmed only at task startup.
590 */
591 HEALTHY = "HEALTHY"
592}
593/**
594 * Port mappings allow containers to access ports on the host container instance to send or receive traffic.
595 */
596export interface PortMapping {
597 /**
598 * The port number on the container that is bound to the user-specified or automatically assigned host port.
599 *
600 * If you are using containers in a task with the awsvpc or host network mode, exposed ports should be specified using containerPort.
601 * If you are using containers in a task with the bridge network mode and you specify a container port and not a host port,
602 * your container automatically receives a host port in the ephemeral port range.
603 *
604 * For more information, see hostPort.
605 * Port mappings that are automatically assigned in this way do not count toward the 100 reserved ports limit of a container instance.
606 */
607 readonly containerPort: number;
608 /**
609 * The port number on the container instance to reserve for your container.
610 *
611 * If you are using containers in a task with the awsvpc or host network mode,
612 * the hostPort can either be left blank or set to the same value as the containerPort.
613 *
614 * If you are using containers in a task with the bridge network mode,
615 * you can specify a non-reserved host port for your container port mapping, or
616 * you can omit the hostPort (or set it to 0) while specifying a containerPort and
617 * your container automatically receives a port in the ephemeral port range for
618 * your container instance operating system and Docker version.
619 */
620 readonly hostPort?: number;
621 /**
622 * The protocol used for the port mapping. Valid values are Protocol.TCP and Protocol.UDP.
623 *
624 * @default TCP
625 */
626 readonly protocol?: Protocol;
627}
628/**
629 * Network protocol
630 */
631export declare enum Protocol {
632 /**
633 * TCP
634 */
635 TCP = "tcp",
636 /**
637 * UDP
638 */
639 UDP = "udp"
640}
641/**
642 * The temporary disk space mounted to the container.
643 */
644export interface ScratchSpace {
645 /**
646 * The path on the container to mount the scratch volume at.
647 */
648 readonly containerPath: string;
649 /**
650 * Specifies whether to give the container read-only access to the scratch volume.
651 *
652 * If this value is true, the container has read-only access to the scratch volume.
653 * If this value is false, then the container can write to the scratch volume.
654 */
655 readonly readOnly: boolean;
656 readonly sourcePath: string;
657 /**
658 * The name of the scratch volume to mount. Must be a volume name referenced in the name parameter of task definition volume.
659 */
660 readonly name: string;
661}
662/**
663 * The details of data volume mount points for a container.
664 */
665export interface MountPoint {
666 /**
667 * The path on the container to mount the host volume at.
668 */
669 readonly containerPath: string;
670 /**
671 * Specifies whether to give the container read-only access to the volume.
672 *
673 * If this value is true, the container has read-only access to the volume.
674 * If this value is false, then the container can write to the volume.
675 */
676 readonly readOnly: boolean;
677 /**
678 * The name of the volume to mount.
679 *
680 * Must be a volume name referenced in the name parameter of task definition volume.
681 */
682 readonly sourceVolume: string;
683}
684/**
685 * The details on a data volume from another container in the same task definition.
686 */
687export interface VolumeFrom {
688 /**
689 * The name of another container within the same task definition from which to mount volumes.
690 */
691 readonly sourceContainer: string;
692 /**
693 * Specifies whether the container has read-only access to the volume.
694 *
695 * If this value is true, the container has read-only access to the volume.
696 * If this value is false, then the container can write to the volume.
697 */
698 readonly readOnly: boolean;
699}
700/**
701 * Kernel parameters to set in the container
702 */
703export interface SystemControl {
704 /**
705 * The namespaced kernel parameter for which to set a value.
706 */
707 readonly namespace: string;
708 /**
709 * The value for the namespaced kernel parameter specified in namespace.
710 */
711 readonly value: string;
712}