How do I bootstrap Gruntwork Pipelines and the ECS Deploy Runner?
I am looking to update from an older Reference Architecture that did not include the ECS Deploy Runner to a modern version, and am stuck trying to figure out how to deploy the ECS Deploy Runner. What are the steps needed to get the deploy runner provisioned and setup?
We have [a guide for this exact thing](https://docs.gruntwork.io/guides/build-it-yourself/pipelines/deployment-walkthrough/deploy-the-ecs-deploy-runner), but to be completely transparent, (as of this comment) this guide is admittedly outdated. We are working on initiatives to massively overhaul those docs, but unfortunately don’t have anything that would be ready in the meantime so there will be a bit of a struggle for getting the ECS deploy runner up and running from scratch. With that said, I can definitely help out with a rudimentary guide for setting up the pipeline: ### Setup Machine User access 1. Setup a machine user for access to the repo and create Personal Access Tokens that the ECS Deploy Runner can use to access the repos. You can follow the steps in [this guide](https://docs.gruntwork.io/guides/reference-architecture/configuration-guide/#set-up-the-machine-user), but ignore the steps around putting the ARNs in the form. We will instead be putting these ARNs directly in `terragrunt.hcl`. 2. Provision an SSH key for authenticating as the machine user, and upload it the private key to Secrets Manager. You can follow the steps in [the guide](https://docs.gruntwork.io/guides/build-it-yourself/pipelines/deployment-walkthrough/deploy-the-ecs-deploy-runner#create-secrets-manager-entries) to create it. Note that you will want to create this in the shared account. 3. Once those secrets manager entries are setup in the shared account, you will want to setup cross account access, which can be done with: 1. Create a KMS key that is accessible in each account (necessary for allowing decryption of secrets manager across accounts). This is done in `account-baseline`, with the terraform code: https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/master/examples/for-production/infrastructure-live/shared/_global/account-baseline/terragrunt.hcl#L48-L61. If you don’t have `account-baseline` deployed, you can use the exact same map as an input to https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/kms-master-key-multi-region 1. Once the shared secret KMS key is created, update the secrets manager entries created above to rekey using the new KMS key. This is best done manually in the AWS web console. 1. Deploy https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/master/examples/for-production/infrastructure-live/shared/us-west-2/_regional/shared-secret-resource-policies/terragrunt.hcl to allow cross account access to the two secrets manager entries created above. **Make sure to update the ARNs to reference the ones you created above!** Note that you can omit `GitHubPAT` if you are using GitHub as your VCS system. ### Build Deploy Runner container images Each of the accounts should have access to the PAT and private SSH key for the machine user in the shared account now. The next step is to setup the container images used by the deploy runner: 1. In the shared account, create the ECR repos to host the deploy-runner and kaniko images. You can use the `ecr-repos` terragrunt config in the [for-production service catalog example](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/examples/for-production/infrastructure-live/shared/us-west-2/_regional/ecr-repos) to create the repos. 2. Once you have the ECR repos, follow the steps in [this knowledge base article](https://github.com/gruntwork-io/knowledge-base/discussions/45) to build and upload the docker images to ECR. ### Deploy ECS Deploy Runner At this point, you should have all the necessary pieces to deploy the ECS Deploy Runner. To deploy the deploy runner, we will be using the [ecs-deploy-runner service module](https://docs.gruntwork.io/reference/services/ci-cd-pipeline/ecs-deploy-runner). The steps are: 1. Create a mgmt VPC to house the deploy runner if you don't have one already. Refer to [this terragrunt.hcl config](https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/master/examples/for-production/infrastructure-live/shared/us-west-2/mgmt/networking/vpc/terragrunt.hcl) and [this envcommon hcl config](https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/master/examples/for-production/infrastructure-live/_envcommon/mgmt/vpc-mgmt.hcl) for an example. 2. Define the same common variables as those [defined here in the example](https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/v0.85.4/examples/for-production/infrastructure-live/common.hcl#L19-L35). 3. Define all the necessary read-only (for `terraform-planner`) and read-write (for `terraform-deployer`) permissions to deploy your modules in YAML files in the envcommon folder. You can use the [deploy_permissions.yml](https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/master/examples/for-production/infrastructure-live/_envcommon/mgmt/deploy_permissions.yml) and [read_only_permissions.yml](https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/master/examples/for-production/infrastructure-live/_envcommon/mgmt/read_only_permissions.yml) examples as a starting point. 4. Define the terragrunt configurations to deploy the deploy runner. Refer to [this terragrunt.hcl config](https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/master/examples/for-production/infrastructure-live/shared/us-west-2/mgmt/ecs-deploy-runner/terragrunt.hcl) and [this envcommon hcl config](https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/master/examples/for-production/infrastructure-live/_envcommon/mgmt/ecs-deploy-runner.hcl) for an example. Note that the `ami-builder` and `docker-image-builder` should only be configured in the **shared** account. Also be sure to update the `git_ssh_private_key_secrets_manager_arn` and `github_pat_secrets_manager_arn` locals to refer to the actual Secrets Manager entries you created above. - NOTE: Be sure to comment out the [ec2_worker_pool_configuration](https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/master/examples/for-production/infrastructure-live/_envcommon/mgmt/ecs-deploy-runner.hcl#L194-L211) variable definition. If you later find out that you do need the EC2 based workers, you can build the AMI using the Fargate ECS Deploy Runner using the [build script](https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/master/examples/for-production/infrastructure-live/shared/us-west-2/_regional/amis/build_ecs_deploy_runner_worker.sh) and add back in the configuration to deploy ECS Deploy Runner in EC2 mode. 6. Finally, deploy with `terragrunt apply`. You will need to repeat this step for each of the accounts in your environment. ### Setup CI/CD pipeline scripts ECS Deploy Runner acts as the main runner for infrastructure calls in your AWS account, but the core infrastructure CI/CD pipeline logic is driven by the CI server (e.g., CircleCI or GitHub actions). Thus, you will not have a full CI/CD pipeline until you provision the pipeline scripts for your `infrastructure-live` repo. To bootstrap the pipeline, start with the version defined in the `for-production` example, and adapt it to your needs. You will need the following at a minimum: 1. Copy the [_ci folder](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/examples/for-production/infrastructure-live/_ci), which contains all the relevant scripts to drive core parts of the pipeline, like AWS authentication and calling ECS Deploy Runner. 2. Copy/Generate the pipeline config. You can refer to [.circleci/config.yml](https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/master/examples/for-production/infrastructure-live/.circleci/config.yml) for CircleCI, and [.github folder](https://github.com/gruntwork-io/terraform-aws-service-catalog/tree/master/examples/for-production/infrastructure-live/.github) for GitHub Actions. 3. Follow the steps in [these docs](https://github.com/gruntwork-io/terraform-aws-service-catalog/blob/master/examples/for-production/infrastructure-live/docs/04-configure-gw-pipelines.md) to configure the relevant CI platforms with the secrets for invoking the pipeline.