Jenkins X GKE Module

This repo contains a Terraform Module for provisioning a Kubernetes cluster for Jenkins X on Google Cloud.

What is a Terraform Module
How do you use this Module
Development
- Releasing
How do I contribute

What is a Terraform Module

A Terraform Module refers to a self-contained package of Terraform configurations that are managed as a group. For more information around Modules refer to the Terraform documentation.

How do you use this Module

Prerequisites

To make use of this Module, you need a Google Cloud project. Instructions on how to do this can be found here. You need your Google Cloud project id as an input variable for using this Module.

You also need to install the Cloud SDK, in particular gcloud. You find instructions on how to install and authenticate in the documentation mentioned above.

Once you have gcloud installed, you need to create Application Default Credentials by running:

gcloud auth application-default login

Last but not least, ensure you have the following binaries installed:

gcloud
kubectl ~> 1.14.0
- kubectl comes bundled with the Cloud SDK
terraform ~> 0.12.0
- Terraform installation instruction can be found here

Cluster provisioning

A default Jenkins X ready cluster can be provisioned by creating a file main.tf in an empty directory with the following content:

module "jx" {
  source  = "jenkins-x/jx/google"

  gcp_project = "<my-gcp-project-id>"
}

You can then apply this Terraform configuration via:

terraform init
terraform apply

This creates a cluster within the specified Google Cloud project with all names and settings defaulted. The default cluster name is jenkins-x. On completion of terraform apply there will also be a jx-requirements.yaml in the working directory which can be used as input to jx boot. Refer to Running jx boot for more information. Per default, no custom domain is used. Instead DNS resolution is via nip.io. For more information on how to configure and use a custom domain, refer to Using a custom domain.

If you just want to experiment with Jenkins X, you can set force_destroy to true. This allows you to remove all generated resources when running terraform destroy, including any generated buckets with their content.

The following two paragraphs provide the full list of configuration and output variables of this Terraform Module.

Inputs

Name	Description	Type	Default	Required
cluster_name	Name of the K8s cluster to create	`string`	`"jenkins-x"`	no
dev_env_approvers	List of git users allowed to approve pull request for dev enviornment repository	`list(string)`	`[]`	no
force_destroy	Flag to determine whether storage buckets get forcefully destroyed	`bool`	`false`	no
gcp_project	The name of the GCP project to use	`string`	n/a	yes
git_owner_requirement_repos	The git id of the owner for the requirement repositories	`string`	`""`	no
max_node_count	Maximum number of cluster nodes	`number`	`5`	no
min_node_count	Minimum number of cluster nodes	`number`	`3`	no
node_disk_size	Node disk size in GB	`string`	`"100"`	no
node_machine_type	Node type for the K8s cluster	`string`	`"n1-standard-2"`	no
parent_domain	The parent domain to be allocated to the cluster	`string`	`""`	no
tls_email	Email used by Let's Encrypt. Required for TLS when parent_domain is specified.	`string`	`""`	no
velero_schedule	The Velero backup schedule in cron notation to be set in the Velero Schedule CRD (see default-backup.yaml)	`string`	`"0 * * * *"`	no
velero_ttl	The the lifetime of a velero backup to be set in the Velero Schedule CRD (see default-backup.yaml)	`string`	`"720h0m0s"`	no
version_stream_ref	The git ref for version stream to use when booting Jenkins X. See https://jenkins-x.io/docs/concepts/version-stream/	`string`	`"master"`	no
version_stream_url	The URL for the version stream to use when booting Jenkins X. See https://jenkins-x.io/docs/concepts/version-stream/	`string`	`"https://github.com/jenkins-x/jenkins-x-versions.git"`	no
webhook	Jenkins X webhook handler for git provider	`string`	`"prow"`	no
zone	Zone in which to create the cluster	`string`	`"us-central1-a"`	no

Outputs

Name	Description
backup_bucket_url	The URL to the bucket for backup storage
cluster_name	The name of the created K8s cluster
gcp_project	The GCP project in which the resources got created in
log_storage_url	The URL to the bucket for log storage
report_storage_url	The URL to the bucket for report storage
repository_storage_url	The URL to the bucket for artefact storage
vault_bucket_url	The URL to the bucket for secret storage
zone	The zone of the created K8s cluster

Running `jx boot`

As an output of applying this Terraform Module a jx-requirements.yaml file is generated in the current directory. This file can be used as input to Jenkins X Boot which is responsible for installing all the required Jenkins X components into the cluster created by this Module.

Copy the generated jx-requirements.yaml into an empty directory, change into this directory and execute:

jx boot --requirements jx-requirements.yaml

You have to provide some more required configuration via interactive prompts. The number of prompts depends on how much you have pre-configured via your Terraform variables.

Using a custom domain

If you want to use a custom domain with your Jenkins X installation, you need to provide values for the variables parent_domain and tls_email. parent_domain is the fully qualified domain name you want to use and tls_email is the email you want to use for issuing Let's Encrypt TLS certificates.

Before you run the Terraform configuration, you also need to create a Cloud DNS managed zone, with the DNS name in the managed zone matching your custom domain name, for example in the case of example.jenkins-x.rocks as domain:

When creating the managed zone, a set of DNS servers get created which you need to specify in the DNS settings of your DNS registrar.

It is essential that before you run jx boot, your DNS servers settings are propagated, and your domain resolves. You can use DNS checker to check whether your domain settings have propagated.

When a custom domain is provided, Jenkins X uses ExternalDNS together with cert-manager to create A record entries in your managed zone for the various exposed applications.

If parent_domain id not set, your cluster will use nip.io in order to create publicly resolvable URLs of the form http://<app-name>-<environment-name>.<cluster-ip>.nip.io.

Development

Releasing

At the moment there is no release pipeline defined in jenkins-x.yml. A Terraform release does not require building an artifact, only a tag needs to be created and pushed. To make this task easier and there is a helper script release.sh which simplifies this process and creates the changelog as well:

./scripts/release.sh <release-version>

This can be executed on demand whenever a release is required.

How do I contribute

Contributions are very welcome! Check out the Contribution Guidelines for instructions.

tomhobson/terraform-google-jx