Manage blueprint repositories

A blueprint repository is a remote repository that contains templates and source code for blueprint functionality. Each time you run the XL CLI xl blueprint command, it fetches files from the blueprint repository.

Define blueprint repositories

Defined blueprint repositories are stored in the ~/.xebialabs/config.yaml file. This file is created automatically when you run any XL CLI command after installing the XL CLI. When you run the xl blueprint command, this file’s presence on your system enables you to select one of the available blueprints stored in a repository.

  • On initial installation, the config.yaml file is configured to access the XebiaLabs public blueprint repository provided in the XebiaLabs public software distribution site.
  • You can also configure your own HTTP blueprint repository and update the config.yaml file to point to it.
  • You can define multiple blueprint repositories in your config.yaml file.
  • You can define one or more GitHub blueprint repositories in addition to HTTP.

HTTP repository configuration fields

Here are the configuration fields for an HTTP repository in the config.yaml file:

Field Expected value Default value Required Description
name Yes Repository configuration name
type http Yes Repository type
url Yes HTTP repository URL, including protocol
username No Basic authentication username
password No Basic authentication password

Note: Only basic authentication is supported at the moment for remote HTTP repositories.

Local repository configuration

The type: local repository is mainly intended to be used for local development and tests. Any local path can be used as a blueprint repository with this type.

Field Expected value Default value Required Description
name - - Yes Repository configuration name
type local - Yes Repository type
path - - Yes Full local path where blueprint definitions can be stored. ~ can be used for stating the current user’s home directory under Unix systems.
ignored-dirs - - No List of comma-separated directories, to be ignored while traversing the local path.
Example: .git, some-other-dir
ignored-files - - No List of comma-separated files, to be ignored while traversing the local path.
Example: .DS_Store, .gitignore

Notes

  • In the case of local repositories, if the path is set too generically - such as ~ - the traversal path will be big and may result in the blueprint command running very slowly.
  • in development you can use the -l flag to use a local repository directly without defining it in configuration. For example, to execute a blueprint in a local directory ~/mySpace/myBlueprint you can run xl blueprint -l ~/mySpace -b myBlueprint.

Define multiple repositories

You can specify multiple blueprint repositories in your config.yaml file.

Important notes:

  • Only one of the listed repositories will be active at a given time.
  • The active blueprint repository should be stated using the current-repository field in the configuration file.
  • If the defined blueprint repository cannot be reached, an error displays.
  • If the current-repository field is not stated, an error displays.

Here is the format for the blueprint section of the config.yaml file that points to a GitHub repository, the public XebiaLabs HTTP repository, and a local repository that you create:

blueprint:
  current-repository: xebialabs-github
  repositories:
    - name: xebialabs-github
      type: github
      repo-name: blueprints
      owner: xebialabs
      token: my-github-token
      branch: master
    - name: xebialabs-dist
      type: http
      url: http://dist.xebialabs.com/public/blueprints
    - name: test
      type: local
      path: /path/to/local/test/blueprints/
      ignored-dirs: .git, .vscode
      ignored-files: .DS_Store, .gitignore

Note that the xebialabs-github repository is declared as the default in this example.

GitHub repository configuration fields

You can maintain blueprints in one or more GitHub repositories and specify these details in your config.yaml file.

Here are the configuration fields for a GitHub repository in the config.yaml file:

Field Expected value Default value Required? Details
name Yes Repository configuration name
type github Yes Repository type
repo-name Yes GitHub remote repository name
owner Yes GitHub remote repository owner
Can be different than the user accessing it
branch master No GitHub remote repository branch to use
token No GitHub user token, please refer to GitHub documentation for generating one.
Repo read permission is required when generating the token for the XL CLI

Note: When the token field is not specified, the GitHub API will be accessed in unauthenticated mode and the rate limit will be much less than the authenticated mode. According to the GitHub API documentation, the unauthenticated rate limit per hour and per IP address is 60, whereas the authenticated rate limit per hour and per user is 5000. You should set the token field in your configuration so as not to receive any GitHub API related rate limit errors.

Define a single GitHub repository

Here is an example of the blueprint section of a config.yaml file that is configured to access a GitHub repository:

blueprint:
  current-repository: my-github
  repositories:
  - name: my-github
    type: github
    repo-name: blueprints
    owner: mycompany
    branch: master
    token: my-github-token

Define multiple GitHub and HTTP repositories

You can specify multiple GitHub and/or HTTP blueprint repositories in your config.yaml file.

Important notes:

  • Only one of the listed repositories will be active at a given time.
  • The active blueprint repository should be stated using the current-repository field in the configuration file.
  • If the defined blueprint repository, or current-repository field is not stated, the XL CLI will auto-update the config.yaml file with the default XebiaLabs blueprint repository.

Here is the format for the blueprint section of the config.yaml file that points to the public XebiaLabs HTTP repository and a second GitHub repository you create:

blueprint:
  current-repository: my-github
  repositories:
  - name: xl-dist
    type: http
    url: https://dist.xebialabs.com/public/blueprints/
  - name: my-github
    type: github
    repo-name: blueprints
    owner: mycompany
    branch: master
    token: GITHUB_TOKEN

Manually specify a blueprint using the blueprint command

You can choose to explicitly specify a local or remote folder path to a blueprint when running the blueprint command. Supported options depend on the version of the DevOps Platform software and XL CLI you are running. See the xl blueprint command in the XL CLI command reference for details.

Repository structure example

To better understand the file and folder structure of a blueprint repository, review the public XebiaLabs blueprint repository.

For example, you can drill down from the root of this repository to see how the Microservice Application on Amazon EKS blueprint is structured:

blueprints
├── index.json
└── aws/
      └── microservice-ecommerce/
            ├── blueprint.yaml
            ├── xebialabs.yaml
            ├── cloudformation/
            │     ├── template1.yaml.tmpl
            │     └── template2.yaml
            │
            └── xebialabs/
                  ├── xld-environment.yaml.tmpl
                  ├── xld-infrastructure.yaml.tmpl
                  ├── xlr-pipeline.yaml.tmpl
                  └── README.md.tmpl

The repository structure consists of:

  • index.json file: The index.json file at the root level of an HTTP blueprint repository provides an index listing off the blueprints stored in the repository, enabling you to select one of these blueprints using the XL CLI.

    For example, the index.json file in the XebiaLabs public repository defines the available blueprints:

    [
    "aws/monolith",
    "aws/microservice-ecommerce",
    "aws/datalake",
    "docker/simple-demo-app"
    ]

    Notes:

    • The index.json file is not needed for a GitHub type repository.
    • If you choose to set up a new HTTP repository, you must update the JSON file to reflect your new repository.
    • To automatically generate an index.json file on your release pipeline, you can refer to the sample generate_index.py python script in the official XebiaLabs blueprint GitHub repository.
  • Blueprint template files: All files with tmpl extension are templates for the blueprint. These template files will be passed through generator to create “ready-to-use” YAML files.

  • Regular files and folders: All files and directories will be copied directly.

File details

Here are the file details for the Microservice Application on Amazon EKS blueprint example.

microservice-ecommerce/
            ├── blueprint.yaml
            ├── xebialabs.yaml
            ├── cloudformation/
            │     ├── template1.yaml.tmpl
            │     └── template2.yaml
            │
            └── xebialabs/
                  ├── xld-environment.yaml.tmpl
                  ├── xld-infrastructure.yaml.tmpl
                  ├── xlr-pipeline.yaml.tmpl
                  └── README.md.tmpl
  • blueprint.yaml file: Each application must have a blueprint.yaml in which you specify the required user prompts and files used for the blueprint.

  • xebialabs.yaml file: This file is an entry point for xl apply command. For your convenience, this file combines all XL Deploy and XL Release YAML templates as an Import kind, enabling you to apply a blueprint with a single command.
  • cloudformation folder: This folder is specific to AWS, containing CloudFormation templates used to provision the AWS infrastructure from XL Deploy. Other blueprint types will include folders and files specific to the type of application.
  • xebialabs folder: You place your XebiaLabs YAML templates in this folder. This folder will also include any generated files, including .gitignore, values.xlvals and secrets.xlvals files.