Merge pull request #3085 from uselagoon/k8s_reqs_docs

uselagoon · Apr 6, 2022 · 96d7915 · 96d7915
2 parents a2dc611 + b0346c0
commit 96d7915
Show file tree

Hide file tree

Showing 6 changed files with 118 additions and 93 deletions.
diff --git a/docs/installing-lagoon/efs-provisioner.md b/docs/installing-lagoon/efs-provisioner.md
@@ -5,21 +5,20 @@
 
 1. Add Helm repository: `helm repo add stable https://charts.helm.sh/stable`
 2. Create `efs-provisioner-values.yml` in your config directory and update the values:
+    ```yaml title="efs-provisioner-values.yml"
+    efsProvisioner:
+      efsFileSystemId: <efsFileSystemId>
+      awsRegion: <awsRegion>
+      path: /
+      provisionerName: example.com/aws-efs
+      storageClass:
+        name: bulk
+        isDefault: false
+        reclaimPolicy: Delete
+        mountOptions: []
+    global:
+      deployEnv: prod
 
-```yaml title="efs-provisioner-values.yml"
-efsProvisioner:
-  efsFileSystemId: <efsFileSystemId>
-  awsRegion: <awsRegion>
-  path: /
-  provisionerName: example.com/aws-efs
-  storageClass:
-    name: bulk
-    isDefault: false
-    reclaimPolicy: Delete
-    mountOptions: []
-global:
-  deployEnv: prod
+    ```
 
-```
-
-3\. Install EFS Provisioner:`helm upgrade --install --create-namespace --namespace efs-provisioner -f efs-provisioner-values.yaml  efs-provisioner stable/efs-provisioner`
+3. Install EFS Provisioner:`helm upgrade --install --create-namespace --namespace efs-provisioner -f efs-provisioner-values.yaml  efs-provisioner stable/efs-provisioner`
diff --git a/docs/installing-lagoon/install-harbor.md b/docs/installing-lagoon/install-harbor.md
@@ -3,40 +3,39 @@
 1. Add Helm repo: `helm repo add harbor https://helm.goharbor.io`
 2. Create the file `harbor-values.yml` inside of your config directory:
 
-```yaml title="harbor-values.yml"
-expose:
-  ingress:
-    annotations:
-      kubernetes.io/tls-acme: "true"
-    hosts:
-     core: harbor.lagoon.example.com
-  tls:
-    enabled: true
-    certSource: secret
-    secret:
-      secretName: harbor-harbor-ingress
-externalURL: https://harbor.lagoon.example.com
-harborAdminPassword: <your Harbor Admin Password>
-chartmuseum:
-  enabled: false
-clair:
-  enabled: false
-notary:
-  enabled: false
-trivy:
-  enabled: false
-jobservice:
-  jobLogger: stdout
-registry:
-  replicas: 1
+    ```yaml title="harbor-values.yml"
+    expose:
+      ingress:
+        annotations:
+          kubernetes.io/tls-acme: "true"
+        hosts:
+        core: harbor.lagoon.example.com
+      tls:
+        enabled: true
+        certSource: secret
+        secret:
+          secretName: harbor-harbor-ingress
+    externalURL: https://harbor.lagoon.example.com
+    harborAdminPassword: <your Harbor Admin Password>
+    chartmuseum:
+      enabled: false
+    clair:
+      enabled: false
+    notary:
+      enabled: false
+    trivy:
+      enabled: false
+    jobservice:
+      jobLogger: stdout
+    registry:
+      replicas: 1
 
-```
+    ```
 
-1. Install Harbor:`helm upgrade --install --create-namespace --namespace harbor --wait -f harbor-values.yaml --version=1.5.2 harbor harbor/harbor`
-   1. We are currently using Harbor version 1.5.2. A recent update to Harbor breaks the API.
+1. Install Harbor:`helm upgrade --install --create-namespace --namespace harbor --wait -f harbor-values.yaml --version=1.5.6 harbor harbor/harbor`
+   1. We are currently using Harbor version 1.5.6. A recent update to Harbor (Harbor 2.2) breaks the API.
 2. Visit Harbor at the URL you set in `harbor.yml`.
    1. Username: admin
    2. Password:
        `kubectl -n harbor get secret harbor-harbor-core -o jsonpath="{.data.HARBOR_ADMIN_PASSWORD}" | base64 --decode`
-3. Add the above Harbor credentials to the Lagoon Core `values.yml` that you created at the beginning of the process, as well as `harbor-values.yml`.
-4. Upgrade lagoon-core release with the updated `values.yml` file: `helm upgrade --namespace lagoon-core -f values.yaml lagoon-core lagoon/lagoon-core`
+3. You will need to add the above Harbor credentials to the Lagoon Remote `values.yml` in the next step, as well as `harbor-values.yml`.
diff --git a/docs/installing-lagoon/install-lagoon-remote.md b/docs/installing-lagoon/install-lagoon-remote.md
@@ -3,46 +3,48 @@
 Now we will install Lagoon Remote into the Lagoon namespace. The [RabbitMQ](../docker-images/rabbitmq.md) service is the broker.
 
 1. Create `remote-values.yml` in your config directory as you did the previous two files, and update the values.
-   1. rabbitMQPassword: `kubectl -n lagoon-core get secret lagoon-core-broker -o jsonpath="{.data.RABBITMQ_PASSWORD}" | base64 --decode`
-   2. rabbitMQHostname: `lagoon-core-broker.lagoon-core.svc.local`
-   3. taskSSHHost: `kubectl get service lagoon-core-broker-amqp-ext -o custom-columns="NAME:.metadata.name,IP ADDRESS:.status.loadBalancer.ingress[*].ip,HOSTNAME:.status.loadBalancer.ingress[*].hostname"`
-2. Run `helm upgrade --install --create-namespace --namespace lagoon -f remote-values.yaml  lagoon-remote lagoon/lagoon-remote`
+    * **rabbitMQPassword** `kubectl -n lagoon-core get secret lagoon-core-broker -o jsonpath="{.data.RABBITMQ_PASSWORD}" | base64 --decode`
+    * **rabbitMQHostname** `lagoon-core-broker.lagoon-core.svc.local`
+    * **taskSSHHost** `kubectl get service lagoon-core-broker-amqp-ext -o custom-columns="NAME:.metadata.name,IP ADDRESS:.status.loadBalancer.ingress[*].ip,HOSTNAME:.status.loadBalancer.ingress[*].hostname"`
+    * **harbor-password** `kubectl -n harbor get secret harbor-harbor-core -o jsonpath="{.data.HARBOR_ADMIN_PASSWORD}" | base64 --decode`
+2. Add the Harbor configuration from the previous step.
+3. Run `helm upgrade --install --create-namespace --namespace lagoon -f remote-values.yaml  lagoon-remote lagoon/lagoon-remote`
 
-```yaml title="remote-values.yml"
-lagoon-build-deploy:
-  enabled: true
-  extraArgs:
-    - "--enable-harbor=true"
-    - "--harbor-url=https://harbor.lagoon.example.com"
-    - "--harbor-api=https://harbor.lagoon.example.com/api/"
-    - "--harbor-username=admin"
-    - "--harbor-password=<HarborAdminPassword>"
-  rabbitMQUsername: lagoon
-  rabbitMQPassword: <from lagoon-core-broker secret>
-  rabbitMQHostname: lagoon-core-broker.lagoon-core.svc.cluster.local
-  lagoonTargetName: <name of lagoon remote, can be anything>
-  taskSSHHost: <IP of ssh service loadbalancer>
-  taskSSHPort: "22"
-  taskAPIHost: "api.lagoon.example.com"
-dbaas-operator:
-  enabled: true
+    ```yaml title="lagoon-remote-values.yml"
+    lagoon-build-deploy:
+      enabled: true
+      extraArgs:
+        - "--enable-harbor=true"
+        - "--harbor-url=https://harbor.lagoon.example.com"
+        - "--harbor-api=https://harbor.lagoon.example.com/api/"
+        - "--harbor-username=admin"
+        - "--harbor-password=<from harbor-harbor-core secret>"
+      rabbitMQUsername: lagoon
+      rabbitMQPassword: <from lagoon-core-broker secret>
+      rabbitMQHostname: lagoon-core-broker.lagoon-core.svc.cluster.local
+      lagoonTargetName: <name of lagoon remote, can be anything>
+      taskSSHHost: <IP of ssh service loadbalancer>
+      taskSSHPort: "22"
+      taskAPIHost: "api.lagoon.example.com"
+    dbaas-operator:
+      enabled: true
 
-  mariadbProviders:
-    production:
-      environment: production
-      hostname: 172.17.0.1.nip.io
-      readReplicaHostnames:
-      - 172.17.0.1.nip.io
-      password: password
-      port: '3306'
-      user: root
+      mariadbProviders:
+        production:
+          environment: production
+          hostname: 172.17.0.1.nip.io
+          readReplicaHostnames:
+          - 172.17.0.1.nip.io
+          password: password
+          port: '3306'
+          user: root
 
-    development:
-      environment: development
-      hostname: 172.17.0.1.nip.io
-      readReplicaHostnames:
-      - 172.17.0.1.nip.io
-      password: password
-      port: '3306'
-      user: root
-```
+        development:
+          environment: development
+          hostname: 172.17.0.1.nip.io
+          readReplicaHostnames:
+          - 172.17.0.1.nip.io
+          password: password
+          port: '3306'
+          user: root
+    ```
diff --git a/docs/installing-lagoon/lagoon-backups.md b/docs/installing-lagoon/lagoon-backups.md
@@ -12,6 +12,7 @@ Lagoon uses the k8up backup operator: [https://k8up.io](https://k8up.io). Lagoon
     `kubectl apply -f https://github.com/vshn/k8up/releases/download/v1.1.0/k8up-crd.yaml`
 
     `helm upgrade --install --create-namespace --namespace k8up -f k8up-values.yaml k8up appuio/k8up`
+
 4. Update `lagoon-core-values.yaml`:
 
       ```yaml title="lagoon-core-values.yaml"

diff --git a/docs/installing-lagoon/requirements.md b/docs/installing-lagoon/requirements.md
@@ -11,8 +11,32 @@
 !!! Note "Note:"
     We acknowledge that this is a lot of steps, and our roadmap for the immediate future includes reducing the number of steps in this process.
 
+## Specific requirements (as of March 2022)
+
+### Kubernetes
+Lagoon supports Kubernetes versions 1.19, 1.20 and 1.21. Support for 1.22 is underway, and mostly complete. There are a number of relevant API deprecations in 1.22 that Lagoon utilized across a number of dependencies.
+
+### ingress-nginx
+Lagoon is currently only for a single ingress-nginx controller, and therefore defining an IngressClass has not been necessary.
+
+This means that Lagoon currently works best with version 3 of the ingress-nginx Helm chart - latest release [3.40.0](https://github.com/kubernetes/ingress-nginx/releases/tag/helm-chart-3.40.0).
+
+In order to use a version of the Helm chart (>=4) that supports Ingress v1 (i.e for Kubernetes 1.22), the following configuration should be used, as per [the ingress-nginx docs](https://kubernetes.github.io/ingress-nginx/#what-is-an-ingressclass-and-why-is-it-important-for-users-of-ingress-nginx-controller-now).
+
+- nginx-ingress should be configured as the default controller - set `.controller.ingressClassResource.default: true` in Helm values
+- nginx-ingress should be configured to watch ingresses without IngressClass set - set `.controller.watchIngressWithoutClass: true` in Helm values
+
+This will configure the controller to create any new ingresses with itself as the IngressClass, and also to handle any existing ingresses without an IngressClass set.
+
+Other configurations may be possible, but have not been tested.
+
+### Harbor
+Only Harbor <2.2 is currently supported - the method of retrieving robot accounts was changed in 2.2, and we are working on a fix.
+
+This means you should install Harbor [2.1.6](https://github.com/goharbor/harbor/releases/tag/v2.1.6) with Helm chart [1.5.6](https://github.com/goharbor/harbor-helm/releases/tag/1.5.6).
+
 ## How much Kubernetes experience/knowledge is required?
 
-Lagoon uses some very involved Kubernetes and Cloud Native concepts, and whilst full familiarity may not be necessary to install and configure Lagoon, diagnosing issues and contributing may prove difficult without a good level of familiarity.
+Lagoon uses some very involved Kubernetes and Cloud Native concepts, and while full familiarity may not be necessary to install and configure Lagoon, diagnosing issues and contributing may prove difficult without a good level of familiarity.
 
 As an indicator, comfort with the curriculum for the [Certified Kubernetes Administrator](https://www.cncf.io/certification/cka/) would be suggested as a minimum.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -70,18 +70,18 @@ nav:
   - Environment Idling: using-lagoon-advanced/environment-idling.md
   - Custom Tasks: using-lagoon-advanced/custom-tasks.md
   - DeployTarget Configs: using-lagoon-advanced/deploytarget-configs.md
-  - Blackfire: using-lagoon-advanced/blackfire.md  
+  - Blackfire: using-lagoon-advanced/blackfire.md
 - Installing Lagoon:
   - Requirements: installing-lagoon/requirements.md
-  - Install Lagoon Core: installing-lagoon/lagoon-core.md
-  - Install the Lagoon CLI: installing-lagoon/lagoon-cli.md
-  - Create Lagoon User: installing-lagoon/create-user.md
+  - EFS Provisioner: installing-lagoon/efs-provisioner.md
   - Install Harbor: installing-lagoon/install-harbor.md
+  - Install Lagoon Core: installing-lagoon/lagoon-core.md
   - Install Lagoon Remote: installing-lagoon/install-lagoon-remote.md
+  - Install the Lagoon CLI: installing-lagoon/lagoon-cli.md
   - Querying with GraphQL: installing-lagoon/querying-graphql.md
+  - Create Lagoon User: installing-lagoon/create-user.md
   - Add a Project: installing-lagoon/add-project.md
   - Deploy Your Project: installing-lagoon/deploy-project.md
-  - EFS Provisioner: installing-lagoon/efs-provisioner.md
   - Add Group: installing-lagoon/add-group.md
   - Lagoon Logging: installing-lagoon/lagoon-logging.md
   - OpenDistro: installing-lagoon/opendistro.md