|
| 1 | +# **Build Your Own Machine Image** |
| 2 | + |
| 3 | +## **Introduction** |
| 4 | +This guide shows how to build your own Azure® Virtual Machine (VM) Image using the same scripts that form the basis of the build process for MathWorks® prebuilt images. |
| 5 | +You can use the scripts to install MATLAB® Parallel Server™, MATLAB toolboxes, and the other features detailed below. |
| 6 | + |
| 7 | +A HashiCorp® Packer template generates the machine image. |
| 8 | +The template is an HCL2 file that tells Packer which plugins (builders, provisioners, post-processors) to use, how to configure each of those plugins, and what order to run them in. |
| 9 | +For more information about templates, see [Packer Templates](https://www.packer.io/docs/templates#packer-templates). |
| 10 | + |
| 11 | +## **Requirements** |
| 12 | +Before starting, you need: |
| 13 | +* [Packer](https://www.packer.io/downloads) 1.7.1 or later. |
| 14 | +* [Azure credentials](https://learn.microsoft.com/en-us/azure/virtual-machines/linux/build-image-with-packer#create-azure-credentials). For details about how Packer authenticates Azure clients, see [Azure authentication for Packer](https://www.packer.io/plugins/builders/azure#authentication). |
| 15 | + |
| 16 | +## **Costs** |
| 17 | +You are responsible for the cost of the Azure services used when you create cloud resources using this guide. Resource settings, such as virtual machine size, will affect the cost of deployment. For cost estimates, see the pricing pages for each Azure service you will be using. Prices are subject to change. |
| 18 | + |
| 19 | +## **Quick Start Instructions** |
| 20 | +This section shows how to build the latest MATLAB Parallel Server machine image in your Azure account. |
| 21 | + |
| 22 | +Pull the source code and navigate to the Packer folder. |
| 23 | +```bash |
| 24 | +git clone https://github.com/mathworks-ref-arch/matlab-parallel-server-on-azure.git |
| 25 | +cd matlab-parallel-server-on-azure/packer/v1 |
| 26 | +``` |
| 27 | + |
| 28 | +Initialize Packer to install the required plugins. |
| 29 | +You only need to do this once. |
| 30 | +For more information, see [init command reference (Packer)](https://developer.hashicorp.com/packer/docs/commands/init). |
| 31 | +```bash |
| 32 | +packer init build-azure-parallel-server.pkr.hcl |
| 33 | +``` |
| 34 | + |
| 35 | +To allow Packer to create resources in your account, you need to provide the credentials `client_id`, `client_secret`, `tenant_id`, and `subscription_id`. |
| 36 | +For instructions on obtaining these credentials, see [Create Azure credentials](https://learn.microsoft.com/azure/virtual-machines/linux/build-image-with-packer#create-azure-credentials). |
| 37 | + |
| 38 | +You also need to specify a resource group to store the custom artifact under. |
| 39 | +For more information on these options, see [Configuration Reference](https://developer.hashicorp.com/packer/integrations/hashicorp/azure/latest/components/builder/arm#configuration-reference). |
| 40 | + |
| 41 | +The command below shows you how to provide these values to Packer as command line parameters. |
| 42 | +You can also [specify them in the Packer template](https://learn.microsoft.com/azure/virtual-machines/linux/build-image-with-packer#define-packer-template) |
| 43 | +or in a variables definition file, as described in [Customize Multiple Variables](#customize-multiple-variables). |
| 44 | + |
| 45 | +Deploy the Packer build with the default settings, specifying the authentication and storage details. |
| 46 | +```bash |
| 47 | +packer build \ |
| 48 | + -var CLIENT_ID = <client_id> \ |
| 49 | + -var CLIENT_SECRET = <client_secret> \ |
| 50 | + -var TENANT_ID = <tenant_id> \ |
| 51 | + -var SUBSCRIPTION_ID = <subscription_id> \ |
| 52 | + -var RESOURCE_GROUP_NAME = <resource_group> \ |
| 53 | + build-azure-parallel-server.pkr.hcl |
| 54 | +``` |
| 55 | + |
| 56 | +The Packer build can take about an hour to complete. |
| 57 | +Packer writes its output, including the resource ID of the generated machine image, to a `manifest.json` file. |
| 58 | +To use this resource ID to deploy the built image, see [Deploy Machine Image](#deploy-machine-image). |
| 59 | + |
| 60 | + |
| 61 | +## **Customize Packer Build** |
| 62 | +This section describes the different options for customising the build and the Packer build process. |
| 63 | + |
| 64 | +### **Build-Time Variables** |
| 65 | +The [Packer template](./build-azure-parallel-server.pkr.hcl) |
| 66 | +supports these build-time variables. |
| 67 | +| Argument Name | Default Value | Description | |
| 68 | +|---|---|---| |
| 69 | +| PRODUCTS | MATLAB, MATLAB Parallel Server and all available toolboxes | Products to install, specified as a list of product names separated by spaces. For example, `MATLAB Simulink MATLAB_Parallel_Server Deep_Learning_Toolbox Parallel_Computing_Toolbox`. For details, see [Customize Products to Install](#customize-products-to-install). | |
| 70 | +| [POLYSPACE_PRODUCTS](#customize-polyspace-products-to-install)| Polyspace® Bug Finder™ Server™ and Polyspace Code Prover™ Server™ | Polyspace products to install, specified as a list of product names separated by spaces. For example, `Polyspace_Bug_Finder_Server Polyspace_Code_Prover_Server`.<br/>If no products are specified, the Packer build will install Polyspace with Polyspace Bug Finder Server and Polyspace Code Prover Server. For more information, see [MATLAB Package Manager](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md).| |
| 71 | +| SPKGS | List of Deep Learning Support Packages, specified in [release-config](https://github.mathworks.com/development/parallel-server-aws-refarch/tree/dev/packer/v1/release-config) | A list of support packages to install, specified as a list of support package names separated by spaces. For example, `Deep_Learning_Toolbox_Model_for_GoogLeNet_Network Deep_Learning_Toolbox_Model_for_ResNet-101_Network` | |
| 72 | +| CLIENT_ID | *unset* | Client ID of Azure service principal. For more information on obtaining Azure service principal credentials, see [Create Azure credentials](https://learn.microsoft.com/en-us/azure/virtual-machines/linux/build-image-with-packer#create-azure-credentials). | |
| 73 | +| CLIENT_SECRET | *unset* | Client secret of Azure service principal. | |
| 74 | +| TENANT_ID | *unset* | Tenant ID of Azure service principal. | |
| 75 | +| SUBSCRIPTION_ID | *unset* | Azure subscription to use for the build. | |
| 76 | +| RESOURCE_GROUP_NAME | *unset* | Resource group that will store the built image. | |
| 77 | +| AZURE_TAGS | {Name="Packer Build", Build="MATLAB Parallel Server", Type="matlab-parallel-server-on-azure"} | Tags applied by Packer to each deployed resource. | |
| 78 | + |
| 79 | +For a full list of the variables used in the build, see the description fields in the |
| 80 | +[Packer template](./build-azure-parallel-server.pkr.hcl). |
| 81 | + |
| 82 | +### **Customize Products to Install** |
| 83 | +Use the Packer build-time variable `PRODUCTS` to specify the list of products you want to install on the machine image. |
| 84 | +If you do not specify any products, Packer installs MATLAB, MATLAB Parallel Server, and all the available toolboxes with the default toolboxes. To see the default toolboxes, go to the |
| 85 | +[release-config](./release-config) folder, open the variable definition file for your release, and see the definition for the variable `PRODUCTS`. |
| 86 | + |
| 87 | +For example, install the latest version of MATLAB and Deep Learning Toolbox. |
| 88 | +This example assumes Azure authentication and storage details have been set in `build-azure-parallel-server.pkr.hcl`. |
| 89 | +```bash |
| 90 | +packer build -var="PRODUCTS=MATLAB MATLAB_Parallel_Server Deep_Learning_Toolbox" build-azure-parallel-server.pkr.hcl |
| 91 | +``` |
| 92 | + |
| 93 | +Packer installs products using MATLAB Package Manager (mpm). For more information, see [MATLAB Package Manager (mpm)](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md). |
| 94 | + |
| 95 | +### **Customize MATLAB Parallel Server Release to Install** |
| 96 | +By default, the Packer build uses the latest MATLAB release. To install an earlier MATLAB release, use one of the variable definition files in the [release-config](./release-config) folder. |
| 97 | + |
| 98 | +The following examples assume Azure authentication and storage details have been set in `build-azure-parallel-server.pkr.hcl`, or added to the `var-file`. |
| 99 | + |
| 100 | +For example, install R2022b for MATLAB, MATLAB Parallel Server, and all available toolboxes. |
| 101 | +```bash |
| 102 | +packer build -var-file="release-config/R2022b.pkrvars.hcl" build-azure-parallel-server.pkr.hcl |
| 103 | +``` |
| 104 | +Command line arguments can also be combined. For example, install R2022b for MATLAB, MATLAB Parallel Server, and the Parallel Computing Toolbox™ only. |
| 105 | +```bash |
| 106 | +packer build -var-file="release-config/R2022b.pkrvars.hcl" -var="PRODUCTS=MATLAB Parallel_Computing_Toolbox" build-azure-parallel-server.pkr.hcl |
| 107 | +``` |
| 108 | +### **Customize Multiple Variables** |
| 109 | +You can set multiple variables in a [Variable Definition File](https://developer.hashicorp.com/packer/docs/templates/hcl_templates/variables#standard-variable-definitions-files). |
| 110 | + |
| 111 | +For example, to generate a machine image with the most recent MATLAB installed with additional toolboxes in a custom resource group, |
| 112 | +create a variable definition file named `custom-variables.pkrvars.hcl` containing these variable definitions. |
| 113 | +``` |
| 114 | +RESOURCE_GROUP_NAME = <resource_group> |
| 115 | +PRODUCTS = "MATLAB Deep_Learning_Toolbox Parallel_Computing_Toolbox" |
| 116 | +``` |
| 117 | + |
| 118 | +Save the variable definition file and include it in the Packer build command. |
| 119 | +The following example assumes Azure authentication and storage details have been set in `build-azure-parallel-server.pkr.hcl`, or added to `custom-variables.pkrvars.hcl`. |
| 120 | +```bash |
| 121 | +packer build -var-file="custom-variables.pkrvars.hcl" build-azure-parallel-server.pkr.hcl |
| 122 | +``` |
| 123 | + |
| 124 | +## **Installation, Runtime, and Startup Scripts** |
| 125 | +The Packer build executes scripts on the image builder instance during the build. |
| 126 | +These scripts perform tasks such as installing tools needed by the build, installing MATLAB Parallel Server, MATLAB and toolboxes on the image using [MATLAB Package Manager (mpm)](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md), and cleaning up build leftovers. |
| 127 | + |
| 128 | +For the full list of scripts that the Packer build executes during the build, see the `BUILD_SCRIPTS` parameter in the [Packer template](https://github.com/mathworks-ref-arch/matlab-parallel-server-on-azure/blob/master/packer/v1/build-azure-parallel-server.pkr.hcl). The prebuilt images that MathWorks provides are built using these scripts as a base. |
| 129 | + |
| 130 | +These scripts perform tasks such as mounting available storage, performing MATLAB startup acceleration, setting up MATLAB Job Scheduler, and setting up autoscaling scripts and cluster management scripts, among other utility tasks. |
| 131 | + |
| 132 | +In addition to the build scripts above, the Packer build copies further scripts to the machine image, to be used during startup and at runtime. |
| 133 | + |
| 134 | +For the full list of startup and runtime scripts, see the `STARTUP_SCRIPTS` and the `RUNTIME_SCRIPTS` parameters in the |
| 135 | +[Packer template](https://github.com/mathworks-ref-arch/matlab-parallel-server-on-azure/blob/master/packer/v1/build-azure-parallel-server.pkr.hcl). |
| 136 | + |
| 137 | +## Validate Packer Template |
| 138 | +To validate the syntax and configuration of a Packer template, use the `packer validate` command. This command also checks whether the provided input variables meet the custom validation rules defined by MathWorks. For more information, see [validate command](https://www.packer.io/docs/commands/validate#validate-command). |
| 139 | + |
| 140 | +You can also use command line interfaces provided by Packer to inspect and format the template. For more information, see [Packer Commands (CLI)](https://www.packer.io/docs/commands). |
| 141 | + |
| 142 | +## Deploy Machine Image |
| 143 | +When the build completes, Packer writes |
| 144 | +the output to a `manifest.json` file, which contains these fields: |
| 145 | +```json |
| 146 | +{ |
| 147 | + "builds": [ |
| 148 | + { |
| 149 | + "name":, |
| 150 | + "builder_type": , |
| 151 | + "build_time": , |
| 152 | + "files": , |
| 153 | + "artifact_id": , |
| 154 | + "packer_run_uuid": , |
| 155 | + "custom_data": { |
| 156 | + "build_scripts": , |
| 157 | + "managed_image_resource_group_name": , |
| 158 | + "release": , |
| 159 | + "resource_group_name": , |
| 160 | + "specified_polyspace_products": , |
| 161 | + "specified_products": , |
| 162 | + "specified_support_packages": , |
| 163 | + } |
| 164 | + } |
| 165 | + ], |
| 166 | + "last_run_uuid": "" |
| 167 | +} |
| 168 | +``` |
| 169 | + |
| 170 | +The `artifact_id` section shows the resource ID of the custom managed image generated by each Packer build. |
| 171 | + |
| 172 | +To deploy the custom machine image, see [Build and Deploy Your Own Machine Image](https://github.com/mathworks-ref-arch/matlab-parallel-server-on-azure/blob/master/README.md#build-and-deploy-your-own-machine-image). |
| 173 | + |
| 174 | +If the build has been customized, for example by removing or modifying one or more of the included scripts, the resultant machine image might no longer be compatible with the provided ARM template. You can restore compatibility by making corresponding modifications to the ARM template. |
| 175 | + |
| 176 | +If the image has been built from the [MATLAB on Azure](https://github.com/mathworks-ref-arch/matlab-on-azure-win) offering, then the resultant machine image **may not be compatible** due to missing autoscaling scripts, job scheduler setup, and other customizations. |
| 177 | + |
| 178 | +## Technical Support |
| 179 | +If you require assistance or have a request for additional features or capabilities, please contact [MathWorks Technical Support](https://www.mathworks.com/support/contact_us.html). |
| 180 | + |
| 181 | +---- |
| 182 | + |
| 183 | +Copyright 2025-2026 The MathWorks, Inc. |
| 184 | + |
| 185 | +---- |
0 commit comments