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 thepackage
section in theattini-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 thedistributionId
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 theid
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 theattini package
command.Default: A random GUID.
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 overridevariables
in theattini-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