DevOps as Code workshop
This workshop will teach you:
- How to start up the XL DevOps Platform with the devops-as-code features installed
- How to install the XL CLI
- How to import and deploy a Docker application with XL Deploy
- How to import and run a pipeline with XL Release
- How to generate XL YAML files to learn about the syntax
You'll need to have Docker installed on your machine before you begin:
- Mac: https://docs.docker.com/docker-for-mac/
- Windows: https://docs.docker.com/docker-for-windows/
- Linux: Refer to the instructions for your Linux distribution on how to install Docker
For part II of the workshop, you will also need:
- Access to an AWS account with administrator privileges
The docker compose setup potentially exposes weakly protected services to the network. Please use a firewall to block incoming network connections and avoid running the setup while connected to public networks. Also make sure to stop all containers by running
docker-compose down when finished with the workshop.
Install the workshop
Get the workshop
- Download and extract the workshop zip:
$ curl -LO https://github.com/xebialabs/devops-as-code-workshop/archive/master.zip $ unzip master.zip $ cd devops-as-code-workshop-master
Install licenses for XL Deploy and XL Release
Copy the XL Deploy license to
Copy the XL Release license to
Start up the XL DevOps Platform
If you are already running XL Deploy or XL Release on your local machine, please stop them.
If you are running the workshop on Windows, execute the following command to be able to run the Docker Compose file:
> set COMPOSE_CONVERT_WINDOWS_PATHS=1
For more information on this environment variable, read the documentation for Docker Compose
- Start up the XL DevOps Platform:
$ docker-compose up --build
- Wait for XL Deploy and XL Release to have started up. This will have occurred when the following line is shown in the logs:
devops-as-code-workshop_xl-cli_1 exited with code 0
Open the XL Deploy GUI at http://localhost:4516/ and login with the username
admin. Verify that the about box reports the version to be 8.6.1.
Open the XL Release GUI at http://localhost:5516/ and login with the username
admin. Verify that the about box reports the version to be 8.6.1.
Install the XL CLI
- Open a new terminal window and install the XL command line client:
$ curl -LO https://s3.amazonaws.com/xl-cli/bin/8.6.1/darwin-amd64/xl $ chmod +x xl $ sudo mv xl /usr/local/bin
$ curl -LO https://s3.amazonaws.com/xl-cli/bin/8.6.1/linux-amd64/xl $ chmod +x xl $ sudo mv xl /usr/local/bin
and place it somewhere on your
- Verify that you have installed the correct version of the XL CLI by executing the following command:
$ xl version
The output should look like this:
CLI version: 8.6.1 Git version: 8.6.0-4-gaf96240 API version XL Deploy: xl-deploy/v1 API version XL Release: xl-release/v1 Git commit: af962402e3b0d9a6cfb7c366e35f21578e848f05 Build date: 2019-03-27T13:07:32.971Z GO version: go1.11 OS/Arch: darwin/amd64
The last line will be different, depending on the architecture of your machine.
- Test the XL CLI by executing the following command:
$ xl help
The output should look like this:
XL Cli 8.6.1 The xl command line tool provides a fast and straightforward method for provisioning XL Release and XL Deploy with YAML files. The files can include items like releases, pipelines, applications and target environments. Usage: xl [command] Available Commands: apply Apply configuration changes blueprint Create a Blueprint generate Generate configuration help Help about any command ide IDE commands license Display license info preview Preview Deployment version Display version info wrapper Generate XL wrapper Flags: --blueprint-current-repository string Current active blueprint repository name --config string config file (default: $HOME/.xebialabs/config.yaml) -h, --help help for xl -q, --quiet suppress all output, except for errors -v, --verbose verbose output --xl-deploy-authmethod string Authentication method to access the XL Deploy server (default "http") --xl-deploy-password string Password to access the XL Deploy server (default "admin") --xl-deploy-url string URL to access the XL Deploy server (default "http://localhost:4516/") --xl-deploy-username string Username to access the XL Deploy server (default "admin") --xl-release-authmethod string Authentication method to access the XL Release server (default "http") --xl-release-password string Password to access the XL Release server (default "admin") --xl-release-url string URL to access the XL Release server (default "http://localhost:5516/") --xl-release-username string Username to access the XL Release server (default "admin") Use "xl [command] --help" for more information about a command.
Part I - Deploying a Docker application
Exercise 1: Review the XL DevOps Platform running on Docker
When the XL DevOps Platform was started up by the Docker Compose file, four containers were started:
xl-deployruns XL Deploy.
xl-releaseruns XL Release.
dockerproxyis where XL Deploy will deploy to. It's a proxy for the Docker engine on your local machine, the same that runs XL Release and XL Deploy..
xl-cliruns the XL CLI to apply the
configure-xl-devops-platform.yamlYAML file. This XL YAML file adds two configurations:
- It adds an XL Deploy configuration to XL Release so that the latter can find the former.
- It adds a
docker.Engineconfiguration to XL Deploy so that XL Deploy can deploy to the Docker engine (via the Docker proxy).
- Open the XL Deploy GUI, find the local-docker entry in the Infrastructure tree and run the Check Connection control task.
Exercise 2: Set up the environment
Now that we have the XL DevOps Platform up and running and connected to our local Docker instance, let's create an environment that contains it.
Open a new terminal window and go to the directory where you unzipped the
Create the environment that contains the Docker engine by applying its XL YAML file:
$ xl apply -f exercise-2/docker-environment.yaml
- Open the XL Deploy GUI and review the environment that you just created.
Exercise 3: Import a simple package and deploy it
Let's try and deploy something to our local Docker instance with XL Deploy. We'll start with a single container; the backend part of the REST-o-rant application. It's called rest-o-rant-api because it serves up the API.
- Import the REST-o-rant-api package:
$ xl apply -f exercise-3/rest-o-rant-api-docker.yaml
Open the XL Deploy GUI and review version 1.0 of the rest-o-rant-api-docker application. Compare it with the contents of the XL YAML file that you applied in the previous step.
Using the GUI, deploy version 1.0 of the rest-o-rant-api-docker application to the Local Docker Engine environment.
When the deployment has finished, check whether the rest-o-rant-api container is running:
$ docker ps
The output should look something like this:
$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES b0611ff9ffbb xebialabsunsupported/rest-o-rant-api "java -Djava.securit…" 11 seconds ago Up 10 seconds 8080/tcp rest-o-rant-api f80c2b00a88e xebialabsunsupported/xl-release:8.6.1 "/opt/xebialabs/tini…" 3 days ago Up About an hour 0.0.0.0:5516->5516/tcp devops-as-code-workshop_xl-release_1 a99c31ddd458 tecnativa/docker-socket-proxy:latest "/docker-entrypoint.…" 3 days ago Up About an hour 2375/tcp devops-as-code-workshop_dockerproxy_1 68a5c6439540 xebialabsunsupported/xl-deploy:8.6.1 "/opt/xebialabs/tini…" 3 days ago Up About an hour 0.0.0.0:4516->4516/tcp devops-as-code-workshop_xl-deploy_1
Exercise 4: Deploy a (slightly) more complex package
Serving a REST API is all nice and dandy, but it's pretty useless without a UI. So let's deploy the rest-o-rant-web container. Because it needs to access the rest-o-rant-api application to get its data, we'll also need to define a Docker network to allow the two containers to communicate. Version 1.1 of the rest-o-rant-api application will define that network.
- Import the new version of the rest-o-rant-api-docker package, as well as the rest-o-rant-web-docker package:
$ xl apply -f exercise-4/rest-o-rant-docker.yaml
Open the XL Deploy GUI and review the two packages that you just imported and compare them with the XL YAML file. Notice the net rest-o-rant-network deployable in the rest-o-rant-api-docker package.
Using the GUI, deploy version 1.1 of the rest-o-rant-api-docker package to the Local Docker Engine environment.
Using the GUI, deploy version 1.0 of the rest-o-rant-web-docker package to the Local Docker Engine environment.
When the deployment has finished, open a new browser tab and access it at 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.
Exercise 5: Import a pipeline
OK, we've deployed the application, but how do we get rid of it? Well, let's do that manually for one last time:
Undeploy the rest-o-rant-web application from the Local Docker Engine environment.
Undeploy the rest-o-rant-api application from the Local Docker Engine environment.
But let's make sure that you don't forget next time that you run this workshop. Let's create a simple pipeline.
- Import that REST-o-rant pipeline:
$ xl apply -f exercise-5/rest-o-rant-docker-pipeline.yaml
Open the XL Release GUI, go to Design tab, click on the REST-o-rant folder and then go to the Templates tab. Review the REST-o-rant on Docker pipeline that you've just imported and compare it to the XL YAML file.
Start a new release from that template and follow the instructions.
Exercise 6: Simplify the package and the pipeline by using dependencies
You'll have noticed that the pipeline has two separate steps to deploy and later undeploy the rest-o-rant-api-docker and the rest-o-rant-web-docker packages. If we make the frontend depend on the backend, we can simplify the pipeline and ensure that the frontend is not deployed without the backend.
In this exercise we will make the necessary modification in the package and the pipeline and then teach you how to generate the XL YAML files for those modifications.
- In XL Deploy, open Applications/rest-o-rant-web-docker/1.0 and add the following entry to the Application Dependencies map:
and change Undeploy Unused Dependencies to
In XL Release, from the REST-o-rant on Docker pipeline template, remove the Deploy REST-o-rant application backend task from the first phase and the Undeploy REST-o-rant application backend step from the last phase.
Run the pipeline to verify that the application dependencies and the updated pipeline function correctly. When the pipeline has completed, go to the XL Deploy UI and check that the rest-o-rant-api-docker application was undeployed.
Generate the XL YAML files for the changes:
$ xl generate -s xl-deploy -p Applications/rest-o-rant-web-docker -f exercise-6/rest-o-rant-web-docker-with-dependencies.yaml $ xl generate -s xl-release -p REST-o-rant -f exercise-6/rest-o-rant-pipeline-with-dependencies.yaml
- Review the generated XL YAML files and compare them with the originals from exercises 4 and 5 respectively.
Exercise 7: Generate an XL YAML file with artifacts
The XL YAML format also allows you to use artifacts. To see what that looks like, let's generate the PetClinic sample package:
In the XL Deploy UI, import the PetClinic-ear/1.0 sample package from the XL Deploy server.
Generate the XL YAML file for the package you just imported to see how to specify artifacts:
$ xl generate -s xl-deploy -p Applications/PetClinic-ear/1.0 -f exercise-7/petlinic-ear.yaml
- Review the generated XL YAML file and the artifact.
Part II - AWS (ECS and Fargate)
In Part II of the workshop we will show you how to use the XL DevOps Platform to provision container infrastructure into AWS with CloudFormation and then deploy a simple monolith application into it.
For this part of the workshop, you'll need access to an AWS account with administrator privileges and you'll need to have Python installed on your machine.
Exercise 8: Import AWS credentials into XL Deploy
Let's start by connecting XL Deploy with your AWS account.
Install the AWS CLI as described here: https://docs.aws.amazon.com/cli/latest/userguide/installing.html
Configure the AWS CLI as described here and select region eu-west-1 (Ireland): https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-quick-configuration
N.B.: If you have already been using the AWS CLI and have multiple profiles, please ensure the default profile is configured correctly.
If you do not have Python installed on your machine, install it.
Run the provided Python script to generate an XL YAML file with your credentials:
$ ./exercise-8/awsconfig2xld.py > exercise-8/AWSConfig.yaml
Review the generate XL YAML file.
Apply the generated XL YAML file:
$ xl apply -f exercise-8/AWSConfig.yaml
- In XL Deploy, navigate to the Infrastructure/aws object in the Explorer tree and execute the "Check connection" task to verify that the connection could be made.
Exercise 9: Create AWS infrastructure with CloudFormation
Now privision the infrastructure using XL Deploy and CloudFormation. We'll let XL Deploy manage and run the CloudFormation template for us and let CloudFormation create the actual resources.
- Import the CloudFormation template and its metadata into XL Deploy:
xl apply -f exercise-9/ecommerce-infrastructure.yaml
In XL Deploy, deploy version 1.0 of the ecommerce-infrastructure package to the AWS environment.
When the deployment has finished, go to the AWS Console, navigate to the CloudFormation service, and review the ecommerce-cloudformation stack and the resources it has created:
- A VPC with routes, subnets, etc.
- IAM roles and policies
- A load balancer with a target group
- An ECS cluster
Exercise 10: Deploy a monolith application
Now that the infrastructure has been provisioned, let's deploy the applicaiton on top of it.
- Import the e-commerce application into XL Deploy:
$ xl apply -f exercise-10/ecommerce-application.yaml
- Import the e-commerce pipeline into XL Release:
$ xl apply -f exercise-10/ecommerce-pipeline.yaml
In XL Release, create a new release based on the e-Commerce CD pipeline template in the e-Commerce folder. Do not start it yet!
We've already provisioned the infrastructure in the previous exercise. So, delete the first task of the first phase (Provision e-commerce infrastructure). In day-to-day use, one would let XL Release handle the complete orchestration, from provisioning the infrastructure to the very end when the infrastructure is deprovisioned.
Start the release.
When the release gets to the Verify application manually task, open the task and follow the instructions to complete it.
Wait until the release has finished.
Exercise 11: Shutting down the XL DevOps Platform
- Shut down the XL DevOps Platform:
$ docker-compose down
Not only will this stop the XL DevOps Platform, it will also remove any data stored on it. Therefore you should make sure that all releases and deployments have finished and that you've undeployed any applications you've deployed with it before you shut down the XL DevOps Platform.
Bonus exercise: create something new!
OK, that was cool and all. Now use the
xl generate command to learn more about the YAML format and build your own YAML file.