CloudFormation Create Stack step

Provision using the CloudFormation Create Stack step.

Use the CloudFormation Create Stack step in a CD stage's Execution section as part of the deployment process. Add the Create Stack step at the point in your deployment workflow where you need the infrastructure provisioned. Typically, you add it before steps that deploy your application to the provisioned infrastructure. The Create Stack step runs the CloudFormation template and supporting files that you supply inline or from your repositories (Git, AWS S3). Harness provisions the CloudFormation stack defined in the template as part of the stage's Execution.

You can also use Create Stack in the Infrastructure section of a CD stage for dynamic provisioning. When you use Create Stack in the Infrastructure section, Harness provisions the infrastructure before running any Execution steps. You can map CloudFormation template outputs to Infrastructure Definition settings to tell Harness where to deploy. During deployment, Harness first provisions the target deployment infrastructure and then the stage's Execution steps deploy to the provisioned infrastructure. Go to Provision target infrastructure dynamically to configure dynamic provisioning.

Before you begin

Harness account with Continuous Delivery enabled: You need Continuous Delivery under Deployments in Harness. Go to Getting started with Harness Platform to access or create a Harness account.
CONTACT HARNESS SUPPORT
If Continuous Delivery does not appear, contact your account administrator or Harness Support.
Pipeline and Deploy stage permissions: You need Create/Edit for Pipelines, View and Create/Edit for Environments, and View for Connectors. An administrator must assign you a role that includes these permissions. Go to RBAC in Harness and Manage roles to configure roles.
AWS account: Access to create CloudFormation stacks and provision target resources (EC2, EKS, ECS, Lambda, etc.). Go to AWS CloudFormation service role to understand IAM role requirements.
CloudFormation template knowledge: Basic understanding of CloudFormation template structure, parameters, outputs, and stack states. Go to AWS CloudFormation template anatomy to learn template basics.
Existing CD pipeline with Deploy stage: A CD pipeline with a Deploy stage configured. Go to Add a stage to set up pipelines and stages.
CloudFormation provisioning fundamentals: Understanding of how CloudFormation provisioning works in Harness. Go to CloudFormation provisioning with Harness to understand CloudFormation integration concepts.

Configure the Create Stack step

In the Execution section of your Deploy stage, click Add Step, and then select the CloudFormation Create Stack step.

Add Step menu showing CloudFormation Create Stack option

The Create Stack step is where you connect Harness to your templates and provide additional settings.

Name

In Name, enter a name for the step, for example, Create EC2 Instance.

Harness will create an Entity Id using the name. The Id is important because you can use Harness expressions to reference settings in this step from another step. For example, to reference the stack name in another step, use <+pipeline.stages.[stage-id].spec.execution.steps.[create-stack-step-id].spec.configuration.stackName>.

Go to Harness expressions to learn about expression syntax and usage.

Timeout

In Timeout, enter how long Harness should wait to complete the step before failing the step and initiating the Step and Stage Failure Strategy.

CLOUDFORMATION TIMING

CloudFormation stack creation can take 10-30 minutes depending on the resources being provisioned. Monitor progress in the pipeline execution console under the Create Stack step logs. Harness waits for the stack to reach CREATE_COMPLETE status before proceeding.

Provisioner Identifier

Enter a unique value in Provisioner Identifier.

The Provisioner Identifier identifies the provisioning done by this step. You reference the Provisioner Identifier in other steps to refer to the provisioning done by this step.

Only one Create Stack step with a specific Provisioner Identifier can be added in the same stage. If you add multiple Create Stack steps with the same Provisioner Identifier, only the first Create Stack step will be successful. Subsequent Create Stack steps with the same Provisioner Identifier will fail with an error. This ensures each provisioned stack can be uniquely identified for rollback and cleanup operations.

The most common use of Provisioner Identifier is between the Create Stack, Delete Stack, and Rollback Stack steps. For example, in the case of a Create Stack failure, the Rollback Stack step rolls back the provisioning from the Create Stack step using its Provisioner Identifier.

Provisioner Identifier field in Create Stack step and matching identifier in Rollback Stack step

Ultimately, Harness determines what stack to roll back to using a combination of Provisioner Identifier + Harness account id + Harness org id + Harness project id.

Provisioner Identifier scope

The Provisioner Identifier is a Project-wide setting. You can reference it across Pipelines in the same Project.

For this reason, it is important that all your Project members know the Provisioner Identifiers. This will prevent one member building a Pipeline from accidentally impacting the provisioning of another member's Pipeline.

AWS Connector

Add or select the Harness AWS Connector that will be used for this step. The AWS Connector includes the credentials needed to perform the provisioning.

The AWS Connector requires IAM permissions to create CloudFormation stacks and provision target resources (EC2, EKS, ECS, etc.). Go to AWS Connector settings reference to configure required permissions and authentication. For CloudFormation-specific permissions, go to AWS CloudFormation service role to understand IAM service role requirements.

For example, to give full access to create and manage EKS clusters, you could use a policy like this:

{  
     "Version": "2012-10-17",  
     "Statement": [  
         {  
             "Effect": "Allow",  
             "Action": [  
                 "autoscaling:*",  
                 "cloudformation:*",  
                 "ec2:*",  
                 "eks:*",  
                 "iam:*",  
                 "ssm:*"  
             ],  
             "Resource": "*"  
         }  
     ]  
 }

The credentials must include the ec2:DescribeRegions policy. This is required by default. It can be made optional with the feature flag CDS_AWS_DESCRIBE_REGIONS_OPTIONAL. Go to AWS Connector DescribeRegions - Optional for details.

Harness delegates execute CloudFormation operations. Ensure your delegate has network access to AWS and the AWS CLI installed. Go to Delegate overview to configure delegates.

Region

Select the AWS region where you want to provision resources in the Region field.

Template File

You can add your CloudFormation template in the following ways:

Inline: Enter the template directly in the Template File field. You can use CloudFormation-compliant JSON or YAML.
AWS S3: Enter the URL of the S3 bucket containing the template file. This can be a public or private URL. If you use a private URL, the AWS credentials in the AWS Connector setting authenticate the request. Ensure the credentials include the AmazonS3ReadOnlyAccess policy and the ec2:DescribeRegions policy described in AWS Connector settings reference. The ec2:DescribeRegions policy is required by default. Go to AWS Connector DescribeRegions - Optional for details.
Remote: Select a Git repository where your template is located. Add or select a Harness Git Connector for the repository. Go to Code Repo Connectors to configure Git Connectors.

Expression and secret support in templates

You can use Harness expressions and secrets in templates for dynamic values. They resolve at runtime. Go to Add text secrets and Harness expressions to configure expressions and secrets.

Stack Name

Enter a name for the CloudFormation stack Harness will create in the Stack Name field.

This is the same as the --stack-name option in the aws cloudformation create-stack command:

aws cloudformation create-stack --stack-name test --template-body file://eks.yml

STACK UPDATE BEHAVIOR

If a CloudFormation stack with the specified name already exists and is in a healthy state, the Create Stack step will update the existing stack with the new template. However, if the stack is in ROLLBACK_COMPLETE state, Harness deletes the stack first and then creates a new one. Go to Configure stack status checks to understand how Harness handles different stack states.

CloudFormation Parameter Files

You can use CloudFormation parameter files to specify input parameters for the stack.

This is the same as using the AWS CloudFormation CLI create-stack option --parameters with a JSON parameters file:

aws cloudformation create-stack --stackname startmyinstance  
--template-body file:///some/local/path/templates/startmyinstance.json  
--parameters https://your-bucket-name.s3.amazonaws.com/params/startmyinstance-parameters.json

Example JSON parameter file:

[  
  {  
    "ParameterKey": "KeyPairName",  
    "ParameterValue": "MyKey"  
  },   
  {  
    "ParameterKey": "InstanceType",  
    "ParameterValue": "m1.micro"  
  }  
]

To add parameter files:

In CloudFormation Parameter Files, click Add.
In Parameter File Connector, select your Git platform, then select or add a Git Connector. Go to Code Repo Connectors to configure Git Connectors. For AWS S3, go to Add an AWS Connector.
In Parameter File Details, enter the following:
- Identifier: Enter an Identifier for the file. This name indicates what the parameters are for.
- Repo Name: If the Git Connector does not have the repository path, enter it here.
- Git Fetch Type: Select Latest from Branch or use a Git commit ID or tag.
- Parameter File Details: Enter the path to the file from the root of the repository. To add multiple files, click Add Path File.

CloudFormation parameter file configuration showing Git connector, repository details, and file paths

Encrypted text secrets and expressions in parameter files

Harness expressions and secrets are supported in parameter files and Parameter File Details settings. They resolve at runtime. Go to Add text secrets to configure secrets.

CloudFormation Parameters Overrides

You can override parameters added in Parameter File Details.

In CloudFormation Parameters Overrides, click Specify Inline Parameters.

Click Retrieve Names from template to retrieve the parameters from the JSON file. You can also manually enter the names and values.

For each parameter you want to override, enter a new value in Value.

Harness text secrets are supported. Go to Add text secrets to configure secrets.

Specify the IAM role ARN

Enter the AWS Role ARN to use when creating the stack in the Role ARN field. Use an existing AWS Identity and Access Management (IAM) service role that CloudFormation can assume.

This is the same as the role you would use when creating a stack using the AWS console Permissions setting or CLI.

Go to AWS CloudFormation service role to understand IAM service role requirements.

Specify Capabilities

To acknowledge the capabilities in the CloudFormation template, click in Specify Capabilities and select capabilities.

This acknowledges that the template contains certain capabilities (for example, CAPABILITY_AUTO_EXPAND), giving AWS CloudFormation the specified capabilities before it creates the stack. This is the same as using the --capabilities option in the aws cloudformation create-stack CLI command. Go to AWS CloudFormation create-stack for details.

Configure stack status checks

In Continue Based on Stack Statuses, add the stack states that allow provisioning to continue.

Harness checks if the stack is in ROLLBACK_COMPLETE state before deployment. If the stack is in ROLLBACK_COMPLETE, Harness deletes the stack and then triggers the deployment. ROLLBACK_COMPLETE indicates a previous stack creation failed and left the stack in an incomplete state. Deleting the stack removes any partially-created resources and allows a clean stack creation.

YAML example

Complete ad hoc provisioning pipeline YAML

This example shows a complete ad hoc CloudFormation provisioning pipeline with Create Stack, Display Outputs, Delete Stack, and Rollback Stack steps.

pipeline:
  name: CloudFormation Ad Hoc Provisioning
  identifier: CloudFormation_Ad_Hoc_Provisioning
  projectIdentifier: your_project
  orgIdentifier: default
  variables:
    - name: stack_name
      type: String
      value: my-adhoc-stack
    - name: aws_region
      type: String
      value: us-east-2
  stages:
    - stage:
        name: Provision Infrastructure
        identifier: Provision_Infrastructure
        type: Deployment
        spec:
          deploymentType: AwsLambda
          service:
            serviceRef: your_service
            serviceInputs:
              serviceDefinition:
                type: AwsLambda
                spec:
                  artifacts:
                    primary:
                      primaryArtifactRef: <+input>
                      sources: <+input>
          environment:
            environmentRef: your_environment
            deployToAll: false
            infrastructureDefinitions:
              - identifier: your_infrastructure
          execution:
            steps:
              - step:
                  type: CreateStack
                  name: Create S3 Bucket Stack
                  identifier: Create_Stack
                  spec:
                    provisionerIdentifier: s3_provisioner
                    configuration:
                      connectorRef: your_aws_connector
                      region: <+pipeline.variables.aws_region>
                      stackName: <+pipeline.variables.stack_name>
                      templateFile:
                        type: Inline
                        spec:
                          templateBody: |
                            AWSTemplateFormatVersion: '2010-09-09'
                            Description: Ad hoc S3 bucket provisioning

                            Resources:
                              S3Bucket:
                                Type: AWS::S3::Bucket
                                Properties:
                                  BucketName: !Sub 'my-bucket-${AWS::AccountId}'
                                  Tags:
                                    - Key: ManagedBy
                                      Value: Harness

                            Outputs:
                              BucketName:
                                Description: Name of the S3 bucket
                                Value: !Ref S3Bucket
                              BucketArn:
                                Description: ARN of the S3 bucket
                                Value: !GetAtt S3Bucket.Arn
                              Region:
                                Description: AWS Region
                                Value: !Ref AWS::Region
                  timeout: 10m

              - step:
                  type: ShellScript
                  name: Display Stack Outputs
                  identifier: Display_Stack_Outputs
                  spec:
                    shell: Bash
                    executionTarget: {}
                    source:
                      type: Inline
                      spec:
                        script: |
                          echo "=========================================="
                          echo "CloudFormation Stack Outputs"
                          echo "=========================================="
                          echo "Bucket Name: <+pipeline.stages.Provision_Infrastructure.spec.execution.steps.Create_Stack.output.BucketName>"
                          echo "Bucket ARN:  <+pipeline.stages.Provision_Infrastructure.spec.execution.steps.Create_Stack.output.BucketArn>"
                          echo "Region:      <+pipeline.stages.Provision_Infrastructure.spec.execution.steps.Create_Stack.output.Region>"
                          echo "=========================================="

              - step:
                  type: DeleteStack
                  name: Delete S3 Bucket Stack
                  identifier: Delete_Stack
                  spec:
                    configuration:
                      type: Inline
                      spec:
                        connectorRef: your_aws_connector
                        region: <+pipeline.variables.aws_region>
                        stackName: <+pipeline.variables.stack_name>
                      connectorRef: your_aws_connector
                  timeout: 10m

            rollbackSteps:
              - step:
                  type: RollbackStack
                  name: Rollback Stack
                  identifier: Rollback_Stack
                  spec:
                    configuration:
                      provisionerIdentifier: s3_provisioner
                  timeout: 10m

        failureStrategies:
          - onFailure:
              errors:
                - AllErrors
              action:
                type: StageRollback

CloudFormation Create Stack step with S3 template

This example shows a Create Stack step that retrieves the template from an S3 URL.

- step:
    type: CreateStack
    name: Create CloudFormation Stack
    identifier: Create_Stack
    spec:
      provisionerIdentifier: cfn_infrastructure
      configuration:
        connectorRef: account.aws_connector
        region: us-east-1
        templateFile:
          type: S3Url
          spec:
            connectorRef: account.aws_connector
            region: us-east-1
            urls:
              - https://s3.amazonaws.com/my-bucket/template.yaml
        stackName: harness-stack-<+pipeline.sequenceId>
        parameterFiles:
          - type: S3Url
            spec:
              connectorRef: account.aws_connector
              region: us-east-1
              urls:
                - https://s3.amazonaws.com/my-bucket/parameters.json
        roleArn: arn:aws:iam::123456789012:role/CloudFormationRole
        capabilities:
          - CAPABILITY_NAMED_IAM
        tags:
          - key: Environment
            value: Production
          - key: ManagedBy
            value: Harness
    timeout: 10m

Advanced settings

The Create Stack step supports standard Harness step settings. Configure advanced step options:

Troubleshooting

Stack name already exists error when creating CloudFormation stack in Harness CD

If the existing stack is in a healthy state, Harness updates it. If the stack is in ROLLBACK_COMPLETE state, Harness deletes it and creates a new one. Ensure the stack name is unique or use the Continue Based on Stack Statuses setting to configure how Harness handles existing stacks.

Permission denied errors when creating AWS resources with CloudFormation in Harness CD

Verify the AWS Connector credentials include required IAM permissions for CloudFormation and target resources. Check the CloudFormation service role ARN has sufficient permissions. Ensure the delegate has network access to AWS.

CloudFormation template validation failure in Harness pipeline

Validate your CloudFormation template syntax using the AWS CloudFormation console or CLI. Ensure all required parameters are provided and resource references are correct. Check that expressions and secrets resolve correctly at runtime.

CloudFormation parameter file not found in Harness Create Stack step

Verify the parameter file path is correct relative to the repository root. Check that the Git Connector has access to the repository and branch. Ensure the parameter file exists at the specified path.

Role ARN authentication failure in CloudFormation Create Stack step

Verify the Role ARN is correct and exists in your AWS account. Ensure the AWS Connector credentials have permission to assume the role. Check that the role's trust policy allows CloudFormation to assume it.

Next steps

Provision target deployment infrastructure dynamically with CloudFormation: Use Create Stack in the Infrastructure section for dynamic provisioning.
CloudFormation Delete Stack step: Remove provisioned resources.
CloudFormation Rollback Stack step: Roll back to the last successfully provisioned version.

PreviousProvision Infrastructure Dynamically

NextCloudFormation Rollback Step

Last updated 7 days ago

Was this helpful?