Service Catalog Version 0.118.5Last updated in version 0.111.4

Jenkins CI Server

View Source Release Notes

Overview

This service contains code to deploy Jenkins CI Server on AWS.

Jenkins architecture

Features

Deploy Jenkins CI Server
Run Jenkins in an Auto Scaling Group for high availability
Store the JENKINS_HOME directory in an EBS Volume
Take nightly snapshots of the EBS Volume using the ec2-backup scheduled Lambda function
Run an ALB in front of Jenkins so it’s not accessible directly to users
Configure DNS in Route 53 and TLS in AWS Certificate Manager (ACM)
Send all logs and metrics to CloudWatch
Configure alerts in CloudWatch for CPU, memory, and disk space usage
Manage SSH access with IAM groups using ssh-grunt
Manage deployment permissions for the server using IAM roles
OS hardening, including fail2ban, ntp, auto-update, ip-lockdown, and more

Learn

note

This repo is a part of the Gruntwork Service Catalog, a collection of reusable, battle-tested, production ready infrastructure code. If you’ve never used the Service Catalog before, make sure to read How to use the Gruntwork Service Catalog!

CI/ CD Core Concepts: An overview of the core concepts you need to understand what a typical CI/CD pipeline entails for application and infrastructure code, including a sample workflow, infrastructure to support CI/CD, an threat models to consider to protect your infrastructure.
Jenkins Documentation: The official documentation for Jenkins.

Deploy

Non-production deployment (quick start for learning)

If you just want to try this repo out for experimenting and learning, check out the following resources:

examples/for-learning-and-testing folder: The examples/for-learning-and-testing folder contains standalone sample code optimized for learning, experimenting, and testing (but not direct production usage).

Production deployment

If you want to deploy this repo in production, check out the following resources:

examples/for-production folder: The examples/for-production folder contains sample code optimized for direct usage in production. This is code from the Gruntwork Reference Architecture, and it shows you how we build an end-to-end, integrated tech stack on top of the Gruntwork Service Catalog.
How to configure a production-grade CI/CD workflow for application and infrastructure code: step-by-step guide on how to configure CI / CD for your apps and infrastructure.

Sample Usage

Terraform
Terragrunt

main.tf

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S JENKINS MODULE
# ------------------------------------------------------------------------------------------------------

module "jenkins" {

  source = "git::git@github.com:gruntwork-io/terraform-aws-service-catalog.git//modules/mgmt/jenkins?ref=v0.118.5"

  # ----------------------------------------------------------------------------------------------------
  # REQUIRED VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # The domain name used for an SSL certificate issued by the Amazon Certificate
  # Manager (ACM).
  acm_ssl_certificate_domain = <string>

  # The IDs of the subnets in which to deploy the ALB that runs in front of
  # Jenkins. Must be subnets in var.vpc_id.
  alb_subnet_ids = <list(string)>

  # The ID of the AMI to run on the Jenkins server. This should be the AMI build
  # from the Packer template jenkins-ubuntu.json. One of var.ami or
  # var.ami_filters is required. Set to null if looking up the ami with filters.
  ami = <string>

  # Properties on the AMI that can be used to lookup a prebuilt AMI for use with
  # Jenkins. You can build the AMI using the Packer template
  # jenkins-ubuntu.json. Only used if var.ami is null. One of var.ami or
  # var.ami_filters is required. Set to null if passing the ami ID directly.
  ami_filters = <object(
    owners = list(string)
    filters = list(object(
      name   = string
      values = list(string)
    ))
  )>

  # The domain name for the DNS A record to add for Jenkins (e.g.
  # jenkins.foo.com). Must be in the domain managed by var.hosted_zone_id.
  domain_name = <string>

  # The ID of the Route 53 Hosted Zone in which to create a DNS A record for
  # Jenkins.
  hosted_zone_id = <string>

  # The instance type to use for the Jenkins server (e.g. t2.medium)
  instance_type = <string>

  # The ID of the subnet in which to deploy Jenkins. Must be a subnet in
  # var.vpc_id.
  jenkins_subnet_id = <string>

  # The amount of memory to give Jenkins (e.g., 1g or 512m). Used for the -Xms
  # and -Xmx settings.
  memory = <string>

  # The ID of the VPC in which to deploy Jenkins
  vpc_id = <string>

  # ----------------------------------------------------------------------------------------------------
  # OPTIONAL VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # The ARNs of SNS topics where CloudWatch alarms (e.g., for CPU, memory, and
  # disk space usage) should send notifications. Also used for the alarms if the
  # Jenkins backup job fails.
  alarms_sns_topic_arn = []

  # The IP address ranges in CIDR format from which to allow incoming HTTP
  # requests to Jenkins.
  allow_incoming_http_from_cidr_blocks = []

  # The IDs of security groups from which to allow incoming HTTP requests to
  # Jenkins.
  allow_incoming_http_from_security_group_ids = []

  # The IP address ranges in CIDR format from which to allow incoming SSH
  # requests to Jenkins.
  allow_ssh_from_cidr_blocks = []

  # The IDs of security groups from which to allow incoming SSH requests to
  # Jenkins.
  allow_ssh_from_security_group_ids = []

  # How often, in seconds, the backup job is expected to run. This is the same
  # as var.backup_job_schedule_expression, but unfortunately, Terraform offers
  # no way to convert rate expressions to seconds. We add a CloudWatch alarm
  # that triggers if the value of var.backup_job_metric_name and
  # var.backup_job_metric_namespace isn't updated within this time period, as
  # that indicates the backup failed to run.
  backup_job_alarm_period = 86400

  # The name for the CloudWatch Metric the AWS lambda backup job will increment
  # every time the job completes successfully.
  backup_job_metric_name = "jenkins-backup-job"

  # The namespace for the CloudWatch Metric the AWS lambda backup job will
  # increment every time the job completes successfully.
  backup_job_metric_namespace = "Custom/Jenkins"

  # A cron or rate expression that specifies how often to take a snapshot of the
  # Jenkins server for backup purposes. See
  # https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html
  # for syntax details.
  backup_job_schedule_expression = "rate(1 day)"

  # Set to true to backup the Jenkins Server using AWS Data Lifecycle Management
  # Policies.
  backup_using_dlm = true

  # Set to true to backup the Jenkins Server using a Scheduled Lambda Function.
  backup_using_lambda = false

  # The list of IAM actions this Jenkins server should be allowed to do: e.g.,
  # ec2:*, s3:*, etc. This should be the list of IAM permissions Jenkins needs
  # in this AWS account to run builds. These permissions will be added to the
  # server's IAM role for all resources ('*').
  build_permission_actions = []

  # Cloud init scripts to run on the Jenkins server when it is booting. See the
  # part blocks in
  # https://www.terraform.io/docs/providers/template/d/cloudinit_config.html for
  # syntax.
  cloud_init_parts = {}

  # The ID (ARN, alias ARN, AWS ID) of a customer managed KMS Key to use for
  # encrypting log data.
  cloudwatch_log_group_kms_key_id = null

  # The number of days to retain log events in the log group. Refer to
  # https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_log_group#retention_in_days
  # for all the valid values. When null, the log events are retained forever.
  cloudwatch_log_group_retention_in_days = null

  # Tags to apply on the CloudWatch Log Group, encoded as a map where the keys
  # are tag keys and values are tag values.
  cloudwatch_log_group_tags = null

  # Set to true to create a public DNS A record in Route53 for Jenkins.
  create_route53_entry = true

  # A list of custom tags to apply to Jenkins and all other resources.
  custom_tags = {}

  # The default OS user for the Jenkins AMI. For AWS Ubuntu AMIs, which is what
  # the Packer template in jenkins-ubunutu.json uses, the default OS user is
  # 'ubuntu'.
  default_user = "ubuntu"

  # How often this lifecycle policy should be evaluated, in hours.
  dlm_backup_job_schedule_interval = 24

  # The name of the data lifecyle management schedule
  dlm_backup_job_schedule_name = "daily-last-two-weeks"

  # How many snapshots to keep. Must be an integer between 1 and 1000.
  dlm_backup_job_schedule_number_of_snapshots_to_retain = 15

  # A list of times in 24 hour clock format that sets when the lifecyle policy
  # should be evaluated. Max of 1.
  dlm_backup_job_schedule_times = ["03:00"]

  # The ARN of the KMS key used for encrypting the Jenkins EBS volume. The
  # module will grant Jenkins permission to use this key.
  ebs_kms_key_arn = null

  # Whether or not the provide EBS KMS key ARN is a key alias. If providing the
  # key ID, leave this set to false.
  ebs_kms_key_arn_is_alias = false

  # Set to true to enable several basic CloudWatch alarms around CPU usage,
  # memory usage, and disk space usage. If set to true, make sure to specify SNS
  # topics to send notifications to using var.alarms_sns_topic_arn.
  enable_cloudwatch_alarms = true

  # Set to true to add AIM permissions to send logs to CloudWatch. This is
  # useful in combination with
  # https://github.com/gruntwork-io/terraform-aws-monitoring/tree/master/modules/logs/cloudwatch-log-aggregation-scripts
  # to do log aggregation in CloudWatch.
  enable_cloudwatch_log_aggregation = true

  # Set to true to add IAM permissions to send custom metrics to CloudWatch.
  # This is useful in combination with
  # https://github.com/gruntwork-io/terraform-aws-monitoring/tree/master/modules/agents/cloudwatch-agent
  # to get memory and disk metrics in CloudWatch for your Jenkins server.
  enable_cloudwatch_metrics = true

  # Enable ip-lockdown to block access to the instance metadata. Defaults to
  # true.
  enable_ip_lockdown = true

  # Set to true to add IAM permissions for ssh-grunt
  # (https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/ssh-grunt),
  # which will allow you to manage SSH access via IAM groups.
  enable_ssh_grunt = true

  # A list of IAM role ARNs in other AWS accounts that Jenkins will be able to
  # assume to do automated deployment in those accounts.
  external_account_auto_deploy_iam_role_arns = []

  # If you are using ssh-grunt and your IAM users / groups are defined in a
  # separate AWS account, you can use this variable to specify the ARN of an IAM
  # role that ssh-grunt can assume to retrieve IAM group and public SSH key info
  # from that account. To omit this variable, set it to an empty string (do NOT
  # use null, or Terraform will complain).
  external_account_ssh_grunt_role_arn = ""

  # The period, in seconds, over which to measure the CPU utilization percentage
  # for the ASG.
  high_asg_cpu_utilization_period = 60

  # Trigger an alarm if the ASG has an average cluster CPU utilization
  # percentage above this threshold.
  high_asg_cpu_utilization_threshold = 90

  # Sets how this alarm should handle entering the INSUFFICIENT_DATA state.
  # Based on
  # https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data.
  # Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.
  high_asg_cpu_utilization_treat_missing_data = "missing"

  # The period, in seconds, over which to measure the root disk utilization
  # percentage for the ASG.
  high_asg_disk_utilization_period = 60

  # Trigger an alarm if the ASG has an average cluster root disk utilization
  # percentage above this threshold.
  high_asg_disk_utilization_threshold = 90

  # Sets how this alarm should handle entering the INSUFFICIENT_DATA state.
  # Based on
  # https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data.
  # Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.
  high_asg_disk_utilization_treat_missing_data = "missing"

  # The period, in seconds, over which to measure the Memory utilization
  # percentage for the ASG.
  high_asg_memory_utilization_period = 60

  # Trigger an alarm if the ASG has an average cluster Memory utilization
  # percentage above this threshold.
  high_asg_memory_utilization_threshold = 90

  # Sets how this alarm should handle entering the INSUFFICIENT_DATA state.
  # Based on
  # https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data.
  # Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.
  high_asg_memory_utilization_treat_missing_data = "missing"

  # Set to true to make the Jenkins ALB an internal ALB that cannot be accessed
  # from the public Internet. We strongly recommend setting this to true to keep
  # Jenkins more secure.
  is_internal_alb = true

  # The OS device name where the Jenkins EBS volume should be attached
  jenkins_device_name = "xvdh"

  # The OS path where the Jenkins EBS volume should be mounted
  jenkins_mount_point = "/jenkins"

  # The OS user that should be used to run Jenkins
  jenkins_user = "jenkins"

  # Sets how the backup job alarm should handle entering the INSUFFICIENT_DATA
  # state. Based on
  # https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data.
  # Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.
  jenkins_volume_alarm_treat_missing_data = "missing"

  # Set to true to encrypt the Jenkins EBS volume.
  jenkins_volume_encrypted = true

  # The amount of disk space, in GB, to allocate for the EBS volume used by the
  # Jenkins server.
  jenkins_volume_size = 200

  # The type of volume to use for the EBS volume used by the Jenkins server.
  # Must be one of: standard, gp2, io1, sc1, or st1.
  jenkins_volume_type = "gp2"

  # The name of a Key Pair that can be used to SSH to the Jenkins server. Leave
  # blank if you don't want to enable Key Pair auth.
  keypair_name = null

  # Enter the name of the Jenkins server
  name = "jenkins"

  # The type of volume to use for the root disk for Jenkins. Must be one of:
  # standard, gp2, io1, sc1, or st1.
  root_block_device_volume_type = "gp2"

  # The amount of disk space, in GB, to allocate for the root volume of this
  # server. Note that all of Jenkins' data is stored on a separate EBS Volume
  # (see var.jenkins_volume_size), so this root volume is primarily used for the
  # OS, temp folders, apps, etc.
  root_volume_size = 100

  # Set to 'true' to allow the server group role to assume itself. See
  # https://aws.amazon.com/blogs/security/announcing-an-update-to-iam-role-trust-policy-behavior/
  server_iam_role_allow_self_assume = false

  # Maximum session duration (in seconds) that you want to set for the server
  # group role. This setting can have a value from 1 hour to 12 hours. Default
  # is 1 hour (3600s).
  server_iam_role_max_session_duration = 3600

  # When true, precreate the CloudWatch Log Group to use for log aggregation
  # from the EC2 instances. This is useful if you wish to customize the
  # CloudWatch Log Group with various settings such as retention periods and KMS
  # encryption. When false, the CloudWatch agent will automatically create a
  # basic log group to use.
  should_create_cloudwatch_log_group = true

  # If set to true, skip the health check, and start a rolling deployment of
  # Jenkins without waiting for it to initially be in a healthy state. This is
  # primarily useful if the server group is in a broken state and you want to
  # force a deployment anyway.
  skip_health_check = false

  # If you are using ssh-grunt, this is the name of the IAM group from which
  # users will be allowed to SSH to this Jenkins server. This value is only used
  # if enable_ssh_grunt=true.
  ssh_grunt_iam_group = "ssh-grunt-users"

  # If you are using ssh-grunt, this is the name of the IAM group from which
  # users will be allowed to SSH to this Jenkins server with sudo permissions.
  # This value is only used if enable_ssh_grunt=true.
  ssh_grunt_iam_group_sudo = "ssh-grunt-sudo-users"

  # The tenancy of this server. Must be one of: default, dedicated, or host.
  tenancy = "default"

  # Set this variable to true to use Instance Metadata Service Version 1
  # (IMDSv1) for the deployment of Jenkins. Set this variable to false to use
  # IMDSv2. Note that while IMDsv2 is preferred due to its special security
  # hardening, we default to IMDSv1 in order to make legacy migrations easier.
  use_imdsv1 = true

  # When true, all IAM policies will be managed as dedicated policies rather
  # than inline policies attached to the IAM roles. Dedicated managed policies
  # are friendlier to automated policy checkers, which may scan a single
  # resource for findings. As such, it is important to avoid inline policies
  # when targeting compliance with various security standards.
  use_managed_iam_policies = true

}

terragrunt.hcl

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S JENKINS MODULE
# ------------------------------------------------------------------------------------------------------

terraform {
  source = "git::git@github.com:gruntwork-io/terraform-aws-service-catalog.git//modules/mgmt/jenkins?ref=v0.118.5"
}

inputs = {

  # ----------------------------------------------------------------------------------------------------
  # REQUIRED VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # The domain name used for an SSL certificate issued by the Amazon Certificate
  # Manager (ACM).
  acm_ssl_certificate_domain = <string>

  # The IDs of the subnets in which to deploy the ALB that runs in front of
  # Jenkins. Must be subnets in var.vpc_id.
  alb_subnet_ids = <list(string)>

  # The ID of the AMI to run on the Jenkins server. This should be the AMI build
  # from the Packer template jenkins-ubuntu.json. One of var.ami or
  # var.ami_filters is required. Set to null if looking up the ami with filters.
  ami = <string>

  # Properties on the AMI that can be used to lookup a prebuilt AMI for use with
  # Jenkins. You can build the AMI using the Packer template
  # jenkins-ubuntu.json. Only used if var.ami is null. One of var.ami or
  # var.ami_filters is required. Set to null if passing the ami ID directly.
  ami_filters = <object(
    owners = list(string)
    filters = list(object(
      name   = string
      values = list(string)
    ))
  )>

  # The domain name for the DNS A record to add for Jenkins (e.g.
  # jenkins.foo.com). Must be in the domain managed by var.hosted_zone_id.
  domain_name = <string>

  # The ID of the Route 53 Hosted Zone in which to create a DNS A record for
  # Jenkins.
  hosted_zone_id = <string>

  # The instance type to use for the Jenkins server (e.g. t2.medium)
  instance_type = <string>

  # The ID of the subnet in which to deploy Jenkins. Must be a subnet in
  # var.vpc_id.
  jenkins_subnet_id = <string>

  # The amount of memory to give Jenkins (e.g., 1g or 512m). Used for the -Xms
  # and -Xmx settings.
  memory = <string>

  # The ID of the VPC in which to deploy Jenkins
  vpc_id = <string>

  # ----------------------------------------------------------------------------------------------------
  # OPTIONAL VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # The ARNs of SNS topics where CloudWatch alarms (e.g., for CPU, memory, and
  # disk space usage) should send notifications. Also used for the alarms if the
  # Jenkins backup job fails.
  alarms_sns_topic_arn = []

  # The IP address ranges in CIDR format from which to allow incoming HTTP
  # requests to Jenkins.
  allow_incoming_http_from_cidr_blocks = []

  # The IDs of security groups from which to allow incoming HTTP requests to
  # Jenkins.
  allow_incoming_http_from_security_group_ids = []

  # The IP address ranges in CIDR format from which to allow incoming SSH
  # requests to Jenkins.
  allow_ssh_from_cidr_blocks = []

  # The IDs of security groups from which to allow incoming SSH requests to
  # Jenkins.
  allow_ssh_from_security_group_ids = []

  # How often, in seconds, the backup job is expected to run. This is the same
  # as var.backup_job_schedule_expression, but unfortunately, Terraform offers
  # no way to convert rate expressions to seconds. We add a CloudWatch alarm
  # that triggers if the value of var.backup_job_metric_name and
  # var.backup_job_metric_namespace isn't updated within this time period, as
  # that indicates the backup failed to run.
  backup_job_alarm_period = 86400

  # The name for the CloudWatch Metric the AWS lambda backup job will increment
  # every time the job completes successfully.
  backup_job_metric_name = "jenkins-backup-job"

  # The namespace for the CloudWatch Metric the AWS lambda backup job will
  # increment every time the job completes successfully.
  backup_job_metric_namespace = "Custom/Jenkins"

  # A cron or rate expression that specifies how often to take a snapshot of the
  # Jenkins server for backup purposes. See
  # https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html
  # for syntax details.
  backup_job_schedule_expression = "rate(1 day)"

  # Set to true to backup the Jenkins Server using AWS Data Lifecycle Management
  # Policies.
  backup_using_dlm = true

  # Set to true to backup the Jenkins Server using a Scheduled Lambda Function.
  backup_using_lambda = false

  # The list of IAM actions this Jenkins server should be allowed to do: e.g.,
  # ec2:*, s3:*, etc. This should be the list of IAM permissions Jenkins needs
  # in this AWS account to run builds. These permissions will be added to the
  # server's IAM role for all resources ('*').
  build_permission_actions = []

  # Cloud init scripts to run on the Jenkins server when it is booting. See the
  # part blocks in
  # https://www.terraform.io/docs/providers/template/d/cloudinit_config.html for
  # syntax.
  cloud_init_parts = {}

  # The ID (ARN, alias ARN, AWS ID) of a customer managed KMS Key to use for
  # encrypting log data.
  cloudwatch_log_group_kms_key_id = null

  # The number of days to retain log events in the log group. Refer to
  # https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_log_group#retention_in_days
  # for all the valid values. When null, the log events are retained forever.
  cloudwatch_log_group_retention_in_days = null

  # Tags to apply on the CloudWatch Log Group, encoded as a map where the keys
  # are tag keys and values are tag values.
  cloudwatch_log_group_tags = null

  # Set to true to create a public DNS A record in Route53 for Jenkins.
  create_route53_entry = true

  # A list of custom tags to apply to Jenkins and all other resources.
  custom_tags = {}

  # The default OS user for the Jenkins AMI. For AWS Ubuntu AMIs, which is what
  # the Packer template in jenkins-ubunutu.json uses, the default OS user is
  # 'ubuntu'.
  default_user = "ubuntu"

  # How often this lifecycle policy should be evaluated, in hours.
  dlm_backup_job_schedule_interval = 24

  # The name of the data lifecyle management schedule
  dlm_backup_job_schedule_name = "daily-last-two-weeks"

  # How many snapshots to keep. Must be an integer between 1 and 1000.
  dlm_backup_job_schedule_number_of_snapshots_to_retain = 15

  # A list of times in 24 hour clock format that sets when the lifecyle policy
  # should be evaluated. Max of 1.
  dlm_backup_job_schedule_times = ["03:00"]

  # The ARN of the KMS key used for encrypting the Jenkins EBS volume. The
  # module will grant Jenkins permission to use this key.
  ebs_kms_key_arn = null

  # Whether or not the provide EBS KMS key ARN is a key alias. If providing the
  # key ID, leave this set to false.
  ebs_kms_key_arn_is_alias = false

  # Set to true to enable several basic CloudWatch alarms around CPU usage,
  # memory usage, and disk space usage. If set to true, make sure to specify SNS
  # topics to send notifications to using var.alarms_sns_topic_arn.
  enable_cloudwatch_alarms = true

  # Set to true to add AIM permissions to send logs to CloudWatch. This is
  # useful in combination with
  # https://github.com/gruntwork-io/terraform-aws-monitoring/tree/master/modules/logs/cloudwatch-log-aggregation-scripts
  # to do log aggregation in CloudWatch.
  enable_cloudwatch_log_aggregation = true

  # Set to true to add IAM permissions to send custom metrics to CloudWatch.
  # This is useful in combination with
  # https://github.com/gruntwork-io/terraform-aws-monitoring/tree/master/modules/agents/cloudwatch-agent
  # to get memory and disk metrics in CloudWatch for your Jenkins server.
  enable_cloudwatch_metrics = true

  # Enable ip-lockdown to block access to the instance metadata. Defaults to
  # true.
  enable_ip_lockdown = true

  # Set to true to add IAM permissions for ssh-grunt
  # (https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/ssh-grunt),
  # which will allow you to manage SSH access via IAM groups.
  enable_ssh_grunt = true

  # A list of IAM role ARNs in other AWS accounts that Jenkins will be able to
  # assume to do automated deployment in those accounts.
  external_account_auto_deploy_iam_role_arns = []

  # If you are using ssh-grunt and your IAM users / groups are defined in a
  # separate AWS account, you can use this variable to specify the ARN of an IAM
  # role that ssh-grunt can assume to retrieve IAM group and public SSH key info
  # from that account. To omit this variable, set it to an empty string (do NOT
  # use null, or Terraform will complain).
  external_account_ssh_grunt_role_arn = ""

  # The period, in seconds, over which to measure the CPU utilization percentage
  # for the ASG.
  high_asg_cpu_utilization_period = 60

  # Trigger an alarm if the ASG has an average cluster CPU utilization
  # percentage above this threshold.
  high_asg_cpu_utilization_threshold = 90

  # Sets how this alarm should handle entering the INSUFFICIENT_DATA state.
  # Based on
  # https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data.
  # Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.
  high_asg_cpu_utilization_treat_missing_data = "missing"

  # The period, in seconds, over which to measure the root disk utilization
  # percentage for the ASG.
  high_asg_disk_utilization_period = 60

  # Trigger an alarm if the ASG has an average cluster root disk utilization
  # percentage above this threshold.
  high_asg_disk_utilization_threshold = 90

  # Sets how this alarm should handle entering the INSUFFICIENT_DATA state.
  # Based on
  # https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data.
  # Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.
  high_asg_disk_utilization_treat_missing_data = "missing"

  # The period, in seconds, over which to measure the Memory utilization
  # percentage for the ASG.
  high_asg_memory_utilization_period = 60

  # Trigger an alarm if the ASG has an average cluster Memory utilization
  # percentage above this threshold.
  high_asg_memory_utilization_threshold = 90

  # Sets how this alarm should handle entering the INSUFFICIENT_DATA state.
  # Based on
  # https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data.
  # Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.
  high_asg_memory_utilization_treat_missing_data = "missing"

  # Set to true to make the Jenkins ALB an internal ALB that cannot be accessed
  # from the public Internet. We strongly recommend setting this to true to keep
  # Jenkins more secure.
  is_internal_alb = true

  # The OS device name where the Jenkins EBS volume should be attached
  jenkins_device_name = "xvdh"

  # The OS path where the Jenkins EBS volume should be mounted
  jenkins_mount_point = "/jenkins"

  # The OS user that should be used to run Jenkins
  jenkins_user = "jenkins"

  # Sets how the backup job alarm should handle entering the INSUFFICIENT_DATA
  # state. Based on
  # https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data.
  # Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.
  jenkins_volume_alarm_treat_missing_data = "missing"

  # Set to true to encrypt the Jenkins EBS volume.
  jenkins_volume_encrypted = true

  # The amount of disk space, in GB, to allocate for the EBS volume used by the
  # Jenkins server.
  jenkins_volume_size = 200

  # The type of volume to use for the EBS volume used by the Jenkins server.
  # Must be one of: standard, gp2, io1, sc1, or st1.
  jenkins_volume_type = "gp2"

  # The name of a Key Pair that can be used to SSH to the Jenkins server. Leave
  # blank if you don't want to enable Key Pair auth.
  keypair_name = null

  # Enter the name of the Jenkins server
  name = "jenkins"

  # The type of volume to use for the root disk for Jenkins. Must be one of:
  # standard, gp2, io1, sc1, or st1.
  root_block_device_volume_type = "gp2"

  # The amount of disk space, in GB, to allocate for the root volume of this
  # server. Note that all of Jenkins' data is stored on a separate EBS Volume
  # (see var.jenkins_volume_size), so this root volume is primarily used for the
  # OS, temp folders, apps, etc.
  root_volume_size = 100

  # Set to 'true' to allow the server group role to assume itself. See
  # https://aws.amazon.com/blogs/security/announcing-an-update-to-iam-role-trust-policy-behavior/
  server_iam_role_allow_self_assume = false

  # Maximum session duration (in seconds) that you want to set for the server
  # group role. This setting can have a value from 1 hour to 12 hours. Default
  # is 1 hour (3600s).
  server_iam_role_max_session_duration = 3600

  # When true, precreate the CloudWatch Log Group to use for log aggregation
  # from the EC2 instances. This is useful if you wish to customize the
  # CloudWatch Log Group with various settings such as retention periods and KMS
  # encryption. When false, the CloudWatch agent will automatically create a
  # basic log group to use.
  should_create_cloudwatch_log_group = true

  # If set to true, skip the health check, and start a rolling deployment of
  # Jenkins without waiting for it to initially be in a healthy state. This is
  # primarily useful if the server group is in a broken state and you want to
  # force a deployment anyway.
  skip_health_check = false

  # If you are using ssh-grunt, this is the name of the IAM group from which
  # users will be allowed to SSH to this Jenkins server. This value is only used
  # if enable_ssh_grunt=true.
  ssh_grunt_iam_group = "ssh-grunt-users"

  # If you are using ssh-grunt, this is the name of the IAM group from which
  # users will be allowed to SSH to this Jenkins server with sudo permissions.
  # This value is only used if enable_ssh_grunt=true.
  ssh_grunt_iam_group_sudo = "ssh-grunt-sudo-users"

  # The tenancy of this server. Must be one of: default, dedicated, or host.
  tenancy = "default"

  # Set this variable to true to use Instance Metadata Service Version 1
  # (IMDSv1) for the deployment of Jenkins. Set this variable to false to use
  # IMDSv2. Note that while IMDsv2 is preferred due to its special security
  # hardening, we default to IMDSv1 in order to make legacy migrations easier.
  use_imdsv1 = true

  # When true, all IAM policies will be managed as dedicated policies rather
  # than inline policies attached to the IAM roles. Dedicated managed policies
  # are friendlier to automated policy checkers, which may scan a single
  # resource for findings. As such, it is important to avoid inline policies
  # when targeting compliance with various security standards.
  use_managed_iam_policies = true

}

Reference

Inputs
Outputs

Required

acm_ssl_certificate_domainstringrequired

The domain name used for an SSL certificate issued by the Amazon Certificate Manager (ACM).

alb_subnet_idslist(string)required

The IDs of the subnets in which to deploy the ALB that runs in front of Jenkins. Must be subnets in vpc_id.

amistringrequired

The ID of the AMI to run on the Jenkins server. This should be the AMI build from the Packer template jenkins-ubuntu.json. One of ami or ami_filters is required. Set to null if looking up the ami with filters.

ami_filtersobject(…)required

Properties on the AMI that can be used to lookup a prebuilt AMI for use with Jenkins. You can build the AMI using the Packer template jenkins-ubuntu.json. Only used if ami is null. One of ami or ami_filters is required. Set to null if passing the ami ID directly.

Type Details

object({
    # List of owners to limit the search. Set to null if you do not wish to limit the search by AMI owners.
    owners = list(string)

    # Name/Value pairs to filter the AMI off of. There are several valid keys, for a full reference, check out the
    # documentation for describe-images in the AWS CLI reference
    # (https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-images.html).
    filters = list(object({
      name   = string
      values = list(string)
    }))
  })

More Details

Details

     Name/Value pairs to filter the AMI off of. There are several valid keys, for a full reference, check out the
     documentation for describe-images in the AWS CLI reference
     (https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-images.html).

domain_namestringrequired

The domain name for the DNS A record to add for Jenkins (e.g. jenkins.foo.com). Must be in the domain managed by hosted_zone_id.

hosted_zone_idstringrequired

The ID of the Route 53 Hosted Zone in which to create a DNS A record for Jenkins.

instance_typestringrequired

The instance type to use for the Jenkins server (e.g. t2.medium)

jenkins_subnet_idstringrequired

The ID of the subnet in which to deploy Jenkins. Must be a subnet in vpc_id.

memorystringrequired

The amount of memory to give Jenkins (e.g., 1g or 512m). Used for the -Xms and -Xmx settings.

vpc_idstringrequired

The ID of the VPC in which to deploy Jenkins

Optional

alarms_sns_topic_arnlist(string)optional

The ARNs of SNS topics where CloudWatch alarms (e.g., for CPU, memory, and disk space usage) should send notifications. Also used for the alarms if the Jenkins backup job fails.

Default:[]

allow_incoming_http_from_cidr_blockslist(string)optional

The IP address ranges in CIDR format from which to allow incoming HTTP requests to Jenkins.

Default:[]

allow_incoming_http_from_security_group_idslist(string)optional

The IDs of security groups from which to allow incoming HTTP requests to Jenkins.

Default:[]

allow_ssh_from_cidr_blockslist(string)optional

The IP address ranges in CIDR format from which to allow incoming SSH requests to Jenkins.

Default:[]

allow_ssh_from_security_group_idslist(string)optional

The IDs of security groups from which to allow incoming SSH requests to Jenkins.

Default:[]

backup_job_alarm_periodnumberoptional

How often, in seconds, the backup job is expected to run. This is the same as backup_job_schedule_expression, but unfortunately, Terraform offers no way to convert rate expressions to seconds. We add a CloudWatch alarm that triggers if the value of backup_job_metric_name and backup_job_metric_namespace isn't updated within this time period, as that indicates the backup failed to run.

Default:86400

More Details

Details


   One day in seconds

backup_job_metric_namestringoptional

The name for the CloudWatch Metric the AWS lambda backup job will increment every time the job completes successfully.

Default:"jenkins-backup-job"

backup_job_metric_namespacestringoptional

The namespace for the CloudWatch Metric the AWS lambda backup job will increment every time the job completes successfully.

Default:"Custom/Jenkins"

backup_job_schedule_expressionstringoptional

A cron or rate expression that specifies how often to take a snapshot of the Jenkins server for backup purposes. See https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html for syntax details.

Default:"rate(1 day)"

backup_using_dlmbooloptional

Set to true to backup the Jenkins Server using AWS Data Lifecycle Management Policies.

Default:true

backup_using_lambdabooloptional

Set to true to backup the Jenkins Server using a Scheduled Lambda Function.

Default:false

build_permission_actionslist(string)optional

The list of IAM actions this Jenkins server should be allowed to do: e.g., ec2:, s3:, etc. This should be the list of IAM permissions Jenkins needs in this AWS account to run builds. These permissions will be added to the server's IAM role for all resources ('*').

Default:[]

cloud_init_partsmap(object(…))optional

Cloud init scripts to run on the Jenkins server when it is booting. See the part blocks in https://www.terraform.io/docs/providers/template/d/cloudinit_config.html for syntax.

Type Details

map(object({
    filename     = string
    content_type = string
    content      = string
  }))

Default:{}

cloudwatch_log_group_kms_key_idstringoptional

The ID (ARN, alias ARN, AWS ID) of a customer managed KMS Key to use for encrypting log data.

Default:null

cloudwatch_log_group_retention_in_daysnumberoptional

The number of days to retain log events in the log group. Refer to https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_log_group#retention_in_days for all the valid values. When null, the log events are retained forever.

Default:null

cloudwatch_log_group_tagsmap(string)optional

Tags to apply on the CloudWatch Log Group, encoded as a map where the keys are tag keys and values are tag values.

Default:null

create_route53_entrybooloptional

Set to true to create a public DNS A record in Route53 for Jenkins.

Default:true

custom_tagsmap(string)optional

A list of custom tags to apply to Jenkins and all other resources.

Default:{}

default_userstringoptional

The default OS user for the Jenkins AMI. For AWS Ubuntu AMIs, which is what the Packer template in jenkins-ubunutu.json uses, the default OS user is 'ubuntu'.

Default:"ubuntu"

dlm_backup_job_schedule_intervalnumberoptional

How often this lifecycle policy should be evaluated, in hours.

Default:24

dlm_backup_job_schedule_namestringoptional

The name of the data lifecyle management schedule

Default:"daily-last-two-weeks"

dlm_backup_job_schedule_number_of_snapshots_to_retainnumberoptional

How many snapshots to keep. Must be an integer between 1 and 1000.

Default:15

dlm_backup_job_schedule_timeslist(string)optional

A list of times in 24 hour clock format that sets when the lifecyle policy should be evaluated. Max of 1.

Default:

[
"03:00"
]

ebs_kms_key_arnstringoptional

The ARN of the KMS key used for encrypting the Jenkins EBS volume. The module will grant Jenkins permission to use this key.

Default:null

ebs_kms_key_arn_is_aliasbooloptional

Whether or not the provide EBS KMS key ARN is a key alias. If providing the key ID, leave this set to false.

Default:false

enable_cloudwatch_alarmsbooloptional

Set to true to enable several basic CloudWatch alarms around CPU usage, memory usage, and disk space usage. If set to true, make sure to specify SNS topics to send notifications to using alarms_sns_topic_arn.

Default:true

enable_cloudwatch_log_aggregationbooloptional

Set to true to add AIM permissions to send logs to CloudWatch. This is useful in combination with https://github.com/gruntwork-io/terraform-aws-monitoring/tree/master/modules/logs/cloudwatch-log-aggregation-scripts to do log aggregation in CloudWatch.

Default:true

enable_cloudwatch_metricsbooloptional

Set to true to add IAM permissions to send custom metrics to CloudWatch. This is useful in combination with https://github.com/gruntwork-io/terraform-aws-monitoring/tree/master/modules/agents/cloudwatch-agent to get memory and disk metrics in CloudWatch for your Jenkins server.

Default:true

enable_ip_lockdownbooloptional

Enable ip-lockdown to block access to the instance metadata. Defaults to true.

Default:true

enable_ssh_gruntbooloptional

Set to true to add IAM permissions for ssh-grunt (https://github.com/gruntwork-io/terraform-aws-security/tree/master/modules/ssh-grunt), which will allow you to manage SSH access via IAM groups.

Default:true

external_account_auto_deploy_iam_role_arnslist(string)optional

A list of IAM role ARNs in other AWS accounts that Jenkins will be able to assume to do automated deployment in those accounts.

Default:[]

external_account_ssh_grunt_role_arnstringoptional

If you are using ssh-grunt and your IAM users / groups are defined in a separate AWS account, you can use this variable to specify the ARN of an IAM role that ssh-grunt can assume to retrieve IAM group and public SSH key info from that account. To omit this variable, set it to an empty string (do NOT use null, or Terraform will complain).

Default:""

high_asg_cpu_utilization_periodnumberoptional

The period, in seconds, over which to measure the CPU utilization percentage for the ASG.

Default:60

high_asg_cpu_utilization_thresholdnumberoptional

Trigger an alarm if the ASG has an average cluster CPU utilization percentage above this threshold.

Default:90

high_asg_cpu_utilization_treat_missing_datastringoptional

Sets how this alarm should handle entering the INSUFFICIENT_DATA state. Based on https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data. Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.

Default:"missing"

high_asg_disk_utilization_periodnumberoptional

The period, in seconds, over which to measure the root disk utilization percentage for the ASG.

Default:60

high_asg_disk_utilization_thresholdnumberoptional

Trigger an alarm if the ASG has an average cluster root disk utilization percentage above this threshold.

Default:90

high_asg_disk_utilization_treat_missing_datastringoptional

Default:"missing"

high_asg_memory_utilization_periodnumberoptional

The period, in seconds, over which to measure the Memory utilization percentage for the ASG.

Default:60

high_asg_memory_utilization_thresholdnumberoptional

Trigger an alarm if the ASG has an average cluster Memory utilization percentage above this threshold.

Default:90

high_asg_memory_utilization_treat_missing_datastringoptional

Default:"missing"

is_internal_albbooloptional

Set to true to make the Jenkins ALB an internal ALB that cannot be accessed from the public Internet. We strongly recommend setting this to true to keep Jenkins more secure.

Default:true

jenkins_device_namestringoptional

The OS device name where the Jenkins EBS volume should be attached

Default:"xvdh"

jenkins_mount_pointstringoptional

The OS path where the Jenkins EBS volume should be mounted

Default:"/jenkins"

jenkins_userstringoptional

The OS user that should be used to run Jenkins

Default:"jenkins"

jenkins_volume_alarm_treat_missing_datastringoptional

Sets how the backup job alarm should handle entering the INSUFFICIENT_DATA state. Based on https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html#alarms-and-missing-data. Must be one of: 'missing', 'ignore', 'breaching' or 'notBreaching'.

Default:"missing"

jenkins_volume_encryptedbooloptional

Set to true to encrypt the Jenkins EBS volume.

Default:true

jenkins_volume_sizenumberoptional

The amount of disk space, in GB, to allocate for the EBS volume used by the Jenkins server.

Default:200

jenkins_volume_typestringoptional

The type of volume to use for the EBS volume used by the Jenkins server. Must be one of: standard, gp2, io1, sc1, or st1.

Default:"gp2"

keypair_namestringoptional

The name of a Key Pair that can be used to SSH to the Jenkins server. Leave blank if you don't want to enable Key Pair auth.

Default:null

namestringoptional

Enter the name of the Jenkins server

Default:"jenkins"

root_block_device_volume_typestringoptional

The type of volume to use for the root disk for Jenkins. Must be one of: standard, gp2, io1, sc1, or st1.

Default:"gp2"

root_volume_sizenumberoptional

The amount of disk space, in GB, to allocate for the root volume of this server. Note that all of Jenkins' data is stored on a separate EBS Volume (see jenkins_volume_size), so this root volume is primarily used for the OS, temp folders, apps, etc.

Default:100

server_iam_role_allow_self_assumebooloptional

Set to 'true' to allow the server group role to assume itself. See https://aws.amazon.com/blogs/security/announcing-an-update-to-iam-role-trust-policy-behavior/

Default:false

server_iam_role_max_session_durationnumberoptional

Maximum session duration (in seconds) that you want to set for the server group role. This setting can have a value from 1 hour to 12 hours. Default is 1 hour (3600s).

Default:3600

should_create_cloudwatch_log_groupbooloptional

When true, precreate the CloudWatch Log Group to use for log aggregation from the EC2 instances. This is useful if you wish to customize the CloudWatch Log Group with various settings such as retention periods and KMS encryption. When false, the CloudWatch agent will automatically create a basic log group to use.

Default:true

skip_health_checkbooloptional

If set to true, skip the health check, and start a rolling deployment of Jenkins without waiting for it to initially be in a healthy state. This is primarily useful if the server group is in a broken state and you want to force a deployment anyway.

Default:false

ssh_grunt_iam_groupstringoptional

If you are using ssh-grunt, this is the name of the IAM group from which users will be allowed to SSH to this Jenkins server. This value is only used if enable_ssh_grunt=true.

Default:"ssh-grunt-users"

ssh_grunt_iam_group_sudostringoptional

If you are using ssh-grunt, this is the name of the IAM group from which users will be allowed to SSH to this Jenkins server with sudo permissions. This value is only used if enable_ssh_grunt=true.

Default:"ssh-grunt-sudo-users"

tenancystringoptional

The tenancy of this server. Must be one of: default, dedicated, or host.

Default:"default"

use_imdsv1booloptional

Set this variable to true to use Instance Metadata Service Version 1 (IMDSv1) for the deployment of Jenkins. Set this variable to false to use IMDSv2. Note that while IMDsv2 is preferred due to its special security hardening, we default to IMDSv1 in order to make legacy migrations easier.

Default:true

use_managed_iam_policiesbooloptional

When true, all IAM policies will be managed as dedicated policies rather than inline policies attached to the IAM roles. Dedicated managed policies are friendlier to automated policy checkers, which may scan a single resource for findings. As such, it is important to avoid inline policies when targeting compliance with various security standards.

Default:true

alb_arn

The ARN of the ALB deployed in front of Jenkins

alb_dns_name

The DNS name of the ALB deployed in front of Jenkins

alb_hosted_zone_id

The hosted zone ID of the ALB deployed in front of Jenkins

alb_http_listener_arns

The ARNs of just the HTTP ALB listeners of the ALB deployed in front of Jenkins

alb_https_listener_acm_cert_arns

The ARNs of just the HTTPS ALB listeners that usse ACM certs of the ALB deployed in front of Jenkins

alb_https_listener_non_acm_cert_arns

The ARNs of just the HTTPS ALB listeners that use non-ACM certs of the ALB deployed in front of Jenkins

alb_listener_arns

The ARNs of the ALB listeners of the ALB deployed in front of Jenkins

alb_name

The name of the ALB deployed in front of Jenkins

alb_security_group_id

The ID of the security group attached to the ALB deployed in front of Jenkins

backup_lambda_function_arn

backup_lambda_function_name

jenkins_asg_name

The name of the Auto Scaling Group in which Jenkins is running

jenkins_domain_name

The public domain name configured for Jenkins

jenkins_ebs_volume_id

The ID of the EBS Volume that will store the JENKINS_HOME directory

jenkins_iam_role_arn

The ARN of the IAM role attached to the Jenkins EC2 Instance

jenkins_iam_role_id

The ID of the IAM role attached to the Jenkins EC2 Instance

jenkins_security_group_id

The ID of the Security Group attached to the Jenkins EC2 Instance

Overview​

Features​

Learn​

Deploy​

Non-production deployment (quick start for learning)​

Production deployment​

Sample Usage​

Reference​

Required​

Optional​

Overview

Features

Learn

Deploy

Non-production deployment (quick start for learning)

Production deployment

Sample Usage

Reference

Required

Optional