Deployment plan types¶
The deployment plan is built on AWS StepFunction and follows the format of AWS State Language. That means that any State Types supported by StepFunction are also supported in the deployment plan. However, Attini also supports some additional types in order to better support a deployment workflow.
AttiniCfn¶
Type: AttiniCfn
Properties:
Template: String
StackName: String
ConfigFile: String
Parameters: Map<String,String>
Tags: Map<String,String>
StackRoleArn: String
ExecutionRoleArn: String
Region: String
OutputPath: String
Variables: Map<String,String>
Action: String
EnableTerminationProtection: Boolean
AttiniCfn will create, update or delete a CloudFormation stack.
See more information about the configuration options here.
Note
If the stack is in the state “ROLLBACK_COMPLETE” and you run the deployment plan, the stack will be deleted and recreated. The “ROLLBACK_COMPLETE” state only occurs after a failed creation, and the rollback has deleted all the resources in the stack.
- Template
Type:
String
The path to the CloudFormation template. Can either be:
A path to a file in the distribution. The path should be from the root of the project and start with a “/”.
A URL to a public S3 file, starting with “https://”.
An S3 path, starting with “s3://”.
Required: Conditional | Required unless it’s configured in the ConfigFile.
Default: None
- StackName
Type:
String
AWS API compatibility: This property is passed directly to the StackName property of the CreateStack or UpdateStack API call.
Required: Conditional | Required unless it’s configured in the ConfigFile.
Default: None
- ConfigFile
Type:
String
This is a reference to a
JSON
or aYAML
file in the distribution. The reference has to start with a “/”, ex “/path/to/my/parameters.json”Note
Public HTTPS endpoints, ex
https://path/to/my/parameters.json
does not work for configuration files.Find more info in the CloudFormation configuration documentation
Required: No
Default: None
- Parameters
Type:
Map<String, String>
The CloudFormation parameters, find more info in the CloudFormation configuration documentation.
Required: No
Default: None
- StackRoleArn
Type:
String
Arn of the StackRole, find more info here: AWS CloudFormation service role
Note
This IAM Role has to be in the same AWS Account that the CloudFormation stack is deployed in, so if “ExecutionRoleArn” is in a different AWS Account this “StackRoleArn” has to be in the same account as the “ExecutionRoleArn”. If the “StackRoleArn” is in a different AWS Account then the “ExecutionRoleArn” you will receive a “Cross-account pass role is not allowed.” error.
Find more information about the security aspects of StackRoles here.
Required: Conditional
If the parameter “UseAdministratorAccessForDeployingCloudformation” in attini-setup CloudFormation stack is false, this parameter or ExecutionRoleArn is required.
Default: None
- ExecutionRoleArn
Type:
String
The role that you want to be assumed when the Attini Framework deploys the CloudFormation stack. This can be useful if you are:
Applying least privilege policies without using Stack roles
The ExecutionRole has to trust the default role
arn:aws:iam::{AccountId}:role/attini/attini-action-role-{Region}
so that it can be assumed.Example trust relationship policy:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111111111111:role/attini/attini-action-role-eu-west-1" ] }, "Action": "sts:AssumeRole" } ] }
Note
If you configure an execution role in another account or region the Attini Framework will use a polling pattern to verify the state of the stack, this makes the deployment plan execution slower and it can lead to throttling issues if it’s used a lot.
Find more information about the security aspects of ExecutionRoles here.
Required: No
Default: arn:aws:iam::{AccountId}:role/attini/attini-action-role-{Region}
- Region
Type:
String
Configure the region you want the CloudFormation stack in.
Note
If you configure a Region other than the current region the Attini Framework will use a polling pattern to verify the state of the stack. This makes the deployment plan execution slower, and it can lead to throttling issues if it’s used a lot.
Required: No
Default: Current region
- OutputPath
Type:
String
If you need an extra level of separation for your output, you can use
OutputPath
. This is useful if you need to have multiple output sections from one step, example when you use AttiniMap type.If you for example have a State name
buzz
and anOutputPath: foo
the output payload will look like this:{ "output": { "buzz": { "foo": { "OutputKey": "OutputValue" } } } }
Required: No
Default: None
- Variables
Type:
Map<String,String>
If your step has a
ConfigFile
configured, you can useVariables
to pass values from your deployment plan payload into the file.If you for example have an AttiniCfn State with the following config:
StateName: Type: AttiniCfn Properties: Template: /ecs-service.yaml ConfigFile: /ecs-config.yaml Variables: Environment: !Ref AttiniEnvironmentName DatabasePort.$: $.output.Database.Port StackRoleArn.$: $.output.StackRoles.EcsStackRole StackName: ecs-service
Your
ConfigFile
can look like this:stackRoleArn: ${StackRoleArn} parameters: ServiceName: ${Environment}-my-ecs-service DatabasePort: ${DatabasePort}
Note
By using Variables you can replace or manipulate any AttiniCfn configuration except for the
ConfigFile
path.Required: No
Default: None
- Action
Type:
String
Specify if the stack should be created/updated or deleted.
Allowed values: Deploy | Delete
Required: No
Default: Deploy
- EnableTerminationProtection
Type:
Boolean
Specify if termination protection should be enabled for the stack.
Note
When first creating a stack this is an atomic operation. However when updating an existing stack the termination protection will be updated before the rest of the stack. This means that if the stack update fails and a rollback is performed the termination protection will not be rolled back with the rest of the updates.
Required: No
Default: false
AttiniSam¶
To simplify the use of the AWS Serverless Application Model (SAM) Attini will automatically build and package your SAM Applications if they are defined in the deployment plan using this (AttiniSam) type.
Attini will package the SAM App and use AttiniCfn to deploy it, meaning that most configurations will work the same way.
For more information on how Attini manages SAM Apps, see Attini and AWS SAM.
Type: AttiniSam
Properties:
Project:
Path: String
Template: String
BuildDir: String
StackName: String
ConfigFile: String
Parameters: Map<String,String>
Tags: Map<String,String>
StackRoleArn: String
ExecutionRoleArn: String
Variables: Map<String,String>
Action: String
EnableTerminationProtection: Boolean
Note
Region from AttiniCfn is not supported because CloudFormation requires Lambda code to be stored in the same region as its being deployed to. The Attini Framework will package the SAM Application into an S3 Bucket in your current region only.
Attini does not support packaging AWS Lambda function with container images.
- Project
Type:
SamProject
Required: Yes
- Path
Type:
String
The path in your Attini project in which you keep the SAM App.
the reference has to start with a
/
, ex/sam-apps/my-public-api
Required: Yes
Default: None
- BuildDir
Type:
String
The path to a directory where the built artifacts are stored. This directory and all of its content are removed with this option.
See
-b
and ``–build-dir``options in AWS SAM CLI build documentation.Required: No
Default: .aws-sam/build
- Template
Type:
String
The path and file name of AWS SAM template file.
See
-t
,--template
and--template-file
option in AWS SAM CLI build documentation.Required: No
Default: template.yaml
Example¶Project: Path: /sam-app
- StackName
See StackName in AttiniCfn.
- ConfigFile
See ConfigFile in AttiniCfn.
- Parameters
See Parameters in AttiniCfn.
- Tags
See Parameters in AttiniCfn.
- StackRoleArn
See StackRoleArn in AttiniCfn.
- ExecutionRoleArn
See ExecutionRoleArn in AttiniCfn.
- Variables
See Variables in AttiniCfn.
- Action
See Action in AttiniCfn.
- EnableTerminationProtection
See EnableTerminationProtection in AttiniCfn.
AttiniCdk¶
To simplify deployments of AWS CDK Projects Attini provides the AttiniCdk type.
AttiniCdk uses the CDK CLI on an Attini runner to perform the deployment so you can optionally configure your own AWS IAM Role and Container Image. This way your deployment can follow the principle of least privilege and use any software versions you need.
AttiniCdk will register all the CDK stacks with Attini, so that your CDK
stacks will be taken into consideration by the attini ops rogue-stacks
report.
Because the AttiniCdk uses the CDK CLI to do the deployment, most configuration options will map to a CDK CLI option. If the configuration is omitted, the CDK CLI default behavior will apply, unless otherwise specified in the docs.
Note
Non-default behavior:
--require-approval never
will be used because the standard approval makes makes no sense when the deployment isn’t executed from your local workstation. If you want manual approval for changes, please follow this guide.
--progress events
will be used.
Type: AttiniCdk
Properties:
Runner: String
Path: String
App: String
Environment: Map<String,String>
Stacks: List<String>
Context: Map<String,String>
Plugins: List<String>
StackConfiguration: List<CdkParameters>
Build: String
BuildExclude: List<String>
Exclusively: Boolean
NotificationArns: List<String>
Force: Boolean
RoleArn: String
- Runner
Type:
String
Reference a
Attini::Deploy::Runner
recourse, find more information here.Required: No
- Path
Type:
String
Location of your CDK project directory inside of your Attini distribution.
Required: Yes
- App
Type:
String
This property is passed to the
--app
option in the CDK CLI.If your project has a cdk.json file with the “app” property configured, this is not needed.
Required: No
- Environment
Type:
Map<String,String>
This property lets you set environment variables on the container that will deploy the CDK project. This way, the CDK project can get data from the deployment plan payload.
These environment variables can be accessed directly by your code, via the Context configuration, or the StackConfiguration (parameters).
Example¶Type: AttiniCdk Properties: Path: my-app Environment: ENV.$: $.environment VPC_ID.$: $.output.vpc.id
Required: No
- Stacks
Type:
List<String>
The Stacks in your CDK project to deploy. If omitted, the
--all
option in the CDK CLI will be used.Required: no
Default: All
- Context
Type:
Map<String,String>
This property is passed to the
--context
option in the CDK CLI.Example¶Type: AttiniCdk Properties: Path: my-app Context: vpd_id: $.output.vpc.id
Required: No
- Plugins
Type: List<String>
This property is passed to the
--plugin
option in the CDK CLI.Required: No
- StackConfiguration
Type: List<CdkParameters>
This property is passed to the
--parameters
option in the CDK CLI.Example¶Type: AttiniCdk Properties: Path: my-app StackConfiguration: - StackName: MyStackName Parameters: VpcId: $.output.vpc.id
Required: No
- StackName:
Type: String
Stack name that you want to configure.
Required: No
- Parameters:
Type: Map<String,String>
Parameter configuration for the CloudFormation stacks.
Required: Yes
- Build
Type:
String
This property is passed to the
--build
option in the CDK CLI.Example¶Type: AttiniCdk Properties: Path: my-app Build: | echo "My build commands" npm install
Required: No
- BuildExclude
Type:
List<String>
This property is passed to the
--build-exclude
option in the CDK CLI.Required: no
- NotificationArns
Type:
List<String>
This property is passed to the
--notification-arns
option in the CDK CLI.Required: no
- Force
Type:
Boolean
This property is passed to the
--force
option in the CDK CLI.Required: no
- RoleArn
Type:
Boolean
This property is passed to the
--role-arn
option in the CDK CLI.Required: no
AttiniLambdaInvoke¶
Type: AttiniLambdaInvoke
Parameters:
FunctionName: String
AttiniLambdaInvoke will call a Lambda function while preserving the payload for subsequent steps. This is an abstraction of the Amazon state language Lambda integration and all parameters are supported.
The difference between using StepFunction native Lambda invoke functionality and the AttiniLambdaInvoke is that AttiniLambdaInvoke will automatically configure the Lambda output to comply with the deployment plan payload structure.
By default, the entire deployment plan payload will be passed as input to the Lambda function. This can be overridden by setting the Payload parameter.
AWSTemplateFormatVersion: "2010-09-09"
Transform:
- AttiniDeploymentPlan
- AWS::Serverless-2016-10-31
Resources:
ExampleDeployment:
Type: Attini::Deploy::DeploymentPlan
Properties:
DeploymentPlan:
- Name: InvokeMyLambda
Type: AttiniLambdaInvoke
Parameters:
FunctionName: some-lambda-function
AttiniMap¶
Note
Experimental feature!
Type: AttiniMap
ItemsPath: String
MaxConcurrency: Number
Iterator:
StartAt: StateName
States:
StateName:
Type: AttiniCfn
This is an abstraction of the Amazon state language Map
that help you use AttiniCfn
within a Map.
In an AttiniMap, your AttiniCfn
will need to have OutputPath
configured.
For an example, see example-ecs-platform.
ATM: It requires a list of S3 Objects keys that are served as input for each iteration. We are working on improving AttiniMap
to make it
more user-friendly.
Note
Experimental feature!
AttiniImport¶
Type: AttiniImport
Properties:
SourceType: String
Source: S3Source | DistributionSource
Mapping: Map<String,String>
ExecutionRoleArn: String
The Attini import step can be used for importing data from different sources. A common use case for this type is reading data from the output of another distribution. For example you could have a distribution responsible for setting up a network that exposes a VPC-id. Then the VPC-id can be imported by other deployment plans.
- SourceType
Type:
String
Specifies what kind of source should be used.
Allowed values: Distribution | S3
Required: Yes
- Source
Type:
S3Source | DistributionSource
Different sources require different information in order to import them. For example, S3 needs a bucket and key while a distribution needs the name of the distribution.
Required: Yes
- S3Source
Used when the source of the import should be a file on S3. The file must be either a
JSON
or aYAML
document.Key: String Bucket: String
- Key
Type:
String
The S3 Key of the document to import.
Required: Yes
- Bucket
Type:
String
The S3 Bucket where the document is located.
Required: Yes
Example¶SourceType: S3 Source: Key: /my/s3/key.json Bucket: my-bucket
- DistributionSource
Used when the source of the import should be another distribution deployed in the environment. Before a distribution can import the output of another distribution, it first needs to be declared as a dependency in the attini-configuration file.
Name: String
- Name
Type:
String
The name of the distribution.
Required: Yes
Example¶SourceType: Distribution Source: Name: network
- Mapping
Type:
Map<String,String>
A key/value map where the value is a path to a value in the imported document. The path follows the JSONPath syntax. The value on the path will be included in the output of the step under the same key name as the mapping.
For example the following JSON source:
{ "my-service-endpoint": "https://some-endpoint.com" }
With the following mapping:
endpoint: $.my-service-endpoint
Would produce the following output for the step in the deployment plan payload.
{ "endpoint": "https://some-endpoint.com" }
Required: Yes
- ExecutionRoleArn
Type:
String
The arn of the execution role that should be used for accessing the source. At the moment only needed for the S3 source type if Attini does not have access to the S3 Bucket.
Required: No
Default: None
AttiniMergeOutput¶
Type: AttiniMergeOutput
Some AWS StepFunction types return a list instead of an object, for example Parallel or Map.
To make the payload easier to work with, the merge step can merge all the data in the list into one object.
Note
This is added automatically after every merge step when using the simplified syntax.
AWSTemplateFormatVersion: "2010-09-09"
Transform:
- AttiniDeploymentPlan
- AWS::Serverless-2016-10-31
Resources:
ExampleDeploy:
Type: Attini::Deploy::DeploymentPlan
Properties:
DeploymentPlan:
StartAt: Step1
States:
Step1:
Type: Parallel
Next: MergeOutputsFromStep1
Branches:
-
StartAt: Stack1
States:
Stack1:
Type: AttiniCfn
Properties:
Template: /template-1.yaml
StackName: stack-1
End: true
-
StartAt: Stack2
States:
Stack2:
Type: AttiniCfn
Properties:
Template: /template-2.yaml
StackName: stack-2
End: true
MergeOutputsFromStep1:
Type: AttiniMergeOutput
Next: Step2
Step2:
Type: AttiniCfn
Properties:
Template: /template-3.yaml
StackName: stack-3
End: true
AttiniManualApproval¶
Type: AttiniManualApproval
The manual approval step will pause the deployment plan and wait for confirmation before continuing.
The deployment can be resumed by running the attini deploy continue
command with the Attini CLI.
AWSTemplateFormatVersion: "2010-09-09"
Transform:
- AttiniDeploymentPlan
- AWS::Serverless-2016-10-31
Resources:
ExampleDeployment:
Type: Attini::Deploy::DeploymentPlan
Properties:
DeploymentPlan:
- Name: WaitForApproval #The deployment plan will pause here until someone runs the continue command
Type: AttiniManualApproval
- Name: InvokeALambda
Type: AttiniLambdaInvoke
Parameters:
FunctionName: some-lambda-function
AttiniRunnerJob¶
Type: AttiniRunnerJob
Properties:
Runner: String
Environment: Map<String,String>
Commands: List<String>
The AttiniRunnerJob is a quick and cost-efficient way to run shell commands using a container.
Find detailed information about the Attini::Deploy::Runner
type here.
Find detailed information about the Attini Runner architecture here.
- Runner
Type:
String
Reference a
Attini::Deploy::Runner
recourse, find more information here.If this parameter is omitted, the Attini default runner will be used.
Required: No
- Environment
Type:
Map<String,String>
This property lets you set environment variables on the Runner.
Example¶Type: AttiniRunnerJob Properties: Environment: ENV.$: $.environment VPC_ID.$: $.output.vpc.id Commands: - echo ${VPC_ID}
Required: No
- Commands
Type:
List<String>
List of shell commands that runs the job.
These commands are run with set -eo pipefail configuration so that they fail quickly. To revert this configuration (and ignore errors in your scrips), begin your commands with the line:
set +eo pipefail
.Note
These strings can NOT integrate with the payload through Amazon state language using the
$.
syntax or its intrinsic functions.If you need these commands to integrate with the payload, see the “Environment” configuration or Attini runner input and output.
Required: Yes
AWSTemplateFormatVersion: "2010-09-09"
Transform:
- AttiniDeploymentPlan
- AWS::Serverless-2016-10-31
Resources:
HelloWorldRunner:
Type: Attini::Deploy::Runner
Properties:
TaskDefinitionArn: !Ref RunnerTaskDefinition
EcsCluster: test
AwsVpcConfiguration:
Subnets:
- "subnet-aaaaaaaa"
- "subnet-bbbbbbbb"
- "subnet-cccccccc"
SecurityGroups:
- 'sg-11111111'
assignPublicIp: ENABLED
ExampleDeployment:
Type: Attini::Deploy::DeploymentPlan
Properties:
DeploymentPlan:
- Name: Step1
Type: AttiniRunnerJob
Properties:
Runner: HelloWorldRunner
Commands:
- echo "my shell commands"