rearrange nav and intro docs a bit

pluralsh · Sep 22, 2024 · 7534956 · 7534956
1 parent 75d4b89
commit 7534956
Show file tree

Hide file tree

Showing 6 changed files with 121 additions and 183 deletions.
diff --git a/pages/how-to/deploy/pr-automation.md b/pages/how-to/deploy/pr-automation.md
@@ -52,7 +52,7 @@ spec:
     type: STRING
     documentation: the name of this blob store (if using s3, this would become an s3 bucket name)
     validation:
-      regex: [a-z][a-z\-0-9]+
+      regex: "[a-z][a-z\-0-9]+"
   - name: type
     type: ENUM
     documentation: the type of blob storage to provision

diff --git a/pages/how-to/index.md b/pages/how-to/index.md
@@ -2,3 +2,18 @@
 title: How To
 description: How To Guides for Getting the Most Out of Plural
 ---
+
+These tutorials will guide you through a miniaturized example of the Kubernetes adoption process.  The basic steps are:
+
+1. Setup your management cluster
+2. Setup a few workload clusters to separate dev and prod workloads
+3. Setup a base kubernetes runtime, in this case for managing networking w/ ingress, cert-manager, and external-dns
+4. Deploy dev + prod microservices
+5. Setup Pipelines between them.
+
+We also go into a few other usecases that will often become useful, in particular:
+
+* Implementing cloud self-service with our PR Automation and Terraform Stacks APIs.
+* Integrating closely with your source control provider, to tightly integrate your deployment workflows with the code review and approval process.
+
+They are meant to be consumed in order, but you can also browse around.
diff --git a/pages/how-to/set-up/controllers.md b/pages/how-to/set-up/controllers.md
@@ -295,3 +295,20 @@ spec:
       ref: main
       folder: services/cluster-issuer # simply source the raw yaml from the services/cluster-issuer folder 
 ```
+
+## Push to Deploy
+
+We registered all these manifests under the root `bootstrap` folder a `plural up`-derived management cluster listens to by default, so all you should need to do is either:
+
+```sh
+git commit -m "setup our cluster runtime"
+git push
+```
+
+or create a PR, approve it, and merge to have the global deploy to all your clusters.  
+
+{% callout severity="info" %}
+You might need to wait a minute or two for the system to poll git and realize there's a new change.
+{% /callout %}
+
+Once you've configured all of these, you should see the new Global Services at https://{your-console-domain}/cd/globalservices.
diff --git a/pages/introduction.md b/pages/introduction.md
@@ -1,90 +1,21 @@
 ---
 title: Introduction
 description: >-
-  Plural empowers you to build and maintain production-ready applications on
-  Kubernetes in minutes with no management overhead.
+  Plural is your single pane of glass for Enterprise-Grade Kubernetes Fleet Management
 ---
 
-## What is Plural?
+# What is Plural?
 
-Plural is a self-hosted, open-source, unified application deployment platform that deploys your selected applictions into a Kubernetes cluster in the cloud provider of your choice. Plural acts as:
+Plural is a unified cloud orchestrator for the management of Kubernetes at scale.  In particular, the fleet management problem as we understand it is decomposed into providing a consistent workflow for 4 main concerns:
 
-- An infrastructure provisioner, spinning up new clusters as needed
-- A continuous deployment solution, allowing you to deploy your services across environments
-- A single pane of glass for complete visibility into what's deployed where
-- An open-source marketplace to deploy 3rd party software into your clusters
+1. Kubernetes Continuous Deployment - you need a GitOps-based, drift-detecting mechanism to sync kubernetes yaml manifests, written in helm, kustomize, raw yaml, etc, into target kubernetes clusters.  It should also be orchestrable via API to support a scalable workflow to any fleet size.
+2. Kubernetes Dashboarding - A secure, SSO-integrated Kubernetes dashboard layer for ad-hoc troubleshooting.  GitOps should handle anything on a write-path, but you still need a strong read-path that's not burdened with friction.
+3. Infrastructure-As-Code Management - implemented via [Stacks](/stacks/overview), this provides a k8s-native, API-driven mechanism to scalably manage the terraform complexity that immediately arises when using kubernetes in earnest.
+4. Self-Service Code Generation - the glue that ties everything together, a repeatable PR Automation API that allows you to self-serviceably generate the manifests for any workflow in 1-3 with a simple UI wizard.  Think of it like Backstage for Kubernetes.
 
-Plural leverages Cluster API, Helm, Terraform, and YAML to create your desired infrastructure. Spinning up a first cluster is as easy as running `plural build`, and all configuration within your Plural Git repository is fully ejectable from the platform and ecosystem.
+In addition, we support a robust, enterprise-ready [Architecture](/deployments/architecture). This uses a separation of management cluster and an agent w/in each workload cluster to achieve scalability and enhanced security to compensate for the risks caused by introducing a Single-Pane-of-Glass to Kubernetes.  The agent can only communicate to the management cluster via egress networking, and executes all write operations with local credentials, removing the need for the management cluster to be a repository of global credentials.  If you want to learn more about the nuts-and-bolts feel free to visit our [Architecture Page](/deployments/architecture).
 
-![](/assets/introduction/introduction-marketplace.png)
-![](/assets/deployments/deployment-services.png)
+## Plural Open Source Marketplace
 
-**Some key features of the platform include:**
+We also maintain a catalog of open source applications like Airbyte, Airflow, etc. that can be deployed to kubernetes on most major clouds.  We're in progress to merging that experience with our modernized Fleet Management platform, but if you're interested in any of them, we're happy to support them in the context of a commercial plan.
 
-- Bundled infrastructure provisioning and application deployment
-- Automated upgrades for open-source software
-- Cross-tool dependency management
-- GitOps workflow with batteries-included transparent secret encryption
-- Built on common open-source tools, so if you don't like us, you can always eject your application from Plural and use it as you please.
-
-Notably, we support bringing your own Kubernetes cluster for our continuous deployment workflows.
-
-## Deployment Options
-
-### Plural CLI
-
-This is the current standard deployment method. Click below for a quickstart to managing configuration locally.
-
-- [Quickstart: Using the Plural CLI on your Machine](/getting-started/quickstart)
-
-### Plural Cloud Shell
-
-We have created a Cloud Shell with all of the tools and dependencies needed to run Plural. This is available [here](https://app.plural.sh/shell) to try out. If you want to **try out Plural without entering cloud credentials**, we offer a demo environment of our Plural Console that you can access [here](https://www.plural.sh/demo-login).
-
-- [Using our in-browser Cloud Shell](/getting-started/cloud-shell-quickstart)
-
-If you need support getting your Plural deployment up and running, join the [Plural Discord here!](https://discord.com/invite/bEBAMXV64s)
-
-## Architecture
-
-The Plural architecture has three main components:
-
-- Plural Console for management of all applications on your infrastructure
-- Plural API and Catalog site (available at [https://app.plural.sh](https://app.plural.sh))
-- Plural CLI and Git SCM to maintain the state of a user's applications
-
-### Plural Console
-
-The Plural Console is the operational hub for all applications managed by Plural. It is deployed in-cluster alongside applications and provides a few key features:
-
-- Horizontally scalable Git cache - we should be able to ingest as many git repos as you'd like and auto-shard them throughout your cluster automatically and efficiently.
-- Configuration Management - supports re-configurable backends, but allows you to easily parameterize services with information like hostnames, docker image tags, and other secret and non-secret information.
-- Auth Proxy - this is a secure bidirectional grpc channel initiated by a deployment agent used to make kubernetes api calls no matter where a cluster may live and give you full dashboarding capabilities from the Plural CD UI.
-- Cluster API Providers - Plural CD natively integrates with cluster api and allows you to create and manage new clusters at scale and fork your own kubernetes cluster APIs on top of existing setups for services like EKS, AKS and GKE or on-prem solutions like Rancher
-- Support - in-person support can be handled in our chat interface available directly in the admin console, with a lot of nice features like direct zoom integration
-
-It's deployed as a highly available, scalable web service, with postgres as its datastore. It also directly integrates with Plural's OIDC for login and user management.
-
-See our [Plural CD Architecture page](/deployments/architecture) for more information
-
-### Plural API
-
-The primary responsibility of the Plural API is to store the packages needed for open-source application installation - terraform, helm - and ingesting high-level dependency information about them. This allows us to properly sequence installations. It also serves as a publish-subscribe layer to communicate updates to clusters that have installed those applications, and can leverage the dependency information ingested to delay updates until a cluster has caught up with all the necessary dependencies.
-
-It also can serve as an identity provider for any Plural application, delegating authentication via OIDC and also maintaining user group info and communicating it down to applications.
-
-### Plural CLI
-
-The Plural CLI can be used for interaction with the Plural API and Plural Console. The CLI effectively uses the Plural API as a package manager, and works as a higher level build tool on top of the DevOps packages it supports.
-
-It also is responsible for managing secret encryption of all application state in plural installation repos and provides a few useful tools for troubleshooting an application our admin console might not be well-suited to solve.
-
-Finally it also provides the toolchain for publishing applications to the plural API.
-
-## Docs Translations
-
-### Japanese
-
-The wonderful team at [St-Hakky](https://www.about.st-hakky.com/) has translated most of our docs to Japanese on their website. To view the [translated docs, click here](https://book.st-hakky.com/docs/plural-overview).
-
-St-Hakky のすばらしいチームが、ウェブサイトでほとんどのドキュメントを日本語に翻訳してくれました。 翻訳されたドキュメントを表示するには、ここをクリックしてください。
diff --git a/pages/operations/security/index.md b/pages/operations/security/index.md
@@ -3,29 +3,24 @@ title: Security Concepts
 description: Learn about what Plural has access to at various steps of deployment.
 ---
 
-## Cloud Access
+# Plural Console
 
-### Plural CLI
+The Plural Console by default has access to nothing in your cloud.  To grant it access you'll have to do one of the following:
 
-Plural **does not** have access to any cloud environments when deployed through the CLI. We generate deployment manifests in the Plural Git repository and then use your configured cloud provider's CLI on your behalf. We cannot perform anything outside of deploying and managing the manifests that are created in your Plural Git repository.
+* manually configure a SCM connection to connect to your Source Control Provider (eg Github)
+* manually bind a workload identity role to the service account used by a Plural console-related pod (eg for stack runners)
 
-### Plural Cloud Shell
+In addition, the Console only will make two outbound network requests, outside of those used to run terraform or pull from Git:
 
-Plural **does** have access to your cloud credentials when deployed through the Cloud Shell. In order to streamline the Cloud Shell experience, we securely store cloud credentials to create resources on your behalf. You can eject from the Cloud Shell to the CLI at any time to save your configuration and revoke our access. This is done with the following steps:
+* A request to validate your instances license.  This can be replaced with a cryptographic license key, and thus disabled.
+* A request to compile our deprecation tables using our upstream dataset.  This can also be replaced by an airgapped version with the tables baked into our binary.  The tradeoff will be staleness.
 
-1. [Install the Plural CLI](/getting-started/quickstart).
-2. Run `plural shell sync` on your local machine.
-3. Run `plural shell purge` in the Cloud Shell to destroy it.
+# Plural Cloud
 
-## Plural Console
+A Plural Console running in Plural Cloud can collect creds in a few ways:
 
-Our console has elevated permissions when running in your Plural Kubernetes cluster, but it runs in its own environment to alleviate security concerns. Its permissions are required in order to listen for new versions of packages to apply automated updates to your applications.
+1. Plural-managed terraform state could have various credentials inside it
+2. SCM credentials are stored row-encrypted in our database (but can be revoked at any time).
+3. Service secrets are stored row-encrypted in our database (but you can use cloud-native secret managers if you prefer robustness over convenience).
 
-## GitHub
-
-When using the CLI or Cloud Shell, Plural will receive the following permissions:
-
-- Create GitHub repositories on your behalf
-- Commit changes to repositories that Plural has created
-
-Plural **does not** have access to repositories that have not been created by Plural.&#x20;
+Since you'll still need to create a small management cluster to attach to your cloud console, that will be what is bound any cloud creds for executing terraform, etc, and so you do not need to exchange any cloud credentials with Plural to use Plural Cloud.
diff --git a/src/NavData.tsx b/src/NavData.tsx
@@ -47,14 +47,6 @@ const rootNavData: NavMenu = deepFreeze([
         title: 'Introduction',
         href: '/introduction',
       },
-      {
-        title: 'What makes Plural different?',
-        href: '/getting-started/plural-difference',
-      },
-      {
-        title: 'Concepts',
-        href: '/getting-started/concepts',
-      },
     ],
   },
   {
@@ -118,15 +110,15 @@ const rootNavData: NavMenu = deepFreeze([
           },
           {
             title: "Set Up a Basic Self-Service Worklfow with PR Automations",
-            href: '/deploy/pr-automation',
+            href: '/how-to/deploy/pr-automation',
           },
           {
             title: 'Deploy Your First Microservice to a Workload Cluster',
-            href: '/deploy/microservice',
+            href: '/how-to/deploy/microservice',
           },
           {
             title: 'Setup Your First Microservice Promotion Pipeline',
-            href: '/deploy/pipelines',
+            href: '/how-to/deploy/pipelines',
           },
         ],
       },
@@ -347,6 +339,68 @@ const rootNavData: NavMenu = deepFreeze([
         title: 'Sharing your Plural Repository',
         href: '/getting-started/manage-git-repositories/sharing-git-repositories',
       },
+      {
+        title: 'Reference',
+        href: '/reference',
+        sections: [
+          {
+            title: 'Cloud Provider CLI Setup',
+            href: '/reference/configuring-cloud-provider',
+          },
+          {
+            title: 'Common Errors',
+            href: '/reference/troubleshooting',
+          },
+          {
+            title: 'Handling Partial Deployments',
+            href: '/reference/partial-installation',
+          },
+          {
+            href: '/getting-started/manage-git-repositories',
+            title: 'Manage Git Repositories',
+            sections: [
+              {
+                href: '/getting-started/manage-git-repositories/setting-up-gitops',
+                title: 'Setting Up GitOps',
+              },
+              {
+                href: '/getting-started/manage-git-repositories/workspace-encryption',
+                title: 'Workspace Encryption Guide',
+              },
+            ],
+          },
+          {
+            href: '/getting-started/manage-git-repositories/your-plural-workspace',
+            title: 'Plural Workspace Layout',
+          },
+          {
+            title: 'API / Developer Tools',
+            href: '/reference/api',
+            sections: [
+              {
+                href: '/reference/api/plural-api',
+                title: 'Plural API',
+              },
+              {
+                title: 'Console API',
+                href: '/reference/api/console-api',
+              },
+            ],
+          },
+          {
+            title: 'CLI Command Reference',
+            href: '/reference/cli-reference',
+          },
+          {
+            href: '/adding-new-application/plural-custom-resources',
+            title: 'Plural Custom Resources',
+          },
+          {
+            href: '/adding-new-application/module-library',
+            title: 'Module Library',
+          },
+        ],
+      },
       {
         href: '/operations/advanced-operations',
         title: 'Advanced Operations',
@@ -440,14 +494,6 @@ const rootNavData: NavMenu = deepFreeze([
         href: '/operations/auth-access-control/openid-connect',
         title: 'What is Plural OIDC?',
       },
-      {
-        href: '/operations/auth-access-control/identity-and-installations/audit-logging',
-        title: 'What audit logging does Plural do?',
-      },
-      {
-        href: '/operations/auth-access-control/identity-and-installations',
-        title: 'How does auth and access control work for Plural?',
-      },
       {
         href: '/faq/certifications',
         title: 'What certifications does Plural have?',
@@ -456,72 +502,6 @@ const rootNavData: NavMenu = deepFreeze([
         href: '/faq/plural-paid-tiers',
         title: 'How do the paid Plural tiers work?',
       },
-      {
-        href: '/faq/local-development',
-        title: 'Can I develop locally?',
-      },
-    ],
-  },
-
-  {
-    title: 'Reference',
-    sections: [
-      {
-        title: 'Cloud Provider CLI Setup',
-        href: '/reference/configuring-cloud-provider',
-      },
-      {
-        title: 'Common Errors',
-        href: '/reference/troubleshooting',
-      },
-      {
-        title: 'Handling Partial Deployments',
-        href: '/reference/partial-installation',
-      },
-      {
-        href: '/getting-started/manage-git-repositories',
-        title: 'Manage Git Repositories',
-        sections: [
-          {
-            href: '/getting-started/manage-git-repositories/setting-up-gitops',
-            title: 'Setting Up GitOps',
-          },
-          {
-            href: '/getting-started/manage-git-repositories/workspace-encryption',
-            title: 'Workspace Encryption Guide',
-          },
-        ],
-      },
-      {
-        href: '/getting-started/manage-git-repositories/your-plural-workspace',
-        title: 'Plural Workspace Layout',
-      },
-      {
-        title: 'API / Developer Tools',
-        href: '/reference/api',
-        sections: [
-          {
-            href: '/reference/api/plural-api',
-            title: 'Plural API',
-          },
-          {
-            title: 'Console API',
-            href: '/reference/api/console-api',
-          },
-        ],
-      },
-      {
-        title: 'CLI Command Reference',
-        href: '/reference/cli-reference',
-      },
-      {
-        href: '/adding-new-application/plural-custom-resources',
-        title: 'Plural Custom Resources',
-      },
-      {
-        href: '/adding-new-application/module-library',
-        title: 'Module Library',
-      },
     ],
   },
   {