diff --git a/README.md b/README.md index 9f1f20da..8af6e423 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,33 @@ -A terraform module to create an EKS cluster and all the necessary infrastructure that serves as an alternative to `jx create cluster eks`. +# Jenkins X EKS Module -This module is based on the Terraform EKS cluster that can be found here: https://github.com/terraform-aws-modules/terraform-aws-eks. +This repository contains a Terraform module for creating an EKS cluster and all the necessary infrastructure to install Jenkins X via `jx boot`. +The module generates for this purpose a templated `jx-requirements.yml` which can be passed to `jx boot`. -This module will also create the necessary resources that Jenkins X will need in order to be installed in this cluster using `jx boot` using the generated `jx-requirements.yml` which should be preconfigured with all the resources that were created by this module. +The module makes use of the [Terraform EKS cluster Module](https://github.com/terraform-aws-modules/terraform-aws-eks). -## Assumptions -You want to create an EKS cluster that will be used to install Jenkins X into. +## Assumptions -It's required that both kubectl (>=1.10) and aws-iam-authenticator are installed and on your shell's PATH. +You want to create an EKS cluster for installation of Jenkins X. -## Usage example +Both `kubectl` (>=1.10) and `aws-iam-authenticator` are installed and on your shell's PATH. + +## Usage example This module works with a series of variables with default values, this will let you easily run it with a default configuration for easy prototyping by just providing the following required variables: - terraform init - terraaform apply -var 'cluster_name=' -var 'region=' -var 'account_id=' +```sh +terraform init +terraform apply -var 'cluster_name=' -var 'region=' -var 'account_id=' +``` Full customization of the EKS and Kubernetes modules through the use of this module is still not supported as this is still work in progress. -There are a number of variables that will let you configure some resources for your EKS cluster. +Several variables allow you to configure the resources for your EKS cluster. ### VPC configuration -With these variables you can define a few variables for the VPC that will be created: +The following variables allow you to configure the settings of the generated VPC: +``` variable "vpc_name" { description = "The name of the VPC to be created for the cluster" type = string @@ -40,11 +45,13 @@ With these variables you can define a few variables for the VPC that will be cre type = string default = "10.0.0.0/16" } +``` -### EKS Worker Nodes configration +### EKS Worker Nodes configuration -With these variables you can configure the worker nodes pool for the EKS cluster: +You can configure the EKS worker node pool with the following variables: +``` variable "desired_number_of_nodes" { description = "The desired number of worker nodes to use for the cluster. Defaults to 3" type = number @@ -68,11 +75,13 @@ With these variables you can configure the worker nodes pool for the EKS cluster type = string default = "m5.large" } +``` ### Long Term Storage You can choose whether to create S3 buckets for long term storage and enable them in the generated `jx-requirements.yml` file. +``` variable "enable_logs_storage" { description = "Flag to enable or disable long term storage for logs" type = bool @@ -90,9 +99,11 @@ You can choose whether to create S3 buckets for long term storage and enable the type = bool default = true } +``` If these variables are `true`, after creating the necessary S3 buckets, it will configure the `jx-requirements.yml` file in the following section: +```yaml storage: logs: enabled: ${enable_logs_storage} @@ -103,125 +114,149 @@ If these variables are `true`, after creating the necessary S3 buckets, it will repository: enabled: ${enable_repository_storage} url: s3://${repository_storage_bucket} +``` -### Vault configuration - -With this module, we can choose to create the Vault resources that will be used by Jenkins X. +### Vault configuration -You can enable the creation of the Vault resources with the following variable: +You can choose to create the Vault resources needed by Jenkins X by setting the following variables: +``` variable "create_vault_resources" { description = "Flag to enable or disable the creation of Vault resources by Terraform" type = bool default = false } +``` If `create_vault_resources` is `true`, the `vault_user` variable will be required: +``` variable "vault_user" { type = string default = "" } +``` -### External DNS and Cert Manager +### External DNS and Cert Manager -#### External DNS +#### External DNS You can enable External DNS with the following variable: +``` variable "enable_external_dns" { description = "Flag to enable or disable External DNS in the final `jx-requirements.yml` file" type = bool default = false } +``` If `enable_external_dns` is true, additional configuration will be required: If you want to use a domain with an already existing Route 53 Hosted Zone, you can provide it through the following variable: +``` variable "apex_domain" { description = "Flag to enable or disable long term storage for logs" type = string default = "" } +``` This domain will be configured in the resulting `jx-requirements.yml` file in the following section: +``` ingress: domain: ${domain} ignoreLoadBalancer: true externalDNS: ${enable_external_dns} +``` -If you want use a subdomain and have this script create and configure a new Hosted Zone with DNS delegation, you can provide the following variables: +If you want to use a subdomain and have this script create and configure a new Hosted Zone with DNS delegation, you can provide the following variables: +``` variable "subdomain" { description = "The subdomain to be used added to the apex domain. If subdomain is set, it will be appended to the apex domain in `jx-requirements-eks.yml` file" type = string default = "" } - + variable "create_and_configure_subdomain" { description = "Flag to create an NS record ser for the subdomain in the apex domain's Hosted Zone" type = bool default = false } +``` -By providing these variables, the script will create a new `Route 53` HostedZone that looks like `.` and it will delegate the resolving of DNS to the apex domain. +By providing these variables, the script creates a new `Route 53` HostedZone that looks like `.`, and it delegates the resolving of DNS to the apex domain. This is done by creating a `NS` RecordSet in the apex domain's Hosted Zone with the subdomain's HostedZone nameservers. -This will make sure that the newly created HostedZone for the subdomain is instantly resolveable instead of having to wait for DNS propagation. +This will make sure that the newly created HostedZone for the subdomain is instantly resolvable instead of having to wait for DNS propagation. #### Cert Manager -You can enable Cert Manager in order to use TLS for your cluster through LetsEncrypt with the following variables: +You can enable Cert Manager to use TLS for your cluster through LetsEncrypt with the following variables: +``` variable "enable_tls" { description = "Flag to enable TLS int he final `jx-requirements.yml` file" type = bool default = false } +``` -LetsEncrypt has two environments, `staging` and `production`, the difference is that if you use staging, you will be provided self signed certificates but will not be rate limited while if you use the `production` environment, you will be provided certificates signed by LetsEncrypt but you can be rate limited. +LetsEncrypt has two environments, `staging` and `production`. + If you use staging, you receive self-signed certificates, but you are not rate limited. +If you use the `production` environment, you receive certificates signed by LetsEncrypt, but you can be rate limited. -You can choose to use the `production` environment with the following variable: +You can choose to use the `production` environment with the following variable: +``` variable "production_letsencrypt" { description = "Flag to use the production environment of letsencrypt in the `jx-requirements.yml` file" type = bool default = false } +``` -You will also need to provide a valid email to register your domain in LetsEncrypt: +You need to provide a valid email to register your domain in LetsEncrypt: +``` variable "tls_email" { description = "The email to register the LetsEncrypt certificate with. Added to the `jx-requirements.yml` file" type = string default = "" } - +``` ## Generation of jx-requirements.yml -The final output of running this module will not only be the creation of cloud resources but also, it will generate a valid `jx-requirements.yml` file that will be used by Jenkins X through `jx boot -r jx-requirements.yml`. -The template can be found in: +The final output of running this module will not only be the creation of cloud resources but also the creation of a valid `jx-requirements.yml` file. +You can use this file to install Jenkins X by running: + +```bash + jx boot -r jx-requirements.yml +``` + +The template can be found [here](https://github.com/jenkins-x/terraform-aws-eks-jx/blob/master/jx/jx-requirements.yml.tpl) -https://github.com/jenkins-x/terraform-aws-eks-jx/blob/master/jx/jx-requirements.yml.tpl +## Conditional creation -## Conditional creation -Sometimes you need to have a way to create resources conditionally but Terraform does not allow to use count inside module block, there still isn't a solution for this in this repository but we will be working to allow users to provide their own VPC, subnets etc. +Sometimes you need to have a way to create resources conditionally; however, Terraform does not allow to use `count` inside a module block. +There still isn't a solution for this in this repository, but we will be working to allow users to provide their own VPC, subnets etc. ## FAQ: Frequently Asked Questions ### IAM Roles for Service Accounts -This module will setup a series of IAM Policies and Roles. These roles will be annotated into a few Kubernetes Service accounts. +This module sets up a series of IAM Policies and Roles. These roles will be annotated into a few Kubernetes Service accounts. -This allows us to make use of IAM Roles for Sercive Accounts in order to set fine grained permissions on a pod per pod basis. +This allows us to make use of IAM Roles for Sercive Accounts to set fine-grained permissions on a pod per pod basis. -There still isn't a way to provide your own roles or define other Service Accounts by variables but you can always modify the `eks/terraform/jx/irsa.tf` Terraform file. +There still isn't a way to provide your roles or define other Service Accounts by variables, but you can always modify the `eks/terraform/jx/irsa.tf` Terraform file. ## Generated Documentation -This documentation is being generated with `terraform-docs`: +The following tables are generated with `terraform-docs`: ### Providers