public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-04-19 21:05:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #828 from MBishop17/pipeline

Browse Source 
Pipeline
This commit is contained in:
Denise
2018-09-25 20:51:50 -07:00
committed by GitHub
parent 075a4a36a3 21207f0e8d
commit 0e2f95d2cd
8 changed files with 934 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

145
content/rancher/v2.x/en/tools/pipelines/_index.md
View File

@@ -5,131 +5,88 @@ aliases:
- /rancher/v2.x/en/concepts/ci-cd-pipelines/
- /rancher/v2.x/en/tasks/pipelines/
---
>**Notes:**
>
>- Pipelines are new and improved for Rancher v2.1! Therefore, if you configured pipelines while using v2.0.x, you'll have to reconfigure them after upgrading to v2.1.
>- Still using v2.0.x? See the pipeline documentation for [previous versions](/rancher/v2.x/en/tools/pipelines/docs-for-v2.0.x).
Pipelines help you automate the software delivery process. You can integrate Rancher with GitHub to create a pipeline.
A _pipeline_ is a software delivery process that is broken into different stages, allowing developers to deliver new software as quickly and efficiently as possible. Within Rancher, you can configure a pipeline for each of your Rancher projects.
You can set up your pipeline to run a series of stages and steps to test your code and deploy it.
The pipeline stages are:
<dl>
<dt>Pipelines</dt>
<dd>Contain a series of stages and steps. Out-of-the-box, the pipelines feature supports fan out and in capabilities.</dd>
<dt>Stages</dt>
<dd>Executed sequentially. The next stage will not execute until all of the steps within the stage execute.</dd>
<dt>Steps</dt>
<dd>Are executed in parallel within a stage. </dd>
</dl>
- **Build:**
## Enabling CI Pipelines
Each time code is checked into your repository, the pipeline automatically clones the repo and builds a new iteration of your software. Throughout this process, the software is typically reviewed by automated tests.
1. Select cluster from drop down.
- **Publish:**
2. Under tools menu select pipelines.
After each build is completed, it's automatically published to a Docker registry, where it can be pulled for manual testing.
3. Follow instructions for setting up github auth on page.
- **Deploy:**
A natural extension of the publish stage, the deploy stage lets you release your software to customers with the click of a button.
## Creating CI Pipelines
## Overview
1. Go to the project you want this pipeline to run in.
Rancher Pipeline provides a simple CI/CD experience. Use it to automatically checkout code, run builds, perform tests, publish docker images, and deploy Kubernetes resources to your clusters.
2. Select workloads from the top level Nav bar
You can configure a pipeline for each project in Rancher. Every project can have individual configurations and setups.
3. Select pipelines from from the secondary Nav bar
Pipelines are represented as pipeline files that are checked into source code repositories. Users can read and edit the pipeline configuration by either:
4. Click Add pipeline button.
- Using the Rancher UI.
- Updating the configuration in the repository, using tools like Git CLI to trigger a build with the latest CI definition.
5. Enter in your repository name (Autocomplete should help zero in on it quickly).
>**Note:** Rancher Pipeline not a replacement for enterprise-grade Jenkins or any other CI tool your team uses.
6. Select Branch options.
## Supported Version Control Platforms
- Only the branch {BRANCH NAME}: Only events triggered by changes to this branch will be built.
Rancher pipelines currently supports GitHub and GitLab (available as of Rancher v2.0.1).
- Evertyhing but {BRANCH NAME}: Build any branch that triggered an event EXCEPT events from this branch.
>**Note:** Additions to pipelines are scoped for future releases of Rancher, such as:
>
>- Additional version control systems
>- Deployment of Kubernetes YAML
>- Catalog deployment
- All branches: Regardless of the branch that triggered the event always build.
## How Pipelines Work
>**Note:** If you want one path for master, but another for PRs or development/test/feature branches, create two separate pipelines.
When you configure a pipeline in one of your projects, a namespace specifically for the pipeline is automatically created. The following components are deployed to it:
7. Select the build trigger events. By default, builds will only happen by manually clicking build now in Rancher UI.
- **Jenkins:**
- Automatically build this pipeline whenever there is a git commit. (This respects the branch selection above)
The pipeline's build engine. Because project users likely won't interact with Jenkins, it's managed and locked.
- Automatically build this pipeline whenever there is a new PR.
>**Note:** There is no option to reuse existing Jenkins deployments as the pipeline engine.
<a id="reg"></a>
- Automatically build the pipeline. (Allows you to configure scheduled builds similar to Cron)
- **Docker Registry:**
8. Click Add button.
Out-of-the-box, the default target for your builds is an internal Docker Registry. However, you can make configurations to push to a remote registry instead. Docker Registry is only accessible from cluster nodes and cannot be directly accessed by users.
By default, Rancher provides a three stage pipeline for you. It consists of a build stage where you would compile, unit test, and scan code. The publish stage has a single step to publish a docker image.
<a id="minio"></a>
- **Minio:**
Minio storage is used to store the logs for pipeline executions.
>**Note:** The managed Jenkins instance works statelessly, so don't worry about its data persistency. The Docker Registry and Minio instances use ephemeral volumes by default, but we recommend that you configure persistent volumes for them, as described in [data persistency for pipeline components](/rancher/v2.x/en/tools/pipelines/configurations/#data-persistency-for-pipeline-components).
8. Add a name to the pipeline in order to complete adding a pipeline.
## Pipeline Triggers
9. Click on the ‘run a script’ box under the ‘Build’ stage.
Here you can set the image, or select from pre-packaged envs.
10. Configure a shell script to run inside the container when building.
11. Click Save to persist the changes.
12. Click the “publish an image’ box under the “Publish” stage.
13. Set the location of the Dockerfile. By default it looks in the root of the workspace. Instead, set the build context for building the image relative to the root of the workspace.
14. Set the image information.
The registry is the remote registry URL. It is defaulted to Docker hub.
Repository is the `<org>/<repo>` in the repository.
15. Select the Tag. You can hard code a tag like ‘latest’ or select from a list of available variables.
16. If this is the first time using this registry, you can add the username/password for pushing the image. You must click save for the registry credentials AND also save for the modal.
After you configure a pipeline, you can trigger it using different methods:
- **Manually:**
After you configure a pipeline, you can trigger a build using the latest CI definition from either Rancher UI or Git CLI. When a pipeline execution is triggered, Rancher dynamically provisions a Kubernetes pod to run your CI tasks and then remove it upon completion.
## Creating a New Stage
- **Automatically:**
1. To add a new stage the user must click the ‘add a new stage’ link in either create or edit mode of the pipeline view.
When you enable a repository for a pipeline, webhooks are automatically added to the version control system. When project users interact with the repo—push code, open pull requests, or create a tag—the version control system sends a webhook to Rancher Server, triggering a pipeline execution.
2. Provide a name for the stage.
3. Click save.
## Creating a New Step
1. Go to create / edit mode of the pipeline.
2. Click “Add Step” button in the stage that you would like to add a step in.
3. Fill out the form as detailed above
## Environment Variables
For your convenience the following environment variables are available in your build steps:
Variable Name | Description
------------------------|------------------------------------------------------------
CICD_GIT_REPO_NAME | Repository Name (Stripped of Github Organization)
CICD_PIPELINE_NAME | Name of the pipeline
CICD_GIT_BRANCH | Git branch of this event
CICD_TRIGGER_TYPE | Event that triggered the build
CICD_PIPELINE_ID | Rancher ID for the pipeline
CICD_GIT_URL | URL of the Git repository
CICD_EXECUTION_SEQUENCE | Build number of the pipeline
CICD_EXECUTION_ID | Combination of {CICD_PIPELINE_ID}-{CICD_EXECUTION_SEQUENCE}
CICD_GIT_COMMIT | Git commit ID being executed.
<!--### Adding a Build Script
Coming Soon
### Publishing an Image
Coming Soon-->
## Importing a Pipeline From YAML
If there is a ##YAML FILE### already checked into the github repository click import.
To use this automation, webhook management permission is required for the repo. Therefore, when users authenticate and fetch their repositories, only those on which they have admin permission will be shown.

22
content/rancher/v2.x/en/tools/pipelines/concepts/_index.md Normal file
View File

@@ -0,0 +1,22 @@
---
title: Pipeline Terminology
weight: 1000
---
When setting up a pipeline, it's helpful to know a few related terms.
- **Pipeline:**
A pipeline consists of stages and steps. It defines the process to build, test, and deploy your code. Rancher pipeline uses the [pipeline as code](https://jenkins.io/doc/book/pipeline-as-code/) model—pipeline configuration is represented as a pipeline file in the source code repository, using the file name `.rancher-pipeline.yml` or `.rancher-pipeline.yaml`.
- **Stages:**
A pipeline stage consists of multiple steps. Stages are executed in the order defined in the pipeline file. The steps in a stage are executed concurrently. A stage starts when all steps in the former stage finish without failure.
- **Steps:**
A pipeline step is executed inside a specified stage. A step fails if it exits with a code other than `0`. If a step exits with this failure code, the entire pipeline fails and terminates.
- **Workspace:**
The workspace is the working directory shared by all pipeline steps. In the beginning of a pipeline, source code is checked out to the workspace. The command for every step bootstraps in the workspace. During a pipeline execution, the artifacts from a previous step will be available in future steps. The working directory is an ephemeral volume and will be cleaned out with the executor pod when a pipeline execution is finished.

593
content/rancher/v2.x/en/tools/pipelines/configurations/_index.md Normal file
View File

@@ -0,0 +1,593 @@
---
title: Configuring Pipelines
weight: 3725
---
Configuring a pipeline automates the process of triggering and publishing builds. This section describes how to set up a pipeline in a production environment.
- The [Basic Configuration](#basic-configuration) section provides sequential instruction on how to configure a functional pipeline.
- The [Advanced Configuration](#advanced-configuration) section provides instructions for configuring pipeline options.
## Basic Configuration
To configure a functional pipeline for your project, begin by completing the mandatory basic configuration steps.
### Pipeline Configuration Outline
Initial configuration of a pipeline in a production environment involves completion of several mandatory procedures.
>**Note:** Before setting up a pipeline for a production environment, we recommend trying the [Pipeline Quick Start Guide]({{< baseurl >}}/rancher/v2.x/en/tools/pipelines/quick-start-guide).
<!-- TOC -->
- [1. Configuring Version Control Providers](#1-configuring-version-control-providers)
- [2. Configuring Pipeline Stages and Steps](#2-configuring-pipeline-stages-and-steps)
- [3. Running the Pipeline](#3-running-the-pipeline)
- [4. Configuring Persistent Data for Pipeline Components](#4-configuring-persistent-data-for-pipeline-components)
- [Advanced Configuration](#advanced-configuration)
<!-- /TOC -->
### 1. Configuring Version Control Providers
Begin configuration of your pipeline by enabling authentication with your version control provider. Rancher Pipeline supports integration with GitHub and GitLab.
Select your provider's tab below and follow the directions.
{{% tabs %}}
{{% tab "GitHub" %}}
1. From the context menu, open the project for which you're configuring a pipeline.
1. From the main menu, select **Resources > Pipelines**.
1. Follow the directions displayed to setup an OAuth application in GitHub.
![GitHub Pipeline Instructions]({{< baseurl >}}/img/rancher/github-pipeline.png)
1. From GitHub, copy the **Client ID** and **Client Secret**. Paste them into Rancher.
1. If you're using GitHub for enterprise, select **Use a private github enterprise installation**. Enter the host address of your GitHub installation.
1. Click **Authenticate**.
1. Enable the repository for which you want to run a pipeline. Then click **Done**.
{{% /tab %}}
{{% tab "GitLab" %}}
1. From the context menu, open the project for which you're configuring a pipeline.
1. From the main menu, select **Resources > Pipelines**.
1. Follow the directions displayed to setup a GitLab application.
![GitLab Pipeline Instructions]({{< baseurl >}}/img/rancher/gitlab-pipeline.png)
1. From GitLab, copy the **Application ID** and **Secret**. Paste them into Rancher.
1. If you're using GitLab for enterprise setup, select **Use a private gitlab enterprise installation**. Enter the host address of your GitLab installation.
1. Click **Authenticate**.
1. Enable the repository for which you want to run a pipeline. Then click **Done**.
>**Note:** If you use GitLab and your Rancher setup is in a local network, enable the **Allow requests to the local network from hooks and services** option in GitLab admin settings.
{{% /tab %}}
{{% /tabs %}}
**Result:** A pipeline is added to the project.
<!-- What happens if you change this value while builds are running? -->
### 2. Configuring Pipeline Stages and Steps
Now that the pipeline is added to your project, you need to configure its automated stages and steps. For your convenience, there are multiple built-in step types for dedicated tasks.
1. From your project's **Pipeline** tab, find your new pipeline, and select **Ellipsis (...) > Edit Config**.
>**Note:** When configuring a pipeline, it takes a few moments for Rancher to check for an existing pipeline configuration.
1. Click **Configure pipeline for this branch**.
1. Add stages to your pipeline execution by clicking **Add Stage**.
1. Add steps to each stage by clicking **Add a Step**. You can add multiple steps to each stage.
>**Note:** As you build out each stage and step, click `Show advanced options` to make [Advanced Configurations](#advanced-configuration), such as rules to trigger or skip pipeline actions, add environment variables, or inject environment variables using secrets. Advanced options are available the pipeline, each stage, and each individual step.
**Step types available include:**
{{% accordion id="clone" label="Clone" %}}
The first stage is preserved to be a cloning step that checks out source code from your repo. Rancher handles the cloning of the git repository. This action is equivalent to `git clone <repository_link> <workspace_dir>`.
{{% /accordion %}}
{{% accordion id="run-script" label="Run Script" %}}
The **Run Script** step executes arbitrary commands in the workspace inside a specified container. You can use it to build, test and do more, given whatever utilities the base image provides. For your convenience you can use variables to refer to metadata of a pipeline execution. Please go to [reference page](/rancher/v2.x/en/tools/pipelines/reference/#variable-substitution) for the list of available vairables.
{{% tabs %}}
{{% tab "By UI" %}}
<br/>
1. From the **Step Type** drop-down, choose **Run Script** and fill in the form.
1. Click **Add**.
{{% /tab %}}
{{% tab "By YAML" %}}
```yaml
# example
stages:
- name: Build something
steps:
- runScriptConfig:
image: golang
shellScript: go build
```
{{% /tab %}}
{{% /tabs %}}
{{% /accordion %}}
{{% accordion id="build-publish-image" label="Build and Publish Images" %}}
The **Build and Publish Image** step builds and publishes a Docker image. This process requires a Dockerfile in your source code's repository to complete successfully.
{{% tabs %}}
{{% tab "By UI" %}}
1. From the **Step Type** drop-down, choose **Build and Publish**.
1. Fill in the rest of the form. Descriptions for each field are listed below. When you're done, click **Add**.
Field | Description |
---------|----------|
Dockerfile Path | The relative path to the Dockerfile in the source code repo. By default, this path is `./Dockerfile`, which assumes the Dockerfile is in the root directory. You can set it to other paths in different use cases (`./path/to/myDockerfile` for example). |
Image Name | The image name in `name:tag` format. The registry address is not required. For example, to build `example.com/repo/my-image:dev`, enter `repo/my-image:dev`. |
Push image to remote repository | An option to set the registry that publishes the image that's built. To use this option, enable it and choose a registry from the drop-down. If this option is disabled, the image is pushed to the internal registry. |
Build Context <br/><br/> (**Show advanced options**)| By default, the root directory of the source code (`.`). For more details, see the Docker [build command documentation](https://docs.docker.com/engine/reference/commandline/build/).
{{% /tab %}}
{{% tab "By YAML" %}}
```yaml
# example
stages:
- name: Publish Image
steps:
- publishImageConfig:
dockerfilePath: ./Dockerfile
buildContext: .
tag: repo/app:v1
pushRemote: true
registry: example.com
```
You can use specific arguments for Docker daemon and the build. They are not exposed in the UI, but they are available in pipeline YAML format, as indicated in the example above. Available variables includes:
Variable Name | Description
------------------------|------------------------------------------------------------
PLUGIN_DRY_RUN | Disable docker push
PLUGIN_DEBUG | Docker daemon executes in debug mode
PLUGIN_MIRROR | Docker daemon registry mirror
PLUGIN_INSECURE | Docker daemon allows insecure registries
PLUGIN_BUILD_ARGS | Docker build args, a comma separated list
{{% /tab %}}
{{% /tabs %}}
{{% /accordion %}}
{{% accordion id="deploy-yaml" label="Deploy YAML" %}}
This step deploys arbitrary Kubernetes resources to the project. This deployment requires a Kubernetes manifest file to be present in the source code repository. Pipeline variable substitution is supported in the manifest file. You can view an example file at [GitHub](https://github.com/rancher/pipeline-example-go/blob/master/deployment.yaml). For available variables, refer to [Pipeline Variable Reference]({{< baseurl >}}rancher/v2.x/en/tools/pipelines/reference/).
{{% tabs %}}
{{% tab "By UI" %}}
1. From the **Step Type** drop-down, choose **Deploy YAML** and fill in the form.
1. Enter the **YAML Path**, which is the path to the manifest file in the source code.
1. Click **Add**.
{{% /tab %}}
{{% tab "By YAML" %}}
```yaml
# example
stages:
- name: Deploy
steps:
- applyYamlConfig:
path: ./deployment.yaml
```
{{% /tab %}}
{{% /tabs %}}
{{% /accordion %}}
1. When you're finished adding stages and steps, click **Done.**
### 3. Running the Pipeline
Run your pipeline for the first time. From the **Pipeline** tab, find your pipeline and select **Ellipsis (...) > Run**.
During this initial run, your pipeline is tested, and the following [pipeline components](/Users/markbishop/Documents/GitHub/docs/content/rancher/v2.x/en/tools/pipelines/#how-pipelines-work) are deployed to your project as workloads in a new namespace dedicated to the pipeline:
- `docker-registry`
- `jenkins`
- `minio`
This process takes several minutes. When it completes, you can view each pipeline component from the project **Workloads** tab.
### 4. Configuring Persistent Data for Pipeline Components
The internal [Docker registry]({{< baseurl >}}/rancher/v2.x/en/tools/pipelines/#reg) and the [Minio]({{< baseurl >}}/rancher/v2.x/en/tools/pipelines/#minio) wokrloads use ephemeral volumes by default. This default storage works out-of-the-box and makes testing easy, but it does not help in cases of disaster recovery. We recommend that you to configure these two deployments to persist their data.
Complete both [A—Configuring Persistent Data for Docker Registry](#a—configuring-persistent-data-for-docker-registry) _and_ [B—Configuring Persistent Data for Minio](#b—configuring-persistent-data-for-minio).
>**Prerequisites (for both parts A and B):**
>
>[Persistent volumes]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/#persistent-volumes) must be available for the cluster.
#### A. Configuring Persistent Data for Docker Registry
1. From the project that you're configuring a pipeline for, select the **Workloads** tab.
1. Find the `docker-registry` workload and select **Ellipsis (...) > Edit**.
1. Scroll to the **Volumes** section and expand it. Make one of the following selections from the **Add Volume** menu, which is near the bottom of the section:
- **Add Volume > Add a new persistent volume (claim)**
- **Add Volume > Use an existing persistent volume (claim)**
1. Complete the form that displays to choose a persistent volume for the internal Docker registry.
{{% tabs %}}
{{% tab "Add a new persistent volume" %}}
<br/>
1. Enter a **Name** for the volume claim.
1. Select a volume claim **Source**:
- If you select **Use a Storage Class to provision a new persistent volume**, select a [Storage Class]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/#storage-classes) and enter a **Capacity**.
- If you select **Use an existing persistent volume**, choose a **Persistent Volume** from the drop-down.
1. From the **Customize** section, choose the read/write access for the volume.
1. Click **Define**.
{{% /tab %}}
{{% tab "Use an existing persistent volume" %}}
<br/>
1. Enter a **Name** for the volume claim.
1. Choose a **Persistent Volume Claim** from the drop-down.
1. From the **Customize** section, choose the read/write access for the volume.
1. Click **Define**.
{{% /tab %}}
{{% /tabs %}}
1. From the **Mount Point** field, enter `/var/lib/registry`, which is the data storage path inside the Docker registry container.
1. Click **Upgrade**.
#### B. Configuring Persistent Data for Minio
1. From the **Workloads** tab, find the `minio` workload and select **Ellipsis (...) > Edit**.
1. Scroll to the **Volumes** section and expand it. Make one of the following selections from the **Add Volume** menu, which is near the bottom of the section:
- **Add Volume > Add a new persistent volume (claim)**
- **Add Volume > Use an existing persistent volume (claim)**
1. Complete the form that displays to choose a persistent volume for the internal Docker registry.
{{% tabs %}}
{{% tab "Add a new persistent volume" %}}
<br/>
1. Enter a **Name** for the volume claim.
1. Select a volume claim **Source**:
- If you select **Use a Storage Class to provision a new persistent volume**, select a [Storage Class]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/volumes-and-storage/#storage-classes) and enter a **Capacity**.
- If you select **Use an existing persistent volume**, choose a **Persistent Volume** from the drop-down.
1. From the **Customize** section, choose the read/write access for the volume.
1. Click **Define**.
{{% /tab %}}
{{% tab "Use an existing persistent volume" %}}
<br/>
1. Enter a **Name** for the volume claim.
1. Choose a **Persistent Volume Claim** from the drop-down.
1. From the **Customize** section, choose the read/write access for the volume.
1. Click **Define**.
{{% /tab %}}
{{% /tabs %}}
1. From the **Mount Point** field, enter `/data`, which is the data storage path inside the Minio container.
1. Click **Upgrade**.
**Result:** Persistent storage is configured for your pipeline components.
## Advanced Configuration
During the process of configuring a pipeline, you can configure advanced options for triggering the pipeline or configuring environment variables.
- [Configuring Pipeline Trigger Rules](#configuring-pipeline-trigger-rules)
- [Configuring Timeouts](#configuring-timeouts)
- [Configuring Environment Variables](#configuring-environment-variables)
- [Configuring Pipeline Secrets](#configuring-pipeline-secrets)
- [Configuring the Executor Quota](#configuring-the-executor-quota)
### Configuring Pipeline Trigger Rules
When a repository is enabled, a webhook for it is automatically set in the version control system. By default, the project pipeline is triggered by a push event to a specific repository, but you can add (or change) events that trigger a build, such as a pull request or a tagging.
Trigger rules come in two types:
- **Run this when:**
This type of rule starts the pipeline, stage, or step when a trigger explicitly occurs.
- **Do Not Run this when:**
If all conditions evaluate to true, then the pipeline/stage/step is executed. Otherwise it is skipped. When a stage/step is skipped, it is considered successful and follow-up stages/steps continue to run. Wildcard character (`*`) expansion is supported in conditions.
{{% tabs %}}
{{% tab "Pipeline Trigger" %}}
You can configure trigger rules for the entire pipeline in two different contexts:
{{% accordion id="pipeline-creation" label="During Initial Pipeline Configuration" %}}
1. From the context menu, open the project for which you've configured a pipeline. Then select the **Pipelines** tab.
1. From the pipeline for which you want to edit build triggers, select **Ellipsis (...) > Edit Config**.
1. Click **Show advanced options**.
1. From **Trigger Rules**, configure rules to run or skip the pipeline.
1. Click **Add Rule**. In the **Value** field, enter the name of the branch that triggers the pipeline.
1. **Optional:** Add more branches that trigger a build.
{{% /accordion %}}
{{% accordion id="pipeline-settings" label="While Editing Pipeline Settings" %}}
After you've configured a pipeline, you can go back and choose the events that trigger a pipeline execution.
>**Note:** This option is not available for example repositories.
1. From the context menu, open the project for which you've configured a pipeline. Then select the **Pipelines** tab.
1. From the pipeline for which you want to edit build triggers, select **Ellipsis (...) > Setting**.
1. Select (or clear) the events that you want to trigger a pipeline execution.
1. Click **Save**.
{{% /accordion %}}
{{% /tab %}}
{{% tab "Stage Trigger" %}}
1. From the context menu, open the project for which you've configured a pipeline. Then select the **Pipelines** tab.
1. From the pipeline for which you want to edit triggers, select **Ellipsis (...) > Edit Config**.
1. From the pipeline stage that you want to configure a trigger for, click the **Edit** icon.
1. Click **Show advanced options**.
1. Add one or more trigger rules.
1. Click **Add Rule**.
1. Choose the **Type** that triggers the stage.
| Type | Value |
| ------ | -------------------------------------------------------------------- |
| Branch | The name of the branch that triggers the stage. |
| Event | The type of event that triggers the stage (Push, Pull Request, Tag). |
1. Click **Save**.
{{% /tab %}}
{{% tab "Step Trigger" %}}
1. From the context menu, open the project for which you've configured a pipeline. Then select the **Pipelines** tab.
1. From the pipeline for which you want to edit triggers, select **Ellipsis (...) > Edit Config**.
1. From the pipeline step that you want to configure a trigger for, click the **Edit** icon.
1. Click **Show advanced options**.
1. Add one or more trigger rules.
1. Click **Add Rule**.
1. Choose the **Type** that triggers the step.
| Type | Value |
| ------ | -------------------------------------------------------------------- |
| Branch | The name of the branch that triggers the stage. |
| Event | The type of event that triggers the stage (Push, Pull Request, Tag). |
1. Click **Save**.
{{% /tab %}}
{{% tab "Do Not Run YAML" %}}
```yaml
# example
stages:
- name: Build something
# Conditions for stages
when:
branch: master
event: [ push, pull_request ]
# Multiple steps run concurrently
steps:
- runScriptConfig:
image: busybox
shellScript: date -R
# Conditions for steps
when:
branch: [ master, dev ]
event: push
# branch conditions for the pipeline
branch:
include: [ master, feature/*]
exlclude: [ dev ]
```
{{% /tab %}}
{{% /tabs %}}
### Configuring Timeouts
Each pipeline execution has a default timeout of 60 second. If the pipeline execution cannot complete within its timeout period, the pipeline is aborted. If a pipeline has more executions than can be completed in 60 minutes,
{{% tabs %}}
{{% tab "By UI" %}}
1. From the context menu, open the project for which you've configured a pipeline. Then select the **Pipelines** tab.
1. From the pipeline for which you want to edit the timeout, select **Ellipsis (...) > Edit Config**.
1. Click **Show advanced options**.
1. Enter a new value in the **Timeout** field.
{{% /tab %}}
{{% tab "By YAML" %}}
```yaml
# example
stages:
- name: Build something
steps:
- runScriptConfig:
image: busybox
shellScript: ls
timeout: 30
```
{{% /tab %}}
{{% /tabs %}}
### Configuring Environment Variables
When configuring a pipeline, you can use environment variables to configure the step's script.
{{% tabs %}}
{{% tab "By UI" %}}
1. From the context menu, open the project for which you've configured a pipeline. Then select the **Pipelines** tab.
1. From the pipeline in which you want to use environment variables, select **Ellipsis (...) > Edit Config**.
1. Click the **Edit** icon for the step in which you want to use environment variables.
1. Click **Show advanced options**.
1. Click **Add Variable**, and then enter a key and value in the fields that appear. Add more variables if needed.
1. Edit the script, adding your environment variable(s).
1. Click **Save**.
{{% /tab %}}
{{% tab "By YAML" %}}
```yaml
# example
stages:
- name: Build something
steps:
- runScriptConfig:
image: busybox
shellScript: echo ${FIRST_KEY} && echo ${SECOND_KEY}
env:
FIRST_KEY: VALUE
SECOND_KEY: VALUE2
```
{{% /tab %}}
{{% /tabs %}}
### Configuring Pipeline Secrets
If you need to use security-sensitive information in your pipeline scripts (like a password), you can pass them in using [secrets]({{< baseurl >}}/rancher/v2.x/en/k8s-in-rancher/secrets/).
>**Prerequisite:** Create a secret for your project for use in pipelines.
>**Note:** Secret injection is disabled on pull request events.
{{% tabs %}}
{{% tab "By UI" %}}
1. From the context menu, open the project for which you've configured a pipeline. Then select the **Pipelines** tab.
1. From the pipeline in which you want to use environment variables, select **Ellipsis (...) > Edit Config**.
1. Click the **Edit** icon for the step in which you want to use environment variables.
1. Click **Show advanced options**.
1. Click **Add From Secret**. Select the secret file that you want to use. Then choose a key. Optionally, you can enter an alias for the key.
1. Click **Save**.
{{% /tab %}}
{{% tab "By YAML" %}}
```yaml
# example
stages:
- name: Build something
steps:
- runScriptConfig:
image: busybox
shellScript: echo ${ALIAS_ENV}
# environment variables from project secrets
envFrom:
- sourceName: my-secret
sourceKey: secret-key
targetKey: ALIAS_ENV
```
{{% /tab %}}
{{% /tabs %}}
### Configuring the Executor Quota
The _executor quota_ decides how many builds can run simultaneously in the project. If the number of triggered builds exceeds the quota, subsequent builds will queue until a vacancy opens. By default, the quota is `2`, but you can change it.
1. From the context menu, open the project for which you've configured a pipeline.
1. From the main menu, select **Resources > Pipelines**.
1. From `The maximum number of pipeline executors` increment the **Scale** up or down to change the quota. A value of `0` or less removes the quota limit.

121
content/rancher/v2.x/en/tools/pipelines/docs-for-v2.0.x/_index.md Normal file
View File

@@ -0,0 +1,121 @@
---
title: v2.0.x Pipeline Documentation
weight: 9000
---
Pipelines help you automate the software delivery process. You can integrate Rancher with GitHub to create a pipeline.
You can set up your pipeline to run a series of stages and steps to test your code and deploy it.
<dl>
<dt>Pipelines</dt>
<dd>Contain a series of stages and steps. Out-of-the-box, the pipelines feature supports fan out and in capabilities.</dd>
<dt>Stages</dt>
<dd>Executed sequentially. The next stage will not execute until all of the steps within the stage execute.</dd>
<dt>Steps</dt>
<dd>Are executed in parallel within a stage. </dd>
</dl>
## Enabling CI Pipelines
1. Select cluster from drop down.
2. Under tools menu select pipelines.
3. Follow instructions for setting up github auth on page.
## Creating CI Pipelines
1. Go to the project you want this pipeline to run in.
2. Select workloads from the top level Nav bar
3. Select pipelines from the secondary Nav bar
4. Click Add pipeline button.
5. Enter in your repository name (Autocomplete should help zero in on it quickly).
6. Select Branch options.
- Only the branch {BRANCH NAME}: Only events triggered by changes to this branch will be built.
- Evertyhing but {BRANCH NAME}: Build any branch that triggered an event EXCEPT events from this branch.
- All branches: Regardless of the branch that triggered the event always build.
>**Note:** If you want one path for master, but another for PRs or development/test/feature branches, create two separate pipelines.
7. Select the build trigger events. By default, builds will only happen by manually clicking build now in Rancher UI.
- Automatically build this pipeline whenever there is a git commit. (This respects the branch selection above)
- Automatically build this pipeline whenever there is a new PR.
- Automatically build the pipeline. (Allows you to configure scheduled builds similar to Cron)
8. Click Add button.
By default, Rancher provides a three stage pipeline for you. It consists of a build stage where you would compile, unit test, and scan code. The publish stage has a single step to publish a docker image.
8. Add a name to the pipeline in order to complete adding a pipeline.
9. Click on the ‘run a script’ box under the ‘Build’ stage.
Here you can set the image, or select from pre-packaged envs.
10. Configure a shell script to run inside the container when building.
11. Click Save to persist the changes.
12. Click the “publish an image’ box under the “Publish” stage.
13. Set the location of the Dockerfile. By default it looks in the root of the workspace. Instead, set the build context for building the image relative to the root of the workspace.
14. Set the image information.
The registry is the remote registry URL. It is defaulted to Docker hub.
Repository is the `<org>/<repo>` in the repository.
15. Select the Tag. You can hard code a tag like ‘latest’ or select from a list of available variables.
16. If this is the first time using this registry, you can add the username/password for pushing the image. You must click save for the registry credentials AND also save for the modal.
## Creating a New Stage
1. To add a new stage the user must click the ‘add a new stage’ link in either create or edit mode of the pipeline view.
2. Provide a name for the stage.
3. Click save.
## Creating a New Step
1. Go to create / edit mode of the pipeline.
2. Click “Add Step” button in the stage that you would like to add a step in.
3. Fill out the form as detailed above
## Environment Variables
For your convenience the following environment variables are available in your build steps:
Variable Name | Description
------------------------|------------------------------------------------------------
CICD_GIT_REPO_NAME | Repository Name (Stripped of Github Organization)
CICD_PIPELINE_NAME | Name of the pipeline
CICD_GIT_BRANCH | Git branch of this event
CICD_TRIGGER_TYPE | Event that triggered the build
CICD_PIPELINE_ID | Rancher ID for the pipeline
CICD_GIT_URL | URL of the Git repository
CICD_EXECUTION_SEQUENCE | Build number of the pipeline
CICD_EXECUTION_ID | Combination of {CICD_PIPELINE_ID}-{CICD_EXECUTION_SEQUENCE}
CICD_GIT_COMMIT | Git commit ID being executed.

60
content/rancher/v2.x/en/tools/pipelines/quick-start-guide/_index.md Normal file
View File

@@ -0,0 +1,60 @@
---
title: Pipelines Quick Start Guide
weight: 500
---
Rancher ships with several example repositories that you can use to familiarize yourself with pipelines. We recommend configuring and testing the example repository that most resembles your environment before using pipelines with your own repositories in a production environment. Use this example repository as a sandbox for repo configuration, build demonstration, etc. Rancher includes example repositories for:
- Go
- Maven
- php
## 1. Configure Repositories
By default, the example pipeline repositories are disabled. Go enable one (or more) to test out the pipeline feature.
1. From the context menu, open the project for which you want to run a pipeline.
1. From the main menu, select **Workloads**. The select the **Pipelines** tab.
1. Click **Configure Repositories**.
**Step Result:** A list of example repositories displays.
>**Note:** Example repositories only display if you haven't fetched your own repos.
1. Click **Enable** for one of the example repos (e.g., `https://github.com/rancher/pipeline-example-go.git`). Then click **Done**.
**Results:**
- A pipeline is configured for the example repository, and it's added to the **Pipeline** tab.
- The following workloads are deployed to a new namespace:
- `docker-registry`
- `jenkins`
- `minio`
## 2. Run Example Pipeline
<<<<<<< HEAD
1. Click Run.
>**Note:** When you are running a pipeline the first time, it will take a few minutes to pull relevant images and provision necessary pipeline components.
To understand what the example pipeline is doing, you can check the `.rancher-pipeline.yml` file in the example repositories, or click `Edit Config` action of the enabled repository to see it via UI wizard.
<<<<<<< HEAD
=======
=======
After configuring an example repository, run the pipeline to see how it works.
1. From the **Pipelines** tab, select **Ellipsis (...) > Run**.
>**Note:** When you run a pipeline the first time, it takes a few minutes to pull relevant images and provision necessary pipeline components.
To understand what the example pipeline is doing, select `Ellipsis (...) > Edit Config` for your repo. Alternatively, view the `.rancher-pipeline.yml` file in the example repositories.
**Result:** The pipeline runs.
## What's Next?
For detailed information about setting up a pipeline in production, see the [Configuring Pipelines]({{< baseurl >}}/rancher/v2.x/en/tools/pipelines/configurations/).

87
content/rancher/v2.x/en/tools/pipelines/reference/_index.md Normal file
View File

@@ -0,0 +1,87 @@
---
title: Pipeline Variable Reference
weight: 8000
---
For your convenience, the following variables are available for your pipeline configuration scripts. During pipeline executions, these variables are replaced by metadata. You can reference them in the form of `${VAR_NAME}`.
Variable Name | Description
------------------------|------------------------------------------------------------
<<<<<<< HEAD
CICD_GIT_REPO_NAME | Repository Name (Stripped of Github Organization)
CICD_GIT_URL | URL of the Git repository
CICD_GIT_COMMIT | Git commit ID being executed.
CICD_GIT_BRANCH | Git branch of this event
CICD_GIT_REF | Git reference specification of this event
CICD_GIT_TAG | Git tag name, set on tag event
CICD_EVENT | Event that triggered the build, can be "push", "pull_request" or "tag"
CICD_PIPELINE_ID | Rancher ID for the pipeline
CICD_EXECUTION_SEQUENCE | Build number of the pipeline
CICD_EXECUTION_ID | Combination of {CICD_PIPELINE_ID}-{CICD_EXECUTION_SEQUENCE}
CICD_REGISTRY | Address for the docker registry of previous publish image step, available in the kubernetes manifest file of a `Deploy YAML` step.
CICD_IMAGE | Name of the built image of previous publish image step, available in the kubernetes manifest file of a `Deploy YAML` step. It does not contain the image tag.
=======
`CICD_GIT_REPO_NAME` | Repository name (Github organization omitted).
`CICD_GIT_URL` | URL of the Git repository.
`CICD_GIT_COMMIT` | Git commit ID being executed.
`CICD_GIT_BRANCH` | Git branch of this event.
`CICD_GIT_REF` | Git reference specification of this event.
`CICD_GIT_TAG` | Git tag name, set on tag event.
`CICD_EVENT` | Event that triggered the build (`push`, `pull_request` or `tag`).
`CICD_PIPELINE_ID` | Rancher ID for the pipeline.
`CICD_EXECUTION_SEQUENCE` | Build number of the pipeline.
`CICD_EXECUTION_ID` | Combination of `{CICD_PIPELINE_ID}-{CICD_EXECUTION_SEQUENCE}`.
`CICD_REGISTRY` | Address for the Docker registry for the previous publish image step, available in the Kubernetes manifest file of a `Deploy YAML` step.
`CICD_IMAGE` | Name of the image built from the previous publish image step, available in the Kubernetes manifest file of a `Deploy YAML` step. It does not contain the image tag.<br/><br/> [Example](https://github.com/rancher/pipeline-example-go/blob/master/deployment.yaml)
>>>>>>> 893010ad... completing draft of pipelines
## Full `.rancher-pipeline.yml` Example
```yaml
# example
stages:
- name: Build something
# Conditions for stages
when:
branch: master
event: [ push, pull_request ]
# Multiple steps run concurrently
steps:
- runScriptConfig:
image: busybox
shellScript: echo ${FIRST_KEY} && echo ${ALIAS_ENV}
# Set environment variables in container for the step
env:
FIRST_KEY: VALUE
SECOND_KEY: VALUE2
# Set environment variables from project secrets
envFrom:
- sourceName: my-secret
sourceKey: secret-key
targetKey: ALIAS_ENV
- runScriptConfig:
image: busybox
shellScript: date -R
# Conditions for steps
when:
branch: [ master, dev ]
event: push
- name: Publish my image
steps:
- publishImageConfig:
dockerfilePath: ./Dockerfile
buildContext: .
tag: rancher/rancher:v2.0.0
# Optionally push to remote registry
pushRemote: true
registry: reg.example.com
- name: Deploy some workloads
steps:
- applyYamlConfig:
path: ./deployment.yaml
# branch conditions for the pipeline
branch:
include: [ master, feature/*]
exlclude: [ dev ]
```

BIN
src/img/rancher/github-pipeline.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 70 KiB

BIN
src/img/rancher/gitlab-pipeline.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB