Skip to content

Commit 70bce02

Browse files
jakebarkjakebark
authored
Merge pull request #28 from aws-samples/readme
doc updates
2 parents 1de1fef + c492606 commit 70bce02

File tree

6 files changed

+97
-88
lines changed

6 files changed

+97
-88
lines changed

‎README.md

Lines changed: 9 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# terraform-aws-pipeline
22

3-
Deploy terraform with terraform.
3+
Deploy Terraform with Terraform.
44

55
🐓 🥚 ?
66

@@ -26,7 +26,7 @@ pipeline repo
2626
main.tf <--module deployed here
2727
```
2828

29-
Segregation enables the pipeline to run commands against the code in "your repo" without affecting the pipeline infrastructure. This could be an infrastructure or bootstrap repo for the AWS account.
29+
Segregation enables the pipeline to run commands against the code in "your repo" without affecting the pipeline infrastructure.
3030

3131
## Module Inputs
3232

@@ -91,95 +91,16 @@ module "pipeline" {
9191
]
9292
}
9393
```
94-
`branch` is the branch to source. It defaults to `main`.
9594

96-
`mode` is [pipeline execution mode](https://docs.aws.amazon.com/codepipeline/latest/userguide/concepts-how-it-works.html#concepts-how-it-works-executions). It defaults to `SUPERSEDED`.
95+
See [optional inputs](./docs/optional_inputs.md) for descriptions.
9796

98-
`detect_changes` is used with third-party services, like GitHub. It enables AWS CodeConnections to invoke the pipeline when there is a commit to the repo. It defaults to `false`.
97+
## Docs
9998

100-
`kms_key` is the arn of an *existing* AWS KMS key. This input will encrypt the Amazon S3 bucket with a AWS KMS key of your choice. Otherwise the bucket will be encrypted using SSE-S3. Your AWS KMS key policy will need to allow codebuild and codepipeline to `kms:GenerateDataKey*` and `kms:Decrypt`.
101-
102-
`access_logging_bucket` S3 server access logs bucket ARN, enables server access logging on the S3 artifact bucket.
103-
104-
`artifact_retention` controls the S3 artifact bucket retention period. It defaults to 90 (days).
105-
106-
`log_retention` controls the CloudWatch log group retention period. It defaults to 90 (days).
107-
108-
`codebuild_policy` replaces the [AWSAdministratorAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html) IAM policy. This can be used if you want to scope the permissions of the pipeline.
109-
110-
`build_timeout` is the CodeBuild project build timeout. It defaults to 10 (minutes).
111-
112-
`terraform_version` controls the terraform version. It defaults to 1.5.7.
113-
114-
`checkov_version` controls the [Checkov](https://www.checkov.io/) version. It defaults to latest.
115-
116-
`tflint_version` controls the [tflint](https://github.com/terraform-linters/tflint) version. It defaults to 0.48.0.
117-
118-
`vpc` configures the CodeBuild projects to [run in a VPC](https://docs.aws.amazon.com/codebuild/latest/userguide/vpc-support.html).
119-
120-
`tags` enables tag validation with [tag-nag](https://github.com/jakebark/tag-nag). Input a list of tag keys and/or tag keys and values to enforce. Input must be passed as a string, see [commands](https://github.com/jakebark/tag-nag?tab=readme-ov-file#commands).
121-
122-
`tagnag_version` controls the [tag-nag](https://github.com/jakebark/tag-nag) version. It defaults to 0.5.8.
123-
124-
`checkov_skip` defines [Checkov](https://www.checkov.io/) skips for the pipeline. This is useful for organization-wide policies, removing the need to add individual resource skips.
125-
126-
127-
## Architecture
128-
129-
![image info](./img/architecture.png)
130-
131-
1. User commits to existing repository.
132-
2. The commit invokes an Amazon EventBridge rule, which runs the AWS CodePipeline pipeline.
133-
3. The pipeline validates the code, then runs a `terraform plan`, before waiting for manual approval. Once this is issued, the resources are built with a `terraform apply` (either within the same account or another AWS account, depending on how your code is configured).
134-
4. Pipeline artifacts are sent to an Amazon S3 bucket. Pipeline activity is logged in Amazon CloudWatch logs.
135-
136-
#### Pipeline Validation
137-
138-
| Check | Description |
139-
|---|---|
140-
| validate | runs `terraform validate` to make sure that the code is syntactically valid. |
141-
| lint | runs [tfLint](https://github.com/terraform-linters/tflint) which will find errors, depreciated syntax, and check naming conventions. |
142-
| fmt | runs `terraform fmt --recursive --check` to ensure code is consistently formatted. |
143-
| sast | runs [checkov](https://www.checkov.io/) for security best practices. |
144-
| tags (optional)| runs [tag-nag](https://github.com/jakebark/tag-nag) to validate tags.|
145-
146-
## Setup a cross-account pipeline
147-
The pipeline can assume a cross-account role and deploy to another AWS account.
148-
149-
1. Ensure there is a [cross-account IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html) that can be assumed by the codebuild roles (validate and execute).
150-
2. Edit the provider in "your repo" to include the [assume role argument](https://developer.hashicorp.com/terraform/tutorials/aws/aws-assumerole).
151-
152-
```hcl
153-
provider "aws" {
154-
region = "eu-west-2"
155-
assume_role {
156-
role_arn = "arn:aws:iam::112233445566:role/cross-account-role"
157-
session_name = "pipeline"
158-
}
159-
}
160-
```
161-
3. Commit the changes and run the pipeline.
162-
163-
## Troubleshooting
164-
165-
| Issue | Fix |
166-
|---|---|
167-
| Failed lint or validate | Read the report or logs to discover why the code has failed, then make a new commit. |
168-
| Failed fmt | This means your code is not formatted. Run `terraform fmt --recursive` on your code, then make a new commit. |
169-
| Failed SAST | Read the Checkov logs (click CodeBuild Project > Reports tab) and either make the correction in code or add a skip to the module inputs. |
170-
| Failed plan or apply stage | Read the report or logs to discover error in terraform code, then make a new commit. |
171-
| Pipeline fails on apply with `the action failed because no branch named main was found ...` | Either nothing has been committed to the repo or the branch is incorrect (Eg using `Master` not `Main`). Either commit to the Main branch or change the module input to fix this. |
172-
173-
## Best Practices
174-
175-
The CodeBuild execution role uses the [AWSAdministratorAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html) IAM policy as this pattern is designed for a wide audience to deploy any resource to an AWS account. It assumes there are strong organizational controls in place and good segregation practices at the AWS account level. If you need to better scope the policy, the `codebuild_policy` optional input can be used to replace this with an IAM policy of your choosing.
176-
177-
Permissions to your CodeCommit repository, CodeBuild projects, and CodePipeline pipeline should be tightly controlled. Here are some ideas:
178-
- [Specify approval permission for specific pipelines and approval actions](https://docs.aws.amazon.com/codepipeline/latest/userguide/approvals-iam-permissions.html#approvals-iam-permissions-limited).
179-
- [Using identity-based policies for AWS CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/auth-and-access-control-iam-identity-based-access-control.html).
180-
- [Limit pushes and merges to branches in AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/how-to-conditional-branch.html)
181-
182-
Checkov skips can be used where Checkov policies conflict with your organization's practices or design decisions. The `checkov_skip` module input allows you to set skips for all resources in your repository. For example, if your organization operates in a single region you may want to add `CKV_AWS_144` (Ensure that S3 bucket has cross-region replication enabled). For individual resource skips, you can still use [inline code comments](https://www.checkov.io/2.Basics/Suppressing%20and%20Skipping%20Policies.html).
99+
- [Optional inputs](./docs/optional_inputs.md)
100+
- [Architecture](./docs/architecture.md)
101+
- [Setup a cross account pipeline](./docs/cross_account_pipeline.md)
102+
- [Troubleshooting](./docs/troubleshooting.md)
103+
- [Best practices](./docs/best_practices.md)
183104

184105
## Related Resources
185106

‎docs/architecture.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Architecture
2+
3+
![image info](../img/architecture.png)
4+
5+
1. User commits to existing repository.
6+
2. The commit invokes an Amazon EventBridge rule, which runs the AWS CodePipeline pipeline.
7+
3. The pipeline validates the code, then runs a `terraform plan`, before waiting for manual approval. Once this is issued, the resources are built with a `terraform apply` (either within the same account or another AWS account, depending on how your code is configured).
8+
4. Pipeline artifacts are sent to an Amazon S3 bucket. Pipeline activity is logged in Amazon CloudWatch logs.
9+
10+
## Pipeline Validation
11+
12+
| Check | Description |
13+
|---|---|
14+
| validate | runs `terraform validate` to make sure that the code is syntactically valid. |
15+
| lint | runs [tfLint](https://github.com/terraform-linters/tflint) which will find errors, depreciated syntax, and check naming conventions. |
16+
| fmt | runs `terraform fmt --recursive --check` to ensure code is consistently formatted. |
17+
| sast | runs [checkov](https://www.checkov.io/) for security best practices. |
18+
| tags (optional)| runs [tag-nag](https://github.com/jakebark/tag-nag) to validate tags.|

‎docs/best_practices.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Best practices
2+
3+
The CodeBuild execution role uses the [AWSAdministratorAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html) IAM policy as this pattern is designed for a wide audience to deploy any resource to an AWS account. It assumes there are strong organizational controls in place and good segregation practices at the AWS account level. If you need to better scope the policy, the `codebuild_policy` optional input can be used to replace this with an IAM policy of your choosing.
4+
5+
Permissions to your CodeCommit repository, CodeBuild projects, and CodePipeline pipeline should be tightly controlled. Here are some ideas:
6+
- [Specify approval permission for specific pipelines and approval actions](https://docs.aws.amazon.com/codepipeline/latest/userguide/approvals-iam-permissions.html#approvals-iam-permissions-limited).
7+
- [Using identity-based policies for AWS CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/auth-and-access-control-iam-identity-based-access-control.html).
8+
- [Limit pushes and merges to branches in AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/how-to-conditional-branch.html)
9+
10+
Checkov skips can be used where Checkov policies conflict with your organization's practices or design decisions. The `checkov_skip` module input allows you to set skips for all resources in your repository. For example, if your organization operates in a single region you may want to add `CKV_AWS_144` (Ensure that S3 bucket has cross-region replication enabled). For individual resource skips, you can still use [inline code comments](https://www.checkov.io/2.Basics/Suppressing%20and%20Skipping%20Policies.html).
11+

‎docs/cross_account_pipeline.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
## Setup a cross-account pipeline
2+
3+
The pipeline can assume a cross-account role and deploy to another AWS account.
4+
5+
1. Ensure there is a [cross-account IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html) that can be assumed by the codebuild roles (validate and execute).
6+
2. Edit the provider in "your repo" to include the [assume role argument](https://developer.hashicorp.com/terraform/tutorials/aws/aws-assumerole).
7+
8+
```hcl
9+
provider "aws" {
10+
region = "eu-west-2"
11+
assume_role {
12+
role_arn = "arn:aws:iam::112233445566:role/cross-account-role"
13+
session_name = "pipeline"
14+
}
15+
}
16+
```
17+
3. Commit the changes and run the pipeline.

‎docs/optional_inputs.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Optional inputs
2+
3+
`branch` is the branch to source. It defaults to `main`.
4+
5+
`mode` is [pipeline execution mode](https://docs.aws.amazon.com/codepipeline/latest/userguide/concepts-how-it-works.html#concepts-how-it-works-executions). It defaults to `SUPERSEDED`.
6+
7+
`detect_changes` is used with third-party services, like GitHub. It enables AWS CodeConnections to invoke the pipeline when there is a commit to the repo. It defaults to `false`.
8+
9+
`kms_key` is the arn of an *existing* AWS KMS key. This input will encrypt the Amazon S3 bucket with a AWS KMS key of your choice. Otherwise the bucket will be encrypted using SSE-S3. Your AWS KMS key policy will need to allow codebuild and codepipeline to `kms:GenerateDataKey*` and `kms:Decrypt`.
10+
11+
`access_logging_bucket` S3 server access logs bucket ARN, enables server access logging on the S3 artifact bucket.
12+
13+
`artifact_retention` controls the S3 artifact bucket retention period. It defaults to 90 (days).
14+
15+
`log_retention` controls the CloudWatch log group retention period. It defaults to 90 (days).
16+
17+
`codebuild_policy` replaces the [AWSAdministratorAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html) IAM policy. This can be used if you want to scope the permissions of the pipeline.
18+
19+
`build_timeout` is the CodeBuild project build timeout. It defaults to 10 (minutes).
20+
21+
`terraform_version` controls the terraform version. It defaults to 1.5.7.
22+
23+
`checkov_version` controls the [Checkov](https://www.checkov.io/) version. It defaults to latest.
24+
25+
`tflint_version` controls the [tflint](https://github.com/terraform-linters/tflint) version. It defaults to 0.48.0.
26+
27+
`vpc` configures the CodeBuild projects to [run in a VPC](https://docs.aws.amazon.com/codebuild/latest/userguide/vpc-support.html).
28+
29+
`tags` enables tag validation with [tag-nag](https://github.com/jakebark/tag-nag). Input a list of tag keys and/or tag keys and values to enforce. Input must be passed as a string, see [commands](https://github.com/jakebark/tag-nag?tab=readme-ov-file#commands).
30+
31+
`tagnag_version` controls the [tag-nag](https://github.com/jakebark/tag-nag) version. It defaults to 0.5.8.
32+
33+
`checkov_skip` defines [Checkov](https://www.checkov.io/) skips for the pipeline. This is useful for organization-wide policies, removing the need to add individual resource skips.

‎docs/troubleshooting.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
## Troubleshooting
2+
3+
| Issue | Fix |
4+
|---|---|
5+
| Failed lint or validate | Read the report or logs to discover why the code has failed, then make a new commit. |
6+
| Failed fmt | This means your code is not formatted. Run `terraform fmt --recursive` on your code, then make a new commit. |
7+
| Failed SAST | Read the Checkov logs (click CodeBuild Project > Reports tab) and either make the correction in code or add a skip to the module inputs. |
8+
| Failed plan or apply stage | Read the report or logs to discover error in terraform code, then make a new commit. |
9+
| Pipeline fails on apply with `the action failed because no branch named main was found ...` | Either nothing has been committed to the repo or the branch is incorrect (Eg using `Master` not `Main`). Either commit to the Main branch or change the module input to fix this. |

0 commit comments

Comments
 (0)