Custom Images

Default images are available for each supported cloud provider and region. The following table lists the default base images available:

Cloud Provider Default Image
AWS Amazon Linux 2017
Azure CentOS 7
GCP CentOS 7
OpenStack CentOS 7

Since these default images may not fit the requirements of some users (for example when user requirements include custom OS hardening, custom libraries, custom tooling, and so on) Cloudbreak allows you to use your own custom base images.

In order to use your own custom base images you must:

  1. Build your custom images
  2. Prepare the custom image catalog JSON file and save it in a location accessible to the Cloudbreak VM
  3. Register your custom image catalog with Cloudbreak
  4. Select a custom image when creating a cluster


Only base images can be created and registered as custom images. Do not create or register prewarmed images as custom images.

Build Custom Images

Refer to Custom Images for Cloudbreak for information on how to build custom images.

This repository includes instructions and scripts to help you build custom images. Once you have the images, refer to the documentation below for information on how to create an image catalog and register it with Cloudbreak.

Prepare the Image Catalog

Once you've built the custom images, prepare your custom image catalog JSON file. Once your image catalog JSON file is ready, save it in a location accessible via HTTP/HTTPS.

Structure of the Image Catalog JSON File

The image catalog JSON file includes the following two high-level sections:

Images Section

The burned images are stored in the base-images sub-section of images. The base-images section stores one or more image "records". Every image "record" must contain the date, description, images, os, os_type, and uuid fields.

Parameter Description
date Date for your image catalog entry.
description Description for your image catalog entry.
images The image sets by cloud provider. An image set must store the virtual machine image IDs by the related region of the provider (AWS, Azure) or contain one default image for all regions (GCP, OpenStack). The virtual machine image IDs come from the result of the image burning process and must be an existing identifier of a virtual machine image on the related provider side. For the providers which use global rather than per-region images, the region should be replaced with default.
os The operating system used in the image.
os_type The type of operating system which will be used to determine the default Ambari and HDP repositories to use. Set os_type to "redhat6" for amazonlinux or centos6 images. Set os_type to "redhat7" for centos7 or rhel7 images.
uuid The uuid field must be a unique identifier within the file. You can generate it or select it manually. The utility uuidgen available from your command line is a convenient way to generate a unique ID.

Versions Section

The versions section includes a single "cloudbreak" entry, which maps the uuids to a specific Cloudbreak version:

Parameter Description
images Image uuid, same as the one that you specified in the base-images section.
versions The Cloudbreak version(s) for which you would like to use the images.

Example Image Catalog JSON File

Here is an example image catalog JSON file that includes two sets of custom base images:

You can also download it from here.

  "images": {
    "base-images": [
        "date": "2017-10-13",
        "description": "Cloudbreak official base image",
        "images": {
          "aws": {
            "ap-northeast-1": "ami-78e9311e",
            "ap-northeast-2": "ami-84b613ea",
            "ap-southeast-1": "ami-75226716",
            "ap-southeast-2": "ami-92ce23f0",
            "eu-central-1": "ami-d95be5b6",
            "eu-west-1": "ami-46429e3f",
            "sa-east-1": "ami-86d5abea",
            "us-east-1": "ami-51a2742b",
            "us-west-1": "ami-21ccfe41",
            "us-west-2": "ami-2a1cdc52"
        "os": "amazonlinux",
        "os_type": "redhat6",
        "uuid": "44b140a4-bd0b-457d-b174-e988bee3ca47"
        "date": "2017-10-13",
        "description": "Cloudbreak official base image",
        "images": {
          "azure": {
            "Australia East": "",
            "Australia South East": "",
            "Brazil South": "",
            "Canada Central": "",
            "Canada East": "",
            "Central India": "",
            "Central US": "",
            "East Asia": "",
            "East US": "",
            "East US 2": "",
            "Japan East": "",
            "Japan West": "",
            "Korea Central": "",
            "Korea South": "",
            "North Central US": "",
            "North Europe": "",
            "South Central US": "",
            "South India": "",
            "Southeast Asia": "",
            "UK South": "",
            "UK West": "",
            "West Central US": "",
            "West Europe": "",
            "West India": "",
            "West US": "",
            "West US 2": ""
          "gcp": {
            "default": "sequenceiqimage/hdc-hdp--1710161226.tar.gz"
          "openstack": {
            "default": "hdc-hdp--1710161226"
        "os": "centos7",
        "os_type": "redhat7",
        "uuid": "f6e778fc-7f17-4535-9021-515351df3691"
  "versions": {
    "cloudbreak": [
        "images": [
        "versions": [

Register Image Catalog

Now that you have created your image catalog JSON file, register it with your Cloudbreak instance.


The content type of your image catalog file should be "application/json" for Cloudbreak to be able to process it.

Register Image Catalog in the UI

Use these steps to register your custom image catalog in the Cloudbreak UI.


  1. In the Cloudbreak UI, select Settings > Image Catalogs from the navigation menu.
  2. Click Create Image Catalog.

  3. Enter name for your image catalog and the URL to the location where it is stored.

  4. Click Create.

After performing these steps, the image catalog will be available and automatically selected as the default entry in the image catalog drop-down list in the create cluster wizard.

Register Image Catalog in the CLI

To register your custom image catalog using the CLI, use the cb imagecatalog create command. Refer to CLI documentation.

Select a Custom Image When Creating a Cluster

Once you have registered your image catalog, you can use your custom image(s) when creating a cluster.

Select a Custom Image in Cloudbreak UI

Perform these steps in the advanced General Configuration section of the create wizard wizard.


  1. Under Choose Image Catalog, select your custom image catalog.
  2. Under Base Images > Choose Image, select the provider-specific image that you would like to use.
    The "os" that you specified in the image catalog will be displayed in the selection and the content of the "description" will be displayed in green.
  3. You can leave the default entries for the Ambari and HDP repositories, or you can customize to point to specific versions of Ambari and HDP that you want to use for the cluster.

Select a Custom Image in CLI

To use the custom image when creating a cluster via CLI, perform these steps.


  1. Obtain the image ID. For example:

    cb imagecatalog images aws --imagecatalog custom-catalog
    "Date": "2017-10-13",
    "Description": "Cloudbreak official base image",
    "Version": "",
    "ImageID": "44b140a4-bd0b-457d-b174-e988bee3ca47"
    "Date": "2017-11-16",
    "Description": "Official Cloudbreak image",
    "Version": "",
    "ImageID": "3c7598a4-ebd6-4a02-5638-882f5c7f7add"

  2. When preparing a CLI JSON template for your cluster, set the "ImageCatalog" parameter to the image catalog that you would like to use, and set the "ImageId" parameter to the uuid of the image from that catalog that you would like to use. For example:

      "name": "aszegedi-cli-ci",
      "network": {
    "subnetCIDR": ""
      "orchestrator": {
    "type": "SALT"
      "parameters": {
    "instanceProfileStrategy": "CREATE"
      "region": "eu-west-1",
      "stackAuthentication": {
    "publicKeyId": "seq-master"
      "userDefinedTags": {
    "owner": "aszegedi"
      "imageCatalog": "custom-catalog",
      "imageId": "3c7598a4-ebd6-4a02-5638-882f5c7f7add"

Related Links
CLI Reference