Attini configuration

The Attini Framework will look for a file in your distributions root directory called attini-config.json, attini-config.yml or attini-config.yaml. Only one of these files is allowed.

Note

This file is not required but its highly recommend to create one.

The attini-config should at the minimum contain a distributionName, so that Attini can separate between your different projects.

JSON

{
  "distributionName": "String",
  "distributionId": "String",
  "distributionTags": {
    "String": "String"
  },
  "initDeployConfig": {
    "template": "String",
    "stackName": "String",
    "forceUpdate": "Boolean",
    "variables": {
      "String": {
        "String": "String"
      }
    },
    "parameters": {
      "String": {
        "String": "String"
      }
    },
    "tags":{
      "String": "String"
    }
  },
  "package": {
    "container": {
      "image": "String",
      "loginCommands": [
        "String"
      ],
      "options": [
        "Sting"
      ]
    },
    "prePackage": {
      "commands": [
        "String"
      ]
    },
    "postPackage": {
      "commands": [
        "String"
      ]
    }
  }
}

YAML

distributionName: String
distributionId: String
distributionTags:
  String: String
initDeployConfig:
  template: String
  stackName: String
  forceUpdate: Boolean
  variables:
    String:
      String: String
  parameters:
    String:
      String: String
  tags:
    String: String
package:
  container:
    image: String
    loginCommands:
      - String
    options:
      - String
  prePackage:
    commands:
      - String
  postPackage:
    commands:
      - String

distributionName

Type: String

Minimum 2 and maximum 128 characters. Allowed characters: “a-z”, “A-Z”, “0-9” and “-_.”.

We recommend that the distributionName is the same as the Git repository to make it easy to understand. But this is not a requirement sometimes a distribution consist of a combination of many Git repository’s and/or external resources, and sometimes it makes sense to split a repository up into many different distributions.

Default: To the name of the distribution zip file.

Required: No

distributionId

Type: String

Minimum 2 and maximum 128 characters. Allowed characters: “a-z”, “A-Z”,”0-9” and “-_.”.

We recommend automatically setting the distributionId using the package section in the attini-config (see example below). This will make it easy for you to use the same package logic on your local computer as you use on your build server. The Git commit id is a good value for the distributionId because it will be easy to see what code runs in your environments. It can also be a good idea to append a timestamp to the id so that you can re-build the same commit if needed.

If you need to mock anything for your local builds (like an environment variable), see the --environment-config-script flag in the attini package command.

Default: A random GUID.

Required: No

distributionTags

Type: Map<String,String>

Metadata that is relevant to your organization or distribution, some normal use-cases include:

  • Keep track of Git branch that was the source of the distribution

  • Add additional version information like semantic version, Git commit id etc

  • Build time

  • Build agent/build container

  • If your distribution consists of a combination of Git repository’s, this is an excellent place to store the Git commit of those repository’s

See limitations

Required: No

initDeployConfig

Type: initDeployConfig

Configuration for the Init deploy.

Within this object, you can use distributionName and environment as sub-string parameters, see examples below.

Required: No


initDeployConfig

initDeployConfig template

Type: String

The path to the init deploy template.

Required: No

initDeployConfig stackName

Type: String

Init deploy stack name.

Required: No

initDeployConfig forceUpdate

Type: Boolean

If true then the init-stack will always update, even if there is no change.

Required: No

Default: false

initDeployConfig variables

Type: Map<String,Map<String,String>>

Global variables for the init deploy stack. Will be passed as variables to every AttiniCfn step in the deployment plan. The key should be an environment name or “default”.

Anything under “default” will be used only if the variable is not configured for the environment.

How are variables different from parameters?

variables only work within the context of AttiniCfn and its associated configuration files. If you specify Variables with the same keys in a AttiniCfn step, it will override variables in the attini-config.

parameters are normal AWS CloudFormation parameters to the init deploy stack.

See examples here examples with variables

Required: No

initDeployConfig parameters

Type: Map<String,Map<String,String>>

Parameters for the init deploy stack, the key should be an environment name or “default”.

Anything under “default” will be used only if the parameter is not configured for the environment.

Required: No

initDeployConfig tags

Type: Map<String,String>

Init deploy stack tags.

Required: No


Pseudo variables in initDeployConfig

Within initDeployConfig in your attini-config file there are a few variables that are always available.

environment

Will always transform to the current environment name.

Usage: ${environment}

distributionName

Will always convert to the current distributionName name.

Usage: ${distributionName}

package

Under the package section, you can list any shell commands you want to execute when packaging a distribution using the attini package command. The attini deploy run command will also perform a package assuming the path supplied points is to a directory.

The Attini CLI will create a temp working directory when packaging a distribution. Therefore you can manipulate any resources without it affecting the original files.

The path to the temp directory will be stored in the ATTINI_WORK_DIR environment variable during the execution of package commands.

prePackage commands

Type: List<String>

List of shell commands that is executed before the final distribution is created.

Useful if you for example want to configure the distribution (see attini configure command) or fetch external resources to be included in the distribution.

Required: No

postPackage commands

Type: List<String>

List of shell commands that is executed before the final distribution is created but before the final distribution is copied from the temp working directory.

Useful if you for example want to move the distribution somewhere after the packaging is done.

Required: No

container loginCommands

Type: List<String>`

List of shell commands that will be executed before the docker run command when using container builds.

Should only be used to log in to the image repository if the image need to be downloaded as they are executed before the container is started.

Required: No

container image

Type: String

An image to use for packaging your distribution in a container.

Useful if you for example want to build your distribution locally inside a container that mimics your build server.

Required: No

container options

Type: List<String>

Command-line options you want to add the docker run command the Attini CLI generates and run for you.

Useful if you need to configure anything specific for your build container, for example, if you need to transfer AWS credentials to the container (-v $HOME/.aws:/root/.aws:ro).

Required: No

Examples

Configuration examples

JSON

{
  "distributionName": "network",
  "distributionId": "3957876a98566823744050eef132c133536ea32b",
  "distributionTags": {
    "Version": "1.1.2",
    "Branch": "feature/add-nlb"
  }
}

{
  "distributionName": "platform",
  "distributionId": "67e13cb77e9139929057602a46229cf0162c8747",
  "distributionTags": {
    "version": "1.1.2",
    "branch": "hotfix/bugfix"
  },
  "initDeployConfig": {
    "template": "pipeline.yaml",
    "stackName": "${environment}-${distributionName}-init-deploy",
    "variables": {
      "default": {
        "configPath": "/my/default/config.json"
      },
      "dev": {
        "configPath": "/my/dev/config.json"
      }
    },
    "parameters": {
      "default": {
        "containerTag": "latest"
      },
      "dev": {
        "containerTag": "1.0.11"
      }
    },
    "tags": {
      "dev": {
        "costCenter": "Development"
      },
      "prod": {
        "costCenter": "Sales"
      }
    }
  },
  "package": {
    "container": {
        "image": "123424324422.dkr.ecr.eu-west-1.amazonaws.com/my-build-images:latest",
        "loginCommands": [
          "export AWS_PROFILE=Shared",
          "aws ecr get-login-password --region eu-west-1 | docker login --username AWS --password-stdin 123424324422.dkr.ecr.eu-west-1.amazonaws.com"
        ],
        "options": [
          "-v $HOME/.aws:/root/.aws:ro"
        ]
    },
    "prePackage": {
      "commands": [
        "echo $ATTINI_WORK_DIR",
        "export AWS_PROFILE=MyProfile",
        "attini configure set-dist-id --override --random",
        "attini configure set-tag --key version --value echo `1.0.2`"
      ]
    },
    "postPackage": {
      "commands": [
        "echo \"done with package\""
      ]
    }
  }
}

YAML

distributionName: network
distributionId: 3957876a98566823744050eef132c133536ea32b
distributionTags:
  version: 1.1.2
  branch: feature/add-nlb

distributionName: platform
distributionId: 67e13cb77e9139929057602a46229cf0162c8747
distributionTags:
  version: 1.1.2
  branch: hotfix/bugfix
initDeployConfig:
  template: pipeline.yaml
  stackName: "${environment}-${distributionName}-init-deploy"
  variables:
    default:
      configPath: /my/default/config.json
    dev:
      configPath: /my/dev/config.json
  parameters:
    default:
      containerTag: latest
    dev:
      containerTag: 1.0.11
  tags:
    dev:
      costCenter: Development
    prod:
      costCenter: Sales
  package:
    container:
      image: 123424324422.dkr.ecr.eu-west-1.amazonaws.com/my-build-images:latest
      loginCommands:
        - export AWS_PROFILE=Shared
        - aws ecr get-login-password --region eu-west-1 | docker login --username AWS --password-stdin 123424324422.dkr.ecr.eu-west-1.amazonaws.com
      options: # Here you can options for the docker run command.
        - -v $HOME/.aws:/root/.aws:ro # this command will transfer your current aws credentials to the container (if the container uses the root user).
    prePackage:
      commands:
        - echo $ATTINI_WORK_DIR
        - export AWS_PROFILE=MyProfile
        - attini configure set-dist-id --override --random
        - attini configure set-tag --key version --value echo `1.0.2`

    postPackage:
      commands:
        - echo "done with package"

Examples with variables

If I have configured my variables in the attini-config like the example below.

initDeployConfig:
  variables:
    default:
      myConfigDirectory: defaultConfigDirectory
      stackNamePrefix: sandbox
    dev:
      myConfigDirectory: devConfigDirectory
      stackNamePrefix: dev

The following will resolve to a valid AttiniCfn configuration file.

extends: ${myConfigDirectory}/file.yaml
parameters:
  ParameterKey: ParameterValue
tags:
  Key: Value

The following will also be a valid AttiniCfn step.

StepName:
  Type: AttiniCfn
  Properties:
    StackName: ${stackNamePrefix}-hello-world-lambda
    Template: /lambda.yaml

If you want to combine AWS CloudFormation Fn::Sub with Attini variables, the following syntax will work.

StepName:
  Type: AttiniCfn
  Properties:
    StackName:
      Fn::Sub:
        - ${AttiniVariable}-${CloudFormationParameter}-hello-world-lambda
        - AttiniVariable: ${stackNamePrefix}
          CloudFormationParameter: !Ref Parameter # this assumes that there is a CloudFormation Parameter called "Parameter"
    Template: /lambda.yaml