add more sandboxing documentation

Author: michaeljguarino

pages/getting-started/advanced-config/sandboxing.md

@@ -38,15 +38,30 @@ To set it up, you need to configure a few env vars as well, in particular:
 
 To simplify permission management, you can also configure specific emails to automatically be made admins via another env var: `CONSOLE_ADMIN_EMAILS`. It should be a comma seperated list, and on login we'll provision that user to be an admin w/in your Plural console instance. We'd recommend only setting this for a small set of users, then using group bindings for permissions from then on
 
-## Self-host git repos
+## Self-Host Git Repos
 
-If your enterprise cannot accept external communication to github, we recommend vendoring the above repos into your own source control provider (most have a mechanism for doing this, or can always build a cron to do it as well which we're happy to help with).
+If your enterprise cannot accept external communication to github, we can provide a fully self-hosted git server built with [soft-serve](https://github.com/charmbracelet/soft-serve) with the required Plural repos pre-cloned at a compatible version for your instance of the console.  This can be easily enabled via helm with the following values:
 
-The deployment-operator and scaffolds repos were both designed to be forked or vendored. Once you've decided upon a strategy for both, you can configure them as repositories in your console, then go to https://{your-plural-console}/cd/settings/repositories and chose to rewire the relevant repos as needed. You can also just directly modify the url and authorization information for the https://github.com/pluralsh/deployment-operator.git and other repos if you'd like too.
+```yaml
+extraEnv:
+- name: CONSOLE_DEPLOY_OPERATOR_URL
+  value: http://git-server.plrl-console:23232/deployment-operator.git # uses the git server for deployment operator updates
+- name: CONSOLE_ARITIFACTS_URL
+  value: http://git-server.plrl-console:23232/scaffolds.git # uses the git server for our default service catalog setup artifacts
+gitServer:
+  enabled: true
+```
+
+We publish a new version of this every release so you will simply need to ensure it's vendored and ready to pull on each helm upgrade.  Many organizations have a natural way to vendor docker images, and since this is deployed as a fully self-contained container image, you can simply repurpose that process to managing the necessary git repositories as well.
 
-To reconfigure a self-managed repo for compatibilities and deprecations, you'll need to fork or vendor https://github.com/pluralsh/console then configure the `GITHUB_RAW_URL` env var to point to the new location. The current default is https://raw.githubusercontent.com/pluralsh/console. This will then be appended w/ the branch + path (eg "${GITHUB_RAW_URL}/master/static/compatibilities) to fetch the relevant data for both uis.
+If you want to vendor the repositories entirely, the upstream repos are here:
+
+- https://github.com/pluralsh/deployment-operator
+- https://github.com/pluralsh/scaffolds
 
-Alternatively, we also bundle the compatibility and deprecation data in our docker images, and you can disable live polling github by setting the env var:
+## Sandboxed Compatibility Tables
+
+We also bundle the compatibility and deprecation data in our docker images, and you can disable live polling github by setting the env var:
 
 ```
 CONSOLE_AIRGAP: "true"
@@ -63,6 +78,7 @@ Lots of enterprises have strict requirements around the docker registries they u
 - pluralsh/deployment-controller
 - pluralsh/deployment-operator
 - pluralsh/agentk
+- pluralsh/git-server (optional if you want to use our vendored git server)
 
 The first three will be configured in the main console chart and are installed once in your management cluster, the latter two are needed for your deployment agent pod, and require a bit more advanced configuration to manage them in bulk.
 
@@ -110,42 +126,44 @@ First, you'll first want to use our agent settings to configure your helm update
 
 ![](/assets/deployments/agent-update.png)
 
-When you're installing an agent on a new cluster, you'll want to specify your custom values so agent pods can properly bootstrap as well. You have two main options, install via cli or terraform. To configure custom values when using the cli, there's a `--values` flag that can point to a yaml file for your custom values, eg something like:
+This can also be set via CRD using:
 
-```bash
-plural cd clusters bootstrap --name my-new-cluster --values ./agent-values.yaml
+```yaml
+apiVersion: deployments.plural.sh/v1alpha1
+kind: DeploymentSettings
+metadata:
+  name: global # this is a singleton resource that is always at this location
+  namespace: plrl-deploy-operator
+spec:
+  agentHelmValues: # from values above
+    image:
+      repository: your.enterprise.registry/pluralsh/deployment-operator
+
+    # configure agentk (if this isn't pullable kubernetes dashboarding functionality will break but deployments can still proceed)
+    agentk:
+      image:
+        repository: your.enterprise.registry/pluralsh/agentk
 ```
 
-This will merge in those values with the chart, and you can use the example yaml above to jumpstart writing the exact spec you need.
-
-For terraform, our provider also supports passing custom values like the following for eks:
+From there, both our CLI and terraform provider will ensure these helm values are always applied either in a direct agent install with:
 
-```tf
-data "aws_eks_cluster" "cluster" {
-  name = var.cluster_name
-}
+```bash
+plural cd clusters bootstrap --name my-new-cluster
+```
 
-data "aws_eks_cluster_auth" "cluster" {
-  name = var.cluster_name
-}
+or via terraform with:
 
-# store agent values in an adjacent file for the purpose of this example
-data "local_file" "agent_values" {
-  filename = "${path.module}/../helm-values/agent.yaml"
-}
-
-# this creates the cluster in our api, then performs a helm install w/ the agent chart in one tf resource
+```tf
 resource "plural_cluster" "my-cluster" {
     handle   = "my-cluster"
-    name     = var.cluster_name
-    tags     = var.tags
+    name     = "my-cluster"
+    
+    tags = {
+      tier = "dev"
+      fleet = "my-fleet"
+    }
 
-    helm_values = data.local_file.agent_values.content # can also just be passed as a raw string instead of using the file import method
+    kubeconfig = { ... }
 
-    kubeconfig = {
-      host                   = data.aws_eks_cluster.cluster.endpoint
-      cluster_ca_certificate = base64decode(data.aws_eks_cluster.cluster.certificate_authority.0.data)
-      token                  = data.aws_eks_cluster_auth.cluster.token
-    }
 }
-```
+```

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

@@ -60,45 +60,13 @@ We've also generated a README that should give an overview of how the repo can b
 If you'd like to configure the plural cli to communicate with your new Console instance, the configuration process is pretty simple, you'll need to set your Console URL and Console token. Set them with:
 
 ```
-PLURAL_CONSOLE_URL
-PLURAL_CONSOLE_TOKEN
+plural cd login
 ```
 
-or alternatively you can run `plural cd login` to set them to a config file within `~/.plural`
-
 {% callout severity="info" %}
-`plural cd` is an alias for `plural deployments`, and can be used interchangeably within the CLI.
+You'll need to generate an access token to perform this command, it'll be available at https://{your-console-url}/profile/access-tokens
 {% /callout %}
 
-## List Clusters, Services, Repositories
-
-The following commands can help you list a lot of the clusters, services, etc that have already been registered:
-
-```sh
-plural cd clusters list
-plural cd services list @{cluster-handle}
-plural cd repositories list
-```
-
-## Import Git Repositories and Deploy services
-
-You'll need to then import the Git repository containing your service and the associated Kubernetes manifests. To do so, use `plural cd repositories create`:
-
-```sh
-plural cd repositories create --url <REPO_URL>
-```
-
-Optionally add flags for Github authorization if necessary.
-
-To then deploy your service, find the repo ID for the service you want to deploy using `plural cd repositories list`.
-
-You can then use the `plural cd services create` command:
-
-```sh
-plural cd services create --name <SERVICE_NAME> --namespace <SERVICE_NAMESPACE> --repo-id <REPO_ID> --git-ref <GIT_REF> --git-folder <GIT_FOLDER> CLUSTER_ID
-
-```
-
-See deployed services with the `plural cd services list` command. Your service should populate initially as `Stale` until your components are Ready, at which point they will flip to `Healthy`.
+or alternatively you can run the env vars `PLURAL_CONSOLE_URL` and `PLURAL_CONSOLE_TOKEN` or set them directly in the config file `~/.plural/console.yml`
 
-Congratulations! You've deployed your first service with Plural.
+To validate your cli is properly configured, simply run `plural cd clusters list`

pages/getting-started/first-steps/existing-cluster.md

@@ -84,14 +84,6 @@ kubectl create secret generic console-values --from-file=values.yaml=values.secr
 2. Create a helm service referencing it in a folder currently being synced via GitOps:
 
 ```yaml
-apiVersion: source.toolkit.fluxcd.io/v1beta2
-kind: HelmRepository
-metadata:
-  name: console
-  namespace: infra # or whatever namespace you prefer
-spec:
-  interval: 5m0s
-  url: https://pluralsh.github.io/console
 ---
 apiVersion: deployments.plural.sh/v1alpha1
 kind: Cluster
@@ -110,14 +102,12 @@ spec:
   namespace: plrl-console # this namespace must be correct
   name: console
   helm:
-    version: 0.3.x #  can use floating versions with the .x syntax or pin to specific versions and automate w/ renovate
+    version: 0.x.x # VERSION (will be used below, 0.x.x means we float minor and patch versions)
     chart: console
+    url: https://pluralsh.github.io/console
     valuesFrom:
       namespace: infra
-      name: console-values
-    repository:
-      namespace: infra
-      name: console # referenced helm repository above
+      name: console-values # maps to the secret we created above
   clusterRef:
     kind: Cluster
     name: mgmt # must be set to your management cluster
@@ -126,3 +116,56 @@ spec:
 
 You can then add additional values configuration using the `values` field of a helm service, or convert it to a multi-source service and source values files directly from git.
 
+## Generate Console Update PRs instead of floating versions
+
+If you want to pin your console version and generate PRs instead of auto-updating, you can use the following Plural CRs to automate that entirely:
+
+```yaml
+apiVersion: deployments.plural.sh/v1alpha1
+kind: PrAutomation
+metadata:
+  name: console-upgrader
+spec:
+  name: console-upgrader
+  documentation: Updates the console service to a new helm version
+  updates:
+    regexReplacements:
+    - regex: "version: (.*) # VERSION" # the VERSION comment is simply to assist regex replacement here
+      file: bootstrap/console.yaml # rewrite to whatever the actual version of your console is
+      replacement: "version: {{ context.version }} # VERSION"
+  scmConnectionRef:
+    name: workspaces
+  title: "Update Plural Console helm chart to {{ context.version }}"
+  message: |
+    Update Plural Console helm chart to {{ context.version }}
+
+    Release notes available here: https://github.com/pluralsh/console/releases
+  identifier: ${YOUR_REPO_SLUG} # eg pluralsh/plrl-infra
+  configuration:
+  - name: version
+    type: STRING
+    documentation: version of the new helm chart
+---
+apiVersion: deployments.plural.sh/v1alpha1
+kind: Observer
+metadata:
+  name: console
+spec:
+  crontab: "*/5 * * * *"
+  initial: '0.3.81' # or whatever your current chart version is
+  target:
+    order: SEMVER
+    type: HELM
+    helm:
+      url: https://pluralsh.github.io/console
+      chart: console
+  actions:
+  - type: PR
+    configuration:
+      pr:
+        prAutomationRef:
+          name: console-upgrader # references the PrAutomation CR we created above
+          namespace: infra
+        context:
+          version: $value
+```