# CloudFormationCreateUpdateStackAction

CodePipeline action to deploy a stack.

Creates the stack if the specified stack doesn't exist. If the stack exists,
AWS CloudFormation updates the stack. Use this action to update existing
stacks.

AWS CodePipeline won't replace the stack, and will fail deployment if the
stack is in a failed state. Use `ReplaceOnFailure` for an action that
will delete and recreate the stack to try and recover from failed states.

Use this action to automatically replace failed stacks without recovering or
troubleshooting them. You would typically choose this mode for testing.

Extends: [Action](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codepipeline.Action.html) › [Action](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codepipeline_actions.Action.html) › CloudFormationCreateUpdateStackAction
Implements: [IAction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codepipeline.IAction.html)

- Source: [`aws-codepipeline-actions/lib/cloudformation/pipeline-actions.ts`](https://github.com/aws/aws-cdk/blob/v2.277.0/packages/aws-cdk-lib/aws-codepipeline-actions/lib/cloudformation/pipeline-actions.ts#L448)

## Example

TypeScript:

```ts
import { PhysicalName } from 'aws-cdk-lib';

// in stack for account 123456789012...
declare const otherAccountStack: Stack;
const actionRole = new iam.Role(otherAccountStack, 'ActionRole', {
  assumedBy: new iam.AccountPrincipal('123456789012'),
  // the role has to have a physical name set
  roleName: PhysicalName.GENERATE_IF_NEEDED,
});

// in the pipeline stack...
const sourceOutput = new codepipeline.Artifact();
new codepipeline_actions.CloudFormationCreateUpdateStackAction({
  actionName: 'CloudFormationCreateUpdate',
  stackName: 'MyStackName',
  adminPermissions: true,
  templatePath: sourceOutput.atPath('template.yaml'),
  role: actionRole, // this action will be cross-account as well
});
```

Python:

```python
from aws_cdk import PhysicalName

# in stack for account 123456789012...
# other_account_stack: Stack

action_role = iam.Role(other_account_stack, "ActionRole",
    assumed_by=iam.AccountPrincipal("123456789012"),
    # the role has to have a physical name set
    role_name=PhysicalName.GENERATE_IF_NEEDED
)

# in the pipeline stack...
source_output = codepipeline.Artifact()
codepipeline_actions.CloudFormationCreateUpdateStackAction(
    action_name="CloudFormationCreateUpdate",
    stack_name="MyStackName",
    admin_permissions=True,
    template_path=source_output.at_path("template.yaml"),
    role=action_role
)
```

Java:

```java
import software.amazon.awscdk.PhysicalName;

// in stack for account 123456789012...
Stack otherAccountStack;

Role actionRole = Role.Builder.create(otherAccountStack, "ActionRole")
        .assumedBy(new AccountPrincipal("123456789012"))
        // the role has to have a physical name set
        .roleName(PhysicalName.GENERATE_IF_NEEDED)
        .build();

// in the pipeline stack...
Artifact sourceOutput = new Artifact();
CloudFormationCreateUpdateStackAction.Builder.create()
        .actionName("CloudFormationCreateUpdate")
        .stackName("MyStackName")
        .adminPermissions(true)
        .templatePath(sourceOutput.atPath("template.yaml"))
        .role(actionRole)
        .build();
```

C# / .NET:

```csharp
// Install: dotnet add package Amazon.CDK.Lib
using Amazon.CDK;

// in stack for account 123456789012...
Stack otherAccountStack;

var actionRole = new Role(otherAccountStack, "ActionRole", new RoleProps {
    AssumedBy = new AccountPrincipal("123456789012"),
    // the role has to have a physical name set
    RoleName = PhysicalName.GENERATE_IF_NEEDED
});

// in the pipeline stack...
var sourceOutput = new Artifact();
new CloudFormationCreateUpdateStackAction(new CloudFormationCreateUpdateStackActionProps {
    ActionName = "CloudFormationCreateUpdate",
    StackName = "MyStackName",
    AdminPermissions = true,
    TemplatePath = sourceOutput.AtPath("template.yaml"),
    Role = actionRole
});
```

Golang:

```go
// Install: go get github.com/aws/aws-cdk-go/awscdk/v2
import "github.com/aws/aws-cdk-go/awscdk"

// in stack for account 123456789012...
var otherAccountStack Stack

actionRole := iam.NewRole(otherAccountStack, jsii.String("ActionRole"), &RoleProps{
	AssumedBy: iam.NewAccountPrincipal(jsii.String("123456789012")),
	// the role has to have a physical name set
	RoleName: awscdk.PhysicalName_GENERATE_IF_NEEDED(),
})

// in the pipeline stack...
sourceOutput := codepipeline.NewArtifact()
codepipeline_actions.NewCloudFormationCreateUpdateStackAction(&CloudFormationCreateUpdateStackActionProps{
	ActionName: jsii.String("CloudFormationCreateUpdate"),
	StackName: jsii.String("MyStackName"),
	AdminPermissions: jsii.Boolean(true),
	TemplatePath: sourceOutput.AtPath(jsii.String("template.yaml")),
	Role: actionRole,
})
```

## Initializer

TypeScript:

```ts
new CloudFormationCreateUpdateStackAction(props: CloudFormationCreateUpdateStackActionProps)
```

Python:

```python
CloudFormationCreateUpdateStackAction(props: CloudFormationCreateUpdateStackActionProps)
```

Java:

```java
new CloudFormationCreateUpdateStackAction(CloudFormationCreateUpdateStackActionProps props)
```

C# / .NET:

```csharp
new CloudFormationCreateUpdateStackAction(CloudFormationCreateUpdateStackActionProps props)
```

Golang:

```go
NewCloudFormationCreateUpdateStackAction(Props CloudFormationCreateUpdateStackActionProps)
```

## Properties

- `actionProperties`: [ActionProperties](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_codepipeline.ActionProperties.html) — The simple properties of the Action, like its Owner, name, etc.

  Note that this accessor will be called before the `bind` callback.

- `deploymentRole`: [IRole](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IRole.html)

## Methods

- `addToDeploymentRolePolicy(statement: PolicyStatement): boolean` — Add statement to the service role assumed by CloudFormation while executing this action.

- `bind(scope: Construct, stage: IStage, options: ActionBindOptions): ActionConfig` — The callback invoked when this Action is added to a Pipeline.

- `onStateChange(name: string, target?: IRuleTarget, options?: RuleProps): Rule` — Creates an Event that will be triggered whenever the state of this Action changes.
