Skip to content
This repository was archived by the owner on Mar 12, 2026. It is now read-only.

Commit c64b786

Browse files
vadim-gleifvadim-gleif
authored
Migrate to README.yaml format (#28)
* Migrate to README.yaml format
1 parent be039f7 commit c64b786

File tree

6 files changed

+525
-91
lines changed

6 files changed

+525
-91
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,6 @@
66
.terraform
77
.idea
88
*.iml
9+
10+
.build-harness
11+
build-harness

‎Makefile‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
SHELL := /bin/bash
22

3+
# List of targets the `readme` target should call before generating the readme
4+
export README_DEPS ?= docs/targets.md docs/terraform.md
5+
36
-include $(shell curl -sSL -o .build-harness "https://git.io/build-harness"; echo .build-harness)
47

8+
## Lint terraform code
59
lint:
6-
$(SELF) terraform/install terraform/get-modules terraform/get-plugins terraform/lint terraform/validate
10+
$(SELF) terraform/install terraform/get-modules terraform/get-plugins terraform/lint terraform/validate

‎README.md‎

Lines changed: 145 additions & 90 deletions
Large diffs are not rendered by default.

‎README.yaml‎

Lines changed: 323 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,323 @@
1+
---
2+
#
3+
# This is the canonical configuration for the `README.md`
4+
# Run `make readme` to rebuild the `README.md`
5+
#
6+
7+
# Name of this project
8+
name: terraform-aws-jenkins
9+
10+
# Logo for this project
11+
#logo: docs/logo.png
12+
13+
# License of this project
14+
license: "APACHE2"
15+
16+
# Canonical GitHub repo
17+
github_repo: cloudposse/terraform-aws-jenkins
18+
19+
# Badges to display
20+
badges:
21+
- name: "Build Status"
22+
image: "https://travis-ci.org/cloudposse/terraform-aws-jenkins.svg?branch=master"
23+
url: "https://travis-ci.org/cloudposse/terraform-aws-jenkins"
24+
- name: "Latest Release"
25+
image: "https://img.shields.io/github/release/cloudposse/terraform-aws-jenkins.svg"
26+
url: "https://github.com/cloudposse/terraform-aws-jenkins/releases/latest"
27+
- name: "Slack Community"
28+
image: "https://slack.cloudposse.com/badge.svg"
29+
url: "https://slack.cloudposse.com"
30+
31+
related:
32+
- name: "terraform-aws-elastic-beanstalk-applicationl"
33+
description: "Terraform module to provision AWS Elastic Beanstalk application"
34+
url: "https://github.com/cloudposse/terraform-aws-elastic-beanstalk-application"
35+
- name: "terraform-aws-elastic-beanstalk-environment"
36+
description: "Terraform module to provision AWS Elastic Beanstalk environment"
37+
url: "https://github.com/cloudposse/terraform-aws-elastic-beanstalk-environment"
38+
- name: "terraform-aws-ecr"
39+
description: "Terraform Module to manage Docker Container Registries on AWS ECR"
40+
url: "https://github.com/cloudposse/terraform-aws-ecr"
41+
- name: "terraform-aws-efs"
42+
description: "Terraform Module to define an EFS Filesystem (aka NFS)"
43+
url: "https://github.com/cloudposse/terraform-aws-efs"
44+
- name: "terraform-aws-efs-backup"
45+
description: "Terraform module designed to easily backup EFS filesystems to S3 using DataPipeline"
46+
url: "https://github.com/cloudposse/terraform-aws-efs-backup"
47+
- name: "terraform-aws-cicd"
48+
description: "Terraform Module for CI/CD with AWS Code Pipeline and Code Build"
49+
url: "https://github.com/cloudposse/terraform-aws-cicd"
50+
- name: "terraform-aws-codebuild"
51+
description: "Terraform Module to easily leverage AWS CodeBuild for Continuous Integration"
52+
url: "https://github.com/cloudposse/terraform-aws-codebuild"
53+
54+
# Short description of this project
55+
description: |-
56+
`terraform-aws-jenkins` is a Terraform module to build a Docker image with [Jenkins](https://jenkins.io/), save it to an [ECR](https://aws.amazon.com/ecr/) repo,
57+
and deploy to [Elastic Beanstalk](https://aws.amazon.com/elasticbeanstalk/) running [Docker](https://www.docker.com/).
58+
59+
This is an enterprise-ready, scalable and highly-available architecture and the CI/CD pattern to build and deploy Jenkins.
60+
## Features
61+
62+
The module will create the following AWS resources:
63+
64+
* Elastic Beanstalk Application
65+
* Elastic Beanstalk Environment with Docker stack to run the Jenkins master
66+
* ECR repository to store the Jenkins Docker image
67+
* EFS filesystem to store Jenkins config and jobs (it will be mounted to a directory on the EC2 host, and then to the Docker container)
68+
* CodePipeline with CodeBuild to build and deploy Jenkins so even Jenkins itself follows the CI/CD pattern
69+
* CloudFormation stack to run a DataPipeline to automatically backup the EFS to S3
70+
* CloudFormation stack for SNS notifications about the status of each backup
71+
72+
73+
After all of the AWS resources are created,
74+
75+
__CodePipeline__ will:
76+
77+
* Get the specified Jenkins repo from GitHub, _e.g._ https://github.com/cloudposse/jenkins
78+
* Build a Docker image from it
79+
* Save the Docker image to the ECR repo
80+
* Deploy the Docker image from the ECR repo to Elastic Beanstalk running Docker stack
81+
* Monitor the GitHub repo for changes and re-run the steps above if new commits are pushed
82+
83+
84+
__DataPipeline__ will run on the specified schedule and will backup all Jenkins files to an S3 bucket by doing the following:
85+
86+
* Spawn an EC2 instance
87+
* Mount the EFS filesystem to a directory on the EC2 instance
88+
* Backup the directory to an S3 bucket
89+
* Notify about the status of the backup (Success or Failure) via email
90+
* Destroy the EC2 instance
91+
92+
93+
![jenkins build server architecture](https://user-images.githubusercontent.com/52489/30888694-d07d68c8-a2d6-11e7-90b2-d8275ef94f39.png)
94+
95+
# How to use this project
96+
usage: |-
97+
For complete examples, see [examples](examples).
98+
99+
# Example usage
100+
101+
examples: |-
102+
### Deploy Jenkins into an existing VPC with existing subnets
103+
104+
```hcl
105+
variable "max_availability_zones" {
106+
default = "2"
107+
}
108+
109+
data "aws_availability_zones" "available" {}
110+
111+
module "jenkins" {
112+
source = "git::https://github.com/cloudposse/terraform-aws-jenkins.git?ref=master"
113+
namespace = "cp"
114+
name = "jenkins"
115+
stage = "prod"
116+
description = "Jenkins server as Docker container running on Elastic Beanstalk"
117+
118+
master_instance_type = "t2.medium"
119+
aws_account_id = "000111222333"
120+
aws_region = "us-west-2"
121+
availability_zones = ["${slice(data.aws_availability_zones.available.names, 0, var.max_availability_zones)}"]
122+
vpc_id = "vpc-a22222ee"
123+
zone_id = "ZXXXXXXXXXXX"
124+
public_subnets = ["subnet-e63f82cb", "subnet-e66f44ab", "subnet-e88f42bd"]
125+
private_subnets = ["subnet-e99d23eb", "subnet-e77e12bb", "subnet-e58a52bc"]
126+
loadbalancer_certificate_arn = "XXXXXXXXXXXXXXXXX"
127+
ssh_key_pair = "ssh-key-jenkins"
128+
129+
github_oauth_token = ""
130+
github_organization = "cloudposse"
131+
github_repo_name = "jenkins"
132+
github_branch = "master"
133+
134+
datapipeline_config = {
135+
instance_type = "t2.medium"
136+
email = "me@mycompany.com"
137+
period = "12 hours"
138+
timeout = "60 Minutes"
139+
}
140+
141+
env_vars = {
142+
JENKINS_USER = "admin"
143+
JENKINS_PASS = "123456"
144+
JENKINS_NUM_EXECUTORS = 4
145+
}
146+
147+
tags = {
148+
BusinessUnit = "ABC"
149+
Department = "XYZ"
150+
}
151+
}
152+
```
153+
154+
### Deploy Jenkins into an existing VPC and new subnets
155+
156+
```hcl
157+
variable "max_availability_zones" {
158+
default = "2"
159+
}
160+
161+
data "aws_availability_zones" "available" {}
162+
163+
module "jenkins" {
164+
source = "git::https://github.com/cloudposse/terraform-aws-jenkins.git?ref=master"
165+
namespace = "cp"
166+
name = "jenkins"
167+
stage = "prod"
168+
description = "Jenkins server as Docker container running on Elastic Beanstalk"
169+
170+
master_instance_type = "t2.medium"
171+
aws_account_id = "000111222333"
172+
aws_region = "us-west-2"
173+
availability_zones = ["${slice(data.aws_availability_zones.available.names, 0, var.max_availability_zones)}"]
174+
vpc_id = "vpc-a22222ee"
175+
zone_id = "ZXXXXXXXXXXX"
176+
public_subnets = "${module.subnets.public_subnet_ids}"
177+
private_subnets = "${module.subnets.private_subnet_ids}"
178+
loadbalancer_certificate_arn = "XXXXXXXXXXXXXXXXX"
179+
ssh_key_pair = "ssh-key-jenkins"
180+
181+
github_oauth_token = ""
182+
github_organization = "cloudposse"
183+
github_repo_name = "jenkins"
184+
github_branch = "master"
185+
186+
datapipeline_config = {
187+
instance_type = "t2.medium"
188+
email = "me@mycompany.com"
189+
period = "12 hours"
190+
timeout = "60 Minutes"
191+
}
192+
193+
env_vars = {
194+
JENKINS_USER = "admin"
195+
JENKINS_PASS = "123456"
196+
JENKINS_NUM_EXECUTORS = 4
197+
}
198+
199+
tags = {
200+
BusinessUnit = "ABC"
201+
Department = "XYZ"
202+
}
203+
}
204+
205+
module "subnets" {
206+
source = "git::https://github.com/cloudposse/terraform-aws-dynamic-subnets.git?ref=master"
207+
availability_zones = ["${slice(data.aws_availability_zones.available.names, 0, var.max_availability_zones)}"]
208+
namespace = "cp"
209+
name = "jenkins"
210+
stage = "prod"
211+
region = "us-west-2"
212+
vpc_id = "vpc-a22222ee"
213+
igw_id = "igw-s32321vd"
214+
cidr_block = "10.0.0.0/16"
215+
nat_gateway_enabled = "true"
216+
217+
tags = {
218+
BusinessUnit = "ABC"
219+
Department = "XYZ"
220+
}
221+
}
222+
```
223+
224+
### Deploy Jenkins into a new VPC and new subnets
225+
226+
```hcl
227+
variable "max_availability_zones" {
228+
default = "2"
229+
}
230+
231+
data "aws_availability_zones" "available" {}
232+
233+
module "jenkins" {
234+
source = "git::https://github.com/cloudposse/terraform-aws-jenkins.git?ref=master"
235+
namespace = "cp"
236+
name = "jenkins"
237+
stage = "prod"
238+
description = "Jenkins server as Docker container running on Elastic Beanstalk"
239+
240+
master_instance_type = "t2.medium"
241+
aws_account_id = "000111222333"
242+
aws_region = "us-west-2"
243+
availability_zones = ["${slice(data.aws_availability_zones.available.names, 0, var.max_availability_zones)}"]
244+
vpc_id = "${module.vpc.vpc_id}"
245+
zone_id = "ZXXXXXXXXXXX"
246+
public_subnets = "${module.subnets.public_subnet_ids}"
247+
private_subnets = "${module.subnets.private_subnet_ids}"
248+
loadbalancer_certificate_arn = "XXXXXXXXXXXXXXXXX"
249+
ssh_key_pair = "ssh-key-jenkins"
250+
251+
github_oauth_token = ""
252+
github_organization = "cloudposse"
253+
github_repo_name = "jenkins"
254+
github_branch = "master"
255+
256+
datapipeline_config = {
257+
instance_type = "t2.medium"
258+
email = "me@mycompany.com"
259+
period = "12 hours"
260+
timeout = "60 Minutes"
261+
}
262+
263+
env_vars = {
264+
JENKINS_USER = "admin"
265+
JENKINS_PASS = "123456"
266+
JENKINS_NUM_EXECUTORS = 4
267+
}
268+
269+
tags = {
270+
BusinessUnit = "ABC"
271+
Department = "XYZ"
272+
}
273+
}
274+
275+
module "vpc" {
276+
source = "git::https://github.com/cloudposse/terraform-aws-vpc.git?ref=master"
277+
namespace = "cp"
278+
name = "jenkins"
279+
stage = "prod"
280+
cidr_block = "10.0.0.0/16"
281+
282+
tags = {
283+
BusinessUnit = "ABC"
284+
Department = "XYZ"
285+
}
286+
}
287+
288+
module "subnets" {
289+
source = "git::https://github.com/cloudposse/terraform-aws-dynamic-subnets.git?ref=master"
290+
availability_zones = ["${slice(data.aws_availability_zones.available.names, 0, var.max_availability_zones)}"]
291+
namespace = "cp"
292+
name = "jenkins"
293+
stage = "prod"
294+
region = "us-west-2"
295+
vpc_id = "${module.vpc.vpc_id}"
296+
igw_id = "${module.vpc.igw_id}"
297+
cidr_block = "${module.vpc.vpc_cidr_block}"
298+
nat_gateway_enabled = "true"
299+
300+
tags = {
301+
BusinessUnit = "ABC"
302+
Department = "XYZ"
303+
}
304+
}
305+
```
306+
307+
# How to get started quickly
308+
#quickstart: |-
309+
# Here's how to get started...
310+
311+
# Other files to include in this README from the project folder
312+
include:
313+
- "docs/targets.md"
314+
- "docs/terraform.md"
315+
316+
# Contributors to this project
317+
contributors:
318+
- name: "Andriy Knysh"
319+
github: "aknysh"
320+
- name: "Ivan Pinatti"
321+
github: "ivan-pinatti"
322+
- name: "Sergey Vasilyev"
323+
github: "s2504s"

‎docs/targets.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
## Makefile Targets
2+
```
3+
Available targets:
4+
5+
help This help screen
6+
help/all Display help for all targets
7+
lint Lint terraform code
8+
9+
```

‎docs/terraform.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
2+
## Inputs
3+
4+
| Name | Description | Type | Default | Required |
5+
|------|-------------|:----:|:-----:|:-----:|
6+
| attributes | Additional attributes (e.g. `policy` or `role`) | list | `<list>` | no |
7+
| availability_zones | List of Availability Zones for EFS | list | - | yes |
8+
| aws_account_id | AWS Account ID. Used as CodeBuild ENV variable $AWS_ACCOUNT_ID when building Docker images. For more info: http://docs.aws.amazon.com/codebuild/latest/userguide/sample-docker.html | string | - | yes |
9+
| aws_region | AWS region in which to provision the AWS resources | string | `us-west-2` | no |
10+
| build_compute_type | CodeBuild compute type, e.g. 'BUILD_GENERAL1_SMALL'. For more info: http://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref.html#build-env-ref-compute-types | string | `BUILD_GENERAL1_SMALL` | no |
11+
| build_image | CodeBuild build image, e.g. 'aws/codebuild/docker:1.12.1'. For more info: http://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref.html#build-env-ref-available | string | `aws/codebuild/docker:1.12.1` | no |
12+
| datapipeline_config | DataPipeline configuration options | map | `<map>` | no |
13+
| delimiter | Delimiter to be used between `name`, `namespace`, `stage`, etc. | string | `-` | no |
14+
| description | Will be used as Elastic Beanstalk application description | string | `Jenkins server as Docker container running on Elastic Benastalk` | no |
15+
| env_default_key | Default ENV variable key for Elastic Beanstalk `aws:elasticbeanstalk:application:environment` setting | string | `DEFAULT_ENV_%d` | no |
16+
| env_default_value | Default ENV variable value for Elastic Beanstalk `aws:elasticbeanstalk:application:environment` setting | string | `UNSET` | no |
17+
| env_vars | Map of custom ENV variables to be provided to the Jenkins application running on Elastic Beanstalk, e.g. env_vars = { JENKINS_USER = 'admin' JENKINS_PASS = 'xxxxxx' } | map | `<map>` | no |
18+
| github_branch | GitHub repository branch, e.g. 'master'. By default, this module will deploy 'https://github.com/cloudposse/jenkins' master branch | string | `master` | no |
19+
| github_oauth_token | GitHub Oauth Token for accessing private repositories. Leave it empty when deploying a public 'Jenkins' repository, e.g. https://github.com/cloudposse/jenkins | string | `` | no |
20+
| github_organization | GitHub organization, e.g. 'cloudposse'. By default, this module will deploy 'https://github.com/cloudposse/jenkins' repository | string | `cloudposse` | no |
21+
| github_repo_name | GitHub repository name, e.g. 'jenkins'. By default, this module will deploy 'https://github.com/cloudposse/jenkins' repository | string | `jenkins` | no |
22+
| healthcheck_url | Application Health Check URL. Elastic Beanstalk will call this URL to check the health of the application running on EC2 instances | string | `/login` | no |
23+
| image_tag | Docker image tag in the ECR repository, e.g. 'latest'. Used as CodeBuild ENV variable $IMAGE_TAG when building Docker images. For more info: http://docs.aws.amazon.com/codebuild/latest/userguide/sample-docker.html | string | `latest` | no |
24+
| loadbalancer_certificate_arn | Load Balancer SSL certificate ARN. The certificate must be present in AWS Certificate Manager | string | - | yes |
25+
| loadbalancer_type | Load Balancer type, e.g. 'application' or 'classic' | string | `application` | no |
26+
| master_instance_type | EC2 instance type for Jenkins master, e.g. 't2.medium' | string | `t2.medium` | no |
27+
| name | Solution name, e.g. 'app' or 'jenkins' | string | `jenkins` | no |
28+
| namespace | Namespace, which could be your organization name, e.g. 'cp' or 'cloudposse' | string | - | yes |
29+
| noncurrent_version_expiration_days | Backup S3 bucket noncurrent version expiration days | string | `35` | no |
30+
| private_subnets | List of private subnets to place EC2 instances and EFS | list | - | yes |
31+
| public_subnets | List of public subnets to place Elastic Load Balancer | list | - | yes |
32+
| security_groups | List of security groups to be allowed to connect to the EC2 instances | list | `<list>` | no |
33+
| solution_stack_name | Elastic Beanstalk stack, e.g. Docker, Go, Node, Java, IIS. For more info: http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/concepts.platforms.html | string | `64bit Amazon Linux 2017.09 v2.8.4 running Docker 17.09.1-ce` | no |
34+
| ssh_key_pair | Name of SSH key that will be deployed on Elastic Beanstalk and DataPipeline instance. The key should be present in AWS | string | `` | no |
35+
| stage | Stage, e.g. 'prod', 'staging', 'dev', or 'test' | string | - | yes |
36+
| tags | Additional tags (e.g. `map('BusinessUnit`,`XYZ`) | map | `<map>` | no |
37+
| use_efs_ip_address | | string | `false` | no |
38+
| vpc_id | ID of the VPC in which to provision the AWS resources | string | - | yes |
39+
| zone_id | Route53 parent zone ID. The module will create sub-domain DNS records in the parent zone for the EB environment and EFS | string | - | yes |
40+

0 commit comments

Comments
 (0)