chore: add upgrading infrastructure section

Author: rawlingsj

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

@@ -13,8 +13,8 @@ This section contains links to the various readmes that will help you configure
 
 Jenkins X cluster git repositories use cloud specific Terraform modules you can use to configure your cloud resources.
 
-[GCP](https://github.com/jenkins-x/terraform-google-jx#inputs)
+* <a href="https://github.com/jenkins-x/terraform-google-jx#inputs" class="btn bg-primary text-light">GCP</a>
 
-[AWS](https://github.com/jenkins-x/terraform-aws-eks-jx#inputs)
+* <a href="https://github.com/jenkins-x/terraform-aws-eks-jx#inputs" class="btn bg-primary text-light">AWS</a>
 
-[Azure](https://github.com/jenkins-x/terraform-azurerm-jx#inputs)
+* <a href="https://github.com/jenkins-x/terraform-azurerm-jx#inputs" class="btn bg-primary text-light">Azure</a>

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

@@ -14,15 +14,15 @@ Go to [Google Domains](https://domains.google.com/registrar) and purchase a doma
 
 Create a DNS zone which will contain the managed DNS records.
 
-```
+```bash
 gcloud dns managed-zones create "foo-io" \
     --dns-name "foo.io." \
     --description "Automatically managed zone by kubernetes.io/external-dns" \
     --project foo
 ```
 
 Make a note of the nameservers that were assigned to your new zone.
-```
+```bash
 gcloud dns record-sets list \
     --zone "foo-io" \
     --name "foo.io." \

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

@@ -7,21 +7,21 @@ weight: 35
 
 This section will describe how to enable automated TLS and DNS for your Jenkins X installation.
 
-To achive this we will use a couple of open source projects to help enable automated DNS for applications you 
+To achive this we will use a couple of open source projects to help enable automated DNS for your applications.
 
 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).  
 
-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.
+Jenkins X services will have URLs like `https://hook-jx.bar.foo.io`.  The jx-requirements.yml `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.
 
 To start with we are focussed on GCP but will expand to other cloud providers.
 
 # Google Cloud Platform
 
-## Prerequisits
+## Prerequisites
 
 - cluster created using Jenkins X [GCP Terraform getting started](/docs/v3/getting-started/gke/)
 - own a domain, we will use [Google Domains](https://domains.google.com/registrar/) in this guide but any provider will work
-- latest Jenkins X [upgrade](/docs/v3/guides/upgrade)
+- latest Jenkins X CLI, Infrastructure and Cluster git repository updates [upgrade](/docs/v3/guides/upgrade)
 
 ### Cloud Infrastructure
 First we will configure the cloud infrastructure requirements:
@@ -31,27 +31,27 @@ First we will configure the cloud infrastructure requirements:
 
 To satisfy these requirements go to your infrastructure repository (contains Terraform main.tf) and add to your `values.auto.tfvars` the following:
 
-```values.tf
+```yaml
 parent_domain = "foo.io"
 ```
 
-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.
+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 all using the same parent domain but two clusters using a different subdomain like development.foo.io, staging.foo.io leaving production using just the parent domain foo.io.
 
 To use a subdomain for this cluster add the following configuration:
 
-```values.tf
+```yaml
 subdomain     = "bar"
 ```
 
 Now apply these changes:
 
-```
+```bash
 git add values.auto.tfvars
 git commit -m 'feat: enable DNS cloud resources'
 git push
 ```
 
-```
+```bash
 terraform plan
 terraform apply
 ```
@@ -64,48 +64,48 @@ You can now see your managed zone in GCP [here](https://console.cloud.google.com
 Next we will configure the cluster requirements:
 
 - 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
-- 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
+- Install [cert-manager](https://cert-manager.io/docs/) - Kubernetes 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
 
 To satisfy these requirements go to your cluster repository (contains helmfile.yaml)
 
 Add external-dns to your clusters helmfile.yaml `releases` section:
 
-```
+```bash
 - chart: bitnami/external-dns
 ```
 
 Add cert-manager to your clusters helmfile.yaml `releases` section:
-```
+```bash
 - chart: jetstack/cert-manager
 ```
 
 Next we install
 - a cluster wide [Issuer](https://cert-manager.io/docs/concepts/issuer/) which tells cert-manager how to validate you own your domain
 - a namespaced [Certificate](https://cert-manager.io/docs/concepts/certificate/) to request a TLS certificate for services running in the `jx` namespace
 
-```
+```bash
 - chart: jx3/acme
-  name: tls-jx
-  values:
-  - issuer:
-      enabled: true
-      cluster: true
+  name: acme-jx
 ```
 
 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.
 
 Now install the `acme` chart into any namespace you require TLS, e.g.
-```
+```bash
 - chart: jx3/acme
   name: tls-jx-staging
   namespace: jx-staging
+
 - chart: jx3/acme
   name: tls-jx-production
   namespace: jx-production
 ```
 
-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
-```
+The domain from setting up your infrastructure in step one should appear in the `jx-requirements.yml` of you cluster git repo.  Next configure your TLS options, update your `jx-requirements.yml` with below.
+
+__NOTE__ this is the top level `ingress:` section and __NOT__ in the `environments:` section:
+
+```bash
 ingress:
   domain: bar.foo.io
   externalDNS: false # this is unused and will be deprecated
@@ -120,18 +120,18 @@ When first installing set `tls.production=false` so you use the Lets Encrtpt sta
 
 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.
 
-```
+```bash
 jx gitops helmfile resolve
 ```
 
-```
+```bash
 git add values.auto.tfvars
 git commit -m 'feat: enable DNS cloud resources'
 git push
 ```
 
 Now tail the admin logs and wait for the job to complete
-```
+```bash
 jx admin logs
 ```
 

content/en/docs/v3/guides/upgrade.md

@@ -17,6 +17,31 @@ To upgrade jx subcommand plugins run:
 jx upgrade plugins
 ```
 
+## Infrastructure
+
+If you have used one of the Jenkins X Terraform Git repositories to create and manage your cloud resources then you have two options.
+
+### Terraform manual apply
+
+If you are running the Terraform apply commands yourself then from your infrastructure Git repository run:
+```
+export TF_VAR_jx_bot_username=[your bot username]
+export TF_VAR_jx_bot_token=[your bot token]
+terraform get -update
+terraform plan
+terraform apply
+```
+
+### Terraform Cloud
+If you are using [Terraform Cloud](https://www.terraform.io/) then from your infrastructure Git repository run:
+
+```
+terraform get -update
+git commit -a -m 'chore: upgrade cloud infra'
+git push
+```
+Terraform Cloud should trigger automatically and apply the updates, view the log in Terraform Cloud.
+
 
 ## Cluster