|
| 1 | +--- |
| 2 | +title: Pipelines |
| 3 | +description: Automate the journey of code from development to production |
| 4 | +--- |
| 5 | + |
| 6 | +Plural Pipelines automate Service Deployments across environments by promoting git-based changes through defined stages. |
| 7 | +With support for approval and job gates, they offer safe, customizable delivery flows. |
| 8 | + |
| 9 | +## Pipeline CRD in a Continuous Deployment Context |
| 10 | + |
| 11 | +The Pipeline CRD defines a custom Kubernetes resource to model and automate complex, multi-stage deployment pipelines. |
| 12 | +It integrates well with continuous deployment (CD) systems by enabling declarative configuration of deployment flows, |
| 13 | +including gating, promotions, and service progression. |
| 14 | + |
| 15 | +### The top-level resource that encapsulates the deployment workflow. |
| 16 | + - Stages represent discrete steps in your deployment pipeline. |
| 17 | + - Edges define the dependencies and ordering between stages. |
| 18 | + - FlowRef & ProjectRef provide contextual linkage to a broader application ecosystem. |
| 19 | + - Bindings can control RBAC policies for reading/writing pipeline data. |
| 20 | + |
| 21 | +#### PipelineStage and PipelineStageService |
| 22 | +Each stage is a logical unit within the pipeline. These can represent environments (e.g., dev, staging, prod) or specific deployment phases. |
| 23 | + - PipelineStageService includes: |
| 24 | + - ServiceRef: the Deployment Service being deployed. |
| 25 | + - Criteria: optional promotion rules that dictate when and how a service is allowed to advance. |
| 26 | + |
| 27 | +This design fits CD by enabling conditional promotions, a critical part of automating production pushes safely. |
| 28 | + |
| 29 | +#### PipelineEdge – Controlling Flow |
| 30 | +Edges define the flow of execution between stages. You can specify edges by name or ID and attach promotion Gates. |
| 31 | + |
| 32 | +#### PipelineGate – Promotion Control |
| 33 | +Gates serve as checkpoints between pipeline stages and enforce promotion policies. |
| 34 | +Three supported gate types: |
| 35 | + - APPROVAL: requires human sign-off (e.g., manager approval). |
| 36 | + - WINDOW: defines time-based constraints (e.g., deploy only during business hours). |
| 37 | + - JOB: runs a custom job (e.g., integration tests, security scans) before allowing promotion. |
| 38 | + |
| 39 | +#### JobSpec and GateSpec – Custom Execution |
| 40 | +For Job gates, the CRD allows inline definition of Kubernetes Jobs to be executed: |
| 41 | + - Specify namespace, containers, and Kubernetes-native configurations like annotations, labels, and serviceAccount. |
| 42 | + - Use Raw if you prefer to define jobs using full Kubernetes manifests. |
| 43 | + - Resource configurations help manage cluster efficiency and enforce compute limits. |
| 44 | + |
| 45 | +## Setup |
| 46 | +You're defining a simple two-stage continuous deployment pipeline using Plural’s Kubernetes-native CRDs. |
| 47 | + 1. dev stage – deployed to a cluster named dev |
| 48 | + 2. prod stage – promoted after passing a job and approval gate |
| 49 | + |
| 50 | +```yaml |
| 51 | +apiVersion: deployments.plural.sh/v1alpha1 |
| 52 | +kind: ServiceDeployment |
| 53 | +metadata: |
| 54 | + name: guestbook-dev |
| 55 | + namespace: default |
| 56 | +spec: |
| 57 | + version: 0.0.1 |
| 58 | + git: |
| 59 | + folder: guestbook |
| 60 | + ref: master |
| 61 | + repositoryRef: |
| 62 | + kind: GitRepository |
| 63 | + name: guestbook |
| 64 | + namespace: default |
| 65 | + clusterRef: |
| 66 | + kind: Cluster |
| 67 | + name: dev |
| 68 | + namespace: default |
| 69 | +--- |
| 70 | +apiVersion: deployments.plural.sh/v1alpha1 |
| 71 | +kind: ServiceDeployment |
| 72 | +metadata: |
| 73 | + name: guestbook-prod |
| 74 | + namespace: default |
| 75 | +spec: |
| 76 | + version: 0.0.1 |
| 77 | + git: |
| 78 | + folder: guestbook |
| 79 | + ref: master |
| 80 | + repositoryRef: |
| 81 | + kind: GitRepository |
| 82 | + name: guestbook |
| 83 | + namespace: default |
| 84 | + clusterRef: |
| 85 | + kind: Cluster |
| 86 | + name: prod |
| 87 | + namespace: default |
| 88 | +``` |
| 89 | +### Pipeline CRD |
| 90 | +
|
| 91 | +```yaml |
| 92 | +apiVersion: deployments.plural.sh/v1alpha1 |
| 93 | +kind: Pipeline |
| 94 | +metadata: |
| 95 | + name: test |
| 96 | + namespace: default |
| 97 | +spec: |
| 98 | + stages: |
| 99 | + - name: dev |
| 100 | + services: |
| 101 | + - serviceRef: |
| 102 | + name: guestbook-dev |
| 103 | + namespace: default |
| 104 | + - name: prod |
| 105 | + services: |
| 106 | + - serviceRef: |
| 107 | + name: guestbook-prod |
| 108 | + namespace: default |
| 109 | + criteria: |
| 110 | + serviceRef: |
| 111 | + name: guestbook-dev |
| 112 | + namespace: default |
| 113 | + secrets: |
| 114 | + - test-secret |
| 115 | + edges: |
| 116 | + - from: dev |
| 117 | + to: prod |
| 118 | + gates: |
| 119 | + - name: job-gate |
| 120 | + type: JOB |
| 121 | + clusterRef: |
| 122 | + name: dev |
| 123 | + namespace: default |
| 124 | + spec: |
| 125 | + job: |
| 126 | + namespace: default |
| 127 | + labels: |
| 128 | + test: test |
| 129 | + annotations: |
| 130 | + plural.sh/annotation: test |
| 131 | + serviceAccount: default |
| 132 | + containers: |
| 133 | + - image: alpine:3.7 |
| 134 | + args: |
| 135 | + - /bin/sh |
| 136 | + - -c |
| 137 | + - sleep 40 |
| 138 | + env: |
| 139 | + - name: TEST_ENV_VAR |
| 140 | + value: pipeline |
| 141 | + - name: approval-gate |
| 142 | + type: APPROVAL |
| 143 | +``` |
| 144 | +This edge controls the transition from dev → prod. It includes: |
| 145 | +
|
| 146 | + 1. Job Gate: A container runs in the dev cluster and must complete successfully |
| 147 | + - In this case, it’s an alpine container sleeping for 40 seconds, but in practice this could run tests, linting, etc. |
| 148 | + 2. Approval Gate: Requires manual approval before deploying to prod |
| 149 | +
|
| 150 | +You can view the complete working example of a Plural Pipeline including clusters, services, promotion logic, and gates on GitHub: |
| 151 | +
|
| 152 | + [pipeline.yaml on GitHub](https://github.com/pluralsh/console/blob/master/go/controller/config/samples/pipeline.yaml) |
| 153 | +
|
| 154 | +This example demonstrates a multi-stage deployment from `dev` to `prod`, using both job and approval gates to control promotion. |
0 commit comments