Deployment plan types¶
AWS Step Functions have a lot of great integrations with other AWS services ex Lambda and CodeBuild. However, to use AWS Step Functions as a deployment pipeline it was missing some important features, that is why we built some additional State Types.
Attini::Deploy::DeploymentPlan AttiniCfn¶
Type: AttiniCfn
Properties:
Template: String
StackName: String
ConfigFile: String
Parameters: Map<String,String>
StackRoleArn: String
ExecutionRoleArn: String
Region: String
OutputPath: String
Variables: Map<String,String>
Action: String
AttiniCfn will create, update or delete a CloudFormation stack.
See more information about the configuration options here.
Note
If the stack is in 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
This has to point towards a CloudFormation template stored in S3. It can either be a URL to a public template, or a reference to a template in the distribution. If the template is in the distribution, the reference has to start with a “/”, ex “/path/to/my/template.yaml”
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 CloudFormation configuration
Required: No
Default: None
- Parameters
Type:
Map<String, String>
The CloudFormation parameters, find more info CloudFormation configuration.
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
Doing cross-account deployments
The ExecutionRole have 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 then 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-serviceYour
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
Attini::Deploy::DeploymentPlan 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.
By default, the entire payment plan payload will be passed as input to the Lambda function. This can be overridden by setting the Payload parameter.
Example
AWSTemplateFormatVersion: "2010-09-09"
Transform:
- AttiniDeploymentPlan
- AWS::Serverless-2016-10-31
Resources:
ExampleDeploy:
Type: Attini::Deploy::DeploymentPlan
Properties:
DeploymentPlan:
StartAt: InvokeMyLambda
States:
InvokeMyLambda:
Type: AttiniLambdaInvoke
Parameters:
FunctionName: some-lambda-function
End: true
Attini::Deploy::DeploymentPlan 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 you AttiniCfn
will need to have OutputPath
configured.
For an example, see example-ecs-platform.
ATM: It requires a list of S3 Objects keys that is served as input for each iteration. We are working on improving AttiniMap
to make it
more user-friendly.
Note
Experimental feature!
Attini::Deploy::DeploymentPlan AttiniMergeOutput¶
Type: AttiniMergeOutput
Some AWS StepFunction types return a list instead of a object, example Parallel or Map.
To make the payload easy to work with the merge step kan merge all the data in the list into one object.
Note
The merge will remove duplicates in all lists in the payload.
Example
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
Attini::Deploy::DeploymentPlan AttiniRunnerJob¶
Note
AttiniRunnerJob is in beta testing
Type: AttiniRunnerJob
Properties:
Runner: String
Commands:
- 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 runners architecture here.
- Runner
Type:
String
Reference a
Attini::Deploy::Runner
recourse, find more information here.Required: Yes
- 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 Attini runner input and output.
Required: Yes
Example
AWSTemplateFormatVersion: "2010-09-09"
Transform:
- AttiniDeploymentPlan
- AWS::Serverless-2016-10-31
Resources:
HelloWorldRunner:
Type: Attini::Deploy::Runner
Properties:
TaskDefinitionArn: !Ref RunnerTaskDefinition
Container: MyContainer
EcsCluster: test
AwsVpcConfiguration:
Subnets:
- "subnet-aaaaaaaa"
- "subnet-bbbbbbbb"
- "subnet-cccccccc"
SecurityGroups:
- 'sg-11111111'
assignPublicIp: ENABLED
ExampleDeploy:
Type: Attini::Deploy::DeploymentPlan
Properties:
DeploymentPlan:
StartAt: Step1
States:
Step1:
Type: AttiniRunnerJob
Properties:
Runner: HelloWorldRunner
Commands:
- echo "my shell commands"
End: true