isabella232 / simple-vsi-toolchain

Develop a Simple Java Application and Deploy on Virtual Server (Virtual Machine)

• Prerequisites
• Advanced User Scenarios
• Application Repository Configuration
• Inventory Repository Configuration
• Delivery Pipeline Configurations
• Additional Information
  • RollBack to an older version of deployed application
  • GitOps Flow
  • Customise the build and deploy script
    • Modify the Continous Integration Pipeline task
    • Modify the Continuous Deployment Pipeline task
• Learn more

Continuously Deliver a Java Application to the Virtual Server Instance.

By following this tutorial, you can create an IBM Cloud Continuous Delivery Toolchain and then use the toolchain and DevOps practices to develop a simple Java web application that you deploy to the IBM Cloud® Virtual Server Instance.

This Simple Java application exposes an HTTP Endpoint at port 8080 of the host machine to present a Hello World Greeting message at the http://{VSI-IP-ADDRESS}:8080/v1/ HTTP Path. The application utilizes a maven build system to provide build and test capability. The application comes preconfigured for a DevOps toolchain that provides continuous delivery with source control, issue tracking, online editing, and deployment to the IBM Virtual Server Instance.

The application code is stored in the application source control repository whereas the build and deploy scripts are stored in the pipeline source control repository. The build and deploy scripts can be customized to suit the development needs of the application.

The toolchain implements the following best practices:

• Builds application binary on every Git commit, sets a tag based on build number, timestamp, and commit id for traceability

• Creates IBM Cloud Storage Instance and Bucket to store the transient build binaries out-of-box. For advanced users, the IBM Cloud Storage Instances and Buckets to store binaries can be customized to utilize existing resources.

• For advanced users with versioning requirements for the build artifacts, the toolchain also supports Artifactory as artifact store. An existing artifactory repository can be configured and integrated with the toolchain to support the versioning of the build artifacts.

• GitOps Flow to deploy changes to the Deployment Environment.

---

Prerequisites:

• Virtual Server Instance

This toolchain requires a Virtual Server Instance running a variant of Linux/Unix in IBM Cloud. If you don't have one, then you need to Create a Virtual Server Instance in IBM Cloud which serves as the target host where the Java Application should be deployed.

• The Virtual Server Instance needs to have a Floating IP that is accessible over the public internet. Reserve Floating IP Address to connect to Virtual Server Instance over internet.

• Please ensure that the Security Group assigned to the Virtual Server Instance has Inbound rule that allows access to the ssh port (default port 22). Update Security Group of the default VPC or the VPC to which the Virtual Server Instance belongs.

• The toolchain needs the login credentials, preferably of a non-privileged user, to connect to the Virtual Server Instance to deploy and run the built application binaries. The toolchain supports credential in the form of Username/Password or Username/SSH-Keys combination. Use SSh Keys to login as privileged user to your VSI and create additional non-privileged user for the toolchain to carry out the deployment operations.

• The toolchain performs health check over the deployed application. The sample Java Application create a web server that listens to incoming requests as port 8080. Therefore, it is required to Update Security Group in order to add an inbound rule for TCP allow port 8080 to access the application.

Note:

If you are providing Username and Password, enable PasswordAuthentication in the Virtual Server Instance.

Advanced User Scenarios:

The Continuous Integration (CI) Pipeline listens to changes in the application source code and triggers a CI Pipeline Run whenever a change is pushed to the application repository. The result of a successful CI Run is an artifact which is pushed to an intermediate storage). The Continuous Deployment (CD) Pipeline copies this artifact to the target Virtual Server Instance and performs the deployment of the application. The toolchain provides a user with options to use either IBM Cloud Object Store (COS) or Artifactory as an intermediate storage location for binary builds.

- If the Artifactory integration is configured correctly with the required fields filled in then that integration is used when determining what store to use for built artifacts.

- If the COS bucket field name is configured then the corresponding bucket is used.

- If neither the Artifactory or COS integration are configured, then toolchain creates a COS instance in the user’s default resource group. After a COS instance is successfully created, the pipeline creates a bucket within the newly created COS instance and uses this bucket for storing artifacts.

• Cloud Object Store (Default) - The toolchain utilizes IBM Cloud Object Storage (COS) to store transient application artifacts. If a user does not have an instance of IBM COS, the toolchain will go ahead and create an instance for them. The toolchain uses this newly created instance of IBM COS to create a bucket which will store the application artifacts. Alternatively, a user can also configure the toolchain to utilise an existing IBM COS Bucket or Create a Bucket. Please note: Based on existing COS Instances and Buckets in your account, toolchain exhibits behaviour as described in below scenarios:

  • If the user does not have any COS instance, a COS instance with same name as toolchain name will be created and it would be used to create the bucket.
  • If the user has only one COS Instance, the same instance will be used for the creating the bucket.
  • If the user has two or more COS Instances, a COS instance with the same name as that of the toolchain will be created and it will be used for creating the bucket.

• Artifactory (Optional) - The toolchain also provides the capability to utilize an existing instance of JFrog Artifactory as intermittent storage location for application artifacts (e.g. jar, exe).

---

To get started, click this button:

---

Steps

1. On the Create Page, please provide inputs for mentioned fields

• Toolchain Name - Unique name to identify your toolchain

• Region - Select the region where toolchain is to be deployed (Ex: us-south)

Application Repository Configuration

Inventory Repository Configuration

1. Inventory repo is used to capture the build and artifact metadata.

2. A successful CI build uploads the artifact to COS/Artifactory and commits the build metadata in JSON Format to the Inventory Repository. The CD Pipeline listens for changes in the inventory and triggers a pipeline run to fetch the artifact from COS/Artifactory and deploys that artifact to the Virtual Server Instance.

Delivery Pipeline Configurations

1. On Create Page, please navigate to "Delivery Pipeline" Tab and fill in details:

2. IBM Cloud API Key - Use an existing key or create a new key. This key is used by the toolchain to interact with other integrated cloud services.

3. Virtual Server Instance Region - Region where Virtual Server Instance is running. (Ex. us-south)

4. Virtual Server Instance - Floating IP Address / DNS Name of the Virtual Server Instance

5. Authentication Type - User Credentials / SSH Key.

   • User Credentials:

     • User Name - Username of the Virtual Server Instance user with permission to deploy and run the application.
     • Password - Password of the Virtual Server Instance user with permission to deploy and run the application.

   • SSH Credentials:

     • User Name - Username of the Virtual Server Instance user with permission to deploy and run the application.
     • SSH KEY - Private SSH Key of the Virtual Server Instance user to deploy and run the application.

More Tool configurations:

1. Cloud Object Storage (Advanced User Scenarios) - For users with an existing Cloud Object Store Instance, navigate to the "More Tools" Tab and add details about your Cloud Object Store Instance.

• Bucket Name in your Cloud Object Storage Instance - Provide the name of the bucket to store the intermediate build artifacts. If you are provide the bucket name, ensure that you create the bucket in the same region where the toolchain is created. This is to ensure that pipeline can access the bucket.

2. Artifactory (Advanced User Scenarios) - For users with an existing Artifactory setup, navigate to the "More Tools" Tab and provide details about your Artifactory Instance:

Input Parameter	Description
Artifactory Server URL	HTTP URL of the Artifactory Server
Type	Choose from (npm/maven/docker)
Artifactory UserID	UserID to login to the Artifactory Server
Artifactory APIKey	Generated by the User (Existing/New)
APIKey	Release URL for the artifactory repo where artifacts are to be stored

Note: Some fields in the artifactory are mandatory only when you do the artifactory configuration.

Additional Information

RollBack to an older version of deployed application

If you want to revert your current deployed version of application and install last working version utilise the GitOps Workflow model as described in steps below

1. Clone the Inventory Repository.

git clone <inventory-repo-url>

2. List commits pushed by CI pipeline after each successful CI Pipeline Run.

git log 

3. Checkout master branch of Inventory Repository.

git checkout master

4. Fetch the ID of the last commit made to the Inventory Repository.

lastCommitID=$(git log --format="%H" -n 1)

5. Revert the last commit. Please provide a commit message for this revert.

git revert $lastCommitID

6. Push the change to inventory repo. Note: The action triggers the CD Pipeline Run for application deployment.

git push origin master --force

GitOps Flow

This Toolchain follows the GitOps Workflow model. The model stores build metadata from each successful build in a separate repository (Inventory Repository). The default configuration of Continuous Deployment Pipeline triggers a pipeline run whenever a successful build metadata is pushed to the master branch.

As a best practice, user's can create a branch in the Inventory repository for each deployment environment. The latest commit to the branch contains metadata of the artifact version deployed in the corresponding environment. The steps below guide a user on how to follow this workflow

1. Create the toolchain instance by following the steps mentioned above.

2. Once the toolchain is configured successfully, click on the Inventory Repository.

3. Create a branch for each of deployment environment ( For example: Production)

4. Navigate to CD Pipeline > Triggers. Modify the trigger with Source as Inventory Repository with the branch which you want to trigger the CD-Pipeline(Master).

5. Perform multiple changes/commits to your Application Source Code. Note that these changes will not be deployed to your environment automatically.

6. Raise Pull/Merge Request to merge changes from master branch to target (prod) environment branch.

7. Submit Pull/Merge Request to merge changes. As can be seen here master branch is 4 commits ahead of prod branch. The current merge request will merge changes from master to prod branch in effect deploying the artifact which contains changes pertaining to those 4 commits.

8. Click on the Merge Icon. This action will trigger the CD pipeline run which is listening for changes on prod branch of the Inventory Repository.

9. Verify the CD Pipeline Run.

Customise the build and deploy script

This toolchain leverages Tekton to perform the pipeline tasks for the build and deploy pipelines. Users can configure the build and deploy steps by making changes to the pipeline code which is maintained in the pipeline repository.

Modify the Continous Integration Pipeline task

The CI Pipeline is responsible for compiling the application source code, running unit test and other tools. Users can modify the existing tasks for the changing needs of their application. The source code for CI Pipeline is present in simple-vsi-app-toolchain-* > .build_pipeline folder.

Task Name	Description	Location
build-source	Task to compile the Application Source Code	pipeline.yaml
unit-tests	Task to run the unit tests and copy the report type and location as result of the task	pipeline.yaml
code-coverage	Task to run the code coverage and copy the report type and location as result of the task	pipeline.yaml
package-build-artifacts	Task to package the artifact as (.jar/.zip/.tar.gz)	pipeline.yaml
build-artifacts-info	Task to build the artifact metadata information	task.yaml

Modify the Continous Deployment Pipeline task

The CD Pipeline is responsible for copying the application artifact ( .jar/.zip/.tar.gz) format to the deployment environment. Users can modify the existing tasks for deploying, restarting the applications based on the system/application environments. The source code for CD Pipeline is present in simple-vsi-app-toolchain-* > .deploy_pipeline folder.

Task Name	Description	Location
deploy-script	Task to create script to run on target environment to perform deployment	task.yaml
backup-script	Task to create script to run on target environment to backup last deployment	task.yaml
deploy	Task to connect to remote target environment and run the deployment script	task.yaml
acceptance-test	Task to run the acceptance tests on the deployed application	task.yaml
roll-back-deployment	Task to rollback deployment to last state in case of failures	task.yaml

Learn more

• Getting started with toolchains

• Documentation