Skip to content

Commit e9f37e7

Browse files
chrispennyeerkunt
chrispenny
and
eerkunt
authored
Add documentation for CircleCI and GitHub Actions integrations (#719)
* Add documentation for CircleCI integration * Add note and link to Pip requirements format * Add note regarding authentication * Add documentation for Github Actions --------- Co-authored-by: Emre Erkunt <emre.erkunt@gmail.com>
1 parent d73c73d commit e9f37e7

File tree

6 files changed

+277
-4
lines changed

6 files changed

+277
-4
lines changed

‎docs/pages/bdd-references/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Feature: Security Groups should be used to protect services/instances
2929
We'll use AWS Security Groups as a Perimeter Defence
3030
```
3131

32-
This won't effect anything about the test steps, but it will ease the pain for everybody to
32+
This won't affect anything about the test steps, but it will ease the pain for everybody to
3333
understand what does that feature aims for.
3434

3535
### Scenario

‎docs/pages/bdd-references/using_tags.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ __Please note that__
8181
- nofail and noskip tags can not be used within the same scenario.
8282

8383
### Case Sensitivity
84-
All steps, under the tagged scenario will use case sensitive matching. This tag also effects regular expressions.
84+
All steps, under the tagged scenario will use case-sensitive matching. This tag also affects regular expressions.
8585
> __Possible formats:__
8686
>
8787
> ▪

‎docs/pages/ci-cd/circle_ci.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
layout: default
3+
title: CircleCI
4+
nav_order: 1
5+
has_children: false
6+
parent: Using in CI/CD
7+
---
8+
9+
# CircleCI
10+
11+
For this example, we are using the following Orbs to illustrate how you might implement Terraform Compliance into your
12+
CI/CD pipeline.
13+
14+
- [circleci/terraform](https://circleci.com/developer/orbs/orb/circleci/terraform)
15+
- [circleci/python](https://circleci.com/developer/orbs/orb/circleci/python)
16+
17+
## Workflow
18+
19+
We have set up our pipeline to follow this basic workflow:
20+
21+
1. `terraform validate`: Using the Job provided by the Terraform Orb
22+
2. `terraform plan`: Using a custom Job, we will use the `plan` command that is provided by the Terraform Orb, but we'll also export that plan to json for `terraform-compliance` to access
23+
3. `terraform-compliance`: Using the Python Orb and Pip to install requirements
24+
4. `terraform apply`: Using the Job provided by the Terraform Orb, and only run on the `main` branch
25+
26+
## Setup
27+
28+
You will need to add a `requirements.txt` to your project. You can rename this file to anything you would like, but
29+
be sure to update the name in your `.circleci/config.yml`.
30+
31+
Following [Pip requirements format](https://pip.pypa.io/en/stable/reference/requirements-file-format/). You can specify
32+
any level of requirement that you desire for `terraform-compliance`.
33+
34+
`requirements.txt`:
35+
36+
```
37+
terraform-compliance >= 1.3.0
38+
```
39+
40+
Below is an example of the workflow described above.
41+
42+
`.circleci/config.yml`:
43+
44+
```yaml
45+
version: '2.1'
46+
47+
orbs:
48+
# Orb used for all of our Terraform related commands/jobs
49+
# https://circleci.com/developer/orbs/orb/circleci/terraform for available versions
50+
terraform: circleci/terraform@3.2.1
51+
# Orb used for installing and running Terraform Compliance
52+
# https://circleci.com/developer/orbs/orb/circleci/python for available versions
53+
python: circleci/python@2.1.1
54+
55+
parameters:
56+
terraform-tag:
57+
type: string
58+
description: Specify the Terraform Docker image tag for the executor
59+
# https://hub.docker.com/r/hashicorp/terraform/tags for available versions
60+
# If you also run Terraform locally, then you should use the same version here
61+
default: 1.5.7
62+
workspace-root:
63+
type: string
64+
description: Path of the workspace to persist to relative to workspace-root
65+
# Can be updated if you desire. The default specified here matches the default used by the CircleCI's Terraform Orb
66+
default: .
67+
workspace-path:
68+
type: string
69+
description: Workspace root path that is either an absolute path or a path relative to the working directory
70+
# Can be updated if you desire. The default specified here matches the default used by the CircleCI's Terraform Orb
71+
default: .
72+
73+
executors:
74+
# This default executor is used for our custom job that needs to run Terraform
75+
default:
76+
docker:
77+
# Our default executor should match the tag that the Terraform Orb will use
78+
- image: hashicorp/terraform:<< pipeline.parameters.terraform-tag >>
79+
80+
jobs:
81+
terraform_plan:
82+
executor: default
83+
steps:
84+
- checkout
85+
# Invoke the terraform/plan command that is provided by the Terraform Orb
86+
- terraform/plan:
87+
# And also output that plan
88+
out: plan.out
89+
# Convert our plan to JSON so that terraform-compliance can run without the use of Terraform
90+
- run:
91+
command: terraform show -json plan.out > plan.out.json
92+
name: Convert Terraform plan to JSON
93+
# Persist our workspace so that plan.out.json is available to terraform-compliance
94+
- persist_to_workspace:
95+
paths:
96+
- << pipeline.parameters.workspace-path >>
97+
root: << pipeline.parameters.workspace-root >>
98+
99+
terraform_compliance:
100+
executor: python/default
101+
steps:
102+
# Attach the workspace so that we have access to plan.out.json from terraform_plan
103+
- attach_workspace:
104+
at: << pipeline.parameters.workspace-root >>
105+
- python/install-packages:
106+
# Update requirements.txt to match the location of your requirements file. This is currently referencing a
107+
# file in the root of your project
108+
pip-dependency-file: requirements.txt
109+
pkg-manager: pip
110+
- run:
111+
command: terraform-compliance -f features -p plan.out.json
112+
name: Terraform Compliance
113+
114+
workflows:
115+
deploy_infra:
116+
jobs:
117+
# Use the standard validate job that is provided by the CircleCI Orb
118+
- terraform/validate:
119+
checkout: true
120+
# Make sure the CircleCI Orb uses the same version of Terraform as our default executor
121+
tag: << pipeline.parameters.terraform-tag >>
122+
123+
# For terraform plan we'll use a custom job so that we can run additional commands
124+
- terraform_plan:
125+
requires:
126+
- terraform/validate
127+
128+
# For terraform-compliance we'll use another custom job, and this will also be using our Python executor
129+
- terraform_compliance:
130+
requires:
131+
- terraform_plan
132+
133+
# Use the standard apply job that is provided by the CircleCI Orb
134+
- terraform/apply:
135+
attach-workspace: true
136+
# Make sure the CircleCI Orb uses the same version of Terraform as our default executor
137+
tag: << pipeline.parameters.terraform-tag >>
138+
# Update your filters as you require. One provided here as an example
139+
filters:
140+
branches:
141+
only: main
142+
requires:
143+
- terraform_compliance
144+
145+
```
146+
147+
Not provided above is the authentication method for AWS.
148+
149+
CircleCI provides authentication through [OpenID Connect](https://circleci.com/blog/openid-connect-identity-tokens/) as
150+
well as through AWS user Access Keys.

‎docs/pages/ci-cd/github_actions.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
layout: default
3+
title: GitHub Actions
4+
nav_order: 2
5+
has_children: false
6+
parent: Using in CI/CD
7+
---
8+
9+
# GitHub Actions
10+
11+
For this example, we'll use the following GitHub Marketplace Actions to illustrate how you might implement Terraform
12+
Compliance into your CI/CD pipeline.
13+
14+
## Workflow
15+
16+
We have set up our job to follow this basic workflow:
17+
18+
1. `terraform init`
19+
2. `terraform validate`
20+
3. `terraform plan`
21+
4. `terraform-compliance`
22+
5. `terraform apply` (but only on the `main` branch)
23+
24+
## Setup
25+
26+
You will need to add a `requirements.txt` to your project. You can rename this file to anything you would like, but
27+
be sure to update the name in your `.github/workflows/main.yml`.
28+
29+
Following [Pip requirements format](https://pip.pypa.io/en/stable/reference/requirements-file-format/). You can specify
30+
any level of requirement that you desire for `terraform-compliance`.
31+
32+
`requirements.txt`:
33+
34+
```
35+
terraform-compliance >= 1.3.0
36+
```
37+
38+
Below is an example of the workflow described above.
39+
40+
`.github/workflows/main.yml`:
41+
42+
```yaml
43+
name: Project Name
44+
45+
# https://docs.github.com/en/actions/using-workflows/triggering-a-workflow for available triggers
46+
on:
47+
# Run this workflow on all pull requests
48+
pull_request:
49+
# Run this workflow on commits made to the main branch
50+
push:
51+
branches:
52+
- main
53+
54+
jobs:
55+
test_and_deploy:
56+
name: Deploy Infrastructure
57+
runs-on: ubuntu-latest
58+
# Required by aws-actions/configure-aws-credentials
59+
permissions:
60+
id-token: write
61+
contents: read
62+
63+
steps:
64+
# Checkout your code
65+
- uses: actions/checkout@v4
66+
67+
# Set up our AWS credentials
68+
- name: Configure AWS credentials
69+
# https://github.com/aws-actions/configure-aws-credentials for available versions
70+
uses: aws-actions/configure-aws-credentials@v4
71+
with:
72+
# Define authentication method
73+
# Check the above repo for authentication methods available
74+
75+
# Set up Terraform for GitHub Actions
76+
- name: Setup Terraform
77+
# https://github.com/hashicorp/setup-terraform for available versions
78+
uses: hashicorp/setup-terraform@v2
79+
with:
80+
# https://hub.docker.com/r/hashicorp/terraform/tags for available versions
81+
# If you also run Terraform locally, then you should use the same version here
82+
terraform_version: 1.5.7
83+
84+
- name: Terraform Init
85+
run: terraform init
86+
87+
- name: Terraform Validate
88+
run: terraform validate
89+
90+
- name: Terraform Plan
91+
# Run terraform plan with an output, and then convert that output to JSON for Terraform Compliance to use later
92+
run: |
93+
terraform plan -out=plan.out
94+
terraform show -json plan.out > plan.out.json
95+
96+
# Set up Python
97+
- name: Install Python
98+
uses: actions/setup-python@v4
99+
with:
100+
python-version: 3.11
101+
cache: 'pip'
102+
103+
# Install Python requirements
104+
- name: Install Requirements
105+
# Update requirements.txt to match the location of your requirements file. This is currently referencing a
106+
# file in the root of your project
107+
run: pip install -r requirements.txt
108+
109+
- name: Terraform Compliance
110+
run: terraform-compliance -f compliance -p plan.out.json
111+
112+
- name: Terraform Apply
113+
# Only trigger this step on the main branch
114+
if: github.ref == 'refs/heads/main'
115+
run: terraform apply -auto-approve
116+
117+
```

‎docs/pages/ci-cd/index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
layout: default
3+
title: Using in CI/CD
4+
nav_order: 6
5+
has_children: true
6+
---

‎docs/pages/contribution/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,12 +30,12 @@ If you are going to reporting something else, please create a [General Question]
3030

3131
Normally, we expect to have either a [Bug Reporting](https://github.com/eerkunt/terraform-compliance/issues/new?assignees=eerkunt&labels=bug&template=bug_report.md&title=) or
3232
a [Feature Request](https://github.com/eerkunt/terraform-compliance/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=) before
33-
having a Pull Request for in the codebase that will effect any functionality. This is not a hard requirement, you are free
33+
having a Pull Request for in the codebase that will affect any functionality. This is not a hard requirement, you are free
3434
to create a new Pull Request if you find something is wrong or missing within the codebase or documentation.
3535

3636
There is few mandatory requirement for the Pull Requests ;
3737

38-
1. All code changes that effects functionality MUST have [tests](https://github.com/eerkunt/terraform-compliance/tree/master/tests) implemented within the same Pull Request.
38+
1. All code changes that affects functionality MUST have [tests](https://github.com/eerkunt/terraform-compliance/tree/master/tests) implemented within the same Pull Request.
3939
2. Any functionality change must be recorded within the [CHANGELOG](https://github.com/eerkunt/terraform-compliance/blob/master/CHANGELOG.md).
4040
3. Your Pull Request must pass the CI in order to be processed.
4141

0 commit comments

Comments
 (0)