Documentation for Stacks (#275)

Adds docs for our new major feature vertical.  This is definitely still WIP but covers all the main workflows for now.

Author: michaeljguarino

pages/deployments/stacks.md

@@ -0,0 +1,4 @@
+---
+title: Stacks
+description: How to manage Infrastructure as Code at Scale Using Plural
+---

pages/stacks/customize-runners.md

@@ -0,0 +1,101 @@
+---
+title: Customize Stack Runners
+description: Configure runner pods to enable workload identity or EKS IRSA
+---
+
+All stacks are run in a dedicated pod to support seamless scalability and enhance security.  That said, you'll likely need to customize the definitions of those pods for a few usecases:
+
+* Needing to add wiring to meet your existing OPA policy constraints around things like custom labels or `securityContext`
+* Needing to configure the pod with service accounts preconfigured for IRSA, GKE workload identity or similar secure cloud credential issuance systems
+* Needing to use your own base image
+
+The process is simple and can be done per-stack or globally
+
+## Configure the base image of your stack
+
+All the stack runner images we provide are open source and available at https://github.com/pluralsh/deployment-operator.  You're free to extend them and add any additional tools you want in the environment.  Once that extended image is baked and published, you can reconfigure your stack CRD with:
+
+
+```yaml
+apiVersion: deployments.plural.sh/v1alpha1
+kind: InfrastructureStack
+metadata:
+  name: gke-demo
+  namespace: stacks
+spec:
+  name: gke-demo
+  type: TERRAFORM
+  ...
+  configuration:
+    image: your.registry/stack-harness
+    tag: your-tag
+```
+
+## Configure Runner for a single stack
+
+The `jobSpec` field with a stack spec can configure that stacks runner, like so:
+
+```yaml
+apiVersion: deployments.plural.sh/v1alpha1
+kind: InfrastructureStack
+metadata:
+  name: gke-demo
+  namespace: stacks
+spec:
+  name: gke-demo
+  type: TERRAFORM
+  approval: true
+  detach: false
+  manageState: true
+  actor: [email protected]
+  configuration:
+    version: 1.8.2
+  repositoryRef:
+    name: fleet
+    namespace: fleets
+  clusterRef:
+    name: mgmt
+    namespace: infra
+  workdir: gke-cluster
+  git:
+    ref: main
+    folder: terraform
+  # add a service account and label
+  jobSpec:
+    serviceAccount: stacks
+    labels:
+      deployment.plural.sh/needed-label: "finally-set"
+```
+
+The expectation being that the service account was preconfigured for IRSA like so:
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: stacks
+  namespace: plrl-deploy-operator
+  annotations:
+    eks.amazonaws.com/role-arn: arn:aws:iam::{your-account-id}:role/plrl-stacks
+```
+
+This will add a service account and labels to the pod, but you can configure more information up to a full k8s JobTemplateSpec object.  We encourage referencing our [CRD docs](/deployments/operator/api) if you want to learn all the knobs available.
+
+## Configure Runner Pods Globally
+
+You can also configure runners globally here:
+
+```yaml
+apiVersion: deployments.plural.sh/v1alpha1
+kind: DeploymentSettings
+metadata:
+  name: global
+spec:
+  stacks:
+    jobSpec:
+      serviceAccount: stacks
+      labels:
+        deployment.plural.sh/needed-label: "finally-set"
+```
+
+Configuration at the stack-level will always take priority, and global configuration is used as the next fallback before finally our hardcoded defaults.

pages/stacks/local-execution.md

@@ -0,0 +1,23 @@
+---
+title: Local Execution
+description: Executing IaC from Plural Stacks Locally
+---
+
+One of the crucial aspects of Infrastructure as Code is you always have local execution as a break-glass measure if your control plane is broken.  We make sure that principle is preserved in all cases.  There are really two cases here to consider:
+
+* You're using a self-managed state store, like s3.  In this case, as long as you can replicate cloud creds locally, you can use your IaC outside of Plural at any time if you wish.
+* You're using Plural to manage your state.
+
+## Run locally with Plural Managed State
+
+Plural's terraform state backend ultimately works by using the `http` remote backend and writing an `_override.tf` file to the local folder to wire in that backend.  You can invoke that logic from the cli with:
+
+```sh
+plural cd stacks gen-backend
+```
+
+This will write the same file locally, and a `terraform init` will initialize terraform against that http backend.  
+
+{% callout severity="warning" %}
+This file will potentially contain secret information, so you should be careful not to commit it to Git
+{% /callout %}

pages/stacks/manual-runs.md

@@ -0,0 +1,45 @@
+---
+title: Manual Runs
+description: Repair errors or one-off tasks in the stack environment
+---
+
+Infrastructure as Code is great, but definitely will occasionally flake.  Anything from drift in infrastructure or a terraform lock going awry can cause annoying breakages.  Manual runs are meant to solve for this.  There are two main modes of a manual run:
+
+* One-off script supplied by the user in-UI
+* Pre-configured runs for common repair workflows, like running `terraform force-unlock {lock-id}` which can enhance self-serviceability of the process
+
+## Launching a Manual Run
+
+To launch a manual run, simply click the `Create manual run` button in the stacks UI
+
+![](/assets/stacks/manual-run.png)
+
+This will provide a simple wizard which can guide you through the workflow.  This will trigger a run with the expected commands, within the same environment as a standard stack run.
+
+## Create a Custom Run
+
+You can create a pre-baked manual run via the `CustomRun` CRD, like so:
+
+```yaml
+apiVersion: deployments.plural.sh/v1alpha1
+kind: CustomStackRun
+metadata:
+  name: force-unlock
+spec:
+  name: force-unlock
+  documentation: "force release a terraform lock if present"
+  commands:
+  - cmd: terraform
+    args: [init]
+  - cmd: terraform
+    args:
+    - force-unlock
+    - '-force'
+    - "{{ context.lockId }}"
+  configuration:
+  - name: lockId
+    type: STRING
+    documentation: the lock id to release
+```
+
+This creates a wizard-based manual run for the `terraform force-unlock` command, which can save your engineers a tedious look through the docs.  It's also incredibly useful if you have customized your runner with additional scripts that might be used for ad-hoc operations.

pages/stacks/overview.md

@@ -0,0 +1,73 @@
+---
+title: Plural Stacks
+description: API-Driven Infrastructure As Code CD
+---
+
+The goal of Plural Stacks is to provide a scalable framework to manage infrastructure as code like Terraform, Ansible and Pulumi with a kubernetes-friendly, api-driven approach.  The core workflow is as follows:
+
+* Declaratively define a stack with a type (terraform, ansible, etc), a location in a git repository to source code from, and a cluster on which it will execute
+* On each commit to the tracked git repository, a run is created which the Plural deployment operator will detect and execute on the targeted cluster
+   - this allows users to fine grain permissions and network location of IaC runs where both are necessary to configure.
+* Plural will carefully execute the run for you, and besides basic information like communicating stdout to the UI, we will also gather and present useful information like inputs/outputs, terraform state diagrams and more
+* On PRs to the tracked repository, a "plan" run is also executed and comments posted on the relevant PR where possible.
+
+To get a better idea of the full power of the experience, feel free to take a look at this demo video (at 2x speed if you want to save some time):
+
+{% embed url="https://youtu.be/06WXbvw6p3w" aspectRatio="16 / 9" /%}
+
+# A Basic Stack
+
+The most common way to instantiate a stack is via Kubernetes CRD.  This gives a flexible, modular way of recreating infrastructure with Terraform and pairs nicely with our PR Automation tooling for full self-service around IaC.
+
+Here's an example:
+
+```yaml
+apiVersion: deployments.plural.sh/v1alpha1
+kind: InfrastructureStack
+metadata:
+  name: gke-demo
+  namespace: stacks
+spec:
+  name: gke-demo
+  type: TERRAFORM
+  approval: true
+  detach: false
+  manageState: true
+  actor: [email protected]
+  configuration:
+    version: 1.8.2
+  repositoryRef:
+    name: fleet
+    namespace: fleets
+  clusterRef:
+    name: mgmt
+    namespace: infra
+  workdir: gke-cluster
+  git:
+    ref: main
+    folder: terraform
+  files:
+  - mountPath: /plural
+    secretRef:
+      name: gcp-creds
+  environment:
+  - name: GOOGLE_APPLICATION_CREDENTIALS
+    value: /plural/creds.json
+  - name: TF_VAR_cluster
+    value: gke-demo
+  - name: TF_VAR_tier
+    value: dev
+  - name: TF_VAR_fleet
+    value: gke-dem
+```
+
+The meaning of this yaml is pretty self-documenting, we are:
+
+* creating a `TERRAFORM` stack, so it will execute the standard terraform workflow
+* we're using Plural as the state store, removing the need to configure S3 or other backends manually
+* `approval` will be required before `terraform apply` will trigger, ensuring a human verifies the plan first to reduce misconfiguration risk
+* we're sourcing manifests from the `fleet` repository (referencing a `GitRepository` crd)
+* we're executing on the `mgmt` cluster (referencing a `Cluster` crd)
+* and we're executing in the `terraform/gke-cluster` folder
+
+You can also see you can bind files and environment variables into the environment, although it is still best practice to use IRSA, GKE workload identity or similar mechanisms for issuing cloud credentials.

pages/stacks/pr-workflow.md

@@ -0,0 +1,46 @@
+---
+title: Stack PR Workflow
+description: API-Driven Infrastructure As Code CD
+---
+
+Plural Stacks have the ability to trigger dry runs on PR giving users clear information as to what infrastructure can change as a result.  This will do two things:
+
+* run a dry run that terminates at the equivalent of `terraform plan` for the relevant stack type
+* post informative messages back to the PR to surface relevant details in Git.
+
+To trigger a PR run, you'll need to follow a few conventions:
+
+* the branch can be named any name like `plrl/stacks/<stack-name>/.*`
+* You include text like `Plural Stack: <stack-name>` in the title or description of the PR
+
+This will tie the PR to the stack and initiate the dry-run process.
+
+## Dependencies
+
+There are a few dependencies to getting these working:
+
+* You need to configure a SCM connection to whatever source control provider you're using.  We currently support Github and Gitlab, and are happy to support others on request as well.
+* You need to configure a webhook against that SCM as well.
+
+Both can be done in the ui.
+
+Finally, you need to configure your stacks to use a given SCM connection, that can be done globally with:
+
+```yaml
+apiVersion: deployments.plural.sh/v1alpha1
+kind: ScmConnection
+metadata:
+  name: github
+spec:
+  name: <name-from-ui>
+  type: GITHUB
+---
+apiVersion: deployments.plural.sh/v1alpha1
+kind: DeploymentSettings
+metadata:
+  name: global
+spec:
+  stacks:
+    connectionRef:
+      name: github
+```

public/assets/stacks/manual-run.png

@@ -160,6 +160,32 @@ const rootNavData: NavMenu = deepFreeze([
           },
         ],
       },
+      {
+        href: '/stacks/',
+        title: 'Iac Management with Stacks',
+        sections: [
+          {
+            title: 'Overview',
+            href: '/stacks/overview',
+          },
+          {
+            title: 'Customizing Stack Runners',
+            href: '/stacks/customize-runners',
+          },
+          {
+            title: 'Pull Request Workflow',
+            href: '/stacks/pr-workflow',
+          },
+          {
+            title: 'Manual Runs',
+            href: '/stacks/manual-runs',
+          },
+          {
+            title: 'Executing IaC Locally',
+            href: '/stacks/local-execution',
+          },
+        ],
+      },
       {
         href: '/deployments/services',
         title: 'Deployments',

src/NavData.tsx

@@ -2150,7 +2150,8 @@ export enum Provider {
   Gcp = 'GCP',
   Generic = 'GENERIC',
   Kind = 'KIND',
-  Kubernetes = 'KUBERNETES'
+  Kubernetes = 'KUBERNETES',
+  Linode = 'LINODE'
 }
 
 export type PublicKey = {