vm

Description

Venue	Equivalent Concept(s)
	Instances
	Virtual Machines

A compute resource that combines aspects of compute, networking, and storage capable of running an operating system and applications.

Venue-Specific Properties

These fields are subject to change in the future. They allow for venue- specific behavior.

AWS

venue:
  aws:
    instance_type:  AWS specific instance size, such as t2.micro or m4.large

Azure

venue:
  azure:
    availability_set:
      name:  The name of tha availability set to join/create.
      platform_update_domain_count:
            The number of update domains in the AS.  The default is 2 and the max is 5.
      platform_fault_domain_count:
            The number of fault domains in the AS.  The default is 2 and the max is 3.
    hyperv_generation: To force a specific generation, use `V1` or `V2`.
    managed_identity_id: The pre-existing managed identity to assign to the instance.
                         This is useful if your instance is accessing other services
                         such as Azure Key Vault.
    vm_size: Azure specific VM size, such as `Standard_B2s`.
             If you use ultra disks you may need to specify this to get a compatible virtual machine.

Features

First-Boot Configuration with Userdata

Feature	AWS	Azure
Linux Cloud-Init Script	✔️	✔️
Linux Shell Script	✔️	✔️
Windows Batch	✔️
Windows Powershell	✔️	✔️

Required Properties

cores (integer)

The total number of processing cores available to a virtual machine.

memory (size)

The amount of memory assigned to a virtual machine.

nics (⏩ compute.nic)

The network interface cards in a virtual machine. A NIC attaches a virtual machine to a network for communication. The order in which the NIC are attached typically affects interface ordering.

At least one NIC must be defined.

Optional Properties

configure (dict)

Directives that indicate how the inner configuration of the virtual machine should be processed once provisioning is complete. If you deploy a stock image without any configuration you may not be able to manage the virtual machine. Some venues require certain configure properties to provision successfully, for example Azure requires an administrative username to be specified. These configuration directives are only valid when creating a virtual machine and will be ignored without any warnings for existing virtual machines.

admin (dict)

Performs basic configuration of the virtual machine by setting an administrative username, password, and SSH public key for a single user on platforms that support those actions.

On AWS for linux instances, we inject a small cloud-init script to process this directive, therefore if userdata is specified then this stanza will be ignored. Your image must have cloud-init installed for this to work.

Azure requires this stanza to create a virtual machine therefore we recommend you populate it for a portable blueprint. These properties are delivered to the Azure Linux Agent.

password (string)

The password to assign to the administrative user during VM creation.

Requirements

Venue	OS	Supported?	Notes
AWS	Linux	No	Use public_key.
AWS	Windows	No	Use public_key.
Azure	Linux	No	Use public_key.
Azure	Windows	Yes	See Azure Docs for Windows VM Password Requirements.

public_key (public_key)

Declares a public key to use during VM creation for administrative authentication. This must contain OpenSSH Public Key content. Valid content typically begins with ssh-rsa.

Requirements

Venue	OS	Supported?	Notes
AWS	Linux	Yes
AWS	Windows	Yes	AWS will generate a random password that you can retrieve using the AWS Console, CLI, or API and then decrypt with your private key.
Azure	Linux	Yes
Azure	Windows	No	Use password instead.

username (string)

The username to assign to the administrative user during VM creation. On Linux instances this user will receive sudo privileges, and on Windows instances this user will be an Administrator.

Requirements

Venue	OS	Supported?	Notes
AWS	Linux	Yes
AWS	Windows	No	The Administrator account is always used.
Azure	Linux	Yes
Azure	Windows	Yes	See Azure Docs for Windows VM Username Requirements.

secrets (⏩ security.secret)

On Azure, a Managed Identity for the virtual machine will be added to the Key Vault to enable reading secrets. See the Microsoft documentation for how to use managed identities to read the secret from Key Vault as part of your bootstrapping code. Tip: setting the key_vault_name on the secret makes the URL to the vault predictable.

This currently does nothing on AWS.

userdata (dict)

Performs inner configuration of virtual machines after first boot by using a cloud-init, shell, batch, or powershell script. When this is declared, the admin stanza will be ignored for AWS linux instances and it becomes the blueprint author's responsibility to properly configure the administrative user's rights on the instance (to sudo, for example).

content (string)

An arbitrary configuration script for the virtual machine that is executed once at first boot. This method of configuration supports cloud-init, shell, batch, or powershell scripts. The maximum length of this script is 16 KiB. You should avoid putting any secrets into this data.

If you are using cloud-init, the Cloud config examples is a great place to find recipes for using cloud-init effectively.

Venue-Specific Help Pages

For detailed information about how each venue handles userdata for each operating system type, refer to the table below.

Venue	OS	Documentation
AWS	Linux	AWS Linux Docs
AWS	Windows	AWS Windows Docs
Azure	Linux	Azure Linux Docs
Azure	Windows	Azure Windows Docs

type (string)

The type of script in content. cloud-init script content must begin with the line:

#cloud-init

shell script content must begin with a shebang.

Allowed Values:

• batch

• cloud-init

• powershell

• shell

disks (⏩ storage.disk)

The disk(s) connected to a virtual machine. These disks are in addition to any disks already present in the image used to create the virtual machine.

image (▶ compute.image)

The image a virtual machine is cloned from. This will provide content for the boot disk, and possibly other disks as well if the image contains more than one disk.

zone (integer)

The number of the availability zone to put the vm in. Every virtual machine is in one availability zone. If this value is not specified then one will be chosen automatically. Resources consumed by this virtual machine will automatically be placed into the same availability zone as the virtual machine.

Common Properties

count (integer)

Indicates how many of this vm should exist. When count is specified the name of the given resource will have a hyphen and numeric suffix added automatically, unless the count variable is referenced in the blueprint object name.

depends_on (⏩ any)

This property can be used to declare a dependency from this vm to any other object in the blueprint. This is not necessary for dependencies generated normally by the schema.

folder (▶ location.folder)

The folder containing this vm. If this is not specified and there is only one folder defined, that folder is used automatically.

name (string)

The name of this vm. The name can be different than the blueprint object name. When the name property is not present we apply automatic naming strategies to make resources easier to identify in each venue's management console. When the name property is specified we will use it exactly as specified.

readonly (boolean)

Indicates whether or not this vm is read-only. If so, we verify only the existence and correctness of this vm to its specification rather than creating or modifying it.

The default value if not specified is false.

tags (dict)

The tags to place on this vm. Tags are metadata stored in (key = value, ...) form. Consumers are not allowed to use tags that begin with _tuono as those are reserved.

Discovered Properties

These properties are populated and available in the inventory following a successful apply.

id (string)

The venue-specific identifier of this vm.

type (string)

The venue-specific instance type of a virtual machine.

uuid (uuid)

The universally unique identifier for this vm. This identifier is typically available inside a vm by inspecting the SMBIOS properties.

Examples

Define a vm with 2 cores, 4gb memory, two nics and some disks:

compute:
  image:
    example-image:
      product: UbuntuServer
      publisher: Canonical
      sku: 18.04-LTS
  vm:
    example:
      configure:
        admin:
          password: not_a_g00d_passw0rd
          username: adminuser
      cores: 2
      disks:
        data:
          size: 64 GB
          tags:
            you_can_put: tags_on_disks_like_this
        log:
          size: 512 GB
          type: hdd
      image: example-image
      memory: 4 GB
      nics:
        external:
          firewall: example-firewall
          ips:
            - private:
                type: dynamic
              public:
                type: static
          subnet: example-public
        internal:
          firewall: example-firewall
          ips:
            - private:
                type: dynamic
          subnet: example-isolated
      tags:
        wicked: cool
location:
  folder:
    example-folder:
      region: example-region
  region:
    example-region:
      area: west
      country: USA
networking:
  firewall:
    example-firewall:
      rules:
        - description: Allow SSH
          from: anywhere
          protocols: ssh
          to: self
  network:
    example-network:
      range: 10.0.0.0/8
      scope: public
  protocol:
    ssh:
      ports:
        - port: 6379
          proto: tcp
  subnet:
    example-isolated:
      network: example-network
      range: 10.100.0.0/24
      scope: isolated
    example-public:
      firewall: example-firewall
      network: example-network
      range: 10.0.0.0/24
      scope: public