From af69002ce4410c6c554c34585e61053ceb07edf0 Mon Sep 17 00:00:00 2001 From: michaeljguarino Date: Sun, 22 Sep 2024 20:35:43 -0400 Subject: [PATCH] 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 | 20 ----- pages/deployments/dashboard.md | 4 +- pages/deployments/notifications.md | 38 +++++++++ pages/deployments/operator/architecture.md | 61 +-------------- pages/deployments/operator/helm-service.md | 90 +++++++++++++++++++--- pages/deployments/terraform-interop.md | 42 +++++++--- src/NavData.tsx | 66 ++++++++-------- 7 files changed, 185 insertions(+), 136 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index fa96c276..033f7831 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,28 +1,8 @@ -## Summary - -## Labels - - - - - -## Test Plan - - - -## Checklist - - - -- [ ] 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. \ No newline at end of file diff --git a/pages/deployments/dashboard.md b/pages/deployments/dashboard.md index c09c4c5c..b6f2a18f 100644 --- a/pages/deployments/dashboard.md +++ b/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 ``` diff --git a/pages/deployments/notifications.md b/pages/deployments/notifications.md index 530aa032..aeb1a46d 100644 --- a/pages/deployments/notifications.md +++ b/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. diff --git a/pages/deployments/operator/architecture.md b/pages/deployments/operator/architecture.md index 2d93a501..cd707493 100644 --- a/pages/deployments/operator/architecture.md +++ b/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: git@github.com: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 diff --git a/pages/deployments/operator/helm-service.md b/pages/deployments/operator/helm-service.md index 2d1d05fc..00f47766 100644 --- a/pages/deployments/operator/helm-service.md +++ b/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 +``` \ No newline at end of file diff --git a/pages/deployments/terraform-interop.md b/pages/deployments/terraform-interop.md index 45c2e503..2663cdd2 100644 --- a/pages/deployments/terraform-interop.md +++ b/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. diff --git a/src/NavData.tsx b/src/NavData.tsx index be09038e..cfe8d9cf 100644 --- a/src/NavData.tsx +++ b/src/NavData.tsx @@ -94,7 +94,7 @@ const rootNavData: NavMenu = deepFreeze([ sections: [ { title: 'Setting Up Your Management Cluster', - href: '/how-to/set-up/mgmt-cluster' + href: '/how-to/set-up/mgmt-cluster', }, { title: 'Integrate with your Source Control Provider', @@ -109,7 +109,7 @@ const rootNavData: NavMenu = deepFreeze([ href: '/how-to/set-up/controllers', }, { - title: "Set Up a Basic Self-Service Worklfow with PR Automations", + title: 'Set Up a Basic Self-Service Worklfow with PR Automations', href: '/how-to/deploy/pr-automation', }, { @@ -122,6 +122,32 @@ const rootNavData: NavMenu = deepFreeze([ }, ], }, + { + href: '/deployments/using-operator', + title: 'Deploying Using Plural Continuous Deployment', + sections: [ + { + title: 'Architecture', + href: '/deployments/operator/architecture', + }, + { + title: 'API Reference', + href: '/deployments/operator/api', + }, + { + title: 'Git Services', + href: '/deployments/operator/git-service', + }, + { + title: 'Helm Services', + href: '/deployments/operator/helm-service', + }, + { + title: 'Global Services', + href: '/deployments/operator/global-service', + }, + ], + }, { href: '/stacks/', title: 'Iac Management with Stacks', @@ -154,35 +180,9 @@ const rootNavData: NavMenu = deepFreeze([ title: 'Auto-Cancellation', href: '/stacks/auto-cancellation', }, - ], - }, - { - href: '/deployments/using-operator', - title: 'Deploying Using the Plural Operator', - sections: [ - { - title: 'Architecture', - href: '/deployments/operator/architecture', - }, - { - title: 'API Reference', - href: '/deployments/operator/api', - }, - { - title: 'Git Services', - href: '/deployments/operator/git-service', - }, { - title: 'Helm Services', - href: '/deployments/operator/helm-service', - }, - { - title: 'Global Services', - href: '/deployments/operator/global-service', - }, - { - title: 'Defining Pipelines', - href: '/deployments/operator/pipeline', + href: '/deployments/terraform-interop', + title: 'Service Contexts', }, ], }, @@ -195,7 +195,7 @@ const rootNavData: NavMenu = deepFreeze([ href: '/deployments/pr/crds', }, { - title: "Testing PR Automations", + title: 'Testing PR Automations', href: '/deployments/pr/testing', }, { @@ -216,10 +216,6 @@ const rootNavData: NavMenu = deepFreeze([ href: '/deployments/templating', title: 'Service Templating', }, - { - href: '/deployments/terraform-interop', - title: 'Service Contexts and Terraform', - }, { href: '/deployments/notifications', title: 'Notifications',