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 it’s highly recommended to create one.
The attini-config
should at the minimum, contain a distributionName
, so that Attini can separate your different projects.
JSON
{
"distributionName": "String",
"distributionId": "String",
"version": "String",
"distributionTags": {
"String": "String"
},
"dependencies" : [
{
"distributionName" : "String",
"version" : "String"
}
],
"initDeployConfig": {
"template": "String",
"stackName": "String",
"forceUpdate": "Boolean",
"tags":{
"String": "String"
},
"variables": {
"String": {
"String": "String"
}
},
"parameters": {
"String": {
"String": "String"
}
}
},
"package": {
"container": {
"image": "String",
"loginCommands": [
"String"
],
"options": [
"Sting"
]
},
"prePackage": {
"commands": [
"String"
]
},
"postPackage": {
"commands": [
"String"
]
}
}
}
YAML
distributionName: String
distributionId: String
version: String
distributionTags:
String: String
dependencies:
- distributionName: String
version: String
initDeployConfig:
template: String
stackName: String
forceUpdate: Boolean
tags:
String: String
variables:
String:
String: String
parameters:
String:
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 “-_.”.
If you don’t have a good name in mind, using your Git repository name is a good place to start. But this is not a requirement, sometimes a distribution consists 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 distribution package
command.Default: A random GUID.
Required: No
- version
Type:
String
A semantic version for your distribution.
The version is intended to be a human-readable and sequential value to identify your distribution. It’s different from the
distributionId
whose primary purpose is to be a unique identifier.It’s recommended to configure the version for distributions that are intended for production. See the
--distribution-version
,-v
flags in theattini distribution package
command.Required: No
- dependencies
Type: List<dependency>
A list of distributions that this distribution is dependent on. Attini will validate that the dependency is present in the environment. Attini will also include a URL to the dependencies output in the deployment plan payload (assuming it contains one).
Required: No
- initDeployConfig
Type: initDeployConfig
Configuration for the Init deploy.
Within this object, you can use
distributionName
andenvironment
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 tags
Type:
Map<String,String>
Init deploy stack tags.
Required: No
- 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 current 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>> | Map<String,Map<String,Import>>
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 current environment.
Under each environment, you can configure a key-value map, where the key is the parameters name.
If your distribution has a dependency on another distribution, then you can import values directly from its output.
Example
initDeployConfig: parameters: default: lambdaRam: 512 vpcId: sourceType: Distribution source: name: network mapping: $.vpc.vpcId dev: lambdaRam: 1028 prod: lambdaRam: 1540
Required: No
- initDeployConfig parameters import
Used when a init deploy stack needs configuration from another distribution.
- sourceType
Type:
String
Only supported value is
Distribution
Required: Yes
- source name
Type:
String
The distribution name that you want to import the value from.
Required: Yes
- source mapping
Type:
String
The path to the value you want to import. The path follows the JSONPath syntax.
Hint: Run command
attini deploy output
with the Attini CLI to see a distributions output.Required: Yes
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 distribution 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:rw
).Required: No
dependency¶
- dependency distributionName
Type:
String
A name of a distribution the current distribution is dependent on.
Required: Yes
- dependency version
Type:
String
The version of the dependency. Specified using the same rules as NPM.
This can be used to make sure that all dependencies have the correct versions.
Required: No
Examples¶
Configuration examples¶
JSON
{
"distributionName": "network",
"distributionId": "3957876a98566823744050eef132c133536ea32b",
"distributionTags": {
"Version": "1.1.2",
"Branch": "feature/add-nlb"
}
}
{
"distributionName": "platform",
"distributionId": "67e13cb77e9139929057602a46229cf0162c8747",
"version": "1.0.1",
"distributionTags": {
"owner": "carl",
"branch": "hotfix/bugfix"
},
"dependencies" : [
{
"distributionName" : "String",
"version" : "String"
}
],
"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:rw"
]
},
"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:
branch: feature/add-nlb
distributionName: platform
distributionId: 67e13cb77e9139929057602a46229cf0162c8747
version: 1.0.1
distributionTags:
owner: carl
branch: hotfix/bugfix
dependencies:
- distributionName: infra
version: ">1.0.0"
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 add options for the docker run command.
- -v $HOME/.aws:/root/.aws:rw # this command will copy your local aws credentials to the container (if the container runs as root).
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