Preview Environments Documentation (#455)

Documents basic lifecycle of preview environments, and also links out to a quick demo.  Backfilled demo videos for upgrade assistant and flows.

Author: michaeljguarino

generated/routes.json

@@ -29,7 +29,7 @@
   },
   "/getting-started/first-steps/cli-quickstart": {
     "relPath": "/getting-started/first-steps/cli-quickstart.md",
-    "lastmod": "2025-05-08T09:00:26.000Z"
+    "lastmod": "2025-05-08T12:32:16.000Z"
   },
   "/getting-started/first-steps/existing-cluster": {
     "relPath": "/getting-started/first-steps/existing-cluster.md",
@@ -121,7 +121,7 @@
   },
   "/plural-features/continuous-deployment/observer": {
     "relPath": "/plural-features/continuous-deployment/observer.md",
-    "lastmod": "2025-04-28T11:49:02.395Z"
+    "lastmod": "2025-05-10T04:29:16.000Z"
   },
   "/plural-features/k8s-upgrade-assistant": {
     "relPath": "/plural-features/k8s-upgrade-assistant/index.md",
@@ -215,13 +215,17 @@
     "relPath": "/plural-features/flows/flow-ai.md",
     "lastmod": "2025-04-18T18:30:29.000Z"
   },
+  "/plural-features/flows/preview-environments": {
+    "relPath": "/plural-features/flows/preview-environments.md",
+    "lastmod": "2025-05-11T22:10:38.846Z"
+  },
   "/plural-features/flows/mcp": {
     "relPath": "/plural-features/flows/mcp.md",
     "lastmod": "2025-04-18T18:30:29.000Z"
   },
   "/plural-features/observability": {
     "relPath": "/plural-features/observability/index.md",
-    "lastmod": "2025-04-30T21:17:22.000Z"
+    "lastmod": "2025-05-10T04:27:39.000Z"
   },
   "/plural-features/observability/prometheus": {
     "relPath": "/plural-features/observability/prometheus.md",
@@ -241,11 +245,11 @@
   },
   "/plural-features/observability/observability-webhooks/datadog": {
     "relPath": "/plural-features/observability/observability-webhooks/datadog.md",
-    "lastmod": "2025-04-30T21:17:22.000Z"
+    "lastmod": "2025-05-10T04:27:39.000Z"
   },
   "/plural-features/observability/observability-webhooks/grafana": {
     "relPath": "/plural-features/observability/observability-webhooks/grafana.md",
-    "lastmod": "2025-04-30T21:17:22.000Z"
+    "lastmod": "2025-05-10T04:27:39.000Z"
   },
   "/plural-features/pr-automation": {
     "relPath": "/plural-features/pr-automation/index.md",
@@ -285,23 +289,23 @@
   },
   "/examples/continuous-deployment": {
     "relPath": "/examples/continuous-deployment/index.md",
-    "lastmod": "2025-05-07T11:15:56.000Z"
+    "lastmod": "2025-05-10T04:28:20.000Z"
   },
   "/examples/continuous-deployment/helm-basic-with-inline-values": {
     "relPath": "/examples/continuous-deployment/helm-basic-with-inline-values.md",
-    "lastmod": "2025-05-07T11:12:43.000Z"
+    "lastmod": "2025-05-10T04:28:20.000Z"
   },
   "/examples/continuous-deployment/helm-basic-with-values-file": {
     "relPath": "/examples/continuous-deployment/helm-basic-with-values-file.md",
-    "lastmod": "2025-05-07T11:12:43.000Z"
+    "lastmod": "2025-05-10T04:28:20.000Z"
   },
   "/examples/continuous-deployment/kustomize-inflate-helm": {
     "relPath": "/examples/continuous-deployment/kustomize-inflate-helm.md",
-    "lastmod": "2025-05-07T11:12:43.000Z"
+    "lastmod": "2025-05-10T04:28:20.000Z"
   },
   "/examples/continuous-deployment/kustomize-stack-with-liquid": {
     "relPath": "/examples/continuous-deployment/kustomize-stack-with-liquid.md",
-    "lastmod": "2025-05-07T11:12:43.000Z"
+    "lastmod": "2025-05-10T04:28:20.000Z"
   },
   "/faq": {
     "relPath": "/faq/index.md",
@@ -361,7 +365,7 @@
   },
   "/deployments/cli-quickstart": {
     "relPath": "/getting-started/first-steps/cli-quickstart.md",
-    "lastmod": "2025-05-08T09:00:26.000Z"
+    "lastmod": "2025-05-08T12:32:16.000Z"
   },
   "/deployments/existing-cluster": {
     "relPath": "/getting-started/first-steps/existing-cluster.md",

pages/plural-features/flows/index.md

@@ -30,7 +30,6 @@ Further, because it gives us a clear circumference to understand what's related
 
 Further, Plural Flows can vector index prs, query app log data and respond to incoming alerts, extending the capabilities of our AI insight engine to be able to be a general troubleshooting tool for application code errors alongside the built-in support for Kubernetes misconfiguration.
 
-
 # Demo Video
 
 To see this all in action, feel free to browse our live demo video on Youtube for all that can be done with Plural Flows:

pages/plural-features/flows/preview-environments.md

@@ -0,0 +1,112 @@
+---
+title: Flow Preview Environments
+description: Easily create a first class PR preview environment experience within Flows
+---
+
+## Overview
+
+Preview environments are a powerful software testing pattern whereby you create a near clone of a dev environment with the code of a feature branch during the duration of a pull request.  This has a few great benefits:
+
+1. Reduces churn in your dev environment, improving overall stability - which is a common failure in large organizations with many in-flight changes
+2. Makes it easier to test code in isolation - the code only has the changes happening in your branch
+3. Reduces dev data corruption issues - true if you implement database forking as part of the preview, making it easy to test things like schema migrations
+
+This is extremely easy to implement with Plural because of a few things:
+
+* GitOps patterns make it really easy to redeploy and reconfigure services
+* Plural already has the webhook and event system to track PR updates natively implemented within its server
+* Plural also already has a secure way of managing SCM credentials, so it can natively implement the Github/Gitlab comment feedback to make an ideal DevEx around preview environments
+
+## Demo Video
+
+If you just want to see it in action, here's a quick YouTube video demo:
+
+{% embed url="https://youtu.be/9hoiQnkgnzQ" aspectRatio="16 / 9" /%}
+
+
+## How to Implement
+
+Implementing preview environments is quite simple.  You functionally just need to register one custom resource, a `PreviewEnvironmentTemplate` like below:
+
+```yaml
+apiVersion: deployments.plural.sh/v1alpha1
+kind: PreviewEnvironmentTemplate
+metadata:
+  name: test
+spec:
+  flowRef:
+    kind: Flow
+    name: flow-test
+
+  referenceServiceRef:
+    kind: ServiceDeployment
+    name: flow-test-dev
+    namespace: flow-test
+  
+  template:
+    namespace: "flow-test-pr-{{ pr.number }}"
+    name: "flow-test-pr-{{ pr.number }}"
+    helm:
+      values:
+        image:
+          tag: "sha-{{ commitSha | slice: 0, 7 }}"
+```
+
+This will then tell Plural to create a preview environment clone of the `flow-test-dev` `ServiceDeployment` whenever a PR has the following annotation in its body:
+
+```
+Plural Flow: flow-test
+Plural Preview: test # notice this is the same as the name of the PreviewEnvironmentTemplate
+```
+
+the `template` field customizes how you'll override the setting of the source service, in this case it will:
+
+1. deploy it in the `flow-test-pr-{{ pr.number }}` namespace
+2. Override the image with `sha-{{ commitSha | slice: 0, 7 }}` (basically the sha image tag we've configured GH actions to build with)
+
+To see how the image was built, you can consult one of our example repos [here](https://github.com/pluralsh/plrl-cd-demo/blob/main/.github/workflows/push.yaml#L48), but the image tagging is easy to accomplish with github actions using:
+
+
+```yaml
+env:
+  DOCKER_METADATA_PR_HEAD_SHA: 'true' # necessary for docker to tag with the commit of the actual branch, not github's phantom pr branch
+
+jobs:
+  publish-docker:
+  ...
+  - name: Docker meta
+    id: meta
+    uses: docker/metadata-action@v5
+    with:
+    # replace with your registry
+    images: |
+        ghcr.io/pluralsh/plrl-cd-test 
+    # generate Docker tags based on the following events/attributes
+    tags: |
+        type=sha
+        type=ref,event=pr
+        type=ref,event=branch
+        type=semver,pattern={{version}}  
+  - name: Build and push
+    uses: docker/build-push-action@v5
+    with:
+      context: "."
+      file: "./Dockerfile"
+      push: true
+      tags: ${{ steps.meta.outputs.tags }}
+      labels: ${{ steps.meta.outputs.labels }}
+      platforms: linux/amd64
+      cache-from: type=gha
+      cache-to: type=gha,mode=max
+      build-args: |
+        GIT_COMMIT=${{ github.sha }}
+```
+
+## Constraints
+
+Plural enforces a few constraints on how preview environments can be created:
+
+1. They will only deploy to the same cluster as their source service
+2. They will only deploy to a namespace with a name that's prefixed by the original service's namespace
+    - this is to prevent preview environments from jumping tenants, but also still make it easy to prevent them from trampling the original service.
+

pages/plural-features/k8s-upgrade-assistant/index.md

@@ -13,3 +13,7 @@ Deprecations will be surfaced at the cluster level in the "Status" column of the
 To see deprecations relevant to a specific service, navigate to the Service details page. You'll see a notification that you can click to review any changes that need to be made:
 
 ![](/assets/deployments/deprecation-warning.png)
+
+To see it all end-to-end, here's a demo video to show the experience:
+
+{% embed url="https://youtu.be/fJmTrELoAKU" aspectRatio="16 / 9" /%}

src/generated/graphql.ts

@@ -573,6 +573,10 @@ export type ConsoleInstance = {
   insertedAt?: Maybe<Scalars['DateTime']['output']>;
   /** the name of this instance (globally unique) */
   name: Scalars['String']['output'];
+  /** the network configuration for this instance */
+  network?: Maybe<ConsoleInstanceNetwork>;
+  /** custom oidc configuration for this instance */
+  oidc?: Maybe<ConsoleInstanceOidc>;
   owner?: Maybe<User>;
   /** the region this instance is hosted in */
   region: Scalars['String']['output'];
@@ -594,6 +598,10 @@ export type ConsoleInstanceAttributes = {
   cloud: CloudProvider;
   /** the name of this instance (globally unique) */
   name: Scalars['String']['input'];
+  /** use this to add network security settings to this instance */
+  network?: InputMaybe<ConsoleNetworkAttributes>;
+  /** use this to add custom oidc configuration to this instance */
+  oidc?: InputMaybe<ConsoleOidcAttributes>;
   /** the region to deploy to (provider specific) */
   region: Scalars['String']['input'];
   /** a heuristic size of this instance */
@@ -614,6 +622,18 @@ export type ConsoleInstanceEdge = {
   node?: Maybe<ConsoleInstance>;
 };
 
+export type ConsoleInstanceNetwork = {
+  __typename?: 'ConsoleInstanceNetwork';
+  allowedCidrs?: Maybe<Array<Maybe<Scalars['String']['output']>>>;
+};
+
+export type ConsoleInstanceOidc = {
+  __typename?: 'ConsoleInstanceOidc';
+  clientId?: Maybe<Scalars['String']['output']>;
+  clientSecret?: Maybe<Scalars['String']['output']>;
+  issuer?: Maybe<Scalars['String']['output']>;
+};
+
 export enum ConsoleInstanceStatus {
   DatabaseCreated = 'DATABASE_CREATED',
   DatabaseDeleted = 'DATABASE_DELETED',
@@ -632,9 +652,21 @@ export enum ConsoleInstanceType {
 
 export type ConsoleInstanceUpdateAttributes = {
   configuration?: InputMaybe<ConsoleConfigurationUpdateAttributes>;
+  network?: InputMaybe<ConsoleNetworkAttributes>;
+  oidc?: InputMaybe<ConsoleOidcAttributes>;
   size?: InputMaybe<ConsoleSize>;
 };
 
+export type ConsoleNetworkAttributes = {
+  allowedCidrs?: InputMaybe<Array<InputMaybe<Scalars['String']['input']>>>;
+};
+
+export type ConsoleOidcAttributes = {
+  clientId?: InputMaybe<Scalars['String']['input']>;
+  clientSecret?: InputMaybe<Scalars['String']['input']>;
+  issuer?: InputMaybe<Scalars['String']['input']>;
+};
+
 export enum ConsoleSize {
   Large = 'LARGE',
   Medium = 'MEDIUM',

src/routing/docs-structure.ts

@@ -140,6 +140,7 @@ export const docsStructure: DocSection[] = [
         sections: [
           { path: 'create-a-flow', title: 'Create a flow' },
           { path: 'flow-ai', title: 'Plural AI and Flows' },
+          { path: 'preview-environments', title: 'Preview Environments' },
           { path: 'mcp', title: 'Flow MCP Server Integration' },
         ],
       },