Customizing XL UP deployments (BETA)

Once you have deployed the XebiaLabs platform using XL UP, it is likely that you will also want to customize the instances. For instance, you may have custom plugins, a custom synthetic xml, scripts, or external libraries which you will want to import into the platform, while the default Docker images only include the bundled plugins.

Note in the Dockerfile examples below, the --chown flag is mandatory to ensure that you use the correct user and group (10001 is the XebiaLabs user in the base container).

Adding custom plugins

To add custom plugins that you have developed manually or you have saved in a location that can be reached with a URL, you can use the Dockerfile at xl-up-blueprint/customizations/plugins/Dockerfile. Add something like the following:

FROM xebialabs/xl-deploy:9.0.5

# Add plugin from local path. user 10001 is the xebialabs user
COPY --chown=10001:0 files/xld-liquibase-plugin-5.0.1.xldp /opt/xebialabs/xl-deploy-server/default-plugins/

# Add plugin from url. user 10001 is the xebialabs user
ADD --chown=10001:0 https://dist.xebialabs.com/public/community/deploy/command2-plugin/3.9.1-1/command2-plugin-3.9.1-1.jar /opt/xebialabs/xl-deploy-server/default-plugins/

In the example above, the official Deploy Docker image is being extended by adding two plugins - one from the local path, and one from a URL.

In the case of an Release Docker image, you should note that the plugins folder has two subfolders - __local__ and xlr-official; custom plugins should be copied into __local__ and official plugins into xlr-official.

The next step is to build the Docker image: docker build . -t YOUR_TAG

Then push your Docker image to the Docker image registry: docker push YOUR_TAG

Adding extensions

If you want to add files into the XLD_HOME/ext or XLR_HOME/ext folder as part of your extensions or modifications you can use the Dockerfile at xl-up-blueprint/customizations/extensions/Dockerfile. Add something like the following:

FROM xebialabs/xl-release:9.0.2

# Add extensions from local path. user 10001 is the xebialabs user
ADD --chown=10001:0 files/ext /opt/xebialabs/xl-release-server/ext/

In the example above the official Deploy Docker image is being extended by adding two plugins - one from the local path, and one from a URL.

The next step is to build the Docker image: docker build . -t YOUR_TAG

Then push your Docker image to the Docker image registry: docker push YOUR_TAG

Adding hotfixes and external libraries

If you want to add hotfixes for plugins, libraries, or external libraries like JDBC drivers to connect to external databases, in the customizations Dockerfile at xl-up-blueprint/customizations/libs-hotfix/Dockerfile add something like the following:

FROM xebialabs/xl-deploy:9.0.3

# Add jdbc lib from local path. user 10001 is the xebialabs user
ADD --chown=10001:0 files/ojdbc6.jar /opt/xebialabs/xl-deploy-server/lib/

# Add hotfix for lib from local path. user 10001 is the xebialabs user
ADD --chown=10001:0 files/lib-hotfix.jar /opt/xebialabs/xl-deploy-server/hotfix/lib/

# Add hotfix for plugin from local path. user 10001 is the xebialabs user
ADD --chown=10001:0 files/plugin-hotfix.jar /opt/xebialabs/xl-deploy-server/hotfix/plugins/

In the example above we are adding:

  • An Oracle JDBC driver to save the Deploy repository in an Oracle database
  • A hotfix for a library
  • A hotfix for plugins

Hotfixes are provided by XebiaLabs to patch bugs in the system.

Note the --chown flag is mandatory to ensure that you use the correct user and group (10001 is the XebiaLabs user in the base container).

The next step is to build the Docker image: docker build . -t YOUR_TAG

Then push your Docker image to the Docker image registry: docker push YOUR_TAG

Using custom images for deployment

XL Up supports custom Deploy and Release images. It is also possible to use custom images for all components of the XL Up deployment. To do this, you should push a set of images to your personal Docker repository.

  1. When XL Up runs in advanced mode, it has a question about using custom Docker images and registry:

? Do you want to use custom Docker Registry and custom images? [? for help] (y/N)

  1. If you select Yes, you will use the custom registry for all deployment images, although you can still select whether to use custom images for Deploy and Release. For more information see Adding custom images to your registry.
? Enter your Docker registry URL and organization:
? Enter your Docker Registry username:
? Enter your Docker Registry password: [? for help]
? Would you like to install Deploy?
? Do you want to use the provided custom Docker Registry for all docker images used by xl-up? [? for help]
  1. If you select No, XL Up will pull the latest Deploy and Release images from the default registry. If you select Yes, you can add the custom image and tag from your Docker registry.
? Enter your custom Deploy image and tag:
? Would you like to install Release? Yes
? Enter your custom Release image and tag:

Adding custom images to your registry

The Docker registry URL depends on your Docker registry setup. In the case of Docker Hub, you need the domain and organization - for example docker.io/xebialabs. In the case of an internal Docker registry where the organization is not required it will be xl-docker.xebialabs.com. Docker credentials are needed if you need to authenticate to the Docker registry in order to pull an image.

If you want to use the Docker registry to pull all images - including your database and monitoring tools - you must supply all the required images, with the correct version as specified below. It could be possible to change a version tag to fit the requirement, but this is not officially supported.

To push the images to your private registry with the correct tags, use the following commands as an example:

docker pull rabbitmq:3.8.0-management
docker tag rabbitmq:3.8.0-management > yourcompanyregistry.com/rabbitmq:3.8.0-management
docker push yourcompanyregistry.com/rabbitmq:3.8.0-management

The images you need will depend on your environment requirements. For example:

  • If you are not using AWS you do not need EFS but you do need NFS.
  • If you do not want to deploy monitoring then Prometheus and Grafana are not needed.
  • If you are using an external database Postgres is not needed.

You should determine your own requirements and allocate your images accordingly. If XL Up cannot find the expected image it will fail the deployment.

Here is the list of Docker Hub images you will need to pull for a complete deployment:

XL-Up (Always required if you say yes to "Do you want to use the provided custom Docker Registry for all docker images used by xl-up?"):
	xebialabs/xl-seed:9.6.0 (this should always match the release version)
Rabbit:
	rabbitmq:3.8.0-management
Postgres:
	xebialabs/tiny-tools
	postgres:10.5
NFS:
	quay.io/external_storage/nfs-client-provisioner:latest
	ha-proxy-ingress-controller:kub
	gcr.io/google_containers/defaultbackend:1.4
	quay.io/jcmoraisjr/haproxy-ingress:v0.6
EFS:
	quay.io/external_storage/efs-provisioner:v1.0.0-k8s1.10
Grafana:
	xebialabs/tiny-tools
	grafana/grafana:5.4.4
KUBE STATE:
	quay.io/coreos/kube-state-metrics:v1.5.0
	k8s.gcr.io/addon-resizer:1.8.3
Prometheus
	xebialabs/tiny-tools
	prom/prometheus:v2.7.2
Elasticsearch
	xebialabs/tiny-tools
	docker.elastic.co/elasticsearch/elasticsearch-oss:6.5.0       
	xebialabs/xl-es-curator
	k8s.gcr.io/fluentd-elasticsearch:v2.3.2
	xebialabs/kibana-dashboard:1.0.0
	docker.elastic.co/kibana/kibana-oss:6.5.0
Deploy
	xebialabs/tiny-tools
Release
	xebialabs/tiny-tools
  • If you are using AWS you will not need EFS
  • If you are not using AWS you need EFS but not NFS
  • If you do not want to deploy monitoring then Prometheus and Grafana are not needed
  • If you are using an external database then Postgres is not needed.

Note The custom Docker image that you want to use should use a version tag that follows the semver standard. An image with a random tag like xl-deploy:test123 will not work.

Specify a Kubernetes namespace

If you wish to use a specific Kubernetes namespace, you can specify this during the advanced setup: ? Do you want to use an existing Kubernetes namespace? The namespace you provide should already exist in the target K8s environment.

Hybrid clusters with Windows nodes

XL UP supports deploying to Kubernetes hybrid clusters that include Windows nodes in the following environments:

  • Amazon EKS
  • Google GKE
  • Azure AKS

In the advanced setup, the following question allows you to specify that tags should be added by XL UP to the generated YAMl files to confirm to the Kubernetes scheduler that the services deployed should be put on the Linux nodes: ? Is this a hybrid cluster?

Custom storage classes

When XL UP deploys to Kubernetes it creates the storage classes it needs for its deployments. However, you may have existing storage classes in your cluster that you would like XL UP to use instead. For instance, you may have security, roles, or policies already set up specific to the EFS mounts, that are not provided by the XL UP installation.

The following question allows you to define your own storage classes: ? Do you want to use existing storage classes from your kubernetes cluster? [? for help] (y/N)

XL UP supports two different kinds of storage classes:

  1. General storage used by the deployments. This is defined by the question: Please enter the name of the storage class that can be used for non-shared storage
  2. A shared storage class which is used by Deploy and Release to share information. This is defined by the question: Please enter the name of the storage class to be used for storage shared between pods