Docs for Plural Cloud (#486)

Make docs changes to highlight and further explain benefits of Plural Cloud, and guide users to it as the default.

Author: michaeljguarino

Makefile

@@ -9,6 +9,9 @@ yarn-install: .PHONY
 web: ## runs the docs site locally
 	yarn dev
 
+routes:
+	yarn generate:route-index
+
 sync-docs: sync-console-crd-docs sync-operator-crd-docs sync-liquid-docs
 
 sync-console-crd-docs:

generated/routes.json

@@ -25,19 +25,19 @@
   },
   "/getting-started/first-steps": {
     "relPath": "/getting-started/first-steps/index.md",
-    "lastmod": "2025-03-12T14:59:41.000Z"
+    "lastmod": "2025-07-14T14:28:27.000Z"
   },
   "/getting-started/first-steps/cli-quickstart": {
     "relPath": "/getting-started/first-steps/cli-quickstart.md",
-    "lastmod": "2025-05-08T12:32:16.000Z"
+    "lastmod": "2025-07-14T14:28:27.000Z"
   },
   "/getting-started/first-steps/existing-cluster": {
     "relPath": "/getting-started/first-steps/existing-cluster.md",
     "lastmod": "2025-03-27T19:09:28.000Z"
   },
   "/getting-started/first-steps/plural-cloud": {
     "relPath": "/getting-started/first-steps/plural-cloud.md",
-    "lastmod": "2025-03-12T14:59:41.000Z"
+    "lastmod": "2025-07-14T14:28:27.000Z"
   },
   "/getting-started/how-to-use": {
     "relPath": "/getting-started/how-to-use/index.md",
@@ -53,23 +53,23 @@
   },
   "/getting-started/how-to-use/scm-connection": {
     "relPath": "/getting-started/how-to-use/scm-connection.md",
-    "lastmod": "2025-03-12T14:59:41.000Z"
+    "lastmod": "2025-07-14T14:28:27.000Z"
   },
   "/getting-started/how-to-use/workload-cluster": {
     "relPath": "/getting-started/how-to-use/workload-cluster.md",
     "lastmod": "2025-03-12T14:59:41.000Z"
   },
   "/getting-started/how-to-use/controllers": {
     "relPath": "/getting-started/how-to-use/controllers.md",
-    "lastmod": "2025-03-12T14:59:41.000Z"
+    "lastmod": "2025-07-14T14:28:27.000Z"
   },
   "/getting-started/how-to-use/observability": {
     "relPath": "/getting-started/how-to-use/observability.md",
-    "lastmod": "2025-03-12T14:59:41.000Z"
+    "lastmod": "2025-07-14T14:28:27.000Z"
   },
   "/getting-started/how-to-use/microservice": {
     "relPath": "/getting-started/how-to-use/microservice.md",
-    "lastmod": "2025-03-12T14:59:41.000Z"
+    "lastmod": "2025-07-14T14:28:27.000Z"
   },
   "/getting-started/how-to-use/pr-automation": {
     "relPath": "/getting-started/how-to-use/pr-automation.md",
@@ -79,6 +79,10 @@
     "relPath": "/getting-started/how-to-use/pipelines.md",
     "lastmod": "2025-03-12T14:59:41.000Z"
   },
+  "/getting-started/how-to-use/cleaning-up": {
+    "relPath": "/getting-started/how-to-use/cleaning-up.md",
+    "lastmod": "2025-07-14T14:28:27.000Z"
+  },
   "/getting-started/advanced-config": {
     "relPath": "/getting-started/advanced-config/index.md",
     "lastmod": "2025-03-12T14:59:41.000Z"
@@ -373,7 +377,7 @@
   },
   "/getting-started/quickstart": {
     "relPath": "/getting-started/first-steps/index.md",
-    "lastmod": "2025-03-12T14:59:41.000Z"
+    "lastmod": "2025-07-14T14:28:27.000Z"
   },
   "/deployments/architecture": {
     "relPath": "/overview/architecture.md",
@@ -389,15 +393,15 @@
   },
   "/deployments/cli-quickstart": {
     "relPath": "/getting-started/first-steps/cli-quickstart.md",
-    "lastmod": "2025-05-08T12:32:16.000Z"
+    "lastmod": "2025-07-14T14:28:27.000Z"
   },
   "/deployments/existing-cluster": {
     "relPath": "/getting-started/first-steps/existing-cluster.md",
     "lastmod": "2025-03-27T19:09:28.000Z"
   },
   "/getting-started/deployments": {
     "relPath": "/getting-started/first-steps/index.md",
-    "lastmod": "2025-03-12T14:59:41.000Z"
+    "lastmod": "2025-07-14T14:28:27.000Z"
   },
   "/how-to/set-up/mgmt-cluster": {
     "relPath": "/getting-started/how-to-use/mgmt-cluster.md",
@@ -409,23 +413,23 @@
   },
   "/how-to/set-up/scm-connection": {
     "relPath": "/getting-started/how-to-use/scm-connection.md",
-    "lastmod": "2025-03-12T14:59:41.000Z"
+    "lastmod": "2025-07-14T14:28:27.000Z"
   },
   "/how-to/set-up/workload-cluster": {
     "relPath": "/getting-started/how-to-use/workload-cluster.md",
     "lastmod": "2025-03-12T14:59:41.000Z"
   },
   "/how-to/set-up/controllers": {
     "relPath": "/getting-started/how-to-use/controllers.md",
-    "lastmod": "2025-03-12T14:59:41.000Z"
+    "lastmod": "2025-07-14T14:28:27.000Z"
   },
   "/how-to/deploy/pr-automation": {
     "relPath": "/getting-started/how-to-use/pr-automation.md",
     "lastmod": "2025-03-12T14:59:41.000Z"
   },
   "/how-to/deploy/microservice": {
     "relPath": "/getting-started/how-to-use/microservice.md",
-    "lastmod": "2025-03-12T14:59:41.000Z"
+    "lastmod": "2025-07-14T14:28:27.000Z"
   },
   "/how-to/deploy/pipelines": {
     "relPath": "/getting-started/how-to-use/pipelines.md",

pages/getting-started/first-steps/cli-quickstart.md

@@ -12,6 +12,12 @@ This guide goes over how to deploy your services with the Plural CLI. At the end
 - Deployed your code onto your clusters of choice.
 - Optionally updated any configurations and permissions for the clusters and services.
 
+{% callout severity="info" %}
+If you want to get started quickly or want us to manage the Plural experience for you, we strongly recommend using [Plural Cloud](/getting-started/first-steps/plural-cloud).
+
+We'll handle hosting Plural for you, but also it comes with automatic integration with Github and observability with Elastic and Prometheus set up by default.  It should seriously reduce DevOps TCO, especially for resource-constrained teams.
+{% /callout %}
+
 ## Install the Plural CLI
 
 The Plural CLI is available on Homebrew, a single line installation can be done with:

pages/getting-started/first-steps/index.md

@@ -17,14 +17,15 @@ The general process of setting up your instance is pretty straightforward, and w
 
 We think the easiest way to understand the workflow is to take a look at our intro video (It is about 14 minutes long):
 
-{% embed url="https://www.youtube.com/watch?v=caDlvskRkAw&ab_channel=Plural" aspectRatio="16 / 9" /%}
+{% embed url="https://www.youtube.com/watch?v=sEb_gflm-ME" aspectRatio="16 / 9" /%}
 
-This will give you a brief tour of using the `plural up` command to set up your management cluster, which you can use directly or can use as a starting point to rework the exact setup needed for your enterprise given security constraints and other considerations for your environment.
+This goes over the setup process for using Plural Cloud in particular, and also shows the `plural up` command and how it connects to your Plural Cloud instance.  That said the workflow is very similar for self-hosted installs as well.
 
 ## Getting Started Docs
 
 We also have thorough documentation to explain how to get your cluster up and running. We recommend using the following:
 
+- {% doclink to="getting_started_first_steps_plural_cloud" %}Plural Cloud Quickstart{% /doclink %} - Explains how to get started quickly with Plural Cloud, ans some of the features it provides.
 - {% doclink to="getting_started_first_steps_cli_quickstart" %}CLI Quickstart{% /doclink %} - details of how to install the Plural Console either on an existing cluster using helm or also guides you through the `plural up` process.
 - {% doclink to="getting_started_first_steps_existing_cluster" %}Import An Existing Cluster{% /doclink %} - some of the main ways to import a cluster you've created into Plural's fleet manager. The main method is to simply use our CLI or to use our terraform provider.
 - [Terraform Docs](https://registry.terraform.io/providers/pluralsh/plural/latest/docs) - docs for our terraform provider.

pages/getting-started/first-steps/plural-cloud.md

@@ -10,7 +10,16 @@ Plural Cloud provides a hybrid deployment model where we take over management of
 * Shared - your cloud instance is hosted on a set of shared k8s clusters and shared postgres servers for minimal cost
 * Dedicated - your cloud instance gets a dedicated k8s cluster and database, allowing maximal scalability and isolating your data fully from other tenants
 
-One key differentiated aspect of the hybrid Plural architecture is we can manage infrastructure *in your cloud* without requiring us to *store your keys on our servers*.  This is due to the fact that the Plural control plane stores all declarative state of what needs to be deployed, but the actual action is performed by our agent that runs in either the management cluster or the leaf clusters you'll create at the end of the onboarding process.  Those clusters are usually wired with best practice cloud IAM solutions like EKS IRSA or GKE Workload Identity.
+One key differentiated aspect of the hybrid Plural architecture is we can manage infrastructure *in your cloud* without requiring us to *store your keys on our servers*.  This is due to the fact that the Plural control plane stores all declarative state of what needs to be deployed, but the actual action is performed by our agent that runs in either the management cluster or the leaf clusters you'll create in your cloud environment.  Those clusters are usually wired with best practice cloud IAM solutions like EKS IRSA or GKE Workload Identity.
+
+In addition, Plural Cloud comes with these key integrations built in by default:
+
+* Log aggregation - ultimately persisted to elasticsearch and hosted by us with logstash preconfigured
+* Scale-out Prometheus - fully compliant prometheus api, again hosted by us, with vmetrics agent preconfgured by us
+* AI - we automatically provide a working ai endpoint for your environment
+* Github Integration - you can simply install our Github App and immediately use Plural to generate PRs and other SCM-related tasks
+
+These are not terribly hard to provision in our self-hosted version either, but they do need to be managed by the user in each case.
 
 # Setup
 
@@ -23,24 +32,45 @@ Once you select Plural Cloud, you'll see a wizard like the below:
 ![](/assets/getting-started/cloud-wizard.png)
 
 
-After filling out the wizard, it'll take about 2-3 minutes to instantiate your cluster, from there, you'll need to perform two more steps, both of which will be explained in a modal in your new cloud instance:
+After filling out the wizard, it'll take about 2-3 minutes to instantiate your cluster, from there, you'll be given a wizard to finalize the setup of your instance.
 
-* create an access token for the Plural CLI to use
-* run `plural up --cloud`
+## Setup Wizard
 
+The setup wizard will cover two main things:
+
+* Setting up a connection to your SCM provider.  The default is to install our Github App, which is the easiest overall flow, but you can provide an access token manually as well.
+* Setting up a webhook against your SCM provider.  This is used to gather statuses of PRs and for the [Pull Request Workflow](/plural-features/stacks-iac-management/pr-workflow) for Plural Stacks.
+* instructing your to run `plural up --cloud` to set up your initial management cluster.
 
 ## The "plural up --cloud" command
 
-The `plural up --cloud` command will handle a few things:
+The `plural up --cloud` command will initialize a git repository and run a sequence of terraform commands to connect your cloud environment to Plural cloud. In particular, it will:
 
-* Setting up an initial GitOps repo with our default, production ready configurations.  This includes a ton of useful stuff, including:
+* Set up an initial GitOps repo with our default, production ready configurations.  This includes a ton of useful stuff, including:
     - initializes a service-of-services structure to set up full GitOps management
     - initializes the Plural Service Catalog, with quick deployments and configuration of a lot of useful tools, like a dev + prod eks fleet, elasticsearch for logging, scale out prometheus with victoria metrics, and Grafana backed by RDS
     - is the assumed repo structure for the [How to Use Plural Guide](/getting-started/how-to-use)
-* Setting up a minimal management EKS Cluster.  This is there primarily so Plural Cloud can operate without requiring you to send us any cloud credentials to our servers.
+* Set up a minimal management EKS Cluster.  This is there primarily so Plural Cloud can operate without requiring you to send us any cloud credentials to our servers.
+
+
+The terraform and scripting should be entirely self-contained, and should take about 10 or so minutes to run to completion (can be longer for AWS).  It's also worth noting that the cloud and region for `plural up --cloud` can be different than the one used for your Plural instance, your infrastructure is entirely self contained.  We also never ingress to your environment nor capture your cloud keys, a core aspect of the Plural Cloud architecture.
+
+## Cleaning Up Your Environment
+
+If you were simply testing and want to clean up your environment there are basically two steps:
+
+* Remove any infrastructure managed by Plural.  This should involve:
+  * Delete the Plural Stacks you set up.  **Be sure to do this via a GitOps process, not the UI, as our operator will recreate the stack if you do not**.
+  * Delete the services that might also spawn resources, especially those that create load balancers.
+  * This is often doable by simply reverting the PRs we generate to provision that infra.
+* from there run `plural down --cloud`.
 
+{% callout severity="warn" %}
+There are two main gotchas to be aware of:
 
-The terraform and scripting should be entirely self-contained, and should take about 15 or so minutes to run to completion (can be longer for AWS).  It's also worth noting that the cloud and region for `plural up --cloud` can be different than the one used for your Plural instance, your infrastructure is entirely self contained.
+* You must run `plural down --cloud` if you're connected via Plural cloud, otherwise there's a `plural_cluster` resource that needs to be manually removed from tf state.
+* If you do not properly clean up the resources Plural created before deleting your management cluster with `plural down --cloud`, **you will have dangling resources that need to be manually deleted.**  Plural actually does a great job of being able to destroy resources, but it is up to the user to know what they created and what they need to delete.
+{% /callout %}
 
 ## Next Steps
 

pages/getting-started/how-to-use/cleaning-up.md

@@ -0,0 +1,38 @@
+---
+title: Cleaning Up
+description: How to deprovision everything you created with Plural
+---
+
+# Cleaning Up Your Environment
+
+If you were simply testing and want to clean up your environment there are basically two steps:
+
+* Remove any infrastructure managed by Plural.  This should involve:
+  * Delete the Plural Stacks you set up.  **Be sure to do this via a GitOps process, not the UI, as our operator will recreate the stack if you do not**.
+  * Delete the services that might also spawn resources, especially those that create load balancers.
+* This is often doable by simply reverting the PRs we generate to provision that infra.
+* from there run `plural down` or `plural down --cloud` if you were using Plural Cloud.
+
+{% callout severity="warn" %}
+There are two main gotchas to be aware of:
+
+* You must run `plural down --cloud` if you're connected via Plural cloud, otherwise there's a `plural_cluster` resource that needs to be manually removed from tf state.
+* If you do not properly clean up the resources Plural created before deleting your management cluster with `plural down --cloud`, **you will have dangling resources that need to be manually deleted.**  Plural actually does a great job of being able to destroy resources, but it is up to the user to know what they created and what they need to delete.
+{% /callout %}
+
+## The plural down command
+
+The `plural down` command is actually a simple wrapper around what is effectively:
+
+```sh
+cd terraform/mgmt && terraform init && terraform destroy
+```
+
+If for whatever reason it isn't working for you, you can always try to fall back to terraform manually.
+
+{% callout severity="warn" %}
+Fundamentally, it simply destroys the infrastructure of your management cluster.  That's why it must be run at the end of the process of destroying the infrastructure Plural creates, otherwise you get in a reverse chicken-egg situation.  
+
+
+Usually to destroy all those resources, you should be able to go to your plural infra repo, and find them being declared in the `/bootstrap` folder.
+{% /callout %}

pages/getting-started/how-to-use/controllers.md

@@ -5,6 +5,10 @@ description: Setting up your edge networking on a cluster, and learn a bit about
 
 # Setting the stage
 
+{% callout severity="info" %}
+If you're using Plural Cloud, this will be configured for you by default!
+{% /callout %}
+
 A very common problem a user will need to solve when setting up a new cluster is getting edge networking set up.  This includes solving a few main concerns:
 
 * Ingress - this sets up an ingress controller for load balancing incoming HTTP requests into the microservices on your cluster

pages/getting-started/how-to-use/microservice.md

@@ -64,7 +64,7 @@ spec:
     kind: GitRepository
     name: cd-demo
     namespace: infra
-  helm:
+  helm: # the /helm folder is a working helm chart, so we can optionally add helm values overrides in line and our deployment operator will respect it.
     values:
       image:
         repository: ghcr.io/pluralsh/plrl-cd-test

pages/getting-started/how-to-use/observability.md

@@ -5,6 +5,10 @@ description: Set up log aggregation with Elastic and Scale out Prometheus with V
 
 # Setting the Stage
 
+{% callout severity="info" %}
+If you're using Plural Cloud, this will be configured for you by default!
+{% /callout %}
+
 If you're actually going to use this infrastructure in earnest, you'll need some form of monitoring and observability.  Plural integrates directly with a number of observability providers, but the easiest *and cheapest* to get going quickly is to use our most streamlined setup, namely:
 
 * Victoria Metrics - a scale-out, prometheus-compatible time series datastore, with a feature rich agent, vmagent.  This gives you unified metrics observability

pages/getting-started/how-to-use/scm-connection.md

@@ -13,6 +13,10 @@ Plural has the ability to spawn pull requests, post review comments, and other f
 
 To get this working you'll first need to give your Plural Console scoped access tokens to your SCM.
 
+{% callout severity="info" %}
+If you're using Plural Cloud, this should have been installed for you by default as part of the setup wizard.
+{% /callout %}
+
 # Prerequisites
 Some things you'll need to run this tutorial: