.. _api-reference_cloudformation-configuration: CloudFormation configuration ============================ Within the Attini Framework, you have 2 options to configure your CloudFormation stacks, `Inline Configuration` and `Configuration Files`. The Attini Framework also automatically populates some CloudFormation parameters. See more at: :ref:`Framework Parameters `. --------------------------------------------------------------------------------------------------- .. _api-reference_cloudformation-inline-configuration: Inline configuration --------------------------------- Inline configuration is configured in the :ref:`AttiniCfn Properties ` section. This configuration has the highest priority and will override the configuration set in the `Configuration File`. .. role:: mini-header :mini-header:`Example` .. code-block:: YAML Type: AttiniCfn Properties: Template: /path/to/my/template.yaml StackName: my-stack ConfigFile: /path/to/my/config.json Parameters: MyParameter: MyValue MyDbURL: dscsdcscsd.ndckjsndc.us-east-1.rds.amazonaws.com RoleArn: arn:aws:iam:my:role:arn --------------------------------------------------------------------------------------------------- .. _api-reference_cloudformation-configuration_file: Configuration file ------------------ A configuration file is in ``JSON`` or ``YAML`` format, containing configuration for a CloudFormation stack. :mini-header:`JSON` .. code-block:: JSON { "extends": "String", "stackName": "String", "templatePath": "String", "region": "String", "executionRole": "String", "stackRoleArn": "String", "outputPath": "String", "action": "String", "parameters": { "ParameterKey": "ParameterValue" }, "tags": { "Key": "Value" } } :mini-header:`YAML` .. code-block:: YAML extends: String stackName: String templatePath: String region: String executionRole: String stackRoleArn: String outputPath: String action: String parameters: ParameterKey: ParameterValue tags: Key: Value Please see :ref:`AttiniCfn ` for property-specific documentation. --------------------------------------------------------------------------------------------------- .. _api-reference_cloudformation-configuration-inheritance: Configuration inheritance ########################## The ``extends`` property allows you to build an inheritance hierarchy for your configuration, similar to how inheritance works in most object-oriented programming languages. The ``extends`` property should contain a path to another configuration file in the distribution (the path should be specified as an absolute path from the distribution root). Attini will merge any configuration in that file into your current configuration. The configuration file that is referenced under ``extends`` will have a lower priority than the current configuration file. :mini-header:`Priority hierarchy:` 1. :ref:`Inline configuration ` have the highest priority 2. A configuration file will always have a higher priority than the file it ``extends``. .. role:: mini-header :mini-header:`Example` These files could be used to configure a CloudFormation template containing an AWS::Lambda::Function. **JSON** `/config/default.json` .. code-block:: JSON { "parameters": { "Runtime": "python3.7", "MemorySize": "256" } } `/config/app.json` .. code-block:: JSON { "extends": "/config/default.json", "parameters": { "MemorySize": "512" }, "tags": { "Version": "1.0.0" } } The final configuration will now look like this: .. code-block:: JSON { "parameters": { "Runtime": "python3.7", "MemorySize": "512" }, "tags": { "Version": "1.0.0" } } **YAML** `/config/default.yaml` .. code-block:: YAML parameters: Runtime: python3.7 MemorySize: 256 `/config/app.yaml` .. code-block:: YAML extends: "/config/default.yaml" parameters: MemorySize: 512 tags: Version: 1.0.0 The final configuration will now look like this: .. code-block:: YAML parameters: Runtime: python3.7 MemorySize: 512 tags: Version: 1.0.0 --------------------------------------------------------------------------------------------------- .. _api-reference_cloudformation-configuration-parameter-value: Parameters and tags -------------------- Your stack's parameters and tags can be specified as a ``String``, ``Integer``, ``Boolean`` or an ``Object``. If it's a ``String``, ``Integer`` or a ``Boolean``, it will directly be applied as a CloudFormation parameter or tag. Attini also allows an ``Object`` structure if you want to use Attinis configuration features, like `fallback properties` or `SSM parameter configuration`. .. note:: The object structure (`fallback properties` or `SSM parameter configuration`) is only supported in :ref:`configuration files ` and can not be used in :ref:`inline configuration `. --------------------------------------------------------------------------------------------------- .. _api-reference_cloudformation-configuration-parameter-value_fallback: Fallback properties #################### **JSON** .. code-block:: JSON { "ParameterKey": { "fallback" : "boolean", "value": "string" } } **YAML** .. code-block:: YAML ParameterKey: fallback: boolean value: string When fallback is **true**, the **current** configuration will always be honored by the Attini Framework. This means that the value will only have relevance when a parameter is set for the first time, either when creating the stack, or adding a new parameter to an existing stack. This is useful if you have people in your organization that should be able to update some parameters straight in the console or via the AWS CLI. For example, if you have a DBA that should be able to update the "AllocatedStorage" parameter on a stack containing an RDS instance manually but the rest of the configuration should be managed by the Attini Framework, the config file could look like this: **JSON** .. code-block:: JSON { "parameters": { "Engine": "postgres", "AllocatedStorage": { "fallback" : true, "value": "500" } } } **YAML** .. code-block:: YAML parameters: Engine: postgres AllocatedStorage: fallback: true value: 500 --------------------------------------------------------------------------------------------------- .. _api-reference_cloudformation-configuration-parameter-ssm: SSM Parameters ############### Attini supports reading from AWS SSM Parameter Store. In this case, the ``value`` should be set to the SSM parameters name. An optional default can be specified if the SSM Parameter does not exist. :mini-header:`Example` **JSON** .. code-block:: JSON { "parameters": { "someParameter": { "value": "/my/ssm/parameter/name", "type": "ssm-parameter", "default": "some-default-value" } } } **YAML** .. code-block:: YAML parameters: someParameter: value: /my/ssm/parameter/name type: ssm-parameter default: some-default-value SSM parameters can also be used as a :ref:`fallback property `. :mini-header:`Example` **JSON** .. code-block:: JSON { "parameters": { "someParameter": { "value": "/my/ssm/parameter/name", "type": "ssm-parameter", "default": "some-default-value", "fallback": true } } } **YAML** .. code-block:: YAML parameters: someParameter: value: /my/ssm/parameter/name type: ssm-parameter default: some-default-value fallback: true --------------------------------------------------------------------------------------------------- .. _api-reference_cloudformation-configuration-framework-parameters: Framework parameters -------------------- Attini will automatically populate some parameters if you specify them in your CloudFormation template. These parameters are: * AttiniEnvironmentName (Can be configured in the attini-setup) * AttiniDistributionName * AttiniDistributionId * AttiniRandomString .. glossary:: AttiniEnvironmentName Your current environment. This name can be "Re-mapped" by configuring the "EnvironmentParameterName" parameter in the `attini-setup `_ AttiniDistributionName The name of the deployment plans distribution. AttiniDistributionId The distributionId of the deployment plans distribution. AttiniRandomString A random `UUID `_ This can be useful to trigger CloudFormation custom resources. :mini-header:`Example` The Attini Framework will automatically configure the parameters in this stack: .. code-block:: YAML AWSTemplateFormatVersion: "2010-09-09" Parameters: AttiniEnvironmentName: Type: String AttiniDistributionName: Type: String AttiniDistributionId: Type: String AttiniRandomString: Type: String Resources: ...