workload-cluster

pages/how-to/set-up/scm-connection.md

@@ -0,0 +1,91 @@
+---
+title: Setting Up an SCM Connection
+description: Connecting Plural to a Source Control Management Provider
+---
+
+# Prerequisites
+* **Plural Console `admin` Permissions**  
+* **SCM Provider Personal Access Token**
+  * [Github](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)  
+  * [GitLab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token)  
+  * [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/access-tokens/)
+* **SCM Provider Organization `admin` Permissions**
+  * This is only required when creating the webhook
+  * The workload cluster can still be created without the SCM webhook
+
+# Set Up
+### Create a New SCM Connection
+* **Navigate to `https://console.[YOUR DOMAIN].onplural.sh/pr/scm`**  
+* **Click the _Create Connection_ Button at the Top Right**  
+![Create SCM Connection Button](/images/how-to/console_create-scm-btn.png)
+
+* **Fil in the Required Fields**
+  * **Provider Type**: The SCM Provider Hosting Git Repositories  
+  * **Name**: Reference Name for the Provider  
+    * ℹ️ **NOTE**: The _cluster-creator_ PR Automation looks for `github` by default
+  * **Token**: The Deploy Token to use  
+
+![Create SCM Connection Modal](/images/how-to/console_create-scm-modal.png)  
+
+### **Create an [`ScmConnection`](https://docs.plural.sh/deployments/operator/api#scmconnection) CRD Instance**  
+Once the connection is created in the UI we can reference it with a CRD instance
+  * ❕ Ensure the Name Provided in the UI matches the `spec.name` in the CRD Exactly
+  * The [`ScmConnection`](https://docs.plural.sh/deployments/operator/api#scmconnection) yaml can be saved in your MGMT Cluster Repo
+  * You can use `kubectl` to apply it to the MGMT cluster 
+```yaml
+apiVersion: deployments.plural.sh/v1alpha1
+kind: ScmConnection
+metadata:
+  name: github
+spec:
+  name: github
+  type: GITHUB
+```
+### **Add an SCM Provider Webhook**
+If you navigate to `https://console.[YOUR DOMAIN].onplural.sh/pr/queue`  
+You'll see even though the SCM connection is complete  
+and the PR is merged the status of the cluster creator PR is still _open_  
+
+We need to add an SCM Webhook to fix this.  
+* **Navigate to `https://console.[YOUR DOMAIN].onplural.sh/pr/scm-webhooks`**  
+* **Click the `Create Webhook` Button**  
+![](/images/how-to/create-scm-webhook-btn.png)
+* **Fill the Required Fields**
+  * **Provider Type**: The SCM Provider Hosting Git Repositories
+      * This may be obvious, but you need to select the same provider as the console webhook
+  * **Owner**: The Organization or Group Within the SCM Provider
+  * **Secret**: The Webhook Secret to Share
+![](/images/how-to/create-scm-webhook-modal-0.png)
+* **Click `Create`**
+    * Copy the Webhook URL and note the secret to use within the SCM Provider Webhook 
+![](/images/how-to/create-scm-webhook-modal-1.png)
+
+
+* **Create the Webhook with the SCM Provider**  
+❕ You Must be an Owner or Have Admin Access to Create Webhooks
+  * [GitHub Organization Webhooks](https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks#creating-an-organization-webhook)
+  * [GitLab Group Webhooks](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#group-webhooks)
+  * [Bitbucket Webhooks](https://confluence.atlassian.com/bitbucketserver/manage-webhooks-938025878.html)
+
+
+
+
+# Troubleshooting
+
+#### Get Kubeconfig for the MGMT Cluster
+```sh
+plural wkspace kube-init
+```
+
+Use `kubectl` with the newly added kube context  
+The key namespaces to check are:   
+* plrl-console
+* plrl-deploy-operator
+* plrl-runtime
+
+#### Check the Status of the SCM Connection
+```sh
+kubectl describe ScmConnection github
+```
+Take note of the status conditions.  
+The Messages will provide failure or success messages.

pages/how-to/set-up/workload-cluster.md

@@ -4,34 +4,43 @@ description: Using Plural CLI to Deploy a Workload Kubernetes Cluster
 ---
 
 # Prerequisites
-[Plural CLI](/how-to/set-up/plural-cli)
+* **[Plural SCM Connection](/how-to/set-up/scm-connection)**
+* **Plural Console `admin` permissions**  
 
-#### Ensure Cloud Provider CLI Authentication
-**Plural** uses the _default_ profile when deploying resources  
-
-AWS  
-```sh
-aws sts get-caller-identity
-```  
-AZ
-```sh
-az account show
-```
-GCP
-```sh
-gcloud auth list
-```
-
-#### Ensure your _[app.plural.sh](https://app.plural.sh/profile/me)_ User has `admin` permissions  
+# Set Up
+### Enable the `Cluster creator` PR Automation
+The Cluster Creator PR Automation CRD is created by default from `plural up`  
+But the [Plural SCM Connection](/how-to/set-up/scm-connection) needs to be instantiated  
+
+### **Create a Workload Cluster**  
+To create a new workload cluster we can use the builtin Plural _cluster-creator_ PR Automation  
+* **Navigate to `https://console.[YOUR DOMAIN].onplural.sh/pr/automations`**  
+* **Click `Create a PR` in the `cluster-creator` Automation Object**  
+![cluster-creator pr button](/images/how-to/cluster-creator-obj.png)
+* **Fill in the Required Fields**  
+  * **Name**: The Name of the Cluster
+  * **Cloud**: Cloud Provider to Deploy the Cluster (Dropdown Menu)
+  * **Fleet**: The Fleet to Associate the cluster
+  * **Tier**: The Tier to Place the Cluster
+![cluster-creator modal 0](/images/how-to/cluster-creator-modal-0.png)
+* **Click `Next`**
+* **Enter the Name of the Branch to Create the PR**
+![cluster-creator modal 1](/images/how-to/cluster-creator-modal-1.png)
+* **Click `Create`**
+  * Optionally [View The PR](https://github.com/pluralsh/plrl-how-to/pull/1) that was created
+![cluster-creator modal 2](/images/how-to/cluster-creator-modal-2.png)
+* **Merge the PR**
+* **Approve the Stack Run changes**
+  * Navigate to `https://console.[YOUR DOMAIN].onplural.sh/staacks`
+* **Click `Pending Approval` Button on the Newly Created Stack** 
+![](/images/how-to/pending-approval-btn.png)
+* **Once Approved the Stack Run will Execute**
 
-```sh
-plural login
-```
 
-# Set Up
-Create first workload cluster with Stacks (should use the cluster-creator PR automation from plural up)
 
 # Troubleshooting
+Adding A GH PR Webhook
+
 #### Get Kubeconfig for the MGMT Cluster
 ```sh
 plural wkspace kube-init

src/NavData.tsx

@@ -120,6 +120,10 @@ const rootNavData: NavMenu = deepFreeze([
                 title: 'Workload Cluster',
                 href: '/how-to/set-up/workload-cluster',
               },
+              {
+                title: 'SCM Connection',
+                href: '/how-to/set-up/scm-connection',
+              },
               {
                 title: 'Controllers',
                 href: '/how-to/set-up/controllers',
@@ -134,24 +138,24 @@ const rootNavData: NavMenu = deepFreeze([
               },
             ],
           },
-          {
-            href: '/how-to/upgrade',
-            title: 'Upgrade',
-            sections: [
-              {
-                title: 'Plural CLI',
-                href: '/how-to/upgrade/plural-cli',
-              },
-              {
-                title: 'MGMT Cluster',
-                href: '/how-to/upgrade/mgmt-cluster',
-              },
-              {
-                title: 'Workload Cluster',
-                href: '/how-to/upgrade/workload-cluster',
-              },
-            ],
-          },
+          // {
+          //   href: '/how-to/upgrade',
+          //   title: 'Upgrade',
+          //   sections: [
+          //     {
+          //       title: 'Plural CLI',
+          //       href: '/how-to/upgrade/plural-cli',
+          //     },
+          //     {
+          //       title: 'MGMT Cluster',
+          //       href: '/how-to/upgrade/mgmt-cluster',
+          //     },
+          //     {
+          //       title: 'Workload Cluster',
+          //       href: '/how-to/upgrade/workload-cluster',
+          //     },
+          //   ],
+          // },
         ],
       },
       {