From ae9effd9c08f95a7899c6de63b6aa3df4bdcca44 Mon Sep 17 00:00:00 2001 From: Hardy Ferentschik Date: Wed, 11 Mar 2020 10:52:52 +0100 Subject: [PATCH] feat(docs): Updating README --- CONTRIBUTING.md | 27 ++++++++ Makefile | 8 ++- README.md | 178 ++++++++++++++++++++++++++++++++++++------------ 3 files changed, 169 insertions(+), 44 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..78e6998 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,27 @@ +# Contributing to Transcriptase + +We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's: + +- Reporting a bug +- Discussing the current state of the code +- Submitting a fix +- Proposing new features +- Becoming a maintainer + +## We Develop with Github + +We use github to host code, to track issues and feature requests, as well as accept pull requests. + +## All code changes happen through pull requests + +Pull requests are the best way to propose changes to the codebase and we use the [Github Flow](https://guides.github.com/introduction/flow/index.html). + +1. Fork the repo and create your branch from `master`. +1. If you've added code that should be tested, add tests. +1. Ensure the test suite passes. +1. Make sure your code lints. +1. Issue that pull request! + +## Report bugs using Github Issues] + +We use GitHub issues to track public bugs. Report a bug by opening a new issue [here](https://github.com/jenkins-x/terraform-google-jx/issues). diff --git a/Makefile b/Makefile index 277ccac..877ef5e 100644 --- a/Makefile +++ b/Makefile @@ -8,12 +8,12 @@ help: @grep -h -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' .PHONY: apply -apply: ## Applies Terraform plan +apply: ## Applies Terraform plan w/ auto approve @test -s $(TERRAFORM_VAR_FILE) || { echo "The 'apply' rule assumes that variables are provided $(TERRAFORM_VAR_FILE)"; exit 1; } terraform apply -auto-approve --var-file $(TERRAFORM_VAR_FILE) .PHONY: destroy -destroy: ## Destroys Terraform infrastructure +destroy: ## Destroys Terraform infrastructure w/ auto approve terraform destroy -auto-approve --var-file $(TERRAFORM_VAR_FILE) .PHONY: plan @@ -46,4 +46,8 @@ test-focus: ## Runs focused ShellSpec tests clean: ## Deletes temporary files rm -rf report rm jx-requirements.yml + +.PHONY: markdown-table +markdown-table: ## Creates markdown tables for in- and output of this module + terraform-docs markdown table . \ No newline at end of file diff --git a/README.md b/README.md index 338ba14..5d4b38d 100644 --- a/README.md +++ b/README.md @@ -1,65 +1,159 @@ -# EXPERIMENTAL terraform-google-jx +# Jenkins X GKE Module + ![Build Status](https://img.shields.io/endpoint?url=https%3A%2F%2Fstatusbadge-jx.jenkins-x.live%2Fterraform-google-jx) ![Terraform Version](https://img.shields.io/badge/tf-%3E%3D0.12.0-blue.svg) -## Basic instructions +This repo contains a Module for provisioning a Kubernetes cluster for [Jenkins X](https://jenkins-x.io/) on [Google Cloud](https://cloud.google.com/) using [Terraform](https://www.terraform.io/). -### Terraform Requirements + -This module requires terraform v0.12 and above. +- [What is a Terraform Module](#what-is-a-terraform-module) +- [How do you use this Module](#how-do-you-use-this-module) + - [Prerequisites](#prerequisites) + - [Cluster provisioning](#cluster-provisioning) + - [Inputs](#inputs) + - [Outputs](#outputs) + - [Running `jx boot`](#running-jx-boot) + - [Using a custom domain](#using-a-custom-domain) +- [How do I contribute](#how-do-i-contribute) -``` -terraform { - required_version = ">= 0.12.0" -} -``` + + +## 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](https://www.terraform.io/docs/modules/index.html). + +## 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](https://cloud.google.com/deployment-manager/docs/step-by-step-guide/installation-and-setup). +You need your Google Cloud project id as an input variable for using this Module. -The module can be configured as follows: +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](https://cloud.google.com/sdk/gcloud/reference/auth/application-default/login) by running: + +```bash +gcloud auth application-default login ``` + +Once you have your Google Cloud project set up and you have yourself authenticated via `gcloud`, 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](https://learn.hashicorp.com/terraform/getting-started/install) + +### Cluster provisioning + + +A default Jenkins X ready cluster can be created by creating a _main.tf_ in an empty directory with the following content: + +```terraform module "jx" { - source = "./jx" + source = "jenkins-x/jx/google" - gcp_project = var.gcp_project - region = var.region - zone = var.zone - cluster_name = var.cluster_name - parent_domain = "test.com" + gcp_project = var.gcp_project } ``` -It is possible to template out the jx-requirements.yaml so that `jx boot` can be run directly -against the generated file. +You can then apply this Terraform configuration via: -``` -resource "local_file" "jx-requirements" { - content = templatefile("${path.module}/jx-requirements.yaml.tpl", { - cluster_name = module.jx.cluster_name - gcp_project = module.jx.gcp_project - zone = module.jx.zone - lts_bucket = module.jx.lts_bucket_url - backup_bucket = module.jx.backup_bucket_url - vault_bucket = module.jx.vault_bucket_name - vault_key = module.jx.vault_key - vault_keyring = module.jx.vault_keyring - vault_name = module.jx.vault_name - vault_sa = module.jx.vault_sa - // from variables - version_stream_ref = var.version_stream_ref - version_stream_url = var.version_stream_url - webhook = var.webhook - }) - filename = "${path.module}/jx-requirements.yaml" -} +```bash +terraform init +terraform apply -var gcp_project= ``` -``` +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 current directory which can be used as input to `jx boot`. +Refer to [Running `jx boot`](#running-jx-boot) for more information. +Per default, no custom domain is used. +Instead DNS resolution is via [nip.io](https://nip.io/). +For more information on how to configure and use a custom domain, refer to [Using a custom domain](#using-a-custom-domain). + +If you want to test drive Jenkins X, you should consider setting `force_destroy` to `true`. +This allows you to remove all generated resources altogether when running `terraform destroy`, including any generated buckets with their content. + +The following two paragraphs define the various configuration variables as well as the Module's output variables. + +#### 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 - check https://github.com/jenkins-x/jenkins-x-boot-config/blob/master/systems/velero-backups/templates/default-backup.yaml for defaults | `string` | `"0 * * * *"` | no | +| velero\_ttl | The time allocated that defines the lifetime of a velero backup - check https://github.com/jenkins-x/jenkins-x-boot-config/blob/master/systems/velero-backups/templates/default-backup.yaml for defaults | `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](https://jenkins-x.io/docs/getting-started/setup/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: + +```bash jx boot --requirements jx-requirements.yaml ``` -# Storing State +You have to provide some more required configuration via interactive prompts. +The number of prompts depends on how much you have [pre-configured](#inputs) via your Terraform variables. + +### Using a custom domain + + +Unless you specify the _parent_domain_ [variable](#inputs), your cluster will use [nip.io](https://nip.io/) in order to create publicly resolvable URLs. +Your URLs will be of the form http://\-\.\.nip.io. + +To use your custom domain, you need your own domain and a [Cloud DNS managed zones](https://cloud.google.com/dns/zones). +The DNS name in the managed zone has to match your custom domain name. +The managed zone creates a set of DNS servers which you need to use to configure your DNS settings at 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](https://dnschecker.org/) to check whether your domain settings have propagated. + +When a custom domain is provided, Jenkins X uses [ExternalDNS](https://github.com/kubernetes-sigs/external-dns) together with [cert-manager](https://github.com/jetstack/cert-manager) to create A record entries in your managed zone for the various exposed applications. -Its recommended to store the terraform state in a remote bucket to avoid persisting this to local disk. +## How do I contribute + -TODO +Contributions are very welcome! Check out the [Contribution Guidelines](./CONTRIBUTING.md) for instructions.