Extending

How to extend Jenkins X 3.x

Jenkins X has a number of extension points you can use to extend the CI/CD platform to suit your needs:

Charts

Helm charts are the standard way to package applications for kubernetes.

It’s easy to use GitOps to add charts to any of your clusters and customize them however you need.

You can also easily add one or more kubernetes resources to a cluster via a source layout chart

Plugins

The jx command line in version 3 is build on plugins.

It turns out anyone can create a new plugin to wrap up some functionality that is either ran on a developer laptop or is used via a container image inside a pipeline step.

Plugins usually written in Go as it has awesome Kubernetes support and generates easy to use statically compiled binaries - though you are free to create plugins in any programming language.

If you wish to create a new plugin try browse the jenkins-x-plugins organisation for inspiration or check out the standard plugins used in the jx cli

Developing Plugins

The easiest way to work on the plugins is to clone the source of a plugin locally and make local changes and build the code (you will need a go 1.15 installation).

e.g.

git clone https://github.com/jenkins-x/jx-gitops 
cd jx-gitops
make build

Now you can test out the local build of a plugin by calling ./build/jx-gitops instead of using, say jx gitops

Testing local builds with jx

If you add your ./build for your locally built plugin to your $PATH environment variable you can invoke your local ./build/jx-gitops binary as if its a regular jx plugin via:

jx gitops help

Basically jx myplugin will normally download the jx-myplugin binary and invoke that - unless it finds jx-myplugin on the $PATH.

Using a specific version of a plugin

If you want to test a new plugin version before its been tested released in the version stream you can use an environment variable…

export JX_GITOPS_VERSION 1.2.3

# we will now try version 1.2.3 of the gitops plugin:
jx gitops help

Triggers

With version 3.x we default to using Pipeline Catalogs containing Tekton resources to define CI/CD pipelines.

e.g. the default CI/CD pipelines from the default Jenkins X Pipeline Catalog define tekton pipelines in the .lighthouse/jenkins-x folder.

Inside each repository there is now a trigger file called triggers.yaml defined at.lighthouse/jenkins-x/triggers.yaml to define the lighthouse presubmits and postsubmits (i.e. Pull Request pipelines and release pipelines).

You can add any number of folders with the .lighthouse folder to add any number of presubmits and postsubmits (i.e. Pull Request pipelines and releases).

If you define a pipeline you want to share with other repositories you can then use kpt pkg get to copy the folder into other repositories. Later on you can then use kpt pkg update to replicate upstream changes to other repositories. Or use the jx gitops upgrade command which uses kpt pkg update under the covers.

Pipeline Catalog

The pipeline catalog contains default triggers, tekton pipelines and associated files (e.g. Dockerfile and helm charts) for different languages and runtimes.

The pipeline catalog is used to default the triggers, pipelines and other files for new projects when you import or create new quickstarts.

You can browse the default Jenkins X Pipeline Catalog here.

If you want you can fork the jenkins-x/jx3-pipeline-catalog repository and make your modifications to add/remove folders for different languages or modify the pipelines and associated files.

We’d prefer if any improvements or enhancements could be submitted back to the project via a Pull Request then we all get to share your improvements; but its totally fine to have some local modifications for your specific business requirements.

To use your custom fork modify the extensions/pipeline-catalog.yaml file in your cluster git repository to link to your fork instead of the jenkins-x/jx3-pipeline-catalog repository:

...
apiVersion: project.jenkins-x.io/v1alpha1
kind: PipelineCatalog
metadata:
  creationTimestamp: null
spec:
  repositories:
  - gitRef: 0ad0e49dca4d3a1e952c6f7c548e77b2136c5035
    gitUrl: https://github.com/myorg/jx3-pipeline-catalog
    label: My Pipeline Catalog

Updatebot for custom pipeline catalogs

You can use updatebot to keep your custom pipeline catalog up to date. Add this config to your cluster repo in .jx/updatebot.yaml:

apiVersion: updatebot.jenkins-x.io/v1alpha1
kind: UpdateConfig
spec:
  rules:
    - urls:
        - https://github.com/my-org/jx3-pipeline-catalog
      changes:
        - regex:
            pattern: "jenkins-x/jx:(.*)"
            files:
              - "**/*.yaml"
        - regex:
            pattern: "jenkins-x/jx-boot:(.*)"
            files:
              - "**/*.yaml"

To update your pipeline catalog with every cluster upgrade, add these steps to your .lighthouse/jenkins-x/release.yaml before the admin-log step:

- image: perl:slim
  name: next-version
  script: |
    #!/usr/bin/env sh
    perl -ne'/version: (.*)/ && print $1' versionStream/packages/jx.yml > VERSION    
- image: uses:jenkins-x/jx3-pipeline-catalog/tasks/updatebot/release.yaml@versionStream
  name: promote-release

This will open a PR on the pipeline catalog repo if updates are available. If Jenkins X manages the pipeline catalog repo, the PRs will be automatically merged.

QuickStarts

Quickstarts are sample projects which are used jx project quickstart when you create new projects

The default quickstart projects are in the jenkins-x-quickstarts github organisation.

The quickstarts are defined in your extensions/quickstarts.yaml file and defaults to including all of the quickstarts in the versionStream/quickstarts.yml file.

You can include/exclude quickstarts from the version stream using the includes and excludes regular expressions in the extensions/quickstarts.yaml file as shown below.

You can add your own quickstarts into the extensions/quickstarts.yaml file as follows

apiVersion: project.jenkins-x.io/v1alpha1
kind: Quickstarts
spec:
  defaultOwner: myorg

  # custom quickstarts
  quickstarts:
  - name: cheese
    language: JavaScript
    downloadZipURL: https://codeload.github.com/jenkins-x-quickstarts/cheese/zip/master

  # shared quickstarts from the version stream
  imports:
  - file: versionStream/quickstarts.yaml
    includes:
    - ".*"
    excludes:
    - ".*/node.*"

Octant

Our preferred UI for Kubernetes, Tekton and Jenkins X is octant as its easy to install/run and has fined grained RBAC and security without the hassle of setting up TLS, DNS and SSO on every cluster.

One of the awesome features of Octant is it supports plugins so that anyone can build a plugin to extend the UI. We’ve created the octant-jx plugin to extend Octant with the Jenkins X capabilities of environments, pipelines, source repositories and so forth.

If you wish to extend Octant further either contribute to the octant-jx plugin or create your own!

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Last modified July 21, 2021: chore: add docs for updatebot with custom pipeline catalogs (74c574db1a)