Skip to content

Commit e0335bf

Browse files
rawlingsjjenkins-x-bot
rawlingsj
authored and
jenkins-x-bot
committed
docs: add docs for enabling automated TLS and DNS for v3 on GCP
1 parent 3d8dbcf commit e0335bf

File tree

4 files changed

+201
-0
lines changed

4 files changed

+201
-0
lines changed

‎content/en/docs/v3/guides/infra/cloud-config.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: Cloud Configuration
3+
linktitle: Cloud Configuration
4+
description: How to configure cloud infrastructure
5+
weight: 25
6+
---
7+
8+
There are many configuration options of your cloud infrastructure for example cluster size, regions and resource names to name a few. Depending on your cloud provider and what method you have used to create the cloud resources there are various ways to apply these configuration changes for cloud resources.
9+
10+
This section contains links to the various readmes that will help you configure __cloud infrastructure resources__, note this is different to Jenkins X own configuration changes which are detailed [here](/docs/v3/guides/config/).
11+
12+
# Terraform
13+
14+
Jenkins X cluster git repositories use cloud specific Terraform modules you can use to configure your cloud resources.
15+
16+
[GCP](https://github.com/jenkins-x/terraform-google-jx#inputs)
17+
18+
[AWS](https://github.com/jenkins-x/terraform-aws-eks-jx#inputs)
19+
20+
[Azure](https://github.com/jenkins-x/terraform-azurerm-jx#inputs)

‎content/en/docs/v3/guides/infra/google_cloud_dns.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Configure Google Cloud DNS to manage my domain
3+
linktitle: Configure Google Cloud DNS to manage my domain
4+
description: Configure Google Cloud DNS to manage my domain
5+
weight: 100
6+
---
7+
8+
This guide will describe how to purchase a domain and configure GCP to manage it with [Cloud DNS](https://cloud.google.com/dns)
9+
10+
11+
Setup below is a cut down version of the original docs located [here](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/tutorials/gke.md#gke-node-scopes)
12+
13+
Go to [Google Domains](https://domains.google.com/registrar) and purchase a domain.
14+
15+
Create a DNS zone which will contain the managed DNS records.
16+
17+
```
18+
gcloud dns managed-zones create "foo-io" \
19+
--dns-name "foo.io." \
20+
--description "Automatically managed zone by kubernetes.io/external-dns" \
21+
--project foo
22+
```
23+
24+
Make a note of the nameservers that were assigned to your new zone.
25+
```
26+
gcloud dns record-sets list \
27+
--zone "foo-io" \
28+
--name "foo.io." \
29+
--type NS \
30+
--project foo
31+
```
32+
33+
In this case it's ns-cloud-{e1-e4}.googledomains.com. but your's could slightly differ, e.g. {a1-a4}, {b1-b4} etc.
34+
35+
Update google domains DNS settings and update the nameservers with the list of nameservers from the above step making sure to remove the last dot.
36+
e.g. in google domains enter the nameservers without the "." suffix
37+
`ns-cloud-e1.googledomains.com`
38+
not
39+
`ns-cloud-e1.googledomains.com.`
40+
41+
![Edit Nameservers GCP](/images/v3/google_domains.png)

‎content/en/docs/v3/guides/infra/tls_dns.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
title: TLS and DNS
3+
linktitle: TLS and DNS
4+
description: Automated TLS and DNS
5+
weight: 35
6+
---
7+
8+
This section will describe how to enable automated TLS and DNS for your Jenkins X installation.
9+
10+
To achive this we will use a couple of open source projects to help enable automated DNS for applications you
11+
12+
For this guide we are going to assume you own a domain called `foo.io` which is managed by Google Cloud DNS, if it is not see [configure cloud dns to manage a domain](/docs/v3/guides/infra/google_cloud_dns).
13+
14+
Jenkins X services will have URLs like `https://hook-jx.bar.foo.io`. The jx-requirement.yaml `namespaceSubDomain:` of `-jx` refers to the Kubernetes namespace the service is running in, this helps avoid clashes of the same application running in different namespaces in the same cluster.
15+
16+
To start with we are focussed on GCP but will expand to other cloud providers.
17+
18+
# Google Cloud Platform
19+
20+
## Prerequisits
21+
22+
- cluster created using Jenkins X [GCP Terraform getting started](/docs/v3/getting-started/gke/)
23+
- own a domain, we will use [Google Domains](https://domains.google.com/registrar/) in this guide but any provider will work
24+
- latest Jenkins X [upgrade](/docs/v3/guides/upgrade)
25+
26+
### Cloud Infrastructure
27+
First we will configure the cloud infrastructure requirements:
28+
29+
- a GCP Service Account with the `dns.admin` role, see [here](https://cloud.google.com/iam/docs/understanding-roles#dns-roles) for more information
30+
- a managed cloud dns zone, see [here](https://cloud.google.com/dns/docs/zones) for more information
31+
32+
To satisfy these requirements go to your infrastructure repository (contains Terraform main.tf) and add to your `values.auto.tfvars` the following:
33+
34+
```values.tf
35+
parent_domain = "foo.io"
36+
```
37+
38+
Most people prefer to use a subdomain for a specific installation rather than purchasing one domain per cluster. For example in a multi cluster setup you will probably want the same parent domain but each cluster using a differnt subdomain like development.foo.io, staging.foo.io and foo.io.
39+
40+
To use a subdomain for this cluster add the following configuration:
41+
42+
```values.tf
43+
subdomain = "bar"
44+
```
45+
46+
Now apply these changes:
47+
48+
```
49+
git add values.auto.tfvars
50+
git commit -m 'feat: enable DNS cloud resources'
51+
git push
52+
```
53+
54+
```
55+
terraform plan
56+
terraform apply
57+
```
58+
59+
You can now see your managed zone in GCP [here](https://console.cloud.google.com/net-services/dns/zones)
60+
61+
62+
### Cluster
63+
64+
Next we will configure the cluster requirements:
65+
66+
- Install [external-dns](https://github.com/kubernetes-sigs/external-dns#externaldns) - Kubernetes controller which watches for new Kubernetes Ingress resources and creates A records in Google Cloud DNS which will propogate globally across the internet
67+
- Install [cert-manager](https://cert-manager.io/docs/) - Kuberbetes controller which watches for requests to ask [Let's Encrypt](https://letsencrypt.org/) to issue a new wildcard TLS certificate for your domain and will manage this including renewals
68+
69+
To satisfy these requirements go to your cluster repository (contains helmfile.yaml)
70+
71+
Add external-dns to your clusters helmfile.yaml `releases` section:
72+
73+
```
74+
- chart: bitnami/external-dns
75+
```
76+
77+
Add cert-manager to your clusters helmfile.yaml `releases` section:
78+
```
79+
- chart: jetstack/cert-manager
80+
```
81+
82+
Next we install
83+
- a cluster wide [Issuer](https://cert-manager.io/docs/concepts/issuer/) which tells cert-manager how to validate you own your domain
84+
- a namespaced [Certificate](https://cert-manager.io/docs/concepts/certificate/) to request a TLS certificate for services running in the `jx` namespace
85+
86+
```
87+
- chart: jx3/acme
88+
name: tls-jx
89+
values:
90+
- issuer:
91+
enabled: true
92+
cluster: true
93+
```
94+
95+
Cert-manager will use the cluster issuer to request a TLS certificate for each namespaces [Certificate](https://cert-manager.io/docs/concepts/certificate/) found. The advantage here is that the same wildcard certificate is cached and reused for multiple namespaces reducing the risk of being [rate limited](https://letsencrypt.org/docs/rate-limits/) by Lets Encrypt.
96+
97+
Now install the `acme` chart into any namespace you require TLS, e.g.
98+
```
99+
- chart: jx3/acme
100+
name: tls-jx-staging
101+
namespace: jx-staging
102+
- chart: jx3/acme
103+
name: tls-jx-production
104+
namespace: jx-production
105+
```
106+
107+
The domain from setting up your infrastructure in step one should appear in the `jx-requirements.yaml` of you cluster git repo. Next configure your TLS options, update your `jx-requirements.yaml` with
108+
```
109+
ingress:
110+
domain: bar.foo.io
111+
externalDNS: false # this is unused and will be deprecated
112+
namespaceSubDomain: -jx.
113+
tls:
114+
email: "[email protected]"
115+
enabled: true
116+
production: false
117+
```
118+
119+
When first installing set `tls.production=false` so you use the Lets Encrtpt staging serivce which allows for more API calls before rate limniting requests. They will issue a self-signed certificate so once happy everything is working change this to `tls.production=true`
120+
121+
Jenkins X uses a version stream to rollout tested versions of images, charts and default configuration. The `jx-boot` job will apply these versions to your helmfile but you can also run the step yourself to see the defaults.
122+
123+
```
124+
jx gitops helmfile resolve
125+
```
126+
127+
```
128+
git add values.auto.tfvars
129+
git commit -m 'feat: enable DNS cloud resources'
130+
git push
131+
```
132+
133+
Now tail the admin logs and wait for the job to complete
134+
```
135+
jx admin logs
136+
```
137+
138+
## How to get TLS in my preview environment?
139+
140+
In your applications preview helm chart you can add a Kubernetes [Certificate](https://cert-manager.io/docs/concepts/certificate/) the same as in your `jx` namespace and cert-manager will create the secret needed by an Ingress rule for TLS.

‎static/images/v3/google_domains.png‎

324 KB
Loading

0 commit comments

Comments
 (0)