This guide shows how to build your own Azure® Virtual Hard Disk (VHD) using the same scripts that form the basis of the build process for MathWorks® prebuilt images. You can use the scripts to install MATLAB®, MATLAB toolboxes, and the other features detailed below.
A HashiCorp® Packer template generates the machine image. 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. For more information about templates, see Packer Templates.
Before starting, you need:
- Packer 1.7.1 or later.
- Azure credentials. For details about how Packer authenticates Azure clients, see Azure authentication for Packer.
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.
This section shows how to build the latest MATLAB machine image in your Azure account.
Pull the source code and navigate to the Packer folder.
git clone https://github.com/mathworks-ref-arch/matlab-on-azure-win.git
cd matlab-on-azure-win/packer/v1To allow Packer to create resources in your account, you need to provide the credentials client_id, client_secret, tenant_id, and subscription_id.
For instructions on obtaining these credentials, see Create Azure credentials.
You also need to specify a resource group and storage account to store the custom artifact under. For more information on these options, see Configuration Reference.
The command below shows you how to provide these values to Packer as command line parameters. You can also specify them in the Packer template or in a variables definition file, as described in Customize Multiple Variables.
Before deploying the Packer build, you need to install the required Azure Packer plugins. You can do this by running the following command:
packer plugins install github.com/hashicorp/azureor by following the instructions on the Packer documentation page for the Azure Plugin. Deploy the Packer build with the default settings, specifying the authentication and storage details.
packer build \
-var CLIENT_ID=<client_id> \
-var CLIENT_SECRET=<client_secret> \
-var TENANT_ID=<tenant_id> \
-var SUBSCRIPTION_ID=<subscription_id> \
-var STORAGE_ACCOUNT=<storage_account> \
-var RESOURCE_GROUP_NAME=<resource_group> \
-var PACKER_ADMIN_PASSWORD=<admin_password> \
build-azure-matlab.pkr.hclThe Packer build can take about an hour to complete.
Packer writes its output, including the URL of the generated machine image, to a manifest.json file.
To use this URL to deploy the built image, see Deploy Machine Image.
This section describes the different options for customising the build and the Packer build process.
The Packer template supports these build-time variables.
| Argument Name | Default Value | Description |
|---|---|---|
| PRODUCTS | MATLAB and all available toolboxes | Products to install, specified as a list of product names separated by spaces. For example, MATLAB Simulink Deep_Learning_Toolbox Parallel_Computing_Toolbox. For details, see Customize Products to Install. |
| CLIENT_ID | unset | Client ID of Azure service principal. For more information on obtaining Azure service principal credentials, see Create Azure credentials. |
| CLIENT_SECRET | unset | Client secret of Azure service principal. |
| TENANT_ID | unset | Tenant ID of Azure service principal. |
| SUBSCRIPTION_ID | unset | Azure subscription to use for the build. |
| STORAGE_ACCOUNT | unset | Storage account that stores the built artifact. |
| RESOURCE_GROUP_NAME | unset | Resource group that contains STORAGE_ACCOUNT. |
| PACKER_ADMIN_PASSWORD | unset | Password used by Packer to connect to the build instance. Must be at least 12 characters long, and be a combination of uppercase letters, lowercase letters, numbers, and symbols. |
| AZURE_TAGS | {Name="Packer Build", Build="MATLAB", Type="matlab-on-azure-win"} | Tags Packer applies to every resource deployed. |
For a full list of the variables used in the build, see the description fields in the Packer template.
Use the Packer build-time variable PRODUCTS to specify the list of products you want to install on the machine image.
If you do not specify any products, Packer installs MATLAB with the default toolboxes. To see the default toolboxes, go to the
release-config folder, open the variable definition file for your release, and see the definition for the variable PRODUCTS.
For example, install the latest version of MATLAB and Deep Learning Toolbox.
This example assumes Azure authentication and storage details have been set in build-azure-matlab.pkr.hcl.
packer build -var "PRODUCTS=MATLAB Deep_Learning_Toolbox" build-azure-matlab.pkr.hclPacker installs products using MATLAB Package Manager (mpm). For more information, see MATLAB Package Manager (mpm).
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 folder.
These are available for MATLAB R2020a and later.
The following examples assume Azure authentication and storage details have been set in build-azure-matlab.pkr.hcl, or added to the var-file.
For example, install MATLAB R2020a and all available toolboxes.
packer build --var-file="release-config/R2020a.pkrvars.hcl" build-azure-matlab.pkr.hclCommand line arguments can also be combined. For example, install MATLAB R2020a and the Parallel Computing Toolbox only.
packer build --var-file="release-config/R2020a.pkrvars.hcl" -var "PRODUCTS=MATLAB Parallel_Computing_Toolbox" build-azure-matlab.pkr.hclYou can set multiple variables in a Variable Definition File.
For example, to generate a machine image with the most recent MATLAB installed with additional toolboxes in a custom storage account and resource group,
create a variable definition file named custom-variables.pkrvars.hcl containing these variable definitions.
STORAGE_ACCOUNT = <storage_account>
RESOURCE_GROUP_NAME = <resource_group>
PRODUCTS = "MATLAB Deep_Learning_Toolbox Parallel_Computing_Toolbox"
To specify a MATLAB release using a variable definition file, modify the variable definition file in the release-config folder corresponding to the desired release.
Save the variable definition file and include it in the Packer build command.
The following example assumes Azure authentication and storage details have been set in build-azure-matlab.pkr.hcl, or added to custom-variables.pkrvars.hcl.
packer build --var-file="custom-variables.pkrvars.hcl" build-azure-matlab.pkr.hclThe Packer build executes scripts on the image builder instance during the build. These scripts perform tasks such as installing tools needed by the build, installing MATLAB and toolboxes on the image using MATLAB Package Manager (mpm), and cleaning up build leftovers (including SSH keys).
For the full list of scripts that the Packer build executes during the build, see the BUILD_SCRIPTS parameter in the
Packer template.
The prebuilt images that MathWorks provides are built using these scripts as a base, and additionally have support packages installed.
In addition to the build scripts above, the Packer build copies further scripts to the machine image, to be used during startup.
For the full list of startup scripts, see the STARTUP_SCRIPTS parameters in the
Packer template.
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.
You can also use command line interfaces provided by Packer to inspect and format the template. For more information, see Packer Commands (CLI).
When the build completes, Packer writes
the output to a manifest.json file, which contains these fields:
{
"builds": [
{
"name": ,
"builder_type": ,
"build_time": ,
"files": ,
"artifact_id": ,
"packer_run_uuid": ,
"custom_data": {
"build_scripts": ,
"release": ,
"resource_group_name": ,
"specified_products": ,
"storage_account": ,
}
}
],
"last_run_uuid": ,
}The artifact_id section shows the URL of the custom VHD generated by each Packer build.
To deploy the custom machine image, see Build and Deploy Your Own Machine Image.
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.
You can help improve MATLAB by providing user experience information on how you use MathWorks products. Your participation ensures that you are represented and helps us design better products.
To opt out of this service, remove the Setup-DDUX.ps1
script under the build folder.
To learn more, see the documentation: Help Make MATLAB Even Better - Frequently Asked Questions.
If you require assistance or have a request for additional features or capabilities, please contact MathWorks Technical Support.