Skip to main content
Version: Release 23.3

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:

  1. You use the XL CLI blueprint command to select a blueprint.
  2. The XL CLI walks you through questions specific to the selected blueprint.
  3. 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.
  4. You make any modifications or improvements in the YAML files.
  5. 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​

Digital.ai 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.

Blueprints repository​

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 Digital.ai and the URL to access it is defined in the ~/.xebialabs/config.yaml file. If you are utilizing the Digital.ai-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:

xl blueprint

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:

  1. Create the necessary configuration items for your deployment
  2. Create the relationships between these configuration items
  3. Apply defaults based on best practices
  4. Create a release orchestration template that you can use to manage your deployment pipeline.

Here is an example of how to run the docker/simple-demo-app blueprint:

  1. From a terminal window, type:

    xl blueprint

  2. Select a blueprint.

    ? Choose a blueprint:  [Use arrows to move, type to filter]
    aws/datalake
    aws/microservice-ecommerce
    aws/monolith
    > docker/simple-demo-app

  3. Each blueprint has a unique set of questions applicable to the type of infrastructure you are provisioning. In this example, the docker/simple-demo-app blueprint 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

  4. 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

  5. Inspect the generated files. Although several folders and files are generated, including multiple YAML files, a single file called xebialabs.yaml brings it all together, listing multiple YAML files and the order in which they will be executed.

  6. You can adjust or customize specific details using the YAML files and then use the XL CLI apply command to apply the specifications. To apply the xebialabs.yaml file:

    xl apply -f xebialabs.yaml

  7. See the results of applying the xebialabs.yaml file.

    • Navigate to:

      http://localhost:5516

      A template you can use to orchestrate your releases was created as well as and other settings depending on the blueprint.

    • Navigate to:

      http://localhost:4516

      Configuration items (CIs) and settings specific to your infrastructure and applications were created within the Applications, Environments, Infrastructure and Configuration nodes.

Blueprint testing​

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​

  1. Create a _test_ directory in your blueprint's directory.
  2. Create a .yaml file that starts with test (e.g. test01.yaml)
  3. Create a .yaml answers file containing key/value pairs. For the format of an answers file, see Blueprint answers file.

Blueprint test file YAML definition file structure​

Root fields​

| Field name | Expected value | Examples | Required | Description | | ----- | ----- | ----- | ----- | -- | ----- | | answers-file | - | answers01.yaml | Yes | The name of the answers file. | | expected-files | Array | dir/file01.txt | - | Full path of the file produced by the blueprint | | not-expected-files | Array | dir/file02.txt | - | full path of the file not produced because of a dependsOnTrue or dependsOnFalse condition. | | expected-xl-values | Dictionary | Varname: val | - | Expected values in values.xlvals | | expected-xl-secrets | Dictionary | Varname: val | - | Expected values in secrets.xlvals |

Example of a testxxx.yaml file:

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 _test_ directory:

aws/
\-- datalake/
    |-- __test__/
    |   |-- test01.yaml
    |   \-- answers01.yaml
    |-- blueprint.yaml
    \-- xebialabs/

When committed, Travis will test your blueprint along with all the others.

Other resources​