Prod 2450/how to use plural docs #289

seemywingz · 2024-07-29T19:47:19Z

Summary

Add How To for plural up , adding a workload cluster, scm connection, controllers and a few placeholders

Labels

enhancement

Test Plan

Viwed changes locally with yarn dev

Checklist

If required, I have updated the Plural documentation accordingly.
I have added tests to cover my changes.
I have added a meaningful title and summary to convey the impact of this PR to a user.
[x I have added relevant labels to this PR to help with categorization for release notes.

linear · 2024-07-29T19:47:21Z

PROD-2450 How To Use Plural Docs

netlify · 2024-07-29T19:47:37Z

✅ Deploy Preview for pluraldocs ready!

Name	Link
🔨 Latest commit	`0733854`
🔍 Latest deploy log	https://app.netlify.com/sites/pluraldocs/deploys/66f0549b1bc93a00087a7fe2
😎 Deploy Preview	https://deploy-preview-289--pluraldocs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

seemywingz · 2024-07-29T19:51:35Z

I added the docs for How To/Set Up a New MGMT Cluster, I also added installing the Plural CLI and Console. there are also placeholders for How To/Use which I think are useful

the placeholders are not added in the NavData

michaeljguarino · 2024-07-29T19:49:07Z

pages/how-to/set-up/new-mgmt-cluster.md

+```
+
+
+### Create a New Repo for Plural


We shouldn't recommend they do this, instead let plural up create the repo for them, which it does via oauth (and explain it can be cloned first if they can't do that due to permissioning constraints).

michaeljguarino · 2024-07-29T19:49:39Z

pages/how-to/set-up/new-mgmt-cluster.md

+### Get Kubeconfig for the MGMT Cluster
+AWS 
+```sh
+aws eks update-kubeconfig --name [CLUSTER_NAME] 


plural wkspace kube-init does that for you actually

this is really cool!
I didn't know this feature existed

michaeljguarino · 2024-07-29T19:50:47Z

pages/how-to/set-up/new-mgmt-cluster.md

+
+##### Add the RBAC Helm Values in the MGMT Cluster Repo
+```sh
+./helm-values/ConsoleClusterRoleBindings.yaml


do not put this in the helm-values folder, that's git-crypted by default so should only be used for secret-ish things, create a new global service in a separate folder for rbac which contains this. Also don't camel-case filenames for k8s resources (not standard convention)

I reference that Here: https://github.com/pluralsh/documentation/blob/main/pages/deployments/dashboard.md

should the doc just link to that or reiterate what the RBAC readme says?

I think this looks and reads better:

and links to: https://github.com/pluralsh/documentation/blob/main/pages/deployments/dashboard.md

seemywingz · 2024-07-30T16:08:45Z

@michaeljguarino I made the requested changes

michaeljguarino

High level comments:

honestly feel like the docs for setting up a management cluster should probably just link to our already thorough docs elsewhere
there's a lot of incomplete content here I don't think we can merge and expose publicly

src/NavData.tsx

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

michaeljguarino · 2024-08-27T01:36:17Z

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

+
+##### Creating an RBAC Service
+* **Create an `rbac` dir in your MGMT repo 
+and add the desired [k8s yaml](https://github.com/pluralsh/documentation/blob/main/pages/deployments/dashboard.md)** 


relative link

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

michaeljguarino · 2024-08-27T01:41:24Z

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

+  type: GITHUB
+```
+### **Add an SCM Provider Webhook**
+If you navigate to `https://console.[YOUR DOMAIN].onplural.sh/pr/queue`  


make these link urls: https://{your-console-domain}/pr/queue (most serious users bring their own domain)

michaeljguarino · 2024-08-27T01:42:07Z

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

+
+# Troubleshooting
+
+#### Get Kubeconfig for the MGMT Cluster


don't make them troubleshoot w/ kubectl, they should be able to see this info in the CD ui (can also add the kubectl command as an addendum but should not be the primary flow as it's user-unfriendly)

michaeljguarino · 2024-08-27T01:42:44Z

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

+
+
+
+# Troubleshooting


michaeljguarino · 2024-08-27T01:43:34Z

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

+![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`


use console urls formatted as above

michaeljguarino · 2024-08-27T01:44:22Z

pages/how-to/upgrade/plural-cli.md

@@ -0,0 +1,28 @@
+---
+title: Upgrading the Plural CLI


don't think we need these docs or at least not here if it's going to rabbithole users

michaeljguarino · 2024-08-28T13:22:50Z

pages/how-to/set-up/controllers.md

+* **Add a new `HelmRepository` CRD to your _infra_ repo `./apps/repositories`**
+  * Example: `ingress-nginx.yaml`
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1beta2


This should use the native helm support not flux-based now that that's fully released. So this resource isn't necessary, and the repository field in the helm block below can just be replaced withurl pointing to the url in this CRD

michaeljguarino · 2024-08-28T13:26:23Z

src/NavData.tsx

+                href: '/how-to/set-up/workload-cluster',
+              },
+              {
+                title: 'SCM Connection',


you'll need to set up the scm connection before the workload cluster since it's a prereq. Also many users aren't going to understand the acronym, this should be titled something like Source Control Integration or something like that.

michaeljguarino · 2024-08-28T13:27:40Z

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

+# 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)  


For github we should strongly nudge people to configure it via a github application which is technically more secure and not bound to a specific user.

michaeljguarino · 2024-08-28T13:27:52Z

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

+* **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)  


This should use group or project tokens not personal tokens

michaeljguarino · 2024-08-28T13:28:05Z

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

+* **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/)


same, bitbucket has repo and org tokens that can be used

…s actually happening, corrects some mistakes and fixes the controller setup docs.

seemywingz added 7 commits July 25, 2024 12:31

add initial How To

363b131

adding more how-to placeholders

cac27f5

adding more how-to placeholders

b1e0cf5

adding more how-to placeholders

9bc5a64

add plural-cli

3573de1

mgmt cluster

fd804f7

cloud auth

3356e70

seemywingz added the enhancement label Jul 29, 2024

seemywingz requested a review from a team July 29, 2024 19:47

seemywingz self-assigned this Jul 29, 2024

seemywingz requested a review from a team as a code owner July 29, 2024 19:47

michaeljguarino reviewed Jul 29, 2024

View reviewed changes

seemywingz added 4 commits July 29, 2024 15:52

console

dc3e517

PR comment fixes

e70614e

repo creation updates

700d0a7

rm repo creation block

c5b3996

seemywingz added 6 commits July 30, 2024 15:58

add other setup and upgrade docs

4fa859b

update services and global services

cb340dd

workload-cluster

0a3170e

nginx controller

fbac381

update controllers

b750083

ext dns

52201c3

michaeljguarino reviewed Aug 27, 2024

View reviewed changes

seemywingz added 3 commits August 27, 2024 12:29

addressing comments

6ae0dc3

addressing comments

8fccb66

addressing comments

f638675

seemywingz added 4 commits August 27, 2024 12:54

addressing comments

e2e711b

addressing comments

a3c6c96

addressing comments

d677a3d

addressing comments

327b983

michaeljguarino reviewed Aug 28, 2024

View reviewed changes

michaeljguarino force-pushed the PROD-2450/how-to-use-plural-docs branch 2 times, most recently from e874933 to 5aa334e Compare September 22, 2024 17:19

Major surgery on the how-to guides. Adds a lot more color as to what'…

0733854

…s actually happening, corrects some mistakes and fixes the controller setup docs.

michaeljguarino force-pushed the PROD-2450/how-to-use-plural-docs branch from 5aa334e to 0733854 Compare September 22, 2024 17:32

michaeljguarino approved these changes Sep 22, 2024

View reviewed changes

michaeljguarino merged commit 99df69d into main Sep 22, 2024
8 of 9 checks passed

michaeljguarino deleted the PROD-2450/how-to-use-plural-docs branch September 22, 2024 17:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Prod 2450/how to use plural docs #289

Prod 2450/how to use plural docs #289

seemywingz commented Jul 29, 2024 •

edited

Loading

linear bot commented Jul 29, 2024

netlify bot commented Jul 29, 2024 •

edited

Loading

seemywingz commented Jul 29, 2024 •

edited

Loading

michaeljguarino Jul 29, 2024

michaeljguarino Jul 29, 2024

seemywingz Jul 29, 2024

michaeljguarino Jul 29, 2024

seemywingz Jul 29, 2024 •

edited

Loading

seemywingz Jul 29, 2024

seemywingz Jul 29, 2024 •

edited

Loading

seemywingz commented Jul 30, 2024

michaeljguarino left a comment

michaeljguarino Aug 27, 2024

seemywingz Aug 27, 2024

michaeljguarino Aug 27, 2024

michaeljguarino Aug 27, 2024 •

edited

Loading

michaeljguarino Aug 27, 2024

michaeljguarino Aug 27, 2024

michaeljguarino Aug 27, 2024

michaeljguarino Aug 28, 2024

michaeljguarino Aug 28, 2024

michaeljguarino Aug 28, 2024

michaeljguarino Aug 28, 2024

michaeljguarino Aug 28, 2024

Prod 2450/how to use plural docs #289

Prod 2450/how to use plural docs #289

Conversation

seemywingz commented Jul 29, 2024 • edited Loading

Summary

Labels

Test Plan

Checklist

linear bot commented Jul 29, 2024

netlify bot commented Jul 29, 2024 • edited Loading

✅ Deploy Preview for pluraldocs ready!

seemywingz commented Jul 29, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

seemywingz Jul 29, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

seemywingz Jul 29, 2024 • edited Loading

Choose a reason for hiding this comment

seemywingz commented Jul 30, 2024

michaeljguarino left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

michaeljguarino Aug 27, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

seemywingz commented Jul 29, 2024 •

edited

Loading

netlify bot commented Jul 29, 2024 •

edited

Loading

seemywingz commented Jul 29, 2024 •

edited

Loading

seemywingz Jul 29, 2024 •

edited

Loading

seemywingz Jul 29, 2024 •

edited

Loading

michaeljguarino Aug 27, 2024 •

edited

Loading