Get started with blueprints
Digital.ai offers blueprints to help you create declarative YAML files that simplify the infrastructure provisioning and application deployment process. You can use blueprints to get started with the cloud by following examples that show best practices for provisioning a cloud-based infrastructure and deploying your applications to it.
A blueprint guides you through a process that automatically generates YAML files for your applications and infrastructure. The blueprint asks a short series of questions about your application and the type of environment it requires, and the XebiaLabs Command Line Interface (XL CLI) uses your answers to generate YAML files that define configuration items and releases, plus special files that manage sensitive data such as passwords.
You can use blueprints to:
- Move from on-premises to the cloud: You want to move your application from an on-premises infrastructure to the cloud. You can use a blueprint to generate YAML files that provide a starting point for your cloud deployment process.
- Manage cloud configurations “as code”: You already run an application in the cloud and need a better way to manage configuration of your cloud instances. By defining the configuration in YAML files and checking them in alongside code in your repository, you can better control configuration specifications and maintain modifications over time.
- Support audit requirements: Your company auditor wants to verify that changes to your infrastructure have been properly tracked over time. You can simplify this tracking by providing the commit history of the YAML file that defines the infrastructure.
Get started with DevOps as Code features
Blueprints are part of the DevOps as Code feature set, so before you begin using them you need to get your DevOps as Code infrastructure up and running. Then, take some time to familiarize yourself with how to work with the Deploy YAML file format and the Release YAML file format.
How blueprints work
Watch: This 3-minute video presents the basics of how blueprints work.
Here’s how a blueprint works:
- You use the XL CLI
blueprintcommand to select a blueprint.
- The XL CLI walks you through questions specific to the selected blueprint.
- The blueprint generates a set of folders and files that you can store with your code, including declarative YAML files, that are specific to the choices you made when running the blueprint.
- You make any modifications or improvements in the YAML files.
- You use the XL CLI to apply the YAML files, enabling you to provision cloud resources, deploy applications, and manage your release pipeline.
Available Deploy/Release Blueprints
XebiaLabs has created several blueprints to help you get started with common infrastructure provisioning, application deployment, and release orchestration scenarios. Each blueprint is stored in a GitHub repository and is accompanied by a Markdown readme file that describes:
- An introduction describing the blueprint
- Usage syntax
- Tools and technologies including the target infrastructures, tools, and application or framework types
- Prerequisites and other information you’ll need on hand to run the blueprint
- Expected output from running the blueprint
- Tips and tricks
- Specific instructions for running the blueprint and applying the files
See the curated list of Deploy/Release Blueprints that are currently available.
By default, the XL CLI is configured to access the Deploy/Release public blueprint repository provided in the Deploy/Release public software distribution site. This repository includes the public blueprints developed by XebiaLabs and the URL to access it is defined in the
~/.xebialabs/config.yaml file. If you are utilizing the XebiaLabs-provided blueprints provided in this repository, you can run the
xl blueprint command and select from one of these publicly-available blueprints.
You can also choose to establish your own blueprints repository, storing them in an accessible location and configuring the XL CLI to point to that repository.
For more information about blueprint repository options, see Managing a blueprint repository.
Run a blueprint
You select and run a blueprint using the following command:
For each type of blueprint, the XL CLI prompts you to provide details specific to the type of blueprint you are using. For example, the details can include a name for the group of instances you will deploy, your credentials, the region to deploy to, instance sizes to use, and so on. Executing the
blueprint command will generate YAML files that you can apply to:
- Create the necessary configuration items for your deployment
- Create the relationships between these configuration items
- Apply defaults based on best practices
- Create a release orchestration template that you can use to manage your deployment pipeline.
Here is an example of how to run the
From a terminal window, type:
Select a blueprint.
? Choose a blueprint: [Use arrows to move, type to filter] aws/datalake aws/microservice-ecommerce aws/monolith > docker/simple-demo-app
Each blueprint has a unique set of questions applicable to the type of infrastructure you are provisioning. In this example, the
docker/simple-demo-appblueprint is selected.
$ xl blueprint ? Choose a blueprint: docker/simple-demo-app ? What is the Application name? MyTestApp ? At what port should the application be exposed in the container? 80 ? At what port should the container port be mapped in the host? 8181 ? What is the Docker Image (repo and path) for the Backend service? xebialabsunsupported/rest-o-rant-api ? What is the Docker Image (repo and path) for the Frontend service? xebialabsunsupported/rest-o-rant-web
Once you have answered all of the questions, press Enter to run the blueprint and generate folders and files with the details you provided.
? Confirm to generate blueprint files? Yes [file] Blueprint output file 'xebialabs/values.xlvals' generated successfully [file] Blueprint output file 'xebialabs/secrets.xlvals' generated successfully [file] Blueprint output file 'xebialabs/.gitignore' generated successfully [file] Blueprint output file 'xebialabs/xld-environment.yaml' generated successfully [file] Blueprint output file 'xebialabs/xld-docker-apps.yaml' generated successfully [file] Blueprint output file 'xebialabs/xlr-pipeline.yaml' generated successfully [file] Blueprint output file 'xebialabs.yaml' generated successfully
- Inspect the generated files. Although several folders and files are generated, including multiple YAML files, a single file called
xebialabs.yamlbrings it all together, listing multiple YAML files and the order in which they will be executed.
You can adjust or customize specific details using the YAML files and then use the XL CLI
applycommand to apply the specifications. To apply the
xl apply -f xebialabs.yaml
See the results of applying the
A template you can use to orchestrate your releases was created as well as and other settings depending on the blueprint.
Configuration items (CIs) and settings specific to your infrastructure and applications were created within the Applications, Environments, Infrastructure and Configuration nodes.
Every blueprint can use a
_test_ folder for running tests on configuration items. The pull requests for the tests are run in Travis.
How to add testing to your blueprint
- Create a
_test_directory in your blueprint’s directory.
- Create a
.yamlfile that starts with
- Create a
.yamlanswers file containing key/value pairs. For the format of an answers file, see Blueprint answers file.
Blueprint test file YAML definition file structure
|Field name||Expected value||Examples||Required||Description|
||Yes||The name of the answers file.|
||-||Full path of the file produced by the blueprint|
||-||full path of the file not produced because of a
||-||Expected values in
||-||Expected values in
Example of a
answers-file: answers01.yaml expected-files: - file01.txt - dir1/file02.txt not-expected-files: - dir2/needsdependency.txt expected-xl-values: Variable1: value1 Variable2: value2 expected-xl-secrets: Variable3: value3
See the answers file documentation for information about the usage and format of an answers file.
Example of a blueprint directory that contains a
aws/ \-- datalake/ |-- __test__/ | |-- test01.yaml | \-- answers01.yaml |-- blueprint.yaml \-- xebialabs/
When committed, Travis will test your blueprint along with all the others.
- Blueprints provided by XebiaLabs: A curated list of available blueprints that includes links to details for each blueprint.
- Blueprint YAML format: Blueprints themselves are written in YAML format. Here’s a reference for the YAML file structure for blueprints.
- Tutorial: Deploy a microservices e-commerce application to AWS using a blueprint: This tutorial provides a more complex example of using the Microservice Application on Amazon EKS blueprint (
microservices-ecommerce) to deploy a sample microservices-based container application to the Elastic Kubernetes Service (EKS).