add docs for byok, architecture, etc

Makefile

@@ -6,5 +6,5 @@ help:
 yarn-install: .PHONY
 	yarn
 
-web: yarn ## runs the docs site locally
+web: ## runs the docs site locally
 	yarn dev

pages/deployments/architecture.md

@@ -0,0 +1,35 @@
+---
+title: Plural CD Architecture
+description: Secure, Scalable Pull-Based Architecture
+---
+
+## Overview
+
+Plural CD is based on a scalable, secure, agent-based pull architecture. It doesn't require direct access to any of the clusters it deploys to, meaning it can manage workloads in any cloud, on-prem, on the edge, or even on a local laptop running KIND. Further since it doesn't require networking intensive kubernetes watch streams, central access to kubernetes, or relies on single-mastered operator control loops, it should scale to virtually any size kubernetes fleet. We also enhance your kubernetes setup with a auth proxy, allowing you to have full visibility to your workloads without compromising the network security of your setup or require the creation of complex multi-cloud networking setups.
+
+Here's a quick diagram of the setup:
+
+![](/assets/deployments/architecture.png)
+
+## Control Plane
+
+The Control Plane layer is a full-stack service deployable onto any kubernetes cluster you designate as your management cluster. It contains a few main components:
+
+- 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
+
+We provide simple installers if you'd like to deploy the control plane layer to a kubernetes cluster already in your fleet, or you can use our own kubernetes setup in the standard plural install flow.
+
+## Deployment Agent
+
+A thin deployment agent is installed onto each cluster and perpetually managed by Plural CD from then on. It will perpetually poll the control plane for new services to apply and if there are any changes to make, apply them into your cluster. It also can do a few other things like:
+
+- establish the bidectional grpc channel for the auth proxy layer (this does require an ingress with websocket support)
+- execute integration tests
+
+There were a few design considerations involved in our agent that are worth understanding as well:
+
+- The expectation is the agent is deployed independently at scale, potentially hundreds of times for a large organization, so it must be maximally simple to reduce operational complexity to near 0.
+- It is designed to be extensible to arbitrarily many frameworks for defining kubernetes manifests. We aren't actually huge fans of helm or kustomize and want organizations to have the flexibility to ultimately use other toolchains for managing their kubernetes YAML codebase (or ultimately de-YAML themselves)

pages/deployments/ci-overview.md

@@ -0,0 +1,22 @@
+---
+title: CI Integration
+description: Deploying your services using the Plural Console UI.
+---
+
+## Overview
+
+Plural CD is meant to help you separate the concerns around software delivery and deployment from your CI provider, which is usually purpose built for running unit tests and compiling build artifacts. There are some major motivations for this separation, among them being:
+
+- Deployment is frequently a much longer running process than a standard code change, encompassing staged releases across multiple environments with multiple rounds of integration testing.
+- A seperated CD system can make it easy to manage drift in micro-service dependencies by allowing them to be tested in tandem and rolled back independently.
+- Separating CD enhances your security posture by not requiring master creds in a build service like Jenkins or a cloud service like Circle-CI.
+- A Central CD service drastically simplifies managing polymorphic infrastructure providers, as a pull based architecture naturally can extend to multi-cloud or on-prem delivery models.
+
+We rely on two models for doing delivery, full GitOps, where the definition of a service is fully specified in Git, and parameterized GitOps, in which case you can define templated manifests and use our service configuration to inject variables like docker image tags, hostnames, etc to parameterize your service.
+
+The parameterized model enables a few useful operational models, namely:
+
+- Updating docker image tags for a service after a successful merge to `main`, then releasing it down a deployment pipeline.
+- Deep-cloning a service to create a pull-request based environment, while only changing a hostname.
+- Full rollbacks/roll-forwards of configuration in the inevitable event of an engineer misconfiguring a service
+- Importing state from terraform/pulumi into one of your CD services.

pages/deployments/ci.md

@@ -0,0 +1,4 @@
+---
+title: Integrate with Your CI
+description: How to integrate Plural CD with your CI Provider, like Github Actions, Jenkins, or CircleCI
+---

pages/deployments/credentials.md

@@ -1,4 +1,4 @@
 ---
 title: Create Provider Credentials
-description: XXX
+description: Set Up a New Cloud Provider
 ---

pages/deployments/existing-cluster.md

@@ -0,0 +1,42 @@
+---
+title: Plural CD Bring-your-own-Kubernes
+description: Bootstrap Plural CD on an existing cluster
+---
+
+## Overview
+
+For users that just want to use our CD capabilities and full control of their kubernetes setup, you can install a simplified version of Plural CD onto an existing kubernetes cluster. We've made this a turnkey process, but there are some prerequisites, namely:
+
+- You'll need to create a postgres db for state storage, and have a jdbc connection string for it ready of the form: `postgres://<user>:<password>@<host>:5432/<db>`
+- You'll need to have your network setup in place so that all clusters you want to deploy to can make outbound network connections to the ingress you configure for plural CD.
+
+## Bootstrapping
+
+Make sure your kubeconfig is pointing to the management cluster you want to deploy to, then run the following:
+
+```sh
+plural login
+plural cd control-plane
+```
+
+This will do a few things:
+
+- ask you for basic configuration like fqdns for your CD install and also the postgres jdbc url
+- set up a oidc provider for your cluster to provide secure user login
+- print a full helm values file that will be used to install your instance.
+
+You'll then want to run the helm command we provide to you, you have the option to inspect the values we've generated first, and also you can add some last mile configuration here. This can be things like flipping out the ingress class or cert manager issuer (we use `nginx` by default and an issuer of `letsencrypt-prod`).
+
+Then run the helm command generated, which ought to be something along the lines of:
+
+```sh
+helm upgrade --install --create-namespace -f values.secret.yaml --repo https://pluralsh.github.io/console console console -n plrl-console
+```
+
+We also strongly recommend you find a secure place to store the generated `values.secret.yaml` file in case you want to manually manage future console updates. You can use tooling like `git-crypt` or `kops` to secure this in git, or save it in a secret manager.
+
+## Configure Console Upgrades
+
+The Plural Console has the capability of self-managing its own upgrades in BYOK mode. This can be configured in the global settings page for deployments.
+
+You can also self-manage the chart to control your own upgrade cadence. We recommend you use our self-management though to simplify this process and ensure your constantly up-to-date.

pages/deployments/import-cluster.md

@@ -0,0 +1,34 @@
+---
+title: Import An Existing Cluster
+description: Set Up deployments to an existing, self-managed cluster
+---
+
+## Overview
+
+Most users will have created a significant amount of kubernetes infrastructure with tooling like terraform, pulumi or other forms of infrastructure automation. You can easily configure deployments to these clusters by installing our agent with a single command, and Plural CD will manage that agent from then on without any manual intervention.
+
+## Installation
+
+Make sure your local kubeconfig is pointing to the cluster you want to set up, then simply run:
+
+```sh
+plural cd bootstrap --name {name-for-your-cluster}
+```
+
+You can also configure a few tags for this cluster at create time with:
+
+```sh
+plural cd bootstrap --name {name} --tag {name}={value} --tag {name2}={value2}
+```
+
+## Terraform
+
+You can also set up a BYOK cluster via terraform with the following:
+
+```tf
+Coming Soon!
+```
+
+## Networking Considerations
+
+You do need to ensure the cluster you're going to be deploying to has egress access to your controlling cluster

src/NavData.tsx

@@ -72,6 +72,10 @@ const rootNavData: NavMenu = deepFreeze([
         href: '/getting-started/deployments',
         title: 'Getting Started',
         sections: [
+          {
+            title: 'Architecture',
+            href: '/deployments/architecture',
+          },
           {
             title: 'Quickstart with our CLI',
             href: '/deployments/cli-quickstart',
@@ -80,12 +84,20 @@ const rootNavData: NavMenu = deepFreeze([
             href: '/deployments/browser-quickstart',
             title: 'Quickstart from your Browser',
           },
+          {
+            href: '/deployments/existing-cluster',
+            title: 'Set Up on your own Cluster',
+          },
         ],
       },
       {
         href: '/deployments/clusters',
         title: 'Cluster Management',
         sections: [
+          {
+            title: 'Import An Existing Cluster',
+            href: '/deployments/import-cluster',
+          },
           {
             title: 'Create Provider Credentials',
             href: '/deployments/credentials',
@@ -130,6 +142,16 @@ const rootNavData: NavMenu = deepFreeze([
           },
         ],
       },
+      {
+        href: '/deployments/ci',
+        title: 'Integrate With your CI',
+        sections: [
+          {
+            title: 'Overview',
+            href: '/deployments/ci-overview',
+          },
+        ],
+      },
       {
         href: '/deployments/pipelines',
         title: 'Pipelines',

src/generated/pages.json

@@ -86,6 +86,9 @@
   {
     "path": "/deployments/browser-quickstart"
   },
+  {
+    "path": "/deployments/cli-quickstart"
+  },
   {
     "path": "/deployments/cluster-config"
   },
@@ -122,6 +125,9 @@
   {
     "path": "/deployments/pipelines"
   },
+  {
+    "path": "/deployments/services-deploy"
+  },
   {
     "path": "/deployments/services"
   },