Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: README changes #1

Open
wants to merge 1 commit into
base: feature/complete_documentation
Choose a base branch
from
Open

docs: README changes #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 72 additions & 37 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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=<cluster_name>' -var 'region=<your_aws_region>' -var 'account_id=<your_aws_account_id>'
```sh
terraform init
terraform apply -var 'cluster_name=<cluster_name>' -var 'region=<your_aws_region>' -var 'account_id=<your_aws_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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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}
Expand All @@ -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 `<subdomain>.<apex_domain>` 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 `<subdomain>.<apex_domain>`, 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

Expand Down