NOTE: While the required minimum Terraform version is 0.12.0, automated CI tests are performed with 0.13 only. The only expected
compatibility issues to be aware of are around provider requirements. For more information see here
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 setup such a project can be found in the Google Cloud Installation and Setup guide.
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 Google Cloud Installation and Setup guide as well.
You can then apply this Terraform configuration via:
terraform init
terraform apply
This creates a cluster within the specified Google Cloud project with all possible configuration options defaulted.
⚠️Note: This example is for getting up and running quickly.
It is not intended for a production cluster.
Refer to Production cluster considerations for things to consider when creating a production cluster.
On completion of terraform apply a jx_requirements output is available which can be used as input to jx boot.
Refer to Running jx boot for more information.
In the default configuration, no custom domain is used.
DNS resolution occurs 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 including 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
apex_domain
The parent / apex domain to be used for the cluster
string
""
no
apex_domain_gcp_project
The GCP project the apex domain is managed by, used to write recordsets for a subdomain if set. Defaults to current project.
string
""
no
apex_domain_integration_enabled
If parent / apex domain is managed in the same
bool
true
no
bucket_location
Bucket location for storage
string
"US"
no
cluster_location
The location (region or zone) in which the cluster master will be created. If you specify a zone (such as us-central1-a), the cluster will be a zonal cluster with a single cluster master. If you specify a region (such as us-west1), the cluster will be a regional cluster with multiple masters spread across zones in the region
string
"us-central1-a"
no
cluster_name
Name of the Kubernetes cluster to create
string
""
no
cluster_network
The name of the network (VPC) to which the cluster is connected
string
"default"
no
cluster_subnetwork
The name of the subnetwork to which the cluster is connected. Leave blank when using the 'default' vpc to generate a subnet for your cluster
string
""
no
create_ui_sa
Whether the service accounts for the UI should be created
bool
true
no
dev_env_approvers
List of git users allowed to approve pull request for dev enviornment repository
list(string)
[]
no
enable_backup
Whether or not Velero backups should be enabled
bool
false
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
gsm
Enables Google Secrets Manager, not available with JX2
bool
false
no
jenkins_x_namespace
Kubernetes namespace to install Jenkins X in
string
"jx"
no
jx2
Is a Jenkins X 2 install
bool
true
no
jx_bot_token
Bot token used to interact with the Jenkins X cluster git repository
string
""
no
jx_bot_username
Bot username used to interact with the Jenkins X cluster git repository
string
""
no
jx_git_url
URL for the Jenins X cluster git repository
string
""
no
kuberhealthy
Enables Kuberhealthy helm installation
bool
true
no
lets_encrypt_production
Flag to determine wether or not to use the Let's Encrypt production server.
bool
true
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_disk_type
Node disk type, either pd-standard or pd-ssd
string
"pd-standard"
no
node_machine_type
Node type for the Kubernetes cluster
string
"n1-standard-2"
no
node_preemptible
Use preemptible nodes
bool
false
no
parent_domain
**Deprecated** Please use apex_domain variable instead.r
string
""
no
parent_domain_gcp_project
**Deprecated** Please use apex_domain_gcp_project variable instead.
Zone in which to create the cluster (deprecated, use cluster_location instead)
string
""
no
Outputs
Name
Description
backup_bucket_url
The URL to the bucket for backup storage
cluster_location
The location of the created Kubernetes cluster
cluster_name
The name of the created Kubernetes cluster
connect
The cluster connection string to use once Terraform apply finishes
externaldns_dns_name
ExternalDNS name
externaldns_ns
ExternalDNS nameservers
gcp_project
The GCP project in which the resources got created
jx_requirements
The jx-requirements rendered output
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 artifact storage
tekton_sa_email
The Tekton service account email address, useful to provide further IAM bindings
tekton_sa_name
The Tekton service account name, useful to provide further IAM bindings
vault_bucket_url
The URL to the bucket for secret storage
Running jx boot
A terraform output (jx_requirements) is available after applying this Terraform module.
terraform output jx_requirements
This jx_requirements output 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.
⚠️Note: The generated jx-requirements is only used for the first run of jx boot.
During this first run of jx boot a git repository containing the source code for Jenkins X Boot is created.
This (new) repository contains a jx-requirements.yml (which is now ahead of the jx-requirements output from terraform) used by successive runs of jx boot.
Execute:
terraform output jx_requirements ><some_empty_dir>/jx-requirements.yml
# jenkins-x creates the environment repository directory localy before pushing to the Git server of choicecd<some_empty_dir>
jx boot --requirements jx-requirements.yml
You are prompted for any further required configuration.
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 variablesapex_domain and tls_email.
apex_domain is the fully qualified domain name you want to use and tls_email is the email address you want to use for issuing Let's Encrypt TLS certificates.
Before you apply 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 apex_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.
Production cluster considerations
The configuration as seen in Cluster provisioning is not suited for creating and maintaining a production Jenkins X cluster.
The following is a list of considerations for a production usecase.
Specify the version attribute of the module, for example:
module"jx" {
source ="jenkins-x/jx/google"
version ="1.2.4"# insert your configuration
}
output"jx_requirements" {
value =module.jx.jx_requirements
}
Specifying the version ensures that you are using a fixed version and that version upgrades cannot occur unintented.
Keep the Terraform configuration under version control, by creating a dedicated repository for your cluster configuration or by adding it to an already existing infrastructure repository.
Setup a Terraform backend to securely store and share the state of your cluster. For more information refer to Configuring a Terraform backend.
Configuring a Terraform backend
A "backend" in Terraform determines how state is loaded and how an operation such as apply is executed.
By default, Terraform uses the local backend which keeps the state of the created resources on the local file system.
This is problematic since sensitive information will be stored on disk and it is not possible to share state across a team.
When working with Google Cloud a good choice for your Terraform backend is the gcs backend which stores the Terraform state in a Google Cloud Storage bucket.
The examples directory of this repository contains configuration examples for using the gcs backed with and without optionally configured customer supplied encryption key.
To use the gcs backend you will need to create the bucket upfront.
You can use gsutil to create the bucket:
gsutil mb gs://<my-bucket-name>/
It is also recommended to enable versioning on the bucket as an additional safety net in case of state corruption.
gsutil versioning set on gs://<my-bucket-name>
You can verify whether a bucket has versioning enabled via:
gsutil versioning get gs://<my-bucket-name>
FAQ
How do I get the latest version of the terraform-google-jx module
terraform init -upgrade
How to I specify a specific google provider version
The recommended way to authenticate to the Google Cloud API is by using a service account.
This allows for authentication regardless of where your code runs.
This Terraform module expects authentication via a service account key.
You can either specify the path to this key directly using the GOOGLE_APPLICATION_CREDENTIALS environment variable or you can run gcloud auth application-default login.
In the latter case gcloud obtains user access credentials via a web flow and puts them in the well-known location for Application Default Credentials (ADC), usually ~/.config/gcloud/application_default_credentials.json.
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
This can be executed on demand whenever a release is required.
For the script to work the envrionment variable $GH_TOKEN must be exported and reference a valid GitHub API token.
请发表评论