Attini deployment plan¶

Deployment plan¶

The Attini deployment plan is an abstraction on the AWS::Serverless::StateMachine resource. It also extends the StateMachine with features that make it an excellent deployment orchestrator. It integrates with the deployment source files, the Attini CLI, and supports the Attini State Types.

You can define your deployment plan in a programming language using the Attini CDK Constructs.

The deployment plan can ONLY be created in the Attini init deploy stack

The deployment plan template requires the following Transform configuration:

AWSTemplateFormatVersion: "2010-09-09"
Transform:
  - AttiniDeploymentPlan
  - AWS::Serverless-2016-10-31

Resource definition¶

Type: Attini::Deploy::DeploymentPlan
Properties:
  DefinitionSubstitutions: Map
  PayloadDefaults: Map
  RoleArn: String
  Policies: String | List | Map
  PermissionsBoundary: String
  Tags: List
  DeploymentPlan: DeploymentPlan Definition

DefinitionSubstitutions

Type: Map<Sting, Sting|Map>

AWS SAM compatibility: This property is passed directly to the DefinitionSubstitutions property of an AWS::Serverless::StateMachine resource.

This is useful if you want to use AWS CloudFormation’s Condition functions when you build your deployment plan. This can also be used for Intrinsic functions but most of them (ex Fn::Sub and Ref) can also be written straight in the deployment plan.

Required: No

PayloadDefaults

Type: Map<Sting, Sting|Map>

A method to create initial default values for the deployment payload.

These default values can be used to avoid runtime errors when reading missing values from the payload.

The PayloadDefaults currently only work in the “output” section of the payload.

Example

Properties:
  PayloadDefaults:
    output:
      MyStepName:
        MyOutput: "MyValue"
This value can be referenced in DeploymentPlan with the JSON string: $.output.MyStepName.MyOutput.

MyValue can be overwritten by a step called MyStepName if it outputs a key called MyOutput.

Required: No

RoleArn

Type: String

AWS SAM compatibility: This property is passed directly to the Role property of an AWS::Serverless::StateMachine resource.

You provide either a RoleArn or Policies.

Default: arn:aws:iam::{Account}:role/attini/attini-deployment-plan-default-states-service-role-{Region}

Required: Conditional

If the parameter CreateDeploymentPlanDefaultRole on the attini-setup CloudFormation stack is false, then this is or Policies required.

Policies

Type: String | List | Map

AWS SAM compatibility: This property is passed directly to the Policies property of an AWS::Serverless::StateMachine resource.

You provide either a RoleArn or Policies.

Required: Conditional

If the parameter CreateDeploymentPlanDefaultRole on the attini-setup CloudFormation stack is false, then this is or RoleArn required.

PermissionsBoundary

Type: String

AWS SAM compatibility: This property is passed directly to the PermissionsBoundary property of an AWS::Serverless::StateMachine resource.

This will only work if you create the IAM Role using the Policies configuration.

Required: No

Tags

Type: Map<Sting, Sting>

AWS SAM compatibility: This property is passed directly to the Tags property of an AWS::Serverless::StateMachine resource.

Required: No

DeploymentPlan

Type: DeploymentPlan Definition

You can define your deployment plan in different 2 ways:

Simplified syntax (List)
Amazon state language (Map)

Required: Yes

Deployment plan definition¶

The deployment plan Definition is an abstraction of AWS::Serverless::StateMachine and it supports Attini types and StepFunctions native Tasks like Optimized integrations for Step Functions and AWS SDK service integrations.

The deployment plan Definition has the same CloudFormation limitations as the AWS::Serverless::StateMachine Definition.

Some Intrinsic functions functions like Fn::Join will need to use the DefinitionSubstitutions property. Simple functions like Ref, Fn::GetAtt and Fn::Sub works like normal CloudFormation.
CloudFormation Conditions are not supported within the definition. However, you can use the Choice State to perform logic within your deployment.

Simplified syntax¶

State

DeploymentPlan:
  - Name: String
    Type: String
    # Optional configuration based on State Type

Attini simplified syntax lets you define your deployment plan using a List instead of Amazon state language. The steps will be executed in the order of the list.

In addition to a simple list of States, the simplified syntax also supports Parallel and Choice.

Name

Type: String

Name of the State. This has to be unique within the deployment plan.

Type

Type: String

Any valid State type like Attini types, StateMachine Task, or other StateMachine States like Pass, Wait, Succeed, Fail.

Parallel and Choice, are supported but have their own simplified syntax.

Example

DeploymentPlan:
  - Name: ManualApproval
    Type: AttiniManualApproval

  - Name: MyDatabaseStack
    Type: AttiniCfn
    Properties:
      StackName: database
      Template: /database.yaml

Parallel¶

Name: String
Type: Parallel
Branches: List<List<State>>

This is a simplified syntax for the Parallel State.

The Parallel State outputs a list of the outputs from all its branches, therefore it’s often desirable to use the AttiniMergeOutput Type after the Parallel State. This is done automatically when using the simplified syntax, assuming that the merge step has not been added manually.

DeploymentPlan:
  - Name: MyParallelName
    Type: Parallel
    Branches:
      -
        - Name: Step_1_in_branch_1
          Type: AttiniLambdaInvoke
          Parameters:
            FunctionName: my-function
        - Name: Step_2_in_branch_1
          Type: AttiniSam
          Properties:
            Project:
              Path: /my-sam-app/
            StackName: my-sam-stack
      -
        - Name: Step_1_in_branch_2
          Type: AttiniRunnerJob
          Commands:
            - echo "hello world"

Choice¶

DeploymentPlan:
  - Name: String
    Type: Choice
    Condition:
      Comparison
    IsTrue:
      - List<State>
    IsFalse:
      - List<State>

The Choice step will help you make choices depending on a condition. The condition can be based on the payload or CloudFormation configuration.

The simplified Choice differs from Amazon state language choice because the simplified syntax only allows for one Comparison while Amazon state language choice can have multiple.

Condition

Type: Comparison

This comparison is a direct translation for Amazon state language choice but without “Next”.

Required: Yes

IsTrue

Type: List<State>

A List of States that will be executed if the Condition is true.

Required: Yes

IsFalse

Type: List<State>

A List of States that will be executed if the Condition is false.

If IsFalse is omitted, the deployment will continue to the next step if the Condition is false (or end if it is the last step).

Required: No

DeploymentPlan:
  - Name: IsDev?
    Type: Choice
    Condition:
      Variable: $.deploymentOriginData.environment
      StringEquals: dev
    IsTrue:
      - Name: RunLoadtest
        Type: AttiniRunnerJob
        Commands:
          - autocannon --amount 100 --connections 1 --connectionRate 10 --renderStatusCodes --bailout 1 https://my-site.com

Amazon state language¶

A definition using Amazon state language that describes your deployment.

In addition to the Amazon state language types, the deployment plan can also use the Attini types.

This definition converts to a AWS State Machine Definition.

DeploymentPlan:
  StartAt: String
  States:
    String:
      Type: String
      # Optional configuration based on State Type
      Next: String
      End: Boolean

StartAt

Type: String

The step that the deployment plan should start with. This is the same as the StartAt property in the Amazon States Language

Required: Yes

States

Type: Map<Sting, Map>

This is the same as the States property in the Amazon States Language after the Attini-specific resources (ex AttiniCfn) have been converted into a valid Amazon States Language definition.

Make sure that the actions that you specify here are allowed by the deployment plan Role.

This map has limited support for CloudFormation functions.

Simple functions like “Ref”, “Fn::GetAtt” and “Fn::Sub” works like normal CloudFormation.
Complex functions like “Fn::Join” will need to use the DefinitionSubstitutions property.
Conditions are not supported. you can often work around this limitation using logic in your definition, example by using the Choice state.

Required: Yes

Type

Type: String

Any valid State type like Attini types, StateMachine Task, or other StateMachine States like Pass, Wait, Succeed, Fail, Choice or Parallel.

Next

Type: String

Name of the next step.

Required: Yes, if End is not configured

End

Type: Boolean

Marks the end of a branch execution.

Required: Yes, if Next is not configured

Example

DeploymentPlan:
  StartAt: ManualApproval
  States:
    ManualApproval:
      Type: AttiniManualApproval
      Next: MyDatabaseStack

    MyDatabaseStack:
      Type: AttiniCfn
      Properties:
        StackName: database
        Template: /database.yaml
      End: True

Transformed resources¶

A Attini::Deploy::DeploymentPlan resource transforms into multiple CloudFormation resources that together creates your deployment plan.

In this example, you can see how the transformed template will look.

Original template

AWSTemplateFormatVersion: "2010-09-09"
Transform:
  - AttiniDeploymentPlan
  - AWS::Serverless-2016-10-31

Resources:
  PublicWebsite:
    Type: Attini::Deploy::DeploymentPlan
    Properties:
      DeploymentPlan:
        ...

Outputs:
  DeploymentSfnPlanArn:
    Description: The arn of the StepFunction generated by PublicWebsite
    Value: !Ref AttiniDeploymentPlanSfnPublicWebsite

Transformed template:

{
  "AWSTemplateFormatVersion": "2010-09-09",
  "Resources": {
    "AttiniDeploymentPlanSfnTriggerPublicWebsite": {
      "Type": "Custom::AttiniDeploymentPlanTrigger",
      "Properties": {
        "...": "..."
      }
    },
    "AttiniDeploymentPlanSfnPublicWebsite": {
      "Type": "AWS::StepFunctions::StateMachine",
      "Properties": {
        "...": "..."
      }
    },
    "AttiniPostExecutionActionsPublicWebsite": {
      "Type": "AWS::Events::Rule",
      "Properties": {
        "...": "..."
      }
    }
  },
  "Outputs": {
    "DeploymentSfnPlanArn": {
      "Description": "The arn of the StepFunction generated by PublicWebsite deployment plan",
      "Value": {
        "Ref": "AttiniDeploymentPlanSfnPublicWebsite"
      }
    }
  }
}