clusters

Creates, updates, deletes or gets a cluster resource or lists clusters in a region

Overview

Name	`clusters`
Type	Resource
Description	The `AWS::ECS::Cluster` resource creates an Amazon Elastic Container Service (Amazon ECS) cluster.
Id	`awscc.ecs.clusters`

Fields

get (all properties)
list (identifiers only)

Name	Datatype	Description
▶`cluster_settings`	`array`	The settings to use when creating a cluster. This parameter is used to turn on CloudWatch Container Insights with enhanced observability or CloudWatch Container Insights for a cluster. Container Insights with enhanced observability provides all the Container Insights metrics, plus additional task and container metrics. This version supports enhanced observability for Amazon ECS clusters using the Amazon EC2 and Fargate launch types. After you configure Container Insights with enhanced observability on Amazon ECS, Container Insights auto-collects detailed infrastructure telemetry from the cluster level down to the container level in your environment and displays these critical performance data in curated dashboards removing the heavy lifting in observability set-up. For more information, see Monitor Amazon ECS containers using Container Insights with enhanced observability in the Amazon Elastic Container Service Developer Guide.
▶`default_capacity_provider_strategy`	`array`	The default capacity provider strategy for the cluster. When services or tasks are run in the cluster with no launch type or capacity provider strategy specified, the default capacity provider strategy is used.
▶`configuration`	`object`	The execute command and managed storage configuration for the cluster.
▶`service_connect_defaults`	`object`	Use this parameter to set a default Service Connect namespace. After you set a default Service Connect namespace, any new services with Service Connect turned on that are created in the cluster are added as client services in the namespace. This setting only applies to new services that set the `enabled` parameter to `true` in the `ServiceConnectConfiguration`. You can set the namespace of each service individually in the `ServiceConnectConfiguration` to override this default parameter. Tasks that run in a namespace can use short names to connect to services in the namespace. Tasks can connect to services across all of the clusters in the namespace. Tasks connect through a managed proxy container that collects logs and metrics for increased visibility. Only the tasks that Amazon ECS services create are supported with Service Connect. For more information, see Service Connect in the Amazon Elastic Container Service Developer Guide.
`capacity_providers`	`array`	The short name of one or more capacity providers to associate with the cluster. A capacity provider must be associated with a cluster before it can be included as part of the default capacity provider strategy of the cluster or used in a capacity provider strategy when calling the CreateService or RunTask actions. If specifying a capacity provider that uses an Auto Scaling group, the capacity provider must be created but not associated with another cluster. New Auto Scaling group capacity providers can be created with the CreateCapacityProvider API operation. To use a FARGATElong capacity provider, specify either the `FARGATE` or `FARGATE_SPOT` capacity providers. The FARGATElong capacity providers are available to all accounts and only need to be associated with a cluster to be used. The PutCapacityProvider API operation is used to update the list of available capacity providers for a cluster after the cluster is created.
`cluster_name`	`string`	A user-generated string that you use to identify your cluster. If you don't specify a name, CFNlong generates a unique physical ID for the name.
`arn`	`string`
▶`tags`	`array`	The metadata that you apply to the cluster to help you categorize and organize them. Each tag consists of a key and an optional value. You define both. The following basic restrictions apply to tags: + Maximum number of tags per resource - 50 + For each resource, each tag key must be unique, and each tag key can have only one value. + Maximum key length - 128 Unicode characters in UTF-8 + Maximum value length - 256 Unicode characters in UTF-8 + If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @. + Tag keys and values are case-sensitive. + Do not use `aws:`, `AWS:`, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for AWS use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
`region`	`string`	AWS region.

Name	Datatype	Description
`cluster_name`	`string`	A user-generated string that you use to identify your cluster. If you don't specify a name, CFNlong generates a unique physical ID for the name.
`region`	`string`	AWS region.

For more information, see AWS::ECS::Cluster.

Methods

Name	Resource	Accessible by	Required Params
`create_resource`	`clusters`	`INSERT`	`region`
`delete_resource`	`clusters`	`DELETE`	`Identifier, region`
`update_resource`	`clusters`	`UPDATE`	`Identifier, PatchDocument, region`
`list_resources`	`clusters_list_only`	`SELECT`	`region`
`get_resource`	`clusters`	`SELECT`	`Identifier, region`

`SELECT` examples

get (all properties)
list (identifiers only)

Gets all properties from an individual cluster.

SELECT
  region,
  cluster_settings,
  default_capacity_provider_strategy,
  configuration,
  service_connect_defaults,
  capacity_providers,
  cluster_name,
  arn,
  tags
FROM awscc.ecs.clusters
WHERE
  region = '{{ region }}' AND
  Identifier = '{{ cluster_name }}';

Lists all clusters in a region.

SELECT
  region,
  cluster_name
FROM awscc.ecs.clusters_list_only
WHERE
  region = '{{ region }}';

`INSERT` example

Use the following StackQL query and manifest file to create a new cluster resource, using stack-deploy.

Required Properties
All Properties
Manifest

/*+ create */
INSERT INTO awscc.ecs.clusters (
  ClusterSettings,
  DefaultCapacityProviderStrategy,
  Configuration,
  ServiceConnectDefaults,
  CapacityProviders,
  ClusterName,
  Tags,
  region
)
SELECT
  '{{ cluster_settings }}',
  '{{ default_capacity_provider_strategy }}',
  '{{ configuration }}',
  '{{ service_connect_defaults }}',
  '{{ capacity_providers }}',
  '{{ cluster_name }}',
  '{{ tags }}',
  '{{ region }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

/*+ create */
INSERT INTO awscc.ecs.clusters (
  ClusterSettings,
  DefaultCapacityProviderStrategy,
  Configuration,
  ServiceConnectDefaults,
  CapacityProviders,
  ClusterName,
  Tags,
  region
)
SELECT
  '{{ cluster_settings }}',
  '{{ default_capacity_provider_strategy }}',
  '{{ configuration }}',
  '{{ service_connect_defaults }}',
  '{{ capacity_providers }}',
  '{{ cluster_name }}',
  '{{ tags }}',
  '{{ region }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

version: 1
name: stack name
description: stack description
providers:
- aws
globals:
- name: region
  value: '{{ vars.AWS_REGION }}'
resources:
- name: cluster
  props:
    - name: cluster_settings
      value:
        - value: '{{ value }}'
          name: '{{ name }}'
    - name: default_capacity_provider_strategy
      value:
        - capacity_provider: '{{ capacity_provider }}'
          weight: '{{ weight }}'
          base: '{{ base }}'
    - name: configuration
      value:
        managed_storage_configuration:
          fargate_ephemeral_storage_kms_key_id: '{{ fargate_ephemeral_storage_kms_key_id }}'
          kms_key_id: '{{ kms_key_id }}'
        execute_command_configuration:
          logging: '{{ logging }}'
          kms_key_id: '{{ kms_key_id }}'
          log_configuration:
            s3_encryption_enabled: '{{ s3_encryption_enabled }}'
            cloud_watch_encryption_enabled: '{{ cloud_watch_encryption_enabled }}'
            cloud_watch_log_group_name: '{{ cloud_watch_log_group_name }}'
            s3_key_prefix: '{{ s3_key_prefix }}'
            s3_bucket_name: '{{ s3_bucket_name }}'
    - name: service_connect_defaults
      value:
        namespace: '{{ namespace }}'
    - name: capacity_providers
      value:
        - '{{ capacity_providers[0] }}'
    - name: cluster_name
      value: '{{ cluster_name }}'
    - name: tags
      value:
        - value: '{{ value }}'
          key: '{{ key }}'

`UPDATE` example

Use the following StackQL query and manifest file to update a cluster resource, using stack-deploy.

/*+ update */
UPDATE awscc.ecs.clusters
SET PatchDocument = string('{{ {
    "ClusterSettings": cluster_settings,
    "DefaultCapacityProviderStrategy": default_capacity_provider_strategy,
    "Configuration": configuration,
    "ServiceConnectDefaults": service_connect_defaults,
    "CapacityProviders": capacity_providers,
    "Tags": tags
} | generate_patch_document }}')
WHERE
  region = '{{ region }}' AND
  Identifier = '{{ cluster_name }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

`DELETE` example

/*+ delete */
DELETE FROM awscc.ecs.clusters
WHERE
  Identifier = '{{ cluster_name }}' AND
  region = '{{ region }}'
RETURNING
  ErrorCode,
  EventTime,
  Identifier,
  Operation,
  OperationStatus,
  RequestToken,
  ResourceModel,
  RetryAfter,
  StatusMessage,
  TypeName
;

Additional Parameters

Mutable resources in the Cloud Control provider support additional optional parameters which can be supplied with INSERT, UPDATE, or DELETE operations. These include:

Parameter	Description
`ClientToken`	A unique identifier to ensure the idempotency of the resource request. This allows the provider to accurately distinguish between retries and new requests. A client token is valid for 36 hours once used. After that, a resource request with the same client token is treated as a new request. If you do not specify a client token, one is generated for inclusion in the request.
`RoleArn`	The ARN of the IAM role used to perform this resource operation. The role specified must have the permissions required for this operation. If you do not specify a role, a temporary session is created using your AWS user credentials.
`TypeVersionId`	For private resource types, the type version to use in this resource operation. If you do not specify a resource version, the default version is used.

Permissions

To operate on the clusters resource, the following permissions are required:

Read
Create
Update
List
Delete

ecs:DescribeClusters,
kms:DescribeKey

ecs:CreateCluster,
ecs:DescribeClusters,
iam:CreateServiceLinkedRole,
ecs:TagResource,
kms:DescribeKey

ecs:PutAccountSettingDefault,
ecs:DescribeClusters,
ecs:TagResource,
ecs:UntagResource,
ecs:PutAccountSetting,
ecs:ListTagsForResource,
ecs:UpdateCluster,
ecs:UpdateClusterSettings,
ecs:PutClusterCapacityProviders,
kms:DescribeKey

ecs:DescribeClusters,
ecs:ListClusters

ecs:DeleteCluster,
ecs:DescribeClusters,
kms:DescribeKey

Overview​

Fields​

Methods​

SELECT examples​

INSERT example​

UPDATE example​

DELETE example​

Additional Parameters​

Permissions​