Working with Blueprint Inputs

Credits: Huge thanks to Rambubu Duddukuri for his work on the code behind inputs, and his patience in taking my questions as I put this blog together.

Inputs are a mechanism for assigning variables to blueprint components at request time. Inputs support a number of different data types - strings, integers, numbers, boolean, and objects. In this post, we will take a look how you can use them.

Using Cloud Assembly Blueprints

Input Schema

const - (Optional) Used with oneOf as the real value associated with the user friendly title.
default - (Optional) Sets a default value for the parameter. If used with enum, must be a valid value contained in the array of options.
description - (Optional) A tooltip that will be rendered on the form at time of deployment. Should be used to provide additional context for the input to the requesting user.
encrypted - (Optional) Hides the user keystrokes behind asterisks in the form. Only supported with the string type. Not compatible with enum.
enum - (Optional) Used to provide a pre-defined selection of options. Supports string, integer, and number as stand-alone types, but not within an array or object. Allows the use of dual-list and multi-select in Service Broker custom forms.
format - (Optional) Sets the expected format for the input. Currently (25/04/19) supports ‘date-time’. Allows the use of the date picker in Service Broker custom forms.
items - (Optional) Used to declare items within an array. Can contain strings, numbers, integers, booleans, or objects.
maxItems - (Optional) Used to constrain the maximum number of selectable items within an array.
maxLength - (Optional) Used to constrain the maximum length of the field for string, integer, and number types. Setting this value to 256 or more renders the input field into a text area, though not when used in concert with encrypted: true.
maximum - (Optional) Used with integer and number types to constrain the permissable maximum value.
minItems - (Optional) Used to constrain the minimum number of selectable items within an array.
minLength - (Optional) Used to constrain the minimum length of the field for string, integer, and number types.
minimum - (Optional) Used with integer and number types to constrain the permissable minimum value.
oneOf - (Optional) Allows the use of a friendly name (title) for a less friendly value (const). The title will be rendered in the form, while const will be the value used. Valid for use with strings, integers, and numbers. If setting a default value, you need to set the const value, and not the title.
pattern - (Optional) Sets a regex pattern to be used for field validation. Only compatible with strings, numbers, and integers.
properties - (Optional) Used to declare the key:value properties block for objects.
readOnly - (Optional) Used to provide a label only.
title - (Optional) Can be used to provide a friendly name that is rendered on the form at time of deployment for an input or a oneof input value.
type - (Required) One of string, number, integer, boolean, or object.
writeOnly - (Optional) Hides the user keystrokes behind asterisks in the form. Not compatible with enum. Renders as a password field in Service Broker custom forms.

Example Usage

String with enumeration

  image:
    type: string
    title: Operating System
    description: The operating system version to use.
    enum:
      - ubuntu 16.04
      - ubuntu 18.04
    default: ubuntu 16.04
  shell:
    type: string
    title: Default shell
    Description: The default shell that will be configured for the created user.
    enum:
      - /bin/bash
      - /bin/sh

Integer with minimum and maximum

  count:
    type: integer
    title: Machine Count
    description: The number of machines that you want to deploy.
    maximum: 5
    minimum: 1
    default: 1

Array of objects

  tags:
    type: array
    title: Tags
    description: Tags that you want applied to the machines.
    items:
      type: object
      properties:
        key:
          type: string
          title: Key
        value:
          type: string
          title: Value

String with friendly names

  platform:
    type: string
    oneOf:
      - title: AWS
        const: platform:aws
      - title: Azure
        const: platform:azure
      - title: vSphere
        const: platform:vsphere
    default: platform:aws

String with pattern validation

  username:
    type: string
    title: Username
    description: The name for the user that will be created when the machine is provisioned.
    pattern: ^[a-zA-Z]+$

String as password

  password:
    type: string
    title: Password
    description: The initial password that will be required to logon to the machine. Will be set to reset on first login.
    writeOnly: true

String as text area

  ssh_public_key:
    type: string
    title: SSH public key
    maxLength: 256

Boolean

  public_ip:
    type: boolean
    title: Assign public IP address
    description: Choose whether your machine should be internet facing.
    default: false

Full blueprint

Updating a Deployment with Inputs

While we often look at inputs during our initial request, there is a another very inportant function that inputs provide - allowing you to modify a Deployment as a Day 2 action. This is not to be confused with modifying the blueprint itself, which can also be used as a mechanism for changing a deployment.

In the image below, you will note that the screen title is “Update”, as I have used the Day 2 update action from the Deployments screen. The input values from my request are all preserved, all render on screen (although you can only see a few on screen in my screenshot), and can all be modified to change your deployment. You could add tags, which would update the deployment, or you could change the operating system which would trigger a re-deploy of the machine in question.

Update Cloud Assembly Deployment Using Inputs

Blueprint Inputs via API

Finally (or should that have been firstly?) we have the API.
You can query the URI below to get the input schema for the blueprint you are intending to request.

GET https://api.mgmt.cloud.vmware.com/blueprint/api/blueprints/{blueprint_id}/inputs-schema

{
    "type": "object",
    "required": [
        "tags",
        "platform",
        "username",
        "ssh_public_key",
        "password"
    ],
    "properties": {
        "image": {
            "type": "string",
            "title": "Operating System",
            "default": "ubuntu 16.04",
            "enum": [
                "ubuntu 16.04",
                "ubuntu 18.04"
            ]
        },
        "count": {
            "type": "integer",
            "minimum": 2,
            "maximum": 5,
            "title": "Machine Count",
            "default": 2
        },
        "size": {
            "type": "string",
            "title": "Machine size",
            "description": "Resource requirements for your workload.",
            "default": "small",
            "enum": [
                "small",
                "medium"
            ]
        },
        "tags": {
            "type": "array",
            "items": {
                "type": "object",
                "encrypted": false,
                "computed": false,
                "recreateOnUpdate": false,
                "ignoreOnUpdate": false,
                "properties": {
                    "key": {
                        "type": "string",
                        "encrypted": false,
                        "computed": false,
                        "recreateOnUpdate": false,
                        "ignoreOnUpdate": false,
                        "title": "Key"
                    },
                    "value": {
                        "type": "string",
                        "encrypted": false,
                        "computed": false,
                        "recreateOnUpdate": false,
                        "ignoreOnUpdate": false,
                        "title": "Value"
                    }
                }
            },
            "title": "Tags",
            "description": "Freeform tags that you would like attached to the provisioned resources."
        },
        "platform": {
            "type": "string",
            "oneOf": [
                {
                    "encrypted": false,
                    "computed": false,
                    "recreateOnUpdate": false,
                    "ignoreOnUpdate": false,
                    "title": "AWS",
                    "const": "platform:aws"
                },
                {
                    "encrypted": false,
                    "computed": false,
                    "recreateOnUpdate": false,
                    "ignoreOnUpdate": false,
                    "title": "Azure",
                    "const": "platform:azure"
                },
                {
                    "encrypted": false,
                    "computed": false,
                    "recreateOnUpdate": false,
                    "ignoreOnUpdate": false,
                    "title": "vSphere",
                    "const": "platform:vsphere"
                }
            ],
            "title": "Deploy to"
        },
        "username": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9]+$",
            "title": "User Account",
            "description": "Name of the user account to be created. Can only contain letters and numbers."
        },
        "shell": {
            "type": "string",
            "title": "Default Shell",
            "default": "/bin/bash",
            "enum": [
                "/bin/bash",
                "/bin/sh"
            ]
        },
        "ssh_public_key": {
            "type": "string",
            "title": "SSH public key"
        },
        "password": {
            "type": "string",
            "writeOnly": true,
            "title": "Password",
            "description": "The initial password that will be required to logon to the machine. Will be set to reset on first login."
        },
        "public_ip": {
            "type": "boolean",
            "title": "Assign public IP address",
            "description": "Choose whether your machine should be internet facing.",
            "default": false
        }
    }
}

The request itself is a POST to https://api.mgmt.cloud.vmware.com/blueprint/api/blueprints-requests/ and the inputs are included in the payload as shown below.

{
  "blueprintId" : "73b91a7e-ddf7-4393-a857-08b6870fa474",
  "deploymentName" : "working with inputs via api",
  "description" : "",
  "plan" : false,
  "content" : null,
  "inputs" : {
    "image" : "ubuntu 16.04",
    "count" : 2,
    "size" : "small",
    "tags" : [
      {
        "key" : "blogging",
        "value" : "finally"
      }
    ],
    "platform" : "platform:aws",
    "username" : "grant",
    "shell" : "/bin/bash",
    "ssh_public_key" : "not really your business",
    "password" : "VMware!",
    "public_ip" : false
  },
  "simulate" : false
}

Happy blueprinting!

{ % include footer.html % }