diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 34011f59..90b7cad6 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -13,7 +13,7 @@ jobs: contents: read security-events: write name: CodeQL - runs-on: ubuntu-20.04 + runs-on: ubuntu-latest strategy: fail-fast: false matrix: diff --git a/generated/routes.json b/generated/routes.json index a3c07845..eff0808a 100644 --- a/generated/routes.json +++ b/generated/routes.json @@ -123,9 +123,13 @@ "relPath": "/plural-features/continuous-deployment/observer.md", "lastmod": "2025-05-10T04:29:16.000Z" }, + "/plural-features/continuous-deployment/pipelines": { + "relPath": "/plural-features/continuous-deployment/pipelines.md", + "lastmod": "2025-04-25T13:05:27.000Z" + }, "/plural-features/k8s-upgrade-assistant": { "relPath": "/plural-features/k8s-upgrade-assistant/index.md", - "lastmod": "2025-03-12T14:59:41.000Z" + "lastmod": "2025-05-11T23:04:59.000Z" }, "/plural-features/k8s-upgrade-assistant/upgrade-insights": { "relPath": "/plural-features/k8s-upgrade-assistant/upgrade-insights.md", @@ -205,7 +209,7 @@ }, "/plural-features/flows": { "relPath": "/plural-features/flows/index.md", - "lastmod": "2025-04-21T22:55:16.000Z" + "lastmod": "2025-05-11T23:04:59.000Z" }, "/plural-features/flows/create-a-flow": { "relPath": "/plural-features/flows/create-a-flow.md", @@ -217,7 +221,7 @@ }, "/plural-features/flows/preview-environments": { "relPath": "/plural-features/flows/preview-environments.md", - "lastmod": "2025-05-11T22:10:38.846Z" + "lastmod": "2025-05-12T00:16:07.000Z" }, "/plural-features/flows/mcp": { "relPath": "/plural-features/flows/mcp.md", @@ -445,7 +449,7 @@ }, "/deployments/deprecations": { "relPath": "/plural-features/k8s-upgrade-assistant/index.md", - "lastmod": "2025-03-12T14:59:41.000Z" + "lastmod": "2025-05-11T23:04:59.000Z" }, "/stacks/customize-runners": { "relPath": "/plural-features/stacks-iac-management/customize-runners.md", diff --git a/pages/plural-features/continuous-deployment/pipelines.md b/pages/plural-features/continuous-deployment/pipelines.md new file mode 100644 index 00000000..d1e55e43 --- /dev/null +++ b/pages/plural-features/continuous-deployment/pipelines.md @@ -0,0 +1,154 @@ +--- +title: Pipelines +description: Automate the journey of code from development to production +--- + +Plural Pipelines automate Service Deployments across environments by promoting git-based changes through defined stages. +With support for approval and job gates, they offer safe, customizable delivery flows. + +## Pipeline CRD in a Continuous Deployment Context + +The Pipeline CRD defines a custom Kubernetes resource to model and automate complex, multi-stage deployment pipelines. +It integrates well with continuous deployment (CD) systems by enabling declarative configuration of deployment flows, +including gating, promotions, and service progression. + +### The top-level resource that encapsulates the deployment workflow. + - Stages represent discrete steps in your deployment pipeline. + - Edges define the dependencies and ordering between stages. + - FlowRef & ProjectRef provide contextual linkage to a broader application ecosystem. + - Bindings can control RBAC policies for reading/writing pipeline data. + +#### PipelineStage and PipelineStageService +Each stage is a logical unit within the pipeline. These can represent environments (e.g., dev, staging, prod) or specific deployment phases. + - PipelineStageService includes: + - ServiceRef: the Deployment Service being deployed. + - Criteria: optional promotion rules that dictate when and how a service is allowed to advance. + +This design fits CD by enabling conditional promotions, a critical part of automating production pushes safely. + +#### PipelineEdge – Controlling Flow +Edges define the flow of execution between stages. You can specify edges by name or ID and attach promotion Gates. + +#### PipelineGate – Promotion Control +Gates serve as checkpoints between pipeline stages and enforce promotion policies. +Three supported gate types: + - APPROVAL: requires human sign-off (e.g., manager approval). + - WINDOW: defines time-based constraints (e.g., deploy only during business hours). + - JOB: runs a custom job (e.g., integration tests, security scans) before allowing promotion. + +#### JobSpec and GateSpec – Custom Execution +For Job gates, the CRD allows inline definition of Kubernetes Jobs to be executed: + - Specify namespace, containers, and Kubernetes-native configurations like annotations, labels, and serviceAccount. + - Use Raw if you prefer to define jobs using full Kubernetes manifests. + - Resource configurations help manage cluster efficiency and enforce compute limits. + +## Setup +You're defining a simple two-stage continuous deployment pipeline using Plural’s Kubernetes-native CRDs. + 1. dev stage – deployed to a cluster named dev + 2. prod stage – promoted after passing a job and approval gate + +```yaml +apiVersion: deployments.plural.sh/v1alpha1 +kind: ServiceDeployment +metadata: + name: guestbook-dev + namespace: default +spec: + version: 0.0.1 + git: + folder: guestbook + ref: master + repositoryRef: + kind: GitRepository + name: guestbook + namespace: default + clusterRef: + kind: Cluster + name: dev + namespace: default +--- +apiVersion: deployments.plural.sh/v1alpha1 +kind: ServiceDeployment +metadata: + name: guestbook-prod + namespace: default +spec: + version: 0.0.1 + git: + folder: guestbook + ref: master + repositoryRef: + kind: GitRepository + name: guestbook + namespace: default + clusterRef: + kind: Cluster + name: prod + namespace: default +``` +### Pipeline CRD + +```yaml +apiVersion: deployments.plural.sh/v1alpha1 +kind: Pipeline +metadata: + name: test + namespace: default +spec: + stages: + - name: dev + services: + - serviceRef: + name: guestbook-dev + namespace: default + - name: prod + services: + - serviceRef: + name: guestbook-prod + namespace: default + criteria: + serviceRef: + name: guestbook-dev + namespace: default + secrets: + - test-secret + edges: + - from: dev + to: prod + gates: + - name: job-gate + type: JOB + clusterRef: + name: dev + namespace: default + spec: + job: + namespace: default + labels: + test: test + annotations: + plural.sh/annotation: test + serviceAccount: default + containers: + - image: alpine:3.7 + args: + - /bin/sh + - -c + - sleep 40 + env: + - name: TEST_ENV_VAR + value: pipeline + - name: approval-gate + type: APPROVAL +``` +This edge controls the transition from dev → prod. It includes: + + 1. Job Gate: A container runs in the dev cluster and must complete successfully + - In this case, it’s an alpine container sleeping for 40 seconds, but in practice this could run tests, linting, etc. + 2. Approval Gate: Requires manual approval before deploying to prod + +You can view the complete working example of a Plural Pipeline including clusters, services, promotion logic, and gates on GitHub: + + [pipeline.yaml on GitHub](https://github.com/pluralsh/console/blob/master/go/controller/config/samples/pipeline.yaml) + +This example demonstrates a multi-stage deployment from `dev` to `prod`, using both job and approval gates to control promotion. diff --git a/src/routing/docs-structure.ts b/src/routing/docs-structure.ts index 6d8284d2..f94e2716 100644 --- a/src/routing/docs-structure.ts +++ b/src/routing/docs-structure.ts @@ -86,6 +86,7 @@ export const docsStructure: DocSection[] = [ path: 'observer', title: 'Plural Observers in Continuous Deployment', }, + { path: 'pipelines', title: 'Pipelines' }, ], }, {