README.adoc

Jenkins Pipeline (Common)

In this section we will present the common setup of Jenkins for any platform. We will also provide answers to most frequently asked questions.

Project setup

.
├── declarative-pipeline
│   └── Jenkinsfile-sample.groovy
├── jobs
│   ├── jenkins_pipeline_empty.groovy
│   ├── jenkins_pipeline_jenkinsfile_empty.groovy
│   ├── jenkins_pipeline_sample.groovy
│   └── jenkins_pipeline_sample_view.groovy
├── seed
│   ├── init.groovy
│   ├── jenkins_pipeline.groovy
│   ├── k8s
│   └── settings.xml
└── src
    ├── main
    └── test

In the declarative-pipeline you can find a definition of a Jenkinsfile-sample.groovy declarative pipeline. It’s used together with the Blueocean UI.

In the jobs folder you have all the seed jobs that will generate pipelines.

  • jenkins_pipeline_empty.groovy - is a template of a pipeline with empty steps using the Jenkins Job DSL plugin

  • jenkins_pipeline_jenkinsfile_empty.groovy - is a template of a pipeline with empty steps using the Pipeline plugin

  • jenkins_pipeline_sample.groovy - is an opinionated implementation using the Jenkins Job DSL plugin

  • jenkins_pipeline_sample_view.groovy - builds the views for the pipelines

In the seed folder you have the init.groovy file which is executed when Jenkins starts. That way we can configure most of Jenkins options for you (adding credentials, JDK etc.). jenkins_pipeline.groovy contains logic to build a seed job (that way you don’t have to even click that job - we generate it for you). Under the k8s folder there are all the configuration files required for deployment to a Kubernetes cluster.

In the src folder you have production and test classes needed for you to build your own pipeline. Currently we have tests only cause the whole logic resides in the jenkins_pipeline_sample file.

Optional customization steps

All the steps below are not necessary to run the demo. They are needed only when you want to do some custom changes.

Deploying infra jars to a different location

It’s enough to set the ARTIFACTORY_URL environmental variable before executing tools/deploy-infra.sh. Example for deploying to Artifactory at IP 192.168.99.100

git clone https://github.com/spring-cloud/spring-cloud-pipelines
cd spring-cloud-pipelines/
ARTIFACTORY_URL="http://192.168.99.100:8081/artifactory/libs-release-local" ./tools/deploy-infra.sh

Setup settings.xml for Maven deployment

Tip
If you want to use the default connection to the Docker version of Artifactory you can skip this step

So that ./mvnw deploy works with Artifactory from Docker we’re already copying the missing settings.xml file for you. It looks more or less like this:

<?xml version="1.0" encoding="UTF-8"?>
<settings>
	<servers>
		<server>
			<id>${M2_SETTINGS_REPO_ID}</id>
			<username>${M2_SETTINGS_REPO_USERNAME}</username>
			<password>${M2_SETTINGS_REPO_PASSWORD}</password>
		</server>
		<server>
			<id>${DOCKER_SERVER_ID}</id>
			<username>${DOCKER_USERNAME}</username>
			<password>${DOCKER_PASSWORD}</password>
			<configuration>
				<email>${DOCKER_EMAIL}</email>
			</configuration>
		</server>
	</servers>
</settings>

As you can see the file is parameterized. In Maven it’s enough to pass to ./mvnw command the proper system property to override that value. For example to pass a different docker email you’d have to call ./mvnw -DDOCKER_EMAIL=foo@bar.com and the value gets updated.

If you want to use your own version of Artifactory / Nexus you have to update the file (it’s in seed/settings.xml).

Setup Jenkins env vars

If you want to only play around with the demo that we’ve prepared you have to set ONE variable which is the REPOS variable. That variable needs to consists of comma separated list of URLs to repositories containing business apps. So you should pass your forked repos URLs.

You can do it in the following ways:

  • globally via Jenkins global env vars (then when you run the seed that variable will be taken into consideration and proper pipelines will get built)

  • modify the seed job parameters (you’ll have to modify the seed job configuration and change the REPOS property)

  • provide the repos parameter when running the seed job

For the sake of simplicity let’s go with the last option.

Important
If you’re choosing the global envs, you HAVE to remove the other approach (e.g. if you set the global env for REPOS, please remove that property in the seed job
Seed properties

Click on the seed job and pick Build with parameters. Then as presented in the screen below (you’ll have far more properties to set) just modify the REPOS property by providing the comma separated list of URLs to your forks. Whatever you set will be parsed by the seed job and passed to the generated Jenkins jobs.

Tip
This is very useful when the repos you want to build differ. E.g. use different JDK. Then some seeds can set the JDK_VERSION param to one version of Java installation and the others to another one.

Example screen:

seed

In the screenshot we could parametrize the REPOS and REPO_WITH_BINARIES params.

Global envs
Important
This section is presented only for informational purposes - for the sake of demo you can skip it

You can add env vars (go to configure Jenkins → Global Properties) for the following properties (example with defaults for PCF Dev):

Example screen:

env vars

Set Git email / user

Since our pipeline is setting the git user / name explicitly for the build step you’d have to go to Configure of the build step and modify the Git name / email. If you want to set it globally you’ll have to remove the section from the build step and follow these steps to set it globally.

You can set Git email / user globally like this:

   

manage jenkins
Step 1: Click 'Manage Jenkins'

   

configure system
Step 2: Click 'Configure System'

   

git
Step 3: Fill out Git user information

   

Add Jenkins credentials for GitHub

The scripts will need to access the credential in order to tag the repo.

You have to set credentials with id: git.

Below you can find instructions on how to set a credential (e.g. for Cloud Foundry cf-test credential but remember to provide the one with id git).

   

credentials system
Step 1: Click 'Credentials, System'

   

credentials global
Step 2: Click 'Global Credentials'

   

credentials add
Step 3: Click 'Add credentials'

   

credentials example
Step 4: Fill out the user / password and provide the git credential ID (in this example cf-test)

   

Testing Jenkins scripts

./gradlew clean build

Warning
The ran test only checks if your scripts compile.

How to work with Jenkins Job DSL plugin

Check out the tutorial. Provide the link to this repository in your Jenkins installation.

Warning
Remember that views can be overridden that’s why the suggestion is to contain in one script all the logic needed to build a view for a single project (check out that spring_cloud_views.groovy is building all the spring-cloud views).

Docker Image

If you would like to run the pre-configured Jenkins image somewhere other than your local machine, we have an image you can pull and use on DockerHub. The latest tag corresponds to the latest snapshot build. You can also find tags corresponding to stable releases that you can use as well.

Important
The Jenkins docker image is setup for demo purposes. For example it has the following system property -Dpermissive-script-security.enabled=no_security that disables script security. YOU SHOULD NOT USE IT ON PRODUCTION UNLESS YOU KNOW WHAT YOU’RE DOING.

Jenkins Pipeline (Cloud Foundry)

Important
In this chapter, we assume that you deploy your application to Cloud Foundry PaaS.

The Spring Cloud Pipelines repository contains job definitions and the opinionated setup pipeline, which uses the Jenkins Job DSL plugin. Those jobs form an empty pipeline and a opinionated sample pipeline that you can use in your company.

The following projects take part in the microservice setup for this demo.

  • Github Analytics: The app that has a REST endpoint and uses messaging — part off our business application.

  • Github Webhook: Project that emits messages that are used by Github Analytics — part of our business application.

  • Eureka: Simple Eureka Server. This is an infrastructure application.

  • Github Analytics Stub Runner Boot: Stub Runner Boot server to be used for tests with Github Analytics and using Eureka and Messaging. This is an infrastructure application.

Step-by-step

This is a guide for the Jenkins Job DSL based pipeline.

If you want only to run the demo as far as possible using PCF Dev and Docker Compose, do the following:

Fork Repositories

Four applications compose the pipeline:

You need to fork only the following, because only then can you tag and push the tag to your repository:

Start Jenkins and Artifactory

Jenkins + Artifactory can be ran locally. To do so, run the start.sh script from this repository. The following listing shows the script:

git clone https://github.com/spring-cloud/spring-cloud-pipelines
cd spring-cloud-pipelines/jenkins
./start.sh yourGitUsername yourGitPassword yourForkedGithubOrg

Then Jenkins runs on port 8080, and Artifactory runs on port 8081. The parameters are passed as environment variables to the Jenkins VM, and credentials are set. That way, you need not do any manual work on the Jenkins side. In the above parameters, the third parameter could be yourForkedGithubOrg or yourGithubUsername. Also the REPOS environment variable contains your GitHub org (in which you have the forked repos).

Instead of the Git username and password parameters, you could pass -key <path_to_private_key> (if you prefer to use key-based authentication with your Git repositories).

Deploy the Infra JARs to Artifactory

When Artifactory is running, run the tools/deploy-infra.sh script from this repo. The following listing shows the script:

git clone https://github.com/spring-cloud/spring-cloud-pipelines
cd spring-cloud-pipelines/
./tools/deploy-infra.sh

As a result, both the eureka and stub runner repositories are cloned, built, and uploaded to Artifactory.

Start PCF Dev

Tip
You can skip this step if you have CF installed and do not want to use PCF Dev. In that case, the only thing you have to do is to set up spaces.
Warning
Servers often run run out of resources at the stage step. If that happens clear some apps from PCF Dev and continue.

You have to download and start PCF Dev, as described here.

The default credentials when using PCF Dev are as follows:

username: user
password: pass
email: user
org: pcfdev-org
space: pcfdev-space
api: api.local.pcfdev.io

You can start PCF Dev as follows:

cf dev start

You must create three separate spaces, as follows:

cf login -a https://api.local.pcfdev.io --skip-ssl-validation -u admin -p admin -o pcfdev-org

cf create-space pcfdev-test
cf set-space-role user pcfdev-org pcfdev-test SpaceDeveloper
cf create-space pcfdev-stage
cf set-space-role user pcfdev-org pcfdev-stage SpaceDeveloper
cf create-space pcfdev-prod
cf set-space-role user pcfdev-org pcfdev-prod SpaceDeveloper

You can also run the ./tools/cf-helper.sh setup-spaces script to do this.

Run the Seed Job

We created the seed job for you, but you have to run it. When you do run it, you have to provide some properties. By default we create a seed that has all the properties options, but you can delete most of it. If you set the properties as global environment variables, you have to remove them from the seed.

To run the demo, provide a comma-separated list of the URLs of the two aforementioned forks (github-webhook and github-analytics') in the `REPOS variable.

The following images shows the steps involved:

   

seed click
Step 1: Click the 'jenkins-pipeline-seed-cf' job for Cloud Foundry and jenkins-pipeline-seed-k8s for Kubernetes

   

seed run
Step 2: Click the 'Build with parameters'

   

seed
Step 3: The REPOS parameter should already contain your forked repos (you’ll have more properties than the ones in the screenshot)

   

seed built
Step 4: This is how the results of seed should look like

Run the github-webhook Pipeline

We already created the seed job for you, but you have to run it. When you do run it, you have to provide some properties. By default, we create a seed that has all the properties options, but you can delete most of it. If you set the properties as global environment variables, you have to remove them from the seed.

To run the demo, provide a comma-separated list of URLs of the two aforementioned forks (github-webhook and github-analytics) in the REPOS variable.

The following images shows the steps involved:

   

seed views
Step 1: Click the 'github-webhook' view

   

pipeline run
Step 2: Run the pipeline

   

Important
If your build fails on deploy previous version to stage due to a missing jar, that means that you forgot to clear the tags in your repository. Typically, that happens because you removed the Artifactory volume with a deployed jar while a tag in the repository still points there. See here for how to remove the tag.

   

pipeline manual
Step 3: Click the manual step to go to stage (remember about killing the apps on test env). To do this click the ARROW next to the job name

   

Important
Servers often run run out of resources at the stage step. For that reason, we suggest killing all applications on test. See the FAQ for more detail.

   

pipeline finished
Step 4: The full pipeline should look like this

   

Declarative Pipeline & Blue Ocean

You can also use the declarative pipeline approach with the Blue Ocean UI.

The Blue Ocean UI is available under the blue/ URL (for example, for Docker Machine-based setup: http://192.168.99.100:8080/blue).

The following images show the various steps involved:

   

blue 1
Step 1: Open Blue Ocean UI and click on github-webhook-declarative-pipeline

   

blue 2
Step 2: Your first run will look like this. Click Run button

   

blue 3
Step 3: Enter parameters required for the build and click run

   

blue 4
Step 4: A list of pipelines will be shown. Click your first run.

   

blue 5
Step 5: State if you want to go to production or not and click Proceed

   

blue 6
Step 6: The build is in progress…​

   

blue 7
Step 7: The pipeline is done!

   

Important
There is no possibility of restarting a pipeline from a specific stage after failure. See this issue for more information
Warning
Currently, there is no way to introduce manual steps in a performant way. Jenkins blocks an executor when a manual step is required. That means that you run out of executors pretty quickly. See this issue and this StackOverflow question for more information.

Jenkins Cloud Foundry Customization

You can customize Jenkins for Cloud Foundry by setting a variety of environment variables.

Note
You need not see all the environment variables described in this section to run the demo. They are needed only when you want to make custom changes.

Environment Variable Summary

The environment variables that are used in all of the jobs are as follows:

Property Name Property Description Default value

BINARY_EXTENSION

Extension of the binary uploaded to Artifactory / Nexus. Example: war for WAR artifacts

jar

PAAS_TEST_API_URL

The URL to the CF API for the TEST environment

api.local.pcfdev.io

PAAS_STAGE_API_URL

The URL to the CF API for the STAGE environment

api.local.pcfdev.io

PAAS_PROD_API_URL

The URL to the CF API for the PROD environment

api.local.pcfdev.io

PAAS_TEST_ORG

Name of the org for the test env

pcfdev-org

PAAS_TEST_SPACE_PREFIX

Prefix of the name of the CF space for the test environment to which the app name is appended

sc-pipelines-test

PAAS_STAGE_ORG

Name of the org for the stage environment

pcfdev-org

PAAS_STAGE_SPACE

Name of the space for the stage environment

sc-pipelines-stage

PAAS_PROD_ORG

Name of the org for the prod environment

pcfdev-org

PAAS_PROD_SPACE

Name of the space for the prod environment

sc-pipelines-prod

REPO_WITH_BINARIES_FOR_UPLOAD

URL of the repository with the deployed jars

http://artifactory:8081/artifactory/libs-release-local

M2_SETTINGS_REPO_ID

The ID of server from Maven settings.xml

artifactory-local

JDK_VERSION

The name of the JDK installation

jdk8

PIPELINE_VERSION

The version of the pipeline (ultimately, also the version of the jar)

1.0.0.M1-${GROOVY,script ="new Date().format('yyMMdd_HHmmss')"}-VERSION

GIT_EMAIL

The email used by Git to tag the repository

email@example.com

GIT_NAME

The name used by Git to tag the repository

Pivo Tal

PAAS_HOSTNAME_UUID

Additional suffix for the route. In a shared environment, the default routes can be already taken

AUTO_DEPLOY_TO_STAGE

Whether deployment to stage be automatic

false

AUTO_DEPLOY_TO_PROD

Whether deployment to prod be automatic

false

API_COMPATIBILITY_STEP_REQUIRED

Whether the API compatibility step is required

true

DB_ROLLBACK_STEP_REQUIRED

Whether the DB rollback step is present

true

DEPLOY_TO_STAGE_STEP_REQUIRED

Whether to the deploy-to-stage step be present

true

BUILD_OPTIONS

Additional options you would like to pass to the Maven / Gradle build

Jenkins Credentials

Our scripts reference the credentials by IDs. The following table describes the defaults for the credentials:

Property Name Property Description Default value

PAAS_PROD_CREDENTIAL_ID

Credential ID for CF Prod environment access

cf-prod

GIT_CREDENTIAL_ID

Credential ID used to tag a Git repo

git

GIT_SSH_CREDENTIAL_ID

SSH credential ID used to tag a Git repo

gitSsh

GIT_USE_SSH_KEY

If true, pick the SSH credential id to use

false

REPO_WITH_BINARIES_CREDENTIAL_ID

Credential ID used for the repository with jars

repo-with-binaries

PAAS_TEST_CREDENTIAL_ID

Credential ID for CF Test environment access

cf-test

PAAS_STAGE_CREDENTIAL_ID

Credential ID for CF Stage environment access

cf-stage

If you already have in your system a credential to (for example) tag a repository, you can use it by passing the value of the GIT_CREDENTIAL_ID property.

Tip
See the cf-helper script for all the configuration options.

Jenkins Pipeline (Kubernetes)

Important
In this chapter, we assume that you deploy your application to Kubernetes PaaS.

The Spring Cloud Pipelines repository contains job definitions and the opinionated setup pipeline that uses Jenkins Job DSL plugin. Those jobs form an empty pipeline and an opinionated sample pipeline that you can use in your company.

The following projects take part in the microservice setup for this demo.

  • Github Analytics: The app that has a REST endpoint and uses messaging — part of our business application.

  • Github Webhook: Project that emits messages that are used by Github Analytics — part of our business application.

  • Eureka: Simple Eureka Server. This is an infrastructure application.

  • Github Analytics Stub Runner Boot: Stub Runner Boot server to be used for tests with Github Analytics ad uses Eureka and Messaging. This is an infrastructure application.

Step-by-step

This is a guide for a Jenkins Job DSL based pipeline.

If you want only to run the demo as far as possible by using PCF Dev and Docker Compose, do the following:

Fork Repositories

Four applications compose the pipeline

You need to fork only the following repositories, because only then can you tag and push the tag to your repository:

Start Jenkins and Artifactory

Jenkins and Artifactory can be ran locally. To do so, run the start.sh script from this repo. The following listing shows the script:

git clone https://github.com/spring-cloud/spring-cloud-pipelines
cd spring-cloud-pipelines/jenkins
./start.sh yourGitUsername yourGitPassword yourForkedGithubOrg yourDockerRegistryOrganization yourDockerRegistryUsername yourDockerRegistryPassword yourDockerRegistryEmail

Then Jenkins runs on port 8080, and Artifactory runs on port 8081. The provided parameters are passed as environment variables to the Jenkins VM and credentials are set. That way, you need not do any manual work on the Jenkins side. In the preceding script, the third parameter could be yourForkedGithubOrg or yourGithubUsername. Also the REPOS environment variable contains your GitHub org in which you have the forked repositories.

Instead of the Git username and password parameters, you could pass -key <path_to_private_key> if you prefer to use the key-based authentication with your Git repositories.

You need to pass the credentials for the Docker organization (by default, we search for the Docker images at Docker Hub) so that the pipeline can push images to your org.

Deploy the Infra JARs to Artifactory

When Artifactory is running, run the tools/deploy-infra.sh script from this repo. The following listing shows the script:

git clone https://github.com/spring-cloud/spring-cloud-pipelines
cd spring-cloud-pipelines/
./tools/deploy-infra-k8s.sh

As a result, both the eureka and stub runner repos are cloned, built, and uploaded to Artifactory and their docker images are built.

Important
Your local Docker process is reused by the Jenkins instance running in Docker. That is why you do not have to push these images to Docker Hub. On the other hand, if you run this sample in a remote Kubernetes cluster, the driver is not shared by the Jenkins workers, so you can consider pushing these Docker images to Docker Hub too.

Run the seed job

We created the seed job for you, but you have to run it. When you do run it, you have to provide some properties. By default we create a seed that has all the properties options, but you can delete most of it. If you set the properties as global environment variables, you have to remove them from the seed.

To run the demo, provide a comma-separated list of the URLs of the two aforementioned forks (github-webhook and github-analytics') in the `REPOS variable.

The following images shows the steps involved:

   

seed click
Step 1: Click the 'jenkins-pipeline-seed-cf' job for Cloud Foundry and jenkins-pipeline-seed-k8s for Kubernetes

   

seed run
Step 2: Click the 'Build with parameters'

   

seed
Step 3: The REPOS parameter should already contain your forked repos (you’ll have more properties than the ones in the screenshot)

   

seed built
Step 4: This is how the results of seed should look like

Run the github-webhook pipeline

We already created the seed job for you, but you have to run it. When you do run it, you have to provide some properties. By default, we create a seed that has all the properties options, but you can delete most of it. If you set the properties as global environment variables, you have to remove them from the seed.

To run the demo, provide a comma-separated list of URLs of the two aforementioned forks (github-webhook and github-analytics) in the REPOS variable.

The following images shows the steps involved:

   

seed views
Step 1: Click the 'github-webhook' view

   

pipeline run
Step 2: Run the pipeline

   

Important
If your build fails on deploy previous version to stage due to a missing jar, that means that you forgot to clear the tags in your repository. Typically, that happens because you removed the Artifactory volume with a deployed jar while a tag in the repository still points there. See here for how to remove the tag.

   

pipeline manual
Step 3: Click the manual step to go to stage (remember about killing the apps on test env). To do this click the ARROW next to the job name

   

Important
Servers often run run out of resources at the stage step. For that reason, we suggest killing all applications on test. See the FAQ for more detail.

   

pipeline finished
Step 4: The full pipeline should look like this

   

Declarative pipeline & Blue Ocean

You can also use the declarative pipeline approach with the Blue Ocean UI.

The Blue Ocean UI is available under the blue/ URL (for example, for Docker Machine-based setup: http://192.168.99.100:8080/blue).

The following images show the various steps involved:

   

blue 1
Step 1: Open Blue Ocean UI and click on github-webhook-declarative-pipeline

   

blue 2
Step 2: Your first run will look like this. Click Run button

   

blue 3
Step 3: Enter parameters required for the build and click run

   

blue 4
Step 4: A list of pipelines will be shown. Click your first run.

   

blue 5
Step 5: State if you want to go to production or not and click Proceed

   

blue 6
Step 6: The build is in progress…​

   

blue 7
Step 7: The pipeline is done!

   

Important
There is no possibility of restarting a pipeline from a specific stage after failure. See this issue for more information
Warning
Currently, there is no way to introduce manual steps in a performant way. Jenkins blocks an executor when a manual step is required. That means that you run out of executors pretty quickly. See this issue and this StackOverflow question for more information.

Jenkins Kubernetes customization

You can customize Jenkins for Cloud Foundry by setting a variety of environment variables.

Note
You need not see all the environment variables described in this section to run the demo. They are needed only when you want to make custom changes.

All env vars

The environment variables that are used in all of the jobs are as follows:

Property Name Property Description Default value

BUILD_OPTIONS

Additional options you would like to pass to the Maven / Gradle build

DOCKER_REGISTRY_ORGANIZATION

Name of the docker organization to which Docker images should be deployed

scpipelines

DOCKER_REGISTRY_CREDENTIAL_ID

Credential ID used to push Docker images

docker-registry

DOCKER_SERVER_ID

Server ID in settings.xml and Maven builds

docker-repo

DOCKER_EMAIL

Email used to connect to Docker registry and Maven builds

change@me.com

DOCKER_REGISTRY_ORGANIZATION

URL of the Kubernetes cluster for the test environment

scpipelines

DOCKER_REGISTRY_URL

URL of the docker registry

https://index.docker.io/v1/

PAAS_TEST_API_URL

URL of the API of the Kubernetes cluster for the test environment

192.168.99.100:8443

PAAS_STAGE_API_URL

URL of the API of the Kubernetes cluster for the stage environment

192.168.99.100:8443

PAAS_PROD_API_URL

URL of the API of the Kubernetes cluster for the prod environment

192.168.99.100:8443

PAAS_TEST_CA_PATH

Path to the certificate authority for test the environment

/usr/share/jenkins/cert/ca.crt

PAAS_STAGE_CA_PATH

Path to the certificate authority for stage the environment

/usr/share/jenkins/cert/ca.crt

PAAS_PROD_CA_PATH

Path to the certificate authority for the prod environment

/usr/share/jenkins/cert/ca.crt

PAAS_TEST_CLIENT_CERT_PATH

Path to the client certificate for the test environment

/usr/share/jenkins/cert/apiserver.crt

PAAS_STAGE_CLIENT_CERT_PATH

Path to the client certificate for the stage environment

/usr/share/jenkins/cert/apiserver.crt

PAAS_PROD_CLIENT_CERT_PATH

Path to the client certificate for the prod environment

/usr/share/jenkins/cert/apiserver.crt

PAAS_TEST_CLIENT_KEY_PATH

Path to the client key for the test environment

/usr/share/jenkins/cert/apiserver.key

PAAS_STAGE_CLIENT_KEY_PATH

Path to the client key for the stage environment

/usr/share/jenkins/cert/apiserver.key

PAAS_PROD_CLIENT_KEY_PATH

Path to the client key for the test environment

/usr/share/jenkins/cert/apiserver.key

PAAS_TEST_CLIENT_TOKEN_PATH

Path to the file containing the token for the test environment

PAAS_STAGE_CLIENT_TOKEN_PATH

Path to the file containing the token for the stage environment

PAAS_PROD_CLIENT_TOKEN_PATH

Path to the file containing the token for the prod environment

PAAS_TEST_CLIENT_TOKEN_ID

ID of the credential containing access token for test environment

PAAS_STAGE_CLIENT_TOKEN_ID

ID of the credential containing access token for the stage environment

PAAS_PROD_CLIENT_TOKEN_ID

ID of the credential containing access token for the prod environment

PAAS_TEST_CLUSTER_NAME

Name of the cluster for the test environment

minikube

PAAS_STAGE_CLUSTER_NAME

Name of the cluster for the stage environment

minikube

PAAS_PROD_CLUSTER_NAME

Name of the cluster for the prod environment

minikube

PAAS_TEST_CLUSTER_USERNAME

Name of the user for the test environment

minikube

PAAS_STAGE_CLUSTER_USERNAME

Name of the user for the stage environment

minikube

PAAS_PROD_CLUSTER_USERNAME

Name of the user for the prod environment

minikube

PAAS_TEST_SYSTEM_NAME

Name of the system for the test environment

minikube

PAAS_STAGE_SYSTEM_NAME

Name of the system for the stage environment

minikube

PAAS_PROD_SYSTEM_NAME

Name of the system for the prod environment

minikube

PAAS_TEST_NAMESPACE

Namespace for the test environment

sc-pipelines-test

PAAS_STAGE_NAMESPACE

Namespace for the stage environment

sc-pipelines-stage

PAAS_PROD_NAMESPACE

Namespace for the prod environment

sc-pipelines-prod

KUBERNETES_MINIKUBE

Whether to connect to Minikube

true

REPO_WITH_BINARIES_FOR_UPLOAD

URL of the repository with the deployed jars

http://artifactory:8081/artifactory/libs-release-local

REPO_WITH_BINARIES_CREDENTIAL_ID

Credential ID used for the repository with jars

repo-with-binaries

M2_SETTINGS_REPO_ID

The ID of server from Maven settings.xml

artifactory-local

JDK_VERSION

The name of the JDK installation

jdk8

PIPELINE_VERSION

The version of the pipeline (ultimately, also the version of the jar)

1.0.0.M1-${GROOVY,script ="new Date().format('yyMMdd_HHmmss')"}-VERSION

GIT_EMAIL

The email used by Git to tag the repository

email@example.com

GIT_NAME

The name used by Git to tag the repository

Pivo Tal

AUTO_DEPLOY_TO_STAGE

Whether deployment to stage be automatic

false

AUTO_DEPLOY_TO_PROD

Whether deployment to prod be automatic

false

API_COMPATIBILITY_STEP_REQUIRED

Whether the API compatibility step is required

true

DB_ROLLBACK_STEP_REQUIRED

Whether the DB rollback step is present

true

DEPLOY_TO_STAGE_STEP_REQUIRED

Whether the deploy-to-stage step is present

true

Preparing to Connect to GCE

Important
Skip this step if you do not use GCE

In order to use GCE, we need to have gcloud running. If you already have the CLI installed, skip this step. If not run the following command to have the CLI downloaded and an installer started:

$ ./tools/k8s-helper.sh download-gcloud

Next, configure gcloud. Run gcloud init and log in to your cluster. You are redirected to a login page. Pick the proper Google account and log in.

Pick an existing project or create a new one.

Go to your platform page (click on Container Engine) in GCP and connect to your cluster with the following values:

$ CLUSTER_NAME=...
$ ZONE=us-east1-b
$ PROJECT_NAME=...
$ gcloud container clusters get-credentials ${CLUSTER_NAME} --zone ${ZONE} --project ${PROJECT_NAME}
$ kubectl proxy

The Kubernetes dashboard runs at http://localhost:8001/ui/.

We need a Persistent Disk for our Jenkins installation. Create it as follows:

$ ZONE=us-east1-b
$ gcloud compute disks create --size=200GB --zone=${ZONE} sc-pipelines-jenkins-disk

Once the disk has been created, you need to format it. See the instructions at https://cloud.google.com/compute/docs/disks/add-persistent-disk#formatting

Connecting to a Kubo or GCE Cluster

Important
Skip this step if you do not use Kubo or GCE

This section describes how to deploy Jenkins and Artifactory to a Kubernetes cluster deployed with Kubo.

Tip
To see the dashboard, run kubectl proxy and access localhost:8081/ui.
  1. Log in to the cluster.

  2. Deploy Jenkins and Artifactory to the cluster:

    • ./tools/k8s-helper.sh setup-tools-infra-vsphere for a cluster deployed on VSphere

    • ./tools/k8s-helper.sh setup-tools-infra-gce for a cluster deployed to GCE

  3. Forward the ports so that you can access the Jenkins UI from your local machine, by using the following settings

$ NAMESPACE=default
$ JENKINS_POD=jenkins-1430785859-nfhx4
$ LOCAL_PORT=32044
$ CONTAINER_PORT=8080
$ kubectl port-forward --namespace=${NAMESPACE} ${JENKINS_POD} ${LOCAL_PORT}:${CONTAINER_PORT}
----
  1. Go to Credentials, click System and Global credentials, as the following image shows: image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-pipelines/master/docs/img/jenkins/kubo_credentials.png[caption="Click `Global credentials`"]

  2. Update git, repo-with-binaries and docker-registry credentials

  3. Run the jenkins-pipeline-k8s-seed seed job and fill it out with the following data

  4. Put kubernetes.default:443 here (or KUBERNETES_API:KUBERNETES_PORT)

    • PAAS_TEST_API_URL

    • PAAS_STAGE_API_URL

    • PAAS_PROD_API_URL

  5. Put /var/run/secrets/kubernetes.io/serviceaccount/ca.crt data here:

    • PAAS_TEST_CA_PATH

    • PAAS_STAGE_CA_PATH

    • PAAS_PROD_CA_PATH

  6. Uncheck the Kubernetes Minikube value.

    • Clear the following variables:

      • PAAS_TEST_CLIENT_CERT_PATH

      • PAAS_STAGE_CLIENT_CERT_PATH

      • PAAS_PROD_CLIENT_CERT_PATH

      • PAAS_TEST_CLIENT_KEY_PATH

      • PAAS_STAGE_CLIENT_KEY_PATH

      • PAAS_PROD_CLIENT_KEY_PATH

  7. Set /var/run/secrets/kubernetes.io/serviceaccount/token value to these variables:

    • PAAS_TEST_CLIENT_TOKEN_PATH

    • PAAS_STAGE_CLIENT_TOKEN_PATH

    • PAAS_STAGE_CLIENT_TOKEN_PATH

      • Set the cluster name to these variables (you can get the cluster name by calling kubectl config current-context):

    • PAAS_TEST_CLUSTER_NAME

    • PAAS_STAGE_CLUSTER_NAME

    • PAAS_PROD_CLUSTER_NAME

  8. Set the system name to these variables (you can get the system name by calling kubectl config current-context):

    • PAAS_TEST_SYSTEM_NAME

    • PAAS_STAGE_SYSTEM_NAME

    • PAAS_PROD_SYSTEM_NAME

  9. Update the DOCKER_EMAIL property with your email address.

  10. Update the DOCKER_REGISTRY_ORGANIZATION with your Docker organization name.

  11. If you do not want to upload the images to DockerHub, update DOCKER_REGISTRY_URL. image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-pipelines/master/docs/img/jenkins/pks_seed.png[caption="Example of a filled out seed job"]

  12. Run the pipeline