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.
If your machine runs macOS or Windows:
- Install the latest version of Docker Desktop: macOS / Windows
- Allocate 6 GB of memory and 4 CPU cores for Docker in the advanced settings: macOS / Windows
- Enable its built-in Kubernetes engine: macOS / Windows
- Ensure that your Docker context is set to docker for desktop.
- Ensure that your
xebialabsnamespace does not exist before you run the workshop. See undeploying instances.
Download the latest XL CLI:
curl -o xl https://dist.xebialabs.com/public/xl-cli/9.5.1/darwin-amd64/xl chmod +x xl
curl -o xl xl https://dist.xebialabs.com/public/xl-cli/9.5.1/linux-amd64/xl chmod +x xl
- 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.
- Download the sample keystore
dummy-keystore.jceksfrom 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
- 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
- Check the available flags for
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")
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 upand choosing it in the prompts.
Run through the prompts and provide answers for them. You can type
?on ever prompt to get a detailed description.
- Select the earliest version of both Deploy and Release.
- When asked to provide the keystore refer to the file
keystore.jceksin this repository. The password is
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.
- After the
xl upcommand 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.
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
In Kubernetes, you will have created the following assets from this scenario:
- 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.
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!
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
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
The advanced setup allows you to choose to use an external database or a custom Docker image for Deploy or Release:
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
xl up --advanced-setup
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)
- The following prompt asks you to
Enter your Docker registry URL and organization. Enter
- Leave the username and password empty and hit Enter. This is a public Docker repo that does not need authentication.
- Choose to install Deploy, and in the
Enter your custom Deploy image and tagprompt, enter
- Do not install Release. For the remaining questions use your standard answers.