.. meta:: :description: ECS Compose-X AWS S3 syntax reference :keywords: AWS, AWS ECS, Docker, Compose, docker-compose, AWS S3, S3 Buckets .. attention:: For production workloads, we recommend to create the buckets separately for any bucket that stores critical data. See :ref:`lookup_syntax_reference` to use existing buckets. .. _s3_syntax_reference: ===================== x-s3 ===================== .. code-block:: yaml x-s3: bucket: Properties: {} MacroParameters: {} Lookup: {} Settings: {} Services: {} Define or use existing S3 buckets to use with your services or other AWS Resources (where applicable). .. hint:: When the bucket uses encryption, ECS Compose-X will automatically identify the KMS key and if applicable, grant the necessary permissions to the service role. The KMS predefined **EncryptDecrypt** policy will be used to that effect. Services ======== Model -------- .. code-block:: yaml Services: service01: Access: bucket: <> objects: <> ReturnValues: {} As for all other resource types, you can define the type of access you want based to the S3 buckets. However, for buckets, this means distinguish the bucket and the objects resource. .. code-block:: yaml :caption: Short example x-s3: bucketA: Properties: {} Settings: {} Services: service-01: Access: objects: RW bucket: ListOnly services: service-01: {} IAM Permissions ---------------- For S3 buckets, the access types is expecting a object with **objects** and **bucket** to distinguish permissions for each. If you indicate a string, the default permissions (bucket: ListOnly and objects: RW) will be applied. .. literalinclude:: ../../../ecs_composex/s3/s3_perms.json :caption: Full access types policies definitions :language: json ReturnValues -------------- For full details, see `AWS S3 Return Values`_ for available options. The return value **BucketName** can be used to return the value of the **Ref** Function. .. warning:: If you return values that rely on features you have not enabled, i.e. **WebsiteURL**, the stack creation / update will fail. Properties =========== For the properties, go to to `AWS CFN S3 Definition`_ We highly encourage not to set the bucket name there. If you did, we recommend to use the `ExpandRegionToBucket`_ and `ExpandAccountIdToBucket`_ to make the bucket unique. MacroParameters ================= Some use-cases require special adjustments. This is what this section is for. * `NameSeparator`_ * `ExpandRegionToBucket`_ * `ExpandAccountIdToBucket`_ NameSeparator -------------- Default is **-** which separates the different parts of the bucket that you might have automatically added via the other MacroParameters As shown below, the separator between the bucket name and AWS::AccountId or AWS::Region is **-**. This parameter allows you to define something else. .. note:: I would recommend not more than 2 characters separator. .. warning:: The separator must allow for DNS compliance **[a-z0-9.-]** ExpandRegionToBucket --------------------- When definining the `BucketName` in properties, if wanted to, for uniqueness or readability, you can append to that string the region id (which is DNS compliant) to the bucket name. .. code-block:: yaml Properties: BucketName: abcd-01 Settings: ExpandRegionToBucket: True Results into .. code-block:: yaml !Sub abcd-01-${AWS::Region} ExpandAccountIdToBucket ------------------------ Similar to ExpandRegionToBucket, it will append the account ID (additional or instead of). .. code-block:: yaml Properties: BucketName: abcd-01 Settings: ExpandRegionToBucket: True Results into .. code-block:: yaml !Sub 'abcd-01-${AWS::AccountId}' .. hint:: If you set both ExpandAccountIdToBucket and ExpandRegionToBucket, you end up with .. code-block:: yaml !Sub 'abcd-01-${AWS::Region}-${AWS::AccountId}' Lookup ======= Refer to :ref:`lookup_syntax_reference` for the full details. .. code-block:: yaml x-s3: existing-bucket: Lookup: Tags: - name: my-first-bucket - environment: dev Examples ========= .. literalinclude:: ../../../use-cases/s3/simple_s3_bucket.yml :language: yaml :caption: Create new S3 buckets .. literalinclude:: ../../../use-cases/s3/lookup_only.yml :language: yaml :caption: Lookup and use only existing buckets .. literalinclude:: ../../../use-cases/s3/full_s3_bucket_properties.yml :language: yaml :caption: Create new bucket with AWS CFN properties JSON Schema ============ Model ---------------- .. jsonschema:: ../../../ecs_composex/s3/x-s3.spec.json Definition ------------ .. literalinclude:: ../../../ecs_composex/s3/x-s3.spec.json :language: json Test files =========== You can find the test files `here `__ to use as reference for your use-case. .. _AWS CFN S3 Definition: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket.html .. _AWS S3 Return Values: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket.html#aws-properties-s3-bucket-return-values