An image mapping groups a set of predefined target operating system specifications for a specific cloud account/region in vRealize Automation by using natural language naming.

Cloud vendor accounts such as Microsoft Azure and Amazon Web Services use images to group a set of target deployment conditions together, including OS and related configuration settings. vCenter and NSX-based environments, including VMware Cloud on AWS, use a similar grouping mechanism to define a set of OS deployment conditions. When you build and eventually deploy and iterate a template, you pick an available image that best fits your needs.

Organize image mappings for a project by similar operating system settings, tagging strategy, and functional deployment intent.

To simplify template creation, you can select a pre-configuration option when you add a new cloud account. When you select the pre-configuration option, your organization's most popular flavor mapping and image mapping for the specified region are selected.

When you add image information to a template, you use either the image or imageRef entry in the properties section of a machine component. For example, if you want to clone from a snapshot, use the imageRef property.

For examples of image and imageRef entries in template code, see Designing your Cloud Assembly deployments.

To assign a permission on a content library, an administrator must grant the permission to the user as a global permission. For related information, see Hierarchical Inheritance of Permissions for Content Libraries in vSphere Virtual Machine Administration at VMware vSphere Documentation.

Synchronizing images for the cloud account/region

You can run image synchronization to ensure that the images you are adding or removing for a given cloud account/region on the Infrastructure > Configure > Image Mapping page are current.
  1. Open the associated Cloud Account/Region by selecting Infrastructure > Connections > Cloud accounts. Select the existing cloud account/region.
  2. Click the Sync Images button and let the action complete.

    picture of the Synchronize Image icon on the cloud account page

  3. When the action is complete, click Infrastructure > Configure > Image Mapping. Define a new or edit an existing image mapping and select the cloud account/region from step 1.
  4. Click the image synchronization icon on the Image Mapping page.

    image synchronization icon shown on Image Mappings page

  5. Configure image mappings settings for the specified cloud account/region on the Image Mapping page.

Viewing OVF details

You can include OVF specifications in Cloud Assembly template objects, such as vCenter machine components and image maps. If your image contains an OVF file, you can discover its content without opening the file. Hover over the View OVF details option to display OVF details, including its name and location. For more information about the OVF file format, see vcenter ovf: property. To view the OVF details, the image mapping must reside on the web server.

hover over the View OVF Details symbol and click to see the OVF contents

Note: You cannot use OVF properties of images in vCenter or content libraries when provisioning from a template. If the OVF is hosted directly in vCenter, the View OVF details option is not visible or otherwise available. The View OVF details option is not available for images in content libraries.

For related information about viewing OVF details by using an OVF link in the mapping field, see external article Cloud template from an OVA.

Using shared and latest images from a Microsoft Azure image gallery

When creating image mappings for Microsoft Azure, you can select images from a shared Azure image gallery in the subscription. The images in the drop-down menu are data-collected and made available based on your selected region.

While shared image galleries can be used across multiple subscriptions, they cannot be listed in the image mapping drop-down menu across subscriptions. Only the images of a particular subscription are data-collected and listed in the image mappings list. To use an image from an image gallery in a different subscription, provide the image ID in the image mapping and use that image mapping in the template.

Using constraints and tags to select a suitable compute for the image

You can use image constraints to select a suitable compute based on the compute's tag. For example, if you have a tag1 constraint on a particular image and if the image is selected during allocation, then a compute with tag tag1 is selected for placing the machine being provisioned. If such compute does not exist, the allocation of the machine fails.

Using a cloud configuration script to control deployment

You can use a cloud configuration script in an image map, template, or both to define custom OS characteristics to be used in a Cloud Assembly deployment. For example, based on whether you are deploying a template to a public or private cloud, you can apply specific user permissions, OS permissions, or other conditions to the image. A cloud configuration script adheres to a cloud-init format for Linux-based images or a cloudbase-init format for Windows-based images. Cloud Assembly supports the cloud-init tool for Linux systems and the cloudbase-init tool for Windows.

For Windows machines, you can use any cloud configuration script format that is supported by cloudbase-init.

The machine resource in the following sample template code uses an image that contains a cloud configuration script, the content of which is seen in the image entry. 
resources:
  demo-machine:
    type: Cloud.vSphere.Machine
    properties:
      flavor: small
      image: MyUbuntu16 
        https://cloud-images.ubuntu.com/releases/16.04/release-20170307/ami-ubuntu-16.04-1.10.3-00-15269239.ova
      cloudConfig: |
        ssh_pwauth: yes
        chpasswd:
          list: |
            ${input.username}:${input.password}
          expire: false
        users:
          - default
          - name: ${input.username}
            lock_passwd: false
            sudo: ['ALL=(ALL) NOPASSWD:ALL']
            groups: [wheel, sudo, admin]
            shell: '/bin/bash'
        runcmd:
          - echo "Defaults:${input.username}  !requiretty" >> /etc/sudoers.d/${input.username}

Dynamic property evaluation works when using cloudConfig directly in a template, but isn't supported for cloudConfig in an image map.

In the template code, you use the image setting to reference an image that is defined as an image mapping. You use the imageRef setting to identify a template that contains a snapshot (for linked clones), an image template, or a content library template OVF.

What happens when an image mapping and a template contain a cloud configuration script

When a template that contains a cloud configuration script uses an image mapping that contains a cloud configuration script, both scripts are combined. The merge action processes the contents of the image mapping script first and the contents of the template script second, with consideration being given to whether the scripts are in #cloud-config format or not.

  • For scripts that are in the #cloud-config format, the merge combines the contents of each module (for example runcmd, users, and write_files) as follows:
    • For modules where the contents are a list, the lists of commands from the image mapping and from the template are merged, excluding commands that are identical in both lists.
    • For modules where the contents are a dictionary, the commands are merged and the result is a combination of both dictionaries. If the same key exists in both dictionaries, the key from the image mapping script dictionary is preserved and the key from the template script dictionary is ignored.
    • For modules where the contents are a string, the content values from the image mapping script are kept and the content values from the template script are ignored.
  • For scripts that are in a format other than #cloud-config or when one script is in #cloud-config format and the other is not, both scripts are combined in a way that the image mapping script is run first and the template script is run when the image mapping script is finished.

Add an image from a vCenter content library

When a local or publisher content library resides in a vCenter that is managed by your vRealize Automation organization, content library template images appear in the image drop-down menu. The images listed include OVF and VM template images in local or publisher vCenter content libraries. Images in subscriber content libraries do not appear in the drop-down menu. The template from which a VM has been cloned is shown in the machine details section of the machine deployments user interface.

Image shows a library item where the image name is prefaced by the library name and separated by a front slash character

Note:

If the publisher content library vCenter is managed by vRealize Automation, then publisher information is displayed in the image mapping selection grid in the following format: publisher_content_library_name / content_item_name

To assign a permission on a content library, an administrator must grant the permission to the user as a global permission. For related information, see Hierarchical Inheritance of Permissions for Content Libraries in vSphere Virtual Machine Administration at VMware vSphere Documentation.

If the publisher content library vCenter is not managed by vRealize Automation, then subscriber information is displayed in the image mapping selection grid in the following format: subscriber_content_library_name / content_item_name

For example, in the following scenario only the subscriber content library items are visible in the vRealize Automation image mapping list:
  • For a vCenter named VC-1, there is a subscriber content library in the VC and a cloud account is created in vRealize Automation that is associated to VC-1.
  • For a vCenter named VC-2, there is a publisher content library in the VC that the subscriber content library of VC-1 is subscribed from. However, there is no cloud account in vRealize Automation that is associated to VC-2.

    Because VC-1 is associated to a vRealize Automation cloud account, the subscriber content library is available in vRealize Automation. Its contents are collected and displayed in the vRealize Automation image mapping list. However, because VC-2 is not associated to a cloud account, vRealize Automation has no knowledge of its publisher content library. To display the publisher content library items in the image mapping list, you must associated a cloud account to the VC-2 vCenter.

When you deploy a template that contains a VM template image mapping, vRealize Automation attempts to access the mapped image in the content library that is closest to the datastore, and then closest to the host, of the machine to be provisioned. This can include a local content library as well as a publisher or subscriber content library.

When you deploy a template that contains an OVF template image mapping, OVF images are accessed as specified in the image mapping row if the image is in a local content library or a local subscriber of a specified remote publisher content library.

For related information about creating and using vCenter content libraries, see Using Content Libraries in vSphere product documentation and VMware blog posts How to Use Content Libraries in vRealize Automation 8 and vRealize Automation Cloud and Manage templates with vSphere content library and vRA 8.

More information about configuring and using cloud configuration scripts

For more information about working with cloud configuration scripts in templates, see Machine initialization in Cloud Assembly .

Also see VMware blog articles vSphere Customization with Cloud-init While Using vRealize Automation 8 or Cloud and Customizing Cloud Assembly Deployments with Cloud-Init.