Merge pull request #3175 from uselagoon/storage_docs

Assorted docs updates - requirements and gists
uselagoon · Jun 9, 2022 · 9296f59 · 9296f59
2 parents 49f3eb7 + d31d2ab
commit 9296f59
Show file tree

Hide file tree

Showing 15 changed files with 350 additions and 102 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -6,5 +6,13 @@
   ],
   "git.ignoreLimitWarning": true,
   "javascript.validate.enable": false,
-  "files.trimTrailingWhitespace": true
+  "files.trimTrailingWhitespace": true,
+  "[markdown]": {
+    "editor.tabSize": 2,
+    "editor.autoIndent": "advanced",
+    "editor.formatOnSave": true,
+    "editor.wordWrap": "on",
+    "editor.renderWhitespace": "all",
+    "editor.acceptSuggestionOnEnter": "off"
+  }
 }
diff --git a/docs/installing-lagoon/add-project.md b/docs/installing-lagoon/add-project.md
@@ -3,14 +3,14 @@
 ## Add the project to Lagoon
 
 1. Run this command:
-   ```bash
-   lagoon add project \
-   --gitUrl <YOUR-GITHUB-REPO-URL> \
-   --openshift 1 \
-   --productionEnvironment <YOUR-PROD-ENV> \
-   --branches <THE-BRANCHES-YOU-WANT-TO-DEPLOY> \
-   --project <YOUR-PROJECT-NAME>
-   ```
+    ```bash
+    lagoon add project \
+      --gitUrl <YOUR-GITHUB-REPO-URL> \
+      --openshift 1 \
+      --productionEnvironment <YOUR-PROD-ENV> \
+      --branches <THE-BRANCHES-YOU-WANT-TO-DEPLOY> \
+      --project <YOUR-PROJECT-NAME>
+    ```
       * The value for `--openshift` is the ID of your Kubernetes cluster.
       * Your production environment should be the name of the branch you want to have as your production   environment.
       * The branches you want to deploy might look like this: “^(main|develop)$”
@@ -22,9 +22,9 @@
 Lagoon creates a deploy key for each project. You now need to add it as a deploy key in your Git repository to allow Lagoon to download the code.
 
 1. Run the following command to get the deploy key:
-   ```bash
-   lagoon get project-key --project <YOUR-PROJECT-NAME>
-   ```
+    ```bash
+    lagoon get project-key --project <YOUR-PROJECT-NAME>
+    ```
 2. Copy the key and save it as a deploy key in your Git repository.
 
 [GitHub](https://docs.github.com/en/developers/overview/managing-deploy-keys#deploy-keys){ .md-button }

diff --git a/docs/installing-lagoon/create-user.md b/docs/installing-lagoon/create-user.md
@@ -1,6 +1,9 @@
 # Create Lagoon user
 
-1. Add user via Lagoon CLI: `lagoon add user --email user@example.com --firstName MyFirstName --lastName MyLastName`
+1. Add user via Lagoon CLI:
+    ```bash
+    lagoon add user --email user@example.com --firstName MyFirstName --lastName MyLastName
+    ```
 2. Go to your email and click the password reset link in the email.
 3. Follow the instructions and log in to Lagoon UI with created password.
 4. Add the SSH public key of the user via **Settings**.
diff --git a/docs/installing-lagoon/deploy-project.md b/docs/installing-lagoon/deploy-project.md
@@ -1,11 +1,11 @@
 # Deploy Your Project
 
 1. Run the following command to deploy your project:
-   ```bash
-   lagoon deploy branch -p <YOUR-PROJECT-NAME> -b <YOUR-BRANCH-NAME>
-   ```
+    ```bash
+    lagoon deploy branch -p <YOUR-PROJECT-NAME> -b <YOUR-BRANCH-NAME>
+    ```
 2. Go to the Lagoon UI and take a look at your project - you should now see the environment for this project!
 3. Look in your cluster at your pods list, and you should see the build pod as it begins to clone Git repositories, set up services, etc.
-   ```bash
-   kubectl get pods --all-namespaces | grep lagoon-build
-   ```
+    ```bash
+    kubectl get pods --all-namespaces | grep lagoon-build
+    ```
diff --git a/docs/installing-lagoon/gitlab.md b/docs/installing-lagoon/gitlab.md
@@ -7,23 +7,23 @@ Not needed for \*most\* installs, but this is configured to integrate Lagoon wit
    1. Enable “repository update events”
 3. Update `lagoon-core-values.yaml`:
 
-      ```yaml title="lagoon-core-values.yaml"
-      api:
-        additionalEnvs:
-          GITLAB_API_HOST: <<URL of Gitlab example: https://your-gitlab.com>>
-          GITLAB_API_TOKEN: << Personal Access token with Access to API >>
-          GITLAB_SYSTEM_HOOK_TOKEN: << System Hook Secret Token >>
-      webhook-haondler:
-        additionalEnvs:
-          GITLAB_API_HOST: <<URL of Gitlab example: https://your-gitlab.com>>
-          GITLAB_API_TOKEN: << Personal Access token with Access to API >>
-          GITLAB_SYSTEM_HOOK_TOKEN: << System Hook Secret Token >>
-      webhooks2tasks:
-        additionalEnvs:
-          GITLAB_API_HOST: <<URL of Gitlab example: https://your-gitlab.com>>
-          GITLAB_API_TOKEN: << Personal Access token with Access to API >>
-          GITLAB_SYSTEM_HOOK_TOKEN: << System Hook Secret Token >>
-      ```
+    ```yaml title="lagoon-core-values.yaml"
+    api:
+      additionalEnvs:
+        GITLAB_API_HOST: <<URL of Gitlab example: https://your-gitlab.com>>
+        GITLAB_API_TOKEN: << Personal Access token with Access to API >>
+        GITLAB_SYSTEM_HOOK_TOKEN: << System Hook Secret Token >>
+    webhook-haondler:
+      additionalEnvs:
+        GITLAB_API_HOST: <<URL of Gitlab example: https://your-gitlab.com>>
+        GITLAB_API_TOKEN: << Personal Access token with Access to API >>
+        GITLAB_SYSTEM_HOOK_TOKEN: << System Hook Secret Token >>
+    webhooks2tasks:
+      additionalEnvs:
+        GITLAB_API_HOST: <<URL of Gitlab example: https://your-gitlab.com>>
+        GITLAB_API_TOKEN: << Personal Access token with Access to API >>
+        GITLAB_SYSTEM_HOOK_TOKEN: << System Hook Secret Token >>
+    ```
 
 4. Helm update the `lagoon-core` helmchart
 5. If you've already created users in Keycloak, delete them.

diff --git a/docs/installing-lagoon/install-harbor.md b/docs/installing-lagoon/install-harbor.md
@@ -1,6 +1,9 @@
 # Install Harbor
 
-1. Add Helm repo: `helm repo add harbor https://helm.goharbor.io`
+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"
@@ -32,10 +35,17 @@
 
     ```
 
-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.
+1. Install Harbor, checking the [requirements](./requirements.md#harbor) for the currently supported Harbor versions.:
+    ```
+    helm upgrade --install --create-namespace \
+      --namespace harbor --wait \
+      -f harbor-values.yaml \
+      harbor harbor/harbor
+    ```
 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`
+       ```
+       kubectl -n harbor get secret harbor-harbor-core -o jsonpath="{.data.HARBOR_ADMIN_PASSWORD}" | base64 --decode
+       ```
 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
@@ -2,14 +2,25 @@
 
 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.
-    * **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`
-
+1. Create `lagoon-remote-values.yml` in your config directory as you did the previous two files, and update the values.
+    * **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 [Install Harbor](./install-harbor.md) step.
     ```yaml title="lagoon-remote-values.yml"
     lagoon-build-deploy:
       enabled: true
@@ -48,3 +59,10 @@ Now we will install Lagoon Remote into the Lagoon namespace. The [RabbitMQ](../d
           port: '3306'
           user: root
     ```
+3. Install Harbor:
+    ```
+    helm upgrade --install --create-namespace \
+      --namespace lagoon \
+      -f remote-values.yaml
+      lagoon-remote lagoon/lagoon-remote
+    ```
diff --git a/docs/installing-lagoon/lagoon-backups.md b/docs/installing-lagoon/lagoon-backups.md
@@ -2,16 +2,85 @@
 
 Lagoon uses the k8up backup operator: [https://k8up.io](https://k8up.io). Lagoon isn’t tightly integrated with k8up, it’s more that Lagoon can create its resources in a way that k8up can automatically discover and backup.
 
-1. Create new AWS User with policies: [https://gist.github.com/Schnitzel/1ad9761042c388a523029a2b4ff9ed75](https://gist.github.com/Schnitzel/1ad9761042c388a523029a2b4ff9ed75)
-2. Create `k8up-values.yaml`.\
-   See gist example: [https://gist.github.com/Schnitzel/5b87a9e9ee7c59b2bc6b29f0f0839d56](https://gist.github.com/Schnitzel/5b87a9e9ee7c59b2bc6b29f0f0839d56)
+Lagoon has been extensively tested with k8up 1.x, but is not compatible with 2.x yet. We recommend using the 1.1.0 chart version (App version v1.2.0)
+
+1. Create new AWS User with policies:
+    ```json title="example K8up IAM user"
+    {
+      "Version":"2012-10-17",
+      "Statement":[
+        {
+          "Sid":"VisualEditor0",
+          "Effect":"Allow",
+          "Action":[
+            "s3:ListAllMyBuckets",
+            "s3:CreateBucket",
+            "s3:GetBucketLocation"
+          ],
+          "Resource":"*"
+        },
+        {
+          "Sid":"VisualEditor1",
+          "Effect":"Allow",
+          "Action":"s3:ListBucket",
+          "Resource":"arn:aws:s3:::baas-*"
+        },
+        {
+          "Sid":"VisualEditor2",
+          "Effect":"Allow",
+          "Action":[
+            "s3:PutObject",
+            "s3:GetObject",
+            "s3:AbortMultipartUpload",
+            "s3:DeleteObject",
+            "s3:ListMultipartUploadParts"
+          ],
+          "Resource":"arn:aws:s3:::baas-*/*"
+        }
+      ]
+    }
+    ```
+2. Create `k8up-values.yaml` (customise for your provider):
+    ```yaml title="k8up-values.yaml"
+    k8up:
+      envVars:
+        - name: BACKUP_GLOBALS3ENDPOINT
+          value: 'https://s3.eu-west-1.amazonaws.com'
+        - name: BACKUP_GLOBALS3BUCKET
+          value: ''
+        - name: BACKUP_GLOBALKEEPJOBS
+          value: '1'
+        - name: BACKUP_GLOBALSTATSURL
+          value: 'https://backup.lagoon.example.com'
+        - name: BACKUP_GLOBALACCESSKEYID
+          value: ''
+        - name: BACKUP_GLOBALSECRETACCESSKEY
+          value: ''
+        - name: BACKUP_BACKOFFLIMIT
+          value: '2'
+        - name: BACKUP_GLOBALRESTORES3BUCKET
+          value: ''
+        - name: BACKUP_GLOBALRESTORES3ENDPOINT
+          value: 'https://s3.eu-west-1.amazonaws.com'
+        - name: BACKUP_GLOBALRESTORES3ACCESSKEYID
+          value: ''
+        - name: BACKUP_GLOBALRESTORES3SECRETACCESSKEY
+          value: ''
+      timezone: Europe/Zurich
+    ```
 3. Install k8up:
 
-    `helm repo add appuio https://charts.appuio.ch`
+    ```
+    helm repo add appuio https://charts.appuio.ch
 
-    `kubectl apply -f https://github.com/vshn/k8up/releases/download/v1.1.0/k8up-crd.yaml`
+    kubectl apply -f https://github.com/vshn/k8up/releases/download/v1.2.0/k8up-crd.yaml
 
-    `helm upgrade --install --create-namespace --namespace k8up -f k8up-values.yaml k8up appuio/k8up`
+    helm upgrade --install --create-namespace \
+      --namespace k8up \
+      -f k8up-values.yaml \
+      --version 1.1.0 \
+      k8up appuio/k8up
+    ```
 
 4. Update `lagoon-core-values.yaml`:
 

diff --git a/docs/installing-lagoon/lagoon-cli.md b/docs/installing-lagoon/lagoon-cli.md
@@ -1,8 +1,8 @@
 # Install the Lagoon CLI
 
 1. Install the Lagoon CLI on your local machine:
-   1. Check [https://github.com/amazeeio/lagoon-cli#install](https://github.com/amazeeio/lagoon-cli#install) on how to install for your operating system. For macOS, you can use Homebrew:
-      1. `brew tap amazeeio/lagoon-cli`
+   1. Check [https://github.com/uselagoon/lagoon-cli#install](https://github.com/uselagoon/lagoon-cli#install) on how to install for your operating system. For macOS, you can use Homebrew:
+      1. `brew tap uselagoon/lagoon-cli`
       2. `brew install lagoon`
 2. The CLI needs to know how to communicate with Lagoon, so run the following command:
     `lagoon config add --graphql https://<YOUR-API-URL>/graphql --ui https://YOUR-UI-URL --hostname <YOUR.SSH.IP> --lagoon <YOUR-LAGOON-NAME> --port 22`
@@ -17,4 +17,4 @@
    2. Verify via `lagoon whoami` that you are logged in.
 
 !!! Note "Note:"
-    Note: We don’t generally recommend using the Lagoon Admin role, but you’ll need to create an admin account at first to get started. Ideally, you’ll immediately create another account to work from which is _not_ an admin.
+    Note: We don’t generally recommend using the Lagoon Admin role, but you’ll need to create an admin account at first to get started. Ideally, you’ll immediately create another account to work from which is _not_ an admin.
diff --git a/docs/installing-lagoon/lagoon-core.md b/docs/installing-lagoon/lagoon-core.md
@@ -3,16 +3,16 @@
 ## Install the Helm chart
 
 1. Add Lagoon Charts repository to your Helm Repos:
-   ```bash
-   helm repo add lagoon https://uselagoon.github.io/lagoon-charts/
-   ```
+    ```bash
+    helm repo add lagoon https://uselagoon.github.io/lagoon-charts/
+    ```
 2. Create a directory for the configuration files we will create, and make sure that it’s version controlled. Ensure that you reference this path in commands referencing your `values.yml` files.
 3. Create `values.yml` in the directory you’ve just created. Update the endpoint URLs (change them from api.lagoon.example.com to your values).
    Example: [https://gist.github.com/Schnitzel/58e390bf1b6f93117a37a3eb02e8bae3](https://gist.github.com/Schnitzel/58e390bf1b6f93117a37a3eb02e8bae3)
 4. Now run `helm upgrade --install` command, pointing to `values.yml`, like so:
-   ```bash
-   helm upgrade --install --create-namespace --namespace lagoon-core -f values.yml lagoon-core lagoon/lagoon-core`
-   ```
+    ```bash
+    helm upgrade --install --create-namespace --namespace lagoon-core -f values.yml lagoon-core lagoon/lagoon-core`
+    ```
 5. Lagoon Core is now installed! :tada:
 
 !!! warning "Warning:"
@@ -25,9 +25,9 @@ Visit the Keycloak dashboard at the URL you defined in the `values.yml` for Keyc
 2. Username: `admin`
 3. Password: use `lagoon-core-keycloak` secret, key-value `KEYCLOAK_ADMIN_PASSWORD`
 4. Retrieve the secret like so:`
-   ```bash
-   kubectl -n lagoon-core get secret lagoon-core-keycloak -o jsonpath="{.data.KEYCLOAK_ADMIN_PASSWORD}" | base64 --decode
-   ```
+    ```bash
+    kubectl -n lagoon-core get secret lagoon-core-keycloak -o jsonpath="{.data.KEYCLOAK_ADMIN_PASSWORD}" | base64 --decode
+    ```
 5. Click on **User** on top right.
 	1. Go to **Manage Account.**
 	2. Add an **Email** for the admin account you created.