AWS released this new feature at re:Invent 2023. Read on for a deep dive and see if this feature is for you!
[Update 19/12 — CLI/SDK is supported links updated once I found them — article updated. Would have been handy to have this info in the Git sync docs but it required hunting]
It is easy to get inundated with all the new shiny things released at AWS re:Invent this year. One release that caught my eye was the new Git sync capability that allows you to sync your CloudFormation stack with your Git CI/CD tooling. Supported integrations are:
- GitHub
- GitHub Enterprise
- GitLab
- Bitbucket
What this new configuration does is simply execute a CloudFormation stack update/deployment when a commit is made to the tracked branch. The tracked branch could be main or any other branch you select during the configuration phase. It avoids the need for any pipeline creation, or AWS credential setup for simple CloudFormation deployment use cases.
If your needs are more complex and require specific tasks to execute pre/post deployment this feature is not for you at this time.
If you just need a simple infrastructure deployment option for a CloudFormation stack and your needs are not complex — read on, this tool might be for you!
AWS have developed a new concept called a deployment file. This file is in YAML format and describes the path to the template to deploy, any parameters required by the CloudFormation template, plus any specific tags. See sample:
You would normally have a deployment file per environment & stack which allows a best practice of keeping the same CloudFormation template for all deploys no matter which environment you are deploying to. This file is kept in your Git repo with the template and makes up part of your Git sync configuration.
Interestingly AWS put a managed EventBridge rule in your account as part of the setup:
Where aws.cloudformation events are captured and sent off somewhere for processing 🙂
The Setup Process
This consists three parts:
- Setup a CodeStar connection to your Git repository of choice. This is a one time setup per AWS account. In my case I setup a connection to GitHub.
- Make sure you have a GitHub repository with your CloudFormation template in it. It’s highly recommended to have a GitHub workflow setup to lint your template to reduce the chance of any deployment failures!
- Setup the Git sync config
SDK/CLI Support
This configuration is supported from the AWS CLI, SDK and CloudFormation and there is a bit of a walkthrough here however today we will ClickOps our way through the journey. It would be handy if all this info was linked from the main documentation page [3]!
Git Sync Setup
There are two roles required.
- One is a Git sync service role so it can deploy the template in your account. This policy is fixed and only required once per account.
- The second one is the role used to manage the stack — this is the role that needs specific IAM Actions to add resources in your account as per stack requirements.
See example for my specific samplestack:
And the trust policy for the role is pretty standard for a CloudFormation service role:
When you have these roles sorted out — you can create your Git sync config for your brand new stack.
The cool thing is — alternatively, you might already have a stack deployed, in which case you can actually modify your stack to be put under Git sync control without having to redeploy any resources. Using this method AWS connector for GitHub sends a PR to your repo with your deployment file. I found this super handy for a config I setup for my customer recently. However please see note [2] below for a tip on this.
I will briefly walk through the new stack setup process.
Step 1
Create a new stack and click on the new Git sync tab.
Step 2
Enter your information you prepared earlier. For the first time setup I am assuming you are providing your own deployment file in your repository:
- Link a Git repository with CloudFormation
- Choose your codestar connection
- Select your repo
- Then branch
- Then deployment file path in your repo
- Select your standard CloudFormation Git sync service role (not the execution role thats the next step)
- Click next
Step 3
Enter the stack CloudFormation execution role which has permissions to deploy resources in the account:
Update any other CloudFormation settings you need, then click next.
Step 4
Click Submit
Your stack will start to deploy within a few seconds as if by magic!
Then assuming your role has the correct policy….success!
Now going forward — the best practice process to update would be to:
- create a branch
- make your changes
- push those changes and raise a PR where your cfn-lint will take place.
- Then if all is well when you merge to main, Git sync will kick off again and your resources will be updated.
The only gotchya is that if your deployment will do anything bad … like an unexpected delete, you cannot catch it before it happens. You can mitigate this with ec2 termination protection being switched on, but a better way would be to add an additional action in your pull request to perform a changeset and review the changes prior to merging to main. This requires the additional step of AWS credentials, which is best done with the GitHub AWS federation setup if you were going to go down this path.
It would be nice if AWS could add some sort of approval workflow into this feature at some point to make this easier. But this is definitely a very useful version 1 for those teams who need some simple infrastructure deployment pipelines!
Reference:
[1] https://aws.amazon.com/blogs/devops/automate-safe-aws-cloudformation-deployments-from-github/
[2] When setting up Git sync for an existing stack there is a bug which I have reported back to the internal AWS service team.
While the parameters of the already deployed stack are identified properly, Git sync fails to save the configuration unless the parameters have “defaults” in the CloudFormation template. I think this is redundant and not required, but you have to manually update the deployed template with these settings otherwise the Git sync config will fail to configure correctly.
The error you see when Git sync fails to save is “IAM role could not be updated for stack test-vpc-stack”:
eg: A template like this will fail the Git sync save:
workaround values which will allow it to work:
Just make sure the defaults match what was deployed and you will be golden!
[3] https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/git-sync.html
