XL UP tutorial (BETA)

This workshop will teach you how to use the xl up command in order to install XL DevOps platform to a local Kubernetes cluster in Docker or AWS EKS. For more information see Introduction to XL UP.

Prerequisites

  1. If your machine runs macOS or Windows:

    1. Install the latest version of Docker Desktop: macOS / Windows
    2. Allocate 6 GB of memory and 4 CPU cores for Docker in the advanced settings: macOS / Windows
    3. Enable its built-in Kubernetes engine: macOS / Windows
    4. Ensure that your Docker context is set to docker for desktop. Docker for desktop
    5. Ensure that your xebialabs namespace does not exist before you run the workshop. See undeploying instances.
  2. Download the latest XL CLI:

    • macOS:

      curl -o xl https://dist.xebialabs.com/public/xl-cli/9.5.1/darwin-amd64/xl
      chmod +x xl
    • Linux:

      curl -o xl xl https://dist.xebialabs.com/public/xl-cli/9.5.1/linux-amd64/xl
      chmod +x xl
    • Windows:

      1. Download https://dist.xebialabs.com/public/xl-cli/9.5.0/windows-amd64/xl.exe and place it somewhere in your %PATH%
    • Make sure the CLI is executable and located in your normal path (in MacOS, usr/local/bin). Otherwise you can place it in a folder and call its path in your commands.
  3. Download the sample keystore dummy-keystore.jceks from here. The password is test123. Alternatively, you can generate your own. For example: keytool -genseckey -alias deployit-passsword-key -keyalg aes -keysize 128 -keypass deployit -keystore /tmp/repository-keystore.jceks -storetype jceks -storepass test123
  4. For more information about the requirements, see Local Kubernetes from Docker Desktop for Mac/Windows.

Optionally, you can watch these videos to get a quick overview of a simple and complex setup:

Quick local setup

Advanced deployment

XL UP

Run XL UP for Docker Kubernetes with simple setup

  1. Check the available flags for xl up: xl up --help
Pulls and runs XL-Seed to deploy XLR and XLD

Usage:
  xl up [flags]

Flags:
      --advanced-setup      Advanced setup
  -a, --answers string      The file containing answers for the questions
  -b, --blueprint string    The folder path containing the xl-infra blueprint, relative to the active repository
      --dry-run             Create files only, nothing will be deployed
  -g, --git-branch string   Use a branch from the official GIT repository instead of the default HTTP repository
  -h, --help                help for up
  -l, --local-repo string   Provide local folder path where blueprints are located, by default a remote repository is used
      --no-cleanup          Leave generated files on the filesystem
      --quick-setup         Quickly run setup with all default values
      --undeploy            Undeploy the deployed resources

Global Flags:
      --blueprint-current-repository string   Current active blueprint repository name
      --config string                         config file (default: $HOME/.xebialabs/config.yaml)
  -q, --quiet                                 suppress all output, except for errors
  -v, --verbose                               verbose output
      --xl-deploy-authmethod string           Authentication method to access the Deploy server (default "http")
      --xl-deploy-password string             Password to access the Deploy server (default "admin")
      --xl-deploy-url string                  URL to access the Deploy server (default "http://localhost:4516/")
      --xl-deploy-username string             Username to access the Deploy server (default "admin")
      --xl-release-authmethod string          Authentication method to access the Release server (default "http")
      --xl-release-password string            Password to access the Release server (default "admin")
      --xl-release-url string                 URL to access the Release server (default "http://localhost:5516/")
      --xl-release-username string            Username to access the Release server (default "admin")
  1. Select the quick setup xl up --quick-setup

    Quick setup hides a lot of the advanced prompts. All prompts that have default values will be skipped. You can also select “quick setup” by running xl up and choosing it in the prompts.

  2. Run through the prompts and provide answers for them. You can type ? on ever prompt to get a detailed description.

    1. Select the earliest version of both Deploy and Release.
    2. When asked to provide the keystore refer to the file keystore.jceks in this repository. The password is test123.
  3. When all prompts were answered and before the deployment starts you will see a table with all the values that were used, including the default or random values that were provided for you:

    Using default values:
     -------------------------------- ----------------------------------------------------
    | LABEL                          | VALUE                                              |
     -------------------------------- ----------------------------------------------------
    | ExternalDatabase               | false                                              |
    | InstallXLD                     | true                                               |
    | InstallXLR                     | true                                               |
    | K8sClientCert                  | *****                                              |
    | K8sClientKey                   | *****                                              |
    | K8sLocalApiServerURL           | https://host.docker.internal:6443                  |
    | K8sSetup                       | LocalK8S                                           |
    | Namespace                      | xebialabs                                          |
    | OsType                         | darwin                                             |
    | PostgresEffectCacheSize        | 1GB                                                |
    | PostgresMaxConn                | 512                                                |
    | PostgresMaxWallSize            | 256MB                                              |
    | PostgresSharedBuff             | 512MB                                              |
    | PostgresSyncCommit             | off                                                |
    | RabbitMQDriver                 | com.rabbitmq.jms.admin.RMQConnectionFactory        |
    | RabbitMQExternal               | false                                              |
    | UseCustomRegistry              | false                                              |
    | UseKubeconfig                  | true                                               |
    | XlKeyStore                     | *****                                              |
    | XlKeyStorePass                 | *****                                              |
    | XldAdminPass                   | hjMEfLPmQFl0QZLE                                   |
    | XldDbName                      | xl-deploy                                          |
    | XldDbPass                      | ezelgm5pyCUQvZpv                                   |
    | XldDbUser                      | sa                                                 |
    | XldDeploymentTimeout           | 120                                                |
    | XldLic                         | *****                                              |
    | XldOfficialVersion             | 9.0.2                                              |
    | XlrAdminPass                   | i8lviaSLbu0X6BHy                                   |
    | XlrDbName                      | xl-release                                         |
    | XlrDbPass                      | ODqsjc1PIN04p6pD                                   |
    | XlrDbUser                      | xl-release                                         |
    | XlrDeploymentTimeout           | 120                                                |
    | XlrLic                         | *****                                              |
    | XlrOfficialVersion             | 9.0.2                                              |
    | XlrReportDbName                | xl-release-report                                  |
    | XlrReportDbPass                | g7TOZ83w6kfHNlia                                   |
    | XlrReportDbUser                | xl-release-report                                  |
     -------------------------------- ----------------------------------------------------
    • Alternatively, you can provide an answer file by running

      xl xl --config=./config up --dev -b xl-up --no-cleanup -a answer-file-example

      Make sure that you fill the correct information in the answers file.

  4. After the xl up command has run successfully you should see this output:
Generated files for deployment successfully!
Spinning up xl seed!
Deploying  K8s-NameSpace 1.0.0

Deployed  K8s-NameSpace 1.0.0

Deploying  K8s-Ingress-Controller v0.6, PostgreSQL 10.5, Answers-Configmap-Deployment 8.6.1

Deployed  K8s-Ingress-Controller v0.6, PostgreSQL 10.5, Answers-Configmap-Deployment 8.6.1

Deploying  XL-Deploy-Deployment 8.6.1

Deployed  XL-Deploy-Deployment 8.6.1

Deploying  XL-Release-Deployment 8.6.1

Deployed  XL-Release-Deployment 8.6.1

***********************************************************************
XL-DEPLOY URL - https://127.0.0.1:30443/deploy/
XL-RELEASE URL - https://127.0.0.1:30443/xl-release/
***********************************************************************

You can run kubectl get pods -n xebialabs && kubectl get svc -n xebialabs if you want to see which resources (pods and services) were deployed to Kubernetes.

Locally, a generated_answers.yaml file will also be generated which has saved all answers and default values, and which can be used if you do not want to answer the prompts interactively on a new run of xl up.

What will be installed

In Kubernetes, you will have created the following assets from this scenario:

  • A xebialabs Namespace
  • An Ingress controller (needed for doing active health checks on Deploy and Release instances)
  • Volume provisioners
  • Storage classes
  • A PostgreSQL instance (if external database is not used)
  • A Configmap with the answers provided by the user
  • Deploy and Release instance (one node)

In addition, service accounts, roles, cluster roles and role bindings are created.

If you selected the option to run xl up on an AWS EKS, GKE, or multinode K8s cluster, then Deploy will be installed on a high availability setup with master and worker nodes; Release will also be installed in high availability, along with solutions for log aggregation and metrics. See Monitoring deployments for more information.

Undeploy resources created by xl up

To undeploy the resources that were created by xl in Kubernetes, run xl up --undeploy

Answer the prompts about how to connect to your Kubernetes cluster. You will also be asked if you are sure you want to undeploy the resources.

The output will be

➜ xl up --undeploy
? Select the Kubernetes setup where the DevOps Platform will be installed: LocalK8S [Local K8s from Docker Desktop for Mac/Windows]
? Do you want to use Kubernetes' current-context from ~/.kube/config? Yes
? DevOps Platform is already deployed on this cluster. Are you sure you want to undeploy everything? This cannot be undone Yes
Deleting namespace...
	Resource "Namespace" still deleting
	Resource "Namespace" still deleting
	Resource "Namespace" still deleting
	Resource "Namespace" still deleting
	Resource "Namespace" still deleting
	Resource "Namespace" deleted
Namespace deleted
Deleting storage classes...
	Resource "StorageClasses" deleted
Storage classes deleted
Deleting cluster role bindings...
	Resource "ClusterRoleBindings" deleted
Cluster role bindings deleted
Deleting cluster roles...
	Resource "ClusterRoles" deleted
Cluster roles deleted
Everything has been undeployed!

Run xl up on Docker with an answers file

In the first example we ran xl up interactively and produced a generated_answers.yaml file that includes all answers and default values. This answer file can be used when running xl up to install the DevOps Platform or to undeploy it. This answer file can be used when running xl up to install or undeploy the DevOps Platform.

xl up -a generated_answers.yaml

Or for undeploying

xl up --undeploy -a generated_answers.yaml

Run xl up on Docker interactively with the advanced setup

Using the advanced setup gives the user the option to answer all available prompts: xl up --advanced-setup

Note that you can also select the advanced setup from the prompts after running xl up.

The advanced setup allows you to choose to use an external database or a custom Docker image for Deploy or Release:

Run a custom Deploy container

XL up supports custom containers with extensions, hotfixes, custom plugins, and custom libraries (such as JDBC libraries).

For more information, see Adding custom plugins. In this example a Docker image can be created which adds two extra plugins:

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/

This image can be built and pushed to a Docker registry such as Docker Hub. For convenience we have pushed this image to a xebialabsunsupported Docker registry in Docker Hub, with the image name and tag xld-up-workshop:9.0.5.

Use the custom image to install Deploy

  1. Run xl up --advanced-setup
  2. Select ‘Yes’ when you are asked to use a custom Docker registry:

    Do you want to use custom Docker Registry and custom images? [? for help] (y/N)
  3. The following prompt asks you to Enter your Docker registry URL and organization. Enter docker.io/xebialabsunsupported.
  4. Leave the username and password empty and hit Enter. This is a public Docker repo that does not need authentication.
  5. Choose to install Deploy, and in the Enter your custom Deploy image and tag prompt, enter xld-up-workshop:9.0.5.
  6. Do not install Release. For the remaining questions use your standard answers.