A Jenkinsfile is a text file that contains the definition of a Jenkins pipeline and is checked into a source code control repository. The Jenkinsfile stores the entire workflow as code, making it the foundation for code review and the pipeline iteration process. For more information, please refer to Jenkins Official Documentation.

This document demonstrates how to create a pipeline based on a Jenkinsfile in a GitHub repository and use that pipeline to deploy a sample application to a development environment and a production environment, both accessible externally.

Note

DevOps supports creating two types of pipelines: one is the pipeline created based on a Jenkinsfile in SCM as introduced in this document, and the other is the pipeline created using the graphical editing panel.

Jenkinsfile in SCM requires a built-in Jenkinsfile in the source code management (SCM), meaning the Jenkinsfile must be part of the SCM. The DevOps system automatically builds the CI/CD pipeline based on the existing Jenkinsfile in the code repository. By defining the workflow, such as stage and step, specific build, test, and deployment requirements can be met.

Prerequisites

  • The DevOps extension must be installed and enabled on the KubeSphere platform.

  • You need a Docker Hub account and a GitHub account.

  • You have created a workspace, a DevOps project, and a user (e.g., project-regular), and have invited this user to the DevOps project and granted the operator role. Please refer to Inviting a User to a DevOps Project.

  • You have created a user (e.g., project-admin) who has the project creation permission in the workspace.

  • You have set up a dedicated CI node for running pipelines. Please refer to Setting Up a CI Node for Caching Dependencies.

  • You have installed and configured SonarQube (optional). Please refer to Integrating SonarQube into a Pipeline. If you skip this part, the following SonarQube Analysis stage will not be present.

Pipeline Overview

This sample pipeline includes the following stages.

Note

  • Stage 1: Checkout SCM: Checks out the source code from the GitHub repository.

  • Stage 2: Unit Test: The next stage proceeds only after this test passes.

  • Stage 3: SonarQube Analysis: SonarQube code quality analysis.

  • Stage 4: Build and Push Snapshot Image: Builds the image based on the branch selected in the Strategy Settings and pushes the SNAPSHOT-$BRANCH_NAME-$BUILD_NUMBER tag to Docker Hub, where $BUILD_NUMBER is the run ID of the record in the pipeline run history list.

  • Stage 5: Push Latest Image: Tags the v4.1.0-sonarqube branch as latest and pushes it to Docker Hub.

  • Stage 6: Deploy to Development Environment: Deploys the v4.1.0-sonarqube branch to the development environment. This stage requires approval.

  • Stage 7: Push with Tag: Generates a tag and releases it to GitHub. This tag is also pushed to Docker Hub.

  • Stage 8: Deploy to Production Environment: Deploys the released tag to the production environment.

Steps 1: Create Credentials

  1. Log in to the KubeSphere console as the project-regular user and enter your workspace.

  2. In the left navigation pane, select DevOps > Credentials.

  3. Select a DevOps project from the drop-down list in the upper left corner of the page.

  4. Create the following credentials. For more information on how to create credentials, refer to Credentials.

    Credential ID Type Purpose

    dockerhub-id

    Username and Password

    Docker Hub

    github-id

    Username and Password

    GitHub

    demo-kubeconfig

    kubeconfig

    Kubernetes
    Note

    Since August 2021, GitHub requires token-based authentication. You need to enter a token here, not your GitHub password. For information on how to generate a token, refer to Creating a personal access token.
    Note

    If your account or password contains special characters, such as @ and $, it may cause errors during pipeline execution due to unrecognized characters. In this case, you need to encode your account or password on a third-party website (e.g., urlencoder) first, then copy and paste the output as your credential information.

  5. (Optional) Create another credential for SonarQube (sonar-token) for the aforementioned Stage 3 (Code Analysis). Select Access Token as the credential type, enter the SonarQube token in the Token field. Refer to Create a SonarQube Token for a New Project. Click OK to complete the operation.

  6. You will see the created credentials on the Credentials page.

Step 2: Modify the Jenkinsfile in the GitHub Repository

  1. Log in to GitHub and Fork all branches of the GitHub repository devops-maven-sample to your personal GitHub account.

  2. In your own GitHub repository devops-maven-sample, switch to the v4.1.0-sonarqube branch, and click the file Jenkinsfile-online in the root directory.

  3. Click the edit icon on the right to edit the environment variables.

    Entry Value Description

    DOCKER_CREDENTIAL_ID

    dockerhub-id

    The name you set for your Docker Hub account in KubeSphere.

    GITHUB_CREDENTIAL_ID

    github-id

    The name you set for your GitHub account in KubeSphere, used to push tags to your GitHub repository.

    KUBECONFIG_CREDENTIAL_ID

    demo-kubeconfig

    The name you set for the kubeconfig in KubeSphere, used to access the running Kubernetes cluster.

    REGISTRY

    docker.io

    Default is docker.io, used as the address for pushing images.

    DOCKERHUB_NAMESPACE

    your-dockerhub-id

    Replace with your Docker Hub account name, or the name of an Organization under that account.

    GITHUB_ACCOUNT

    your-github-id

    Please replace it with your GitHub account name. For example, if your GitHub address is https://github.com/kubesphere/, then your GitHub account name is kubesphere. You can also replace it with an Organization name under that account.

    APP_NAME

    devops-maven-sample

    Application name.

    SONAR_CREDENTIAL_ID

    sonar-token

    The name you set for the SonarQube token in KubeSphere, used for code quality detection.

  4. After editing the environment variables, click Commit changes to update the file in the v4.1.0-sonarqube branch.

Step 3: Create Projects

Create two projects, for example, kubesphere-sample-dev and kubesphere-sample-prod, representing the development environment and production environment respectively. After the pipeline runs successfully, the relevant Deployments and Services for the application will be automatically created in these two projects.

Note

You need to create the project-admin account in advance to serve as the reviewer for the CI/CD pipeline.

  1. Log in to KubeSphere as the project-admin user and create the following two projects in the workspace where the DevOps project is created.

    Project Name Alias

    kubesphere-sample-dev

    development environment

    kubesphere-sample-prod

    production environment

  2. Invite the project-regular account to these two projects and assign the operator role.

Step 4: Create a Pipeline

  1. On the DevOps > Pipelines page, click Create.

  2. In the dialog box that pops up, name it jenkinsfile-in-scm.

  3. Under Pipeline Type, select Multi-branch Pipeline.

  4. Under Code Repository, select a code repository and click Next to continue.

    If there is no available code repository, click Create Code Repository below. For more information, please refer to Import Code Repository.

    1. In the Import Code Repository dialog box, enter a code repository name (custom), and click to select a code repository.

    2. On the GitHub tab, select github-id from the drop-down menu of Credential, then click OK.

    3. In the GitHub list, select your GitHub account. All repositories associated with this token will be listed on the right. Select devops-maven-sample and click Select.

    4. Click OK to select your code repository.

  5. In Advanced Settings, check Discard old branches. For this tutorial, it is recommended to use the default values for Days to keep branches and Max # of branches to keep.

    Discarding old branches means you will also discard the branch records. Branch records include console output, archived artifacts, and other metadata related to specific branches. Fewer branches mean you can save disk space used by Jenkins. DevOps provides two options to determine when to discard old branches:

    • Days to keep branches: Branches older than the retention period will be deleted.

    • Max # of branches to keep: When the number of branches exceeds the maximum number, the oldest branch will be deleted.

    Note

    Days to keep branches and Max # of branches to keep can be applied to branches simultaneously. As long as a branch meets the condition set by either field, it will be deleted. For example, if you specify the retention days and the maximum number of branches as 2 and 3 respectively, when a branch’s retention days exceed 2 or the number of retained branches exceeds 3, that branch will be deleted. DevOps pre-fills these two fields with 7 and 5 by default.

  6. In Strategy Settings, DevOps provides four strategies by default. This example will not use the Discover PR from Forks strategy, so you can delete it. For the other strategies, there is no need to modify the settings; use the default values directly.

    Note

    You must select GitHub as the code repository to enable the Strategy Settings here.

    When Jenkins pipelines are running, pull requests (PRs) submitted by developers will also be treated as separate branches.

    Discover branches

    • Exclude branches that are also filed as PRs: Does not scan source branches, such as the master branch of the source repository. These branches need to be merged.

    • Only branches that are also filed as PRs: Scans only PR branches.

    • All branches: Pulls all branches from the source repository.

    Discover PR from origin

    • Source Code after PR is merged: After the PR is merged into the target branch, the pipeline is created and run based on the source code.

    • Source Code of PR: Creates and runs a pipeline according to the source code of the PR itself.

    • Create both Pipelines: Creates two pipelines, one using the source code version after the PR is merged with the target branch, and the other using the source code version of the PR itself.

  7. Scroll down to Script Path and change it to Jenkinsfile-online, which is the filename of the Jenkinsfile located in the root directory of the example repository. This field specifies the path to the Jenkinsfile in the code repository. It represents the root directory of the repository. If the file location changes, the script path also needs to be updated.

  8. Under Scan Repository Triggers, check Periodically if not otherwise run and set the interval to 5 minutes. Click Create to finish the configuration.

Note

Setting a specific time interval allows the pipeline to scan the remote repository to detect code updates or new PRs according to the policy you set in Strategy Settings.

Step 5: Run the Pipeline

  1. After the pipeline is created, it will be displayed in the list. Click the pipeline name to view its details page.

    Note

    • On the Pipelines list page, click the more icon on the right side of the pipeline and select Copy to create a copy of the pipeline.

    • If you want to run multiple pipelines that do not contain multi-branches simultaneously, select all these pipelines on the Pipelines list page, and then click Run to run them in batches.

    • The Sync Status on the pipeline details page shows the synchronization result between KubeSphere and Jenkins. If successful, it will display Success along with a green checkmark icon.

  2. Under the Run Records tab, multiple branches are being scanned. Click Run on the right, and the pipeline will run according to the behavior policies you have set. Select the v4.1.0-sonarqube branch from the drop-down list, then add a tag number, such as v0.0.2. Click OK to start the run.

    Note

    • If you do not see any run records on this page, you need to manually refresh the browser or click Scan Repository in the Actions button.

    • The tag name is used to refer to the newly generated release and image in GitHub and Docker Hub. Existing tag names cannot be reused for the TAG_NAME field. Otherwise, the pipeline will fail to run.

  3. Wait a moment, then click on the run record to view the details.

    Note

    Pipeline failures can be caused by various factors. In this example, when editing the environment variables for the branch in the previous steps, only the Jenkinsfile for the v4.1.0-sonarqube branch was modified, while the variables in the v4.1.0 branch were not updated (using incorrect GitHub and Docker Hub accounts). Selecting the v4.1.0 branch will cause the run to fail. Other reasons such as network issues or incorrect coding in the Jenkinsfile may also lead to failures.

    Under the Run Logs tab of the run record details page, review the detailed information of the logs to troubleshoot and resolve issues based on them.

  4. If the pipeline runs successfully, it will pause at the deploy to dev stage, requiring a user with review permissions to click Proceed.

    In the Jenkinsfile, three stages are defined: deploy to dev, push with tag, and deploy to production. Each stage requires review. Therefore, when the pipeline reaches these stages, it pauses and waits for review.

    In development or production environments, personnel with higher permissions (e.g., release managers) may be needed to review the pipeline, images, and code analysis results. They have the authority to decide whether the pipeline can proceed to the next stage. In the Jenkinsfile, input can be used to specify the user who reviews the pipeline. If you want to specify a user (e.g., project-admin) for review, you can add a field in the Jenkinsfile. If there are multiple users, they need to be separated by commas, as shown below:

    input(id: 'release-image-with-tag', message: 'release image with tag?', submitter: 'project-admin,project-admin1')

  5. Log in to the KubeSphere web console with a user that has pipeline review permissions and enter your workspace. On the DevOps > Pipelines page, click the pipeline name to go to the details page. Under the Run Records tab, click the record you want to review, then click Continue to approve the pipeline.

Note

In KubeSphere, if no reviewer is specified, then the account that can run the pipeline can also continue or terminate that pipeline. In addition, the pipeline creator, users with the project-admin role of that project, or the accounts you specify also have permission to continue or terminate the pipeline.

Steps 6: Check Pipeline Status

  1. On the Pipeline tab of the run record, check the running status of the pipeline. The pipeline will initialize for a few minutes after it is created.

  2. Click the Run Logs tab to view the pipeline run logs. Click each stage to view its detailed logs. Click View Full Logs to troubleshoot and resolve issues based on the logs, or download the logs locally for further analysis.

Steps 7: Verify Results

  1. After the pipeline runs successfully, click Code Check to view the results via SonarQube. If SonarQube is not configured beforehand, this part is not available.

  2. As defined in the Jenkinsfile, the Docker image built by the pipeline has also been successfully pushed to Docker Hub. In Docker Hub, you will see an image tagged v0.0.2, which was specified before the pipeline run.

  3. Meanwhile, a new tag and a new release will be generated in GitHub.

  4. The sample application will be deployed to kubesphere-sample-dev and kubesphere-sample-prod, and the corresponding Deployments and Services will be created. Go to these two projects, and the expected results are as follows:

    Environment URL Namespace Deployment Service

    Development Environment

    http://{$NodeIP}:{$30861}

    kubesphere-sample-dev

    ks-sample-dev

    ks-sample-dev

    Production Environment

    http://{$NodeIP}:{$30961}

    kubesphere-sample-prod

    ks-sample

    ks-sample
    Note

    You may need to open this port in your security group to access the application via the URL.

Steps 8: Access Sample Service

  1. Log in to the KubeSphere web console as user platform-admin.

  2. Enter the kubesphere-sample-dev project, click ks-sample-dev under Services in Application Workloads. On the details page, obtain the Endpoint for accessing this service.

  3. Use kubectl in the Toolbox at the bottom right to execute the following command:

    curl 10.233.120.230:8080

  4. Expected output:

    Really appreciate your star, that's the power of our life.
    Note

    Use curl to access the Endpoint, or access {$Virtual IP}:{$Port} or {$Node IP}:{$NodePort}.

  5. You can also test the service in the kubesphere-sample-prod project, and you will see the same output.

    $ curl 10.233.120.236:8080
Really appreciate your star, that's the power of our life.