Rearrange some docs, rewrite some other docs (#305)

* moved service contexts to the stacks docs
* fixup on notifications docs
* fixup on CD docs

Fixes PROD-2666

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,28 +1,8 @@
 <!--- Hello Plural contributor! It's great to have you on board! -->
 
-## Summary
 <!-- Describe your changes here, include the motivation/context, test coverage, -->
 <!-- the type of change i.e. breaking change, new feature, or bug fix -->
 <!-- and related GitHub issue or screenshots (if applicable). -->
 
 <!-- Adding a meaningful title and description allows us to better communicate -->
 <!-- your work with our users. -->
-
-## Labels
-<!-- For breaking changes, add the `breaking-change` label.️ -->
-<!-- For bug fixes, add the `bug-fix` label. -->
-<!-- For new features and notable changes, add the `enhancement` label. -->
-
-
-## Test Plan
-<!--- Please describe the tests you have added and your testing environment (if applicable). -->
-
-
-## Checklist
-<!--- Go over all the following points to make sure you've checked all that apply before merging. -->
-<!--- If you're unsure about any of these, don't hesitate to ask in our Discord. -->
-
-- [ ] If required, I have updated the Plural documentation accordingly.
-- [ ] I have added tests to cover my changes.
-- [ ] I have added a meaningful title and summary to convey the impact of this PR to a user.
-- [ ] I have added relevant labels to this PR to help with categorization for release notes.

pages/deployments/dashboard.md

@@ -55,7 +55,7 @@ We recommend leveraging a global service by placing your fleet-wide RBAC policy
 
 ```yaml
 apiVersion: deployments.plural.sh/v1alpha1
-kind: ServiceDeployment
+kind: GlobalService
 metadata:
   name: rbac
 spec:
@@ -66,7 +66,7 @@ spec:
       ref: main
     repositoryRef:
       kind: GitRepository
-      name: infra # can point to any git repository CRD
+      name: infra # should point to a CRD that references the repo you're working in
       namespace: infra
 ```
 

pages/deployments/notifications.md

@@ -63,3 +63,41 @@ spec:
 ```
 
 Once those resources are configured, you should start to see events trickle in to whatever channel you've configured them against.
+
+## Supported Notification Events
+
+At the moment, a router will receive the following notification events:
+
+* `service.update`
+* `pipeline.update` 
+* `pr.create` 
+* `pr.close` 
+* `cluster.create`
+* `stack.run`
+
+We'll update this list as future events are defined.
+
+## Supported Notification Sink Types
+
+We currently support the following notification sink types:
+
+* `SLACK` - a Slack incoming webhook
+* `TEAMS` - a Microsoft Teams incoming webhook
+* `PLURAL` - in-app Plural Console notifications
+
+The `PLURAL` sink type is unique in that it pairs with the `bindings` attribute of the sink to control what users receive notifications.  For instance you could use:
+
+```yaml
+apiVersion: deployments.plural.sh/v1alpha1
+kind: NotificationSink
+metadata:
+  name: sres
+  namespace: infra # can be any namespace you wish of course
+spec:
+  type: PLURAL
+  name: sres
+  bindings:
+  - groupName: sre
+```
+
+To only deliver in-app notifications to the `sre` group.  This doesn't work for external notification sinks because Console user groups are not meaningful constructs in Slack, Teams, etc.

pages/deployments/operator/architecture.md

@@ -5,68 +5,11 @@ description: GitOps Management using the Plural Operator
 
 The Plural operator defines a set of CRDs that allow you to manage your deployments in a fully GitOps manner. The controller ultimately communicates with our core apis and acts effectively as a frontend to automate provisioning/deprovisioning the requisite resources. The CRD structures also imitate the patterns used by Flux and is interoperable with many Flux types (particularly those from its source controller), with modular distinct types for the various roles in deployments, e.g. git/helm repositories, clusters, and services.
 
-To illustrate the flexibility this model provides a very simple example to set up a helm multi-source deployment would look like this:
-
-```yaml
-# helm repository to use for the service
-apiVersion: source.toolkit.fluxcd.io/v1beta2
-kind: HelmRepository
-metadata:
-  name: nginx
-  namespace: infra
-spec:
-  interval: 5m0s
-  url: https://kubernetes.github.io/ingress-nginx
----
-# cluster to deploy to
-apiVersion: deployments.plural.sh/v1alpha1
-kind: Cluster
-metadata:
-  name: k3s-test
-  namespace: infra
-spec:
-  handle: k3s-test
----
-apiVersion: deployments.plural.sh/v1alpha1
-kind: GitRepository
-metadata:
-  name: infra
-  namespace: infra
-spec:
-  url: [email protected]:some/repo.git # source repo for helm values
----
-apiVersion: deployments.plural.sh/v1alpha1
-kind: ServiceDeployment
-metadata:
-  name: nginx-threes-test
-  namespace: infra
-spec:
-  namespace: ingress-nginx
-  name: ingress-nginx
-  git:
-    folder: helm-values
-    ref: main
-  repositoryRef:
-    kind: GitRepository
-    name: infra
-    namespace: infra
-  helm:
-    version: 4.4.x
-    chart: ingress-nginx
-    valuesFiles:
-      - ingress-nginx.yaml # values file sourced from the git repository
-    repository:
-      namespace: infra
-      name: nginx # referenced helm repository above
-  clusterRef:
-    kind: Cluster
-    name: k3s-test
-    namespace: infra
-```
+In general, Plural tries to be fully GitOps compliant, meaning virtually any write operation in the system can be realized via a CRD defined by our operator.  That ensures you always have full auditability and reproducibility for all changes executed in your kubernetes infrastructure.
 
 ## Full API Spec
 
-The full api spec can be found by looking through the go types [here](https://github.com/pluralsh/console/tree/master/controller/api/v1alpha1) (full docsite coming soon!)
+The full api spec can be found by looking through the go types [here](/deployments/operator/api).  You can also look at the code [here](https://github.com/pluralsh/console/tree/master/go/controller/api/v1alpha1).
 
 ## Read-Only vs Write resources
 

pages/deployments/operator/helm-service.md

@@ -6,16 +6,7 @@ description: Source manifests from a helm repository registered anywhere
 You can also source manifests from a https or OCI-compatible helm repository. This is very useful for provisioning kubernetes add-ons, which are usually packaged using helm, or occasionally for complex release processes where helms versioning independent of git can be valuable. The path here requires creation of a Flux `HelmRepository` CR first, then the service, e.g.:
 
 ```yaml
-# the HelmRepository and Cluster resources should ideally be defined elsewhere in your infra repo
-apiVersion: source.toolkit.fluxcd.io/v1beta2
-kind: HelmRepository
-metadata:
-  name: nginx
-  namespace: infra
-spec:
-  interval: 5m0s
-  url: https://kubernetes.github.io/ingress-nginx
----
+# the Cluster resource should ideally be defined in separate files in your infra repo
 apiVersion: deployments.plural.sh/v1alpha1
 kind: Cluster
 metadata:
@@ -35,6 +26,7 @@ spec:
   helm:
     version: 4.4.x
     chart: ingress-nginx
+    url: https://kubernetes.github.io/ingress-nginx
     values:
       # in-line helm values, will be stored encrypted at rest
       controller:
@@ -52,4 +44,80 @@ spec:
     namespace: infra
 ```
 
-You can also source values files, from a git repository alongside sourcing the chart from the helm repository, this can make for a nicer version control experience of complex helm values files. There's a full multi-source example in the architecture section.
+## Multi-Source Helm
+
+Say you want to source the helm templates from an upstream helm repository, but the values files from a Git repository.  In that case, you can define a multi-sourced service, which has both a git and helm repository defined.  It would look like so:
+
+```yaml
+apiVersion: deployments.plural.sh/v1alpha1
+kind: GitReposiotry
+metadata:
+  name: infra
+  namespace: infra
+spec:
+  url: https://github.com/pluralsh/my-infra-repo.git # replace w/ your own repo
+---
+apiVersion: deployments.plural.sh/v1alpha1
+kind: ServiceDeployment
+metadata:
+  name: nginx
+  namespace: infra
+spec:
+  namespace: ingress-nginx
+  name: ingress-nginx
+  repositoryRef:
+    kind: GitRepository
+    name: infra # points to the CRD above
+    namespace: infra
+  git: 
+    ref: main
+    folder: helm # where helm values files are stored
+  helm:
+    version: 4.4.x
+    chart: ingress-nginx
+    url: https://kubernetes.github.io/ingress-nginx
+    values:
+      # in-line helm values, will be stored encrypted at rest
+      controller:
+        image:
+          digest: null
+          digestChroot: null
+        admissionWebhooks:
+          enabled: false
+    valuesFiles:
+    - ingress-nginx.values.yaml # using helm/ingress-nginx.values.yaml as our values file
+  clusterRef:
+    kind: Cluster
+    name: k3s
+    namespace: infra
+```
+
+## Helm Repositories Stored in Git
+
+It's also quite common for users to store helm charts in Git repos.  In that case, you simply create a standard git service pointing to that folder and our agent will auto-detect it's a helm chart, and use helm to template the manifests then apply.  You're also free to add additional values overrides like any other chart, or customize the `release` name of the helm install.  Here's an example:
+
+```yaml
+apiVersion: deployments.plural.sh/v1alpha1
+kind: ServiceDeployment
+metadata:
+  name: helm-app
+  namespace: infra
+spec:
+  namespace: helm-app
+  name: helm-app
+  repositoryRef:
+    kind: GitRepository
+    name: infra # points to the CRD above
+    namespace: infra
+  git: 
+    ref: main
+    folder: chart # where the helm chart lives
+  helm:
+    values:
+      image:
+        tag: override-tag # example in-line helm values
+  clusterRef:
+    kind: Cluster
+    name: k3s
+    namespace: infra
+```

pages/deployments/terraform-interop.md

@@ -3,7 +3,15 @@ title: Terraform Interop with Service Contexts
 description: Communicate data between terraform and kubernetes using Service Contexts
 ---
 
-A common and incredibly frustrating challenge with managing kubernetes, especially at scale, is sharing state between terraform and the common tools used to manage Kubernetes configuration like helm and kustomize. We've created a system called Service Contexts to facilitate this. At its core, it is simply named bundles of configuration that can be created via api (thus easily integrated with Terraform or Pulumi) and mounted to Plural services. Here's a simple example, involving setting up an IRSA role for external-dns:
+# Overview
+
+A common and incredibly frustrating challenge with managing kubernetes, especially at scale, is sharing state between terraform and the common tools used to manage Kubernetes configuration like helm and kustomize, or with other independent sections of terraform code. 
+
+We've created an API called Service Contexts to facilitate this. At its core, it is simply named bundles of configuration that can be created via api (thus easily integrated with Terraform or Pulumi) and mounted to Plural services, or imported as data resources in other stacks. This will guide you through how to leverage the api throughout your IAC Usage.
+
+## Defining a service context
+
+Here's a simple example, involving setting up an IRSA role for external-dns:
 
 ```tf
 module "assumable_role_externaldns" {
@@ -24,7 +32,24 @@ resource "plural_service_context" "externaldns" {
 }
 ```
 
-You could then attach it to an externaldns service like so:
+## Using in another Plural Terraform stack
+
+Refering a service context in another stack is simple:
+
+```tf
+data "plural_service_context "externaldns" {
+  name = "externaldns"
+}
+
+local {
+  # can wire it in wherever, this is just an example
+  external_dns_arn = data.plural_service_context.externaldns.configuration.roleArn 
+}
+```
+
+## Attaching to a Plural CD ServiceDeployment
+
+You can also attach it to an externaldns service like so:
 
 ```yaml
 apiVersion: deployments.plural.sh/v1alpha1
@@ -35,7 +60,7 @@ metadata:
 spec:
   namespace: external-dns
   git:
-    folder: helm-values
+    folder: helm
     ref: main
   repositoryRef:
     kind: GitRepository
@@ -46,11 +71,9 @@ spec:
   helm:
     version: '6.14.1'
     chart: external-dns
+    url: https://charts.bitnami.com/bitnami
     valuesFiles:
       - external-dns.yaml.liquid # we're using a multi-source service sourcing this values file from `helm-values/external-dns.yaml.liquid` in the infra repo above
-    repository:
-      namespace: infra
-      name: external-dns
   clusterRef:
     kind: Cluster
     name: target-cluster
@@ -61,15 +84,16 @@ spec:
 The `.liquid` extension on `external-dns.yaml.liquid` tells the deployment agent to attempt to template the values file, otherwise it will interpret it as plain yaml.
 {% /callout %}
 
-Then in `helm-values/external-dns.yaml.liquid` you could easily template in the role arn like so:
+Then in `helm/external-dns.yaml.liquid` you could easily template in the role arn like so:
 
 ```yaml
 serviceAccount:
   create: true
   annotations:
-    eks.amazonaws.com/role-arn: { { contexts.externaldns.roleArn } }
+    eks.amazonaws.com/role-arn: {{ contexts.externaldns.roleArn }}
 ```
 
 (You can of course layer on any additional externaldns configuration you'd like, we're only interested in the eks iam role attachment here)
 
-What this is doing is on each attempt to retemplate the service, we're pulling the current value of the context alongside the service and injecting it into the passed values file. This helps simplify the process of managing the disparate toolchains and their independent state systems and it also dramatically reduces the risk of drift throughout your infrastructure.
+
+Under the hood, on each attempt to retemplate the service, we're pulling the current value of the context alongside the service and injecting it into the passed values file. Ensuring your k8s configuration is always in sync with the desired state in the upstream cloud infrastructure.