Track progress using XL CLI output

You can follow deployment and release pipeline activities defined in your YAML files as they are executed by Deploy or Release using the output provided in the XL Command Line Interface (CLI).

Prerequisite: Utilize the DevOps as Code workshop environment

We recommend that you run the DevOps as Code workshop to spin up the environment on which the examples described in this topic are based. The workshop describes how to install the XL CLI executable on your local host and set up a local Docker instance.

Example: Follow a deployment using the XL CLI

You can track provisioning and deployment progress in the XL CLI as tasks are executed by Deploy. To get a more granular view of your progress when you use the xl apply command, add the -v or --verbose flag.

Deploy XL CLI behavior

When you run the xl apply command on one or more YAML files, you can now see all the execution steps, like in the GUI interface. These steps show whether the deployment is successful or failed.

The XL CLI deployment is locked until one of the following occurs:

• Successful completion of all deployment tasks.
  • The XL CLI output indicates DONE when complete.
• Occurrence of a task failure.
  • The XL CLI output indicates FAILED, and you can view the error logs and re-run the deployment from the XL CLI.

Important: If there are any missing placeholders, incorrect placeholders, or wrong environment configurations, the XL CLI provides detailed error messages similar to those in the GUI.

The following provides a detailed description of the error, indicating the missing placeholder and where it occurred in the YAML file.

Detach option

In some cases you may not want to track progress of deployment or release progress in the CLI output. You can use the detach option (-d flag) with the xl apply command to apply the YAML specification but not follow deployment execution or release steps as they are completed in the terminal output.

YAML file

In the following example, you apply a single YAML file called deploy-rest-o-rant.yaml. When applied, this YAML file:

1. Creates an environment called Local Docker Engine.
2. Creates versions 1.0 and 1.1 of the Rest-o-rant sample application.

deploy-rest-o-rant.yaml

apiVersion: xl-deploy/v1
kind: Environments
spec:
- name: Local Docker Engine
  type: udm.Environment
  members:
  - Infrastructure/local-docker
---  

apiVersion: xl-deploy/v1
kind: Applications
spec:
- name: rest-o-rant-api-docker
  type: udm.Application
  children:
  - name: '1.1'
    type: udm.DeploymentPackage
    deployables:
    - name: rest-o-rant-network
      type: docker.NetworkSpec
      networkName: rest-o-rant
      driver: bridge
    - name: rest-o-rant-api
      type: docker.ContainerSpec
      image: xebialabsunsupported/rest-o-rant-api
      networks:
      - rest-o-rant
      showLogsAfter: 5
---
apiVersion: xl-deploy/v1
kind: Applications
spec:
- name: rest-o-rant-web-docker
  type: udm.Application
  children:
  - name: '1.0'
    type: udm.DeploymentPackage
    orchestrator:
    - sequential-by-dependency
    deployables:
    - name: rest-o-rant-web
      type: docker.ContainerSpec
      image: xebialabsunsupported/rest-o-rant-web
      networks:
      - rest-o-rant
      showLogsAfter: 5
      portBindings:
      - name: ports
        type: docker.PortSpec
        hostPort: 8181
        containerPort: 80
        protocol: tcp

Create the deployment

Here is the enhanced output displayed when you add the -v (verbose) option to the apply command:

Using configuration file: C:\Users\joe.user/.xebialabs/config.yaml
[1/1] Applying C:\devops\yaml\test\deploy-rest-o-rant.yaml
    Values:
        EMPTY

    Applying document at line 1
        Updated CI Environments/Local Docker Engine

    Applying document at line 9
        Created CI Applications/rest-o-rant-api-docker/1.1/rest-o-rant-network
        Created CI Applications/rest-o-rant-api-docker/1.1/rest-o-rant-api
        Created CI Applications/rest-o-rant-api-docker/1.1
        Created CI Applications/rest-o-rant-api-docker

    Applying document at line 30
        Created CI Applications/rest-o-rant-web-docker/1.0/rest-o-rant-web/ports
        Created CI Applications/rest-o-rant-web-docker/1.0/rest-o-rant-web
        Created CI Applications/rest-o-rant-web-docker/1.0
        Created CI Applications/rest-o-rant-web-docker

Undeploy an Application

To undeploy an application using XL CLI, perform the following steps:

1. Create an undeployment YAML file. Ensure that it includes the correct apiVersion, kind, and spec fields. For example,

apiVersion: xl-deploy/v1
kind: Deployment
spec:
 package: Applications/XL/cmd/AppWithCommands/1.0
 environment: Environments/XL/Production
 type: UnDeployment

2. Run the following command, replacing your yaml file name:

xl-apply xl-deploy -f.\undeployment.yaml

After executing the command, verify that the specified application has been successfully undeployed. You can check the deployment tasks for confirmation.

note

If the undeployment is not successful, the XL CLI displays an error message Error: Undeployment failed for application <AppPackageVersionID>. Reason: <error code and/or message>. Verify the YAML specification and repeat the steps.

Remediate issues or failures

You can investigate and resolve the cause of a task failure in your YAML specifications or in the Deploy GUI. You can then re-run the operation from the XL CLI. Tasks already successfully performed (for example, creating an infrastructure or environment) will be updated.

note

You can choose to use the detach option and not track progress in the CLI.

Example: Follow a release using the XL CLI

To extend the deployment example, create a release pipeline using the XL CLI that will deploy, test, and undeploy the Rest-o-rant sample application.

XL CLI behavior

When you run the apply command, the XL CLI will be locked until one of the following occurs:

• All release tasks are successfully completed.
  • The XL CLI output will indicate DONE when complete
  • The release is archived in Release (marked as DONE and listed under Reports in the GUI).
• A task fails or cannot be completed without manual intervention. In this case, the point of failure is indicated in the XL CLI output and the progress of the release pipeline is stopped.

YAML files

This example builds on the environment and application that were created in Deploy. You will first apply YAML file called template-rest-o-rant.yaml to create a release pipeline and then start a release using this template by applying a YAML file called release-rest-o-rant.yaml:

1. The template-rest-o-rant.yaml creates an Release directory called REST-o-rant and a template called Rest-o-rant on Docker.
2. The template consists of three phases: Deploy, Test, and Clean up.
   1. The Deploy phase consists of two tasks that deploy a backend and frontend application to a local Docker environment.
   2. The Test phase consists of a manual task to test that the deployment is successful and the application is accessible on the local Docker environment.
   3. The Clean up phase undeploys the application frontend and backend.
3. The release-rest-o-rant.yaml starts a release using the Rest-o-rant on Docker template.

template-rest-o-rant.yaml

apiVersion: xl-release/v1
kind: Templates
spec:
- directory: REST-o-rant
  children:
  - template: REST-o-rant on Docker
    description: |
      This Release template shows how to deploy and undeploy an application to Docker using Deploy.
    tags:
    - REST-o-rant
    - Docker
    phases:
    - phase: Deploy
      tasks:
      - name: Deploy REST-o-rant application backend
        type: xldeploy.Deploy
        server: Deploy
        deploymentPackage:  rest-o-rant-api-docker/1.1
        deploymentEnvironment: Environments/Local Docker Engine
      - name: Deploy REST-o-rant application frontend
        type: xldeploy.Deploy
        server: Deploy
        deploymentPackage:  rest-o-rant-web-docker/1.0
        deploymentEnvironment: Environments/Local Docker Engine
    - phase: Test
      tasks:
      - name: Test the REST-o-rant application
        type: xlrelease.Task
        team: Release Admin
        description: |
          The REST-o-rant app is now live on your local Docker Engine. Open the following link in a new browser tab or window:

          http://localhost:8181/

          You should see a text saying "Find the best restaurants near you!". Type "Cow" in the search bar and click "Search" to find the "Old Red Cow" restaurant.

          When everything looks OK, complete this task to continue the release and undeploy the application.
    - phase: Clean up
      tasks:
      - name: Undeploy REST-o-rant application frontend
        type: xldeploy.Undeploy
        server: Deploy
        deployedApplication: Environments/Local Docker Engine/rest-o-rant-web-docker
      - name: Undeploy REST-o-rant application backend
        type: xldeploy.Undeploy
        server: Deploy
        deployedApplication: Environments/Local Docker Engine/rest-o-rant-api-docker

release-rest-o-rant.yaml

apiVersion: xl-release/v1
kind: Release
spec:
  name: Release Test
  template: REST-o-rant/REST-o-rant on Docker
  variables:
    pipeline: '1.0'

Create the release template

Here is the enhanced output displayed when you add the -v (verbose) option to the apply command:

xl apply -v -f template-rest-o-rant.yaml
Using configuration file: C:\Users\joe.user/.xebialabs/config.yaml
[1/1] Applying C:\devops\yaml\test\template-rest-o-rant.yaml
    Values:
        EMPTY

    Applying document at line 1
        Updated CI Applications/Folderc6e269c523d04882a61606c0d788793a/Release30e947a83677475bbad37d9431c29b22

Check results in the Release GUI

1. Go to Release and navigate to Folders. A new folder called REST-o-rant has been created.
2. Click the REST-o-rant on Docker template.

Run the release pipeline

You can now use the release-rest-o-rant.yaml file to start a new release using the REST-o-rant on Docker template. Use the following command:

xl apply -v -f release-rest-o-rant.yaml

Observations

The two tasks in the Deploy phase completed successfully, as they are automated and do not require any manual intervention. Since the task in the Test phase is a manual task, the progress of the release is stopped.

Remediate manual tasks or failures

Unlike running a deployment pipeline in Deploy in which most or all of the tasks performed are automated, Release can consist of phases and tasks with a mix of automated and manual tasks that occur over a longer period of time.

The XL CLI will track a release in which the state is In Progress, tracking progress of each task as it is executed:

• If no manual tasks or failures are encountered, the release is completed and archived.

• When a manual task or a task that requires user input is encountered, the CLI will stop tracking the release. A message displays in the XL CLI output indicating that you must go to the Release GUI and perform the manual intervention to complete the task and continue the release pipeline phases and tasks. At this point, the XL CLI stops following the release and you must track progress using the Release GUI.

• If a task fails, the XL CLI stops following the release and displays a message detailing the status. The release changes to a Stopped status, and you can only resume the release pipeline manually using the Release GUI.

note

You can choose to use the detach option and not track progress in the CLI.