.. meta::
    :description: ECS Compose-X docker-compose secrets syntax support
    :keywords: AWS, AWS ECS, Docker, Compose, docker-compose, ecs-composex, secrets


.. _secrets_syntax_reference:

========
secrets
========

.. code-block::

    secrets:
      my-docker-compose-secret:
        x-secrets:
          Name: str
          VarName: str
          LinksTo: []
          JsonKeys: []
          Lookup: {}


With docker-compose, you can define secrets to use for the application.

To help continue with docker-compose syntax compatibility, you can now declare your secret in docker-compose,
and add an extension field which will be a direct mapping to the secret name you have in AWS Secrets Manager.

ECS ComposeX will automatically add IAM permissions to **the execution** role of your Task definition and will export the secret
to your container, using the same name as in the compose file.

.. seealso::

    `docker-compose secrets reference`_

.. hint::

    For security purposes, the containers **envoy** / **CloudWatch** / **xray-daemon** are not getting
    assigned the secrets when part of the same service family.

Name
----

Type: String

The name of the secret in secrets manager to use and import.

.. hint::

    If you want to put the full ARN, you can. There will be a validation for it.

VarName
---------

Allows to override the environment variable name for the secret ARN that woult otherwise be auto-generated by compose-x.

.. code-block:: yaml

    secrets:
      my-secret: # Results into MY_SECRET
        x-secrets:
          Name: /path/to/my-secret

      another-secret:
        x-secret:
          Name: /path/to/another
          VarName: MY_OTHER_SECRET


LinksTo
-------

Type: List of Strings

AllowedValues (also default):

* EcsExecutionRole
* EcsTaskRole


.. code-block:: yaml

        secret-name:
          x-secrets:
            Name: String
            LinksTo:
              - EcsExecutionRole
              - EcsTaskRole

.. warning::

    If you do not specify **EcsExecutionRole** when specifying **LinksTo** then you will not get the secret exposed
    to your container via AWS ECS Secrets property of your Container Definition

JsonKeys
--------

Type: List of objects/dicts

.. note::

    Only Fargate 1.4.0+ Platform Version supports secrets JSON Key

.. code-block:: yaml
    :caption: JsonKeys objects structure

    SecretKey: str
    VarName: str
    Transform: str

SecretKey
""""""""""""

Name of the JSON Key in your secret.

VarName
""""""""

The Name of the secret specifically for the secret JSON key

Transform
""""""""""

When you want to transform the original secret key into something else, here are simple transforms.

java_properties
++++++++++++++++

Take a string and replaces all letters to their uppercase version and replaces **.** with **_**

title
++++++

Set to uppercase the first letter of every word. **some.properties** becomes **Some.Properties**

capitalize
+++++++++++

Changes all letters from lower case to uppercase but does not change anything else.


Examples
========

.. code-block:: yaml
    :caption: Short example

    secrets:
      topsecret_info:
        x-secrets:
          Name: /path/to/my/secret

    services:
      serviceA:
        secrets:
          - topsecret_info

.. code-block:: yaml
    :caption: Secret with assignment to Task and Execution Role

    secrets:
      abcd: {}
      john:
        x-secrets:
          LinksTo:
            - EcsExecutionRole
            - EcsTaskRole
          Name: SFTP/asl-cscs-files-dev


.. code-block:: yaml
    :caption: Secret Looked up from Tags and Name, also using JsonKeys

    secrets:
      zyx:
        x-secrets:
          Name: secret/with/kmskey
          Lookup:
            Tags:
              - costcentre: lambda
              - composexdev: "yes"
          JsonKeys:
            - SecretKey: username
              VarName: PSQL_USERNAME
            - SecretKey: password
              VarName: PSQL_PASSWORD


.. code-block:: yaml
    :caption: Secret with assignment to Task and Execution Role

    secrets:
      abcd: {}
      john:
        x-secrets:
          LinksTo:
            - EcsExecutionRole
            - EcsTaskRole
          Name: arn:aws:secretsmanager:eu-west-1:123456789012:secret:/secret/abcd

JSON Schema
============

Model
-------

.. jsonschema:: ../../../ecs_composex/specs/secrets.x-secrets.spec.json


Definition
-----------

.. literalinclude:: ../../../ecs_composex/specs/secrets.x-secrets.spec.json

.. _docker-compose secrets reference: https://docs.docker.com/compose/compose-file/#secrets