|
| 1 | +# **Build Your Own Machine Image** |
| 2 | + |
| 3 | +## **Introduction** |
| 4 | +This guide shows how to build your own Amazon® Machine Image (AMI) 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 | + |
| 12 | + |
| 13 | +## **Requirements** |
| 14 | +Before starting, you will need: |
| 15 | +* A valid Packer installation later than 1.7.0. For more information, see [Install Packer](https://www.packer.io/downloads). |
| 16 | +* AWS credentials with sufficient permission. For more information, see [Packer Authentication](https://www.packer.io/plugins/builders/amazon#authentication). |
| 17 | + |
| 18 | +## **Costs** |
| 19 | +You are responsible for the cost of the AWS services used when you create cloud resources using this guide. Resource settings, such as instance type, will affect the cost of deployment. For cost estimates, see the pricing pages for each AWS service you will be using. Prices are subject to change. |
| 20 | + |
| 21 | +## **Quick Launch Instructions** |
| 22 | +This section shows how to build the latest MATLAB Parallel Server machine image in your own AWS account. |
| 23 | + |
| 24 | +Pull the source code and navigate to the Packer folder. |
| 25 | +```bash |
| 26 | +git clone https://github.com/mathworks-ref-arch/matlab-parallel-server-on-aws-win |
| 27 | +cd matlab-parallel-server-on-aws-win/packer/v1 |
| 28 | +``` |
| 29 | + |
| 30 | +Initialize Packer to install the required plugins. |
| 31 | +You only need to do this once. |
| 32 | +For more information, see [init command reference (Packer)](https://developer.hashicorp.com/packer/docs/commands/init). |
| 33 | +```bash |
| 34 | +packer init build-parallel-server-ami.pkr.hcl |
| 35 | +``` |
| 36 | + |
| 37 | +Launch the Packer build with the default settings. |
| 38 | +```bash |
| 39 | +packer build build-parallel-server-ami.pkr.hcl |
| 40 | +``` |
| 41 | +Packer writes its output, including the ID of the generated machine image, to a `manifest.json` file at the end of the build. |
| 42 | +To use the built image with a MathWorks CloudFormation template, see [Deploy Machine Image](#deploy-machine-image). |
| 43 | + |
| 44 | + |
| 45 | +## **How to Run the Packer Build** |
| 46 | +This section describes the complete Packer build process and the different options for launching the build. |
| 47 | + |
| 48 | +### **Build-Time Variables** |
| 49 | +The [Packer template](https://github.mathworks.com/development/parallel-server-aws-win-refarch/tree/dev/packer/v1/build-parallel-server-ami.pkr.hcl) supports these build-time variables. |
| 50 | +| Argument Name | Default Value | Description | |
| 51 | +|---|---|---| |
| 52 | +| [PRODUCTS](#customize-products-to-install)| 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`.<br>MATLAB parallel server must be installed with MATLAB in order to deploy a parallel server cluster to the cloud. If no products are specified, the Packer build will install MATLAB with all available toolboxes. For more information, see [MATLAB Package Manager](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md).| |
| 53 | +| [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).| |
| 54 | +| 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` | |
| 55 | +| VPC_ID | *unset* | VPC to assign to the Packer build instance. If no VPC is specified, the default VPC will be used.| |
| 56 | +| SUBNET_ID | *unset* | Subnet to assign to the Packer build instance. If no subnet is specified, the subnet with the most free IPv4 addresses will be used.| |
| 57 | +| INSTANCE_TAGS |{Name="Packer Builder", Build="MATLAB_Parallel_Server"} | Tags to add to the Packer build instance.| |
| 58 | +| AMI_TAGS | {Name="Packer Build", Build="MATLAB_Parallel_Server", Type="matlab-parallel-server-on-aws"} | Tags to add to the machine image. | |
| 59 | +| PACKER_ADMIN_USERNAME | Administrator | Username for the build instance. Sets the ssh_username. | |
| 60 | +| SSH_INTERFACE | public_ip | Type of network interface address used by packer for SSH connections. Acceptable values are 'public_ip', 'private_ip', 'public_dns', or 'private_dns'. | |
| 61 | + |
| 62 | +For a full list of the variables used in the build, see the description fields in the |
| 63 | +[Packer template](https://github.mathworks.com/development/parallel-server-aws-refarch/tree/dev/packer/v1/build-parallel-server-ami.pkr.hcl). |
| 64 | + |
| 65 | + |
| 66 | + |
| 67 | +### **Customize Packer Build** |
| 68 | +#### **Customize Products to Install** |
| 69 | +Use the Packer build-time variable `PRODUCTS` to specify the list of products you want to install on the machine image. If unspecified, Packer will install MATLAB, MATLAB Parallel Server, and all the available toolboxes. Use the Packer build-time variable `POLYSPACE_PRODUCTS` to specify the list of Polyspace products you want to install on the machine image. If unspecified, Packer will install Polyspace Bug Finder Server and Polyspace Code Prover Server. |
| 70 | + |
| 71 | +For example, install the latest version of MATLAB and Deep Learning Toolbox. |
| 72 | +```bash |
| 73 | +packer build -var="PRODUCTS=MATLAB MATLAB_Parallel_Server Deep_Learning_Toolbox" build-parallel-server-ami.pkr.hcl |
| 74 | +``` |
| 75 | + |
| 76 | +#### **Customize MATLAB Parallel Server Release to Install** |
| 77 | +To use an earlier MATLAB Parallel Server release, you must use one of the variable definition files in the [release-config](https://github.com/mathworks-ref-arch/matlab-parallel-server-on-aws-win/tree/master/packer/v1/release-config) folder. |
| 78 | + |
| 79 | +For example, install R2023a for MATLAB Parallel Server and all necessary and available toolboxes. |
| 80 | +```bash |
| 81 | +packer build -var-file="release-config/R2023a.pkrvars.hcl" build-parallel-server-ami.pkr.hcl |
| 82 | +``` |
| 83 | +Command line arguments can also be combined. For example, install R2023a for MATLAB, MATLAB Parallel Server, and the Parallel Computing Toolbox only. |
| 84 | +```bash |
| 85 | +packer build -var-file="release-config/R2023a.pkrvars.hcl" -var="PRODUCTS=MATLAB MATLAB_Parallel_Server Parallel_Computing_Toolbox" build-parallel-server-ami.pkr.hcl |
| 86 | +``` |
| 87 | +Launch the customized image using the corresponding CloudFormation Template. |
| 88 | +For instructions on how to use CloudFormation Templates, see the Deployment Steps |
| 89 | +section on [MATLAB Parallel Server on Amazon Web Services](https://github.com/mathworks-ref-arch/matlab-parallel-server-on-aws-win). |
| 90 | +#### **Customize Multiple Variables** |
| 91 | +You can set multiple variables in a [Variable Definition File](https://developer.hashicorp.com/packer/docs/templates/hcl_templates/variables#standard-variable-definitions-files). |
| 92 | + |
| 93 | +For example, to generate a machine image with the most recent MATLAB installed with necessary and additional toolboxes in a custom VPC, create a variable definition file named `custom-variables.pkrvars.hcl` containing these variable definitions. |
| 94 | +``` |
| 95 | +VPC_ID = <any_VPC_id> |
| 96 | +PRODUCTS = "MATLAB MATLAB_Parallel_Server Deep_Learning_Toolbox Parallel_Computing_Toolbox" |
| 97 | +POLYSPACE_PRODUCTS = "Polyspace_Bug_Finder_Server Polyspace_Code_Prover_Server" |
| 98 | +``` |
| 99 | + |
| 100 | +To specify a MATLAB release using a variable definition file, modify the variable definition file |
| 101 | +in the [release-config](https://github.com/mathworks-ref-arch/matlab-parallel-server-on-aws-win/tree/master/packer/v1/release-config) |
| 102 | +folder corresponding to the desired release. |
| 103 | + |
| 104 | +Save the variable definition file and include it in the Packer build command. |
| 105 | +```bash |
| 106 | +packer build -var-file="custom-variables.pkrvars.hcl" build-parallel-server-ami.pkr.hcl |
| 107 | +``` |
| 108 | + |
| 109 | +### **Installation, Runtime, and Startup Scripts** |
| 110 | +The Packer build executes scripts on the image builder instance during the build. |
| 111 | +These scripts perform tasks such as |
| 112 | +installing tools needed by the build, |
| 113 | +installing MATLAB Parallel Server and toolboxes on the image using [MATLAB Package Manager](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md), |
| 114 | +and cleaning up build leftovers (including powershell history, SSH keys). |
| 115 | + |
| 116 | +For the full list of scripts that the Packer build executes during the build, see the `BUILD_SCRIPTS` parameter in the |
| 117 | +[Packer template](https://github.com/mathworks-ref-arch/matlab-parallel-server-on-aws-win/tree/master/packer/v1/build-parallel-server-ami.pkr.hcl). |
| 118 | +The prebuilt images that MathWorks provides are built using these scripts as a base, and additionally have support packages installed. |
| 119 | + |
| 120 | +In addition to the build scripts above, the Packer build copies further scripts to the machine image, |
| 121 | +to be used during startup and at runtime. These scripts perform tasks such as |
| 122 | +mounting available storage, |
| 123 | +initializing CloudWatch logging (if this is chosen), |
| 124 | +performing MATLAB startup acceleration, |
| 125 | +setting up [MATLAB Job Scheduler](https://github.com/mathworks-ref-arch/matlab-parallel-server-on-aws-win?tab=readme-ov-file#what-is-matlab-job-scheduler), |
| 126 | +and setting up autoscaling scripts and cluster management scripts, |
| 127 | +among other utility tasks. |
| 128 | + |
| 129 | +For the full list of startup and runtime scripts, see the `STARTUP_SCRIPTS` and the `RUNTIME_SCRIPTS` parameters in the |
| 130 | +[Packer template](https://github.com/mathworks-ref-arch/matlab-parallel-server-on-aws-win/tree/master/packer/v1/build-parallel-server-ami.pkr.hcl). |
| 131 | + |
| 132 | + |
| 133 | +## Validate Packer Template |
| 134 | +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). |
| 135 | + |
| 136 | +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). |
| 137 | + |
| 138 | +## Deploy Machine Image |
| 139 | +When the build finishes, Packer writes |
| 140 | +the output to a `manifest.json` file, which contains these fields: |
| 141 | +```json |
| 142 | +{ |
| 143 | + "builds": [ |
| 144 | + { |
| 145 | + "name":, |
| 146 | + "builder_type": , |
| 147 | + "build_time": , |
| 148 | + "files": , |
| 149 | + "artifact_id": , |
| 150 | + "packer_run_uuid": , |
| 151 | + "custom_data": { |
| 152 | + "release": , |
| 153 | + "specified_products": , |
| 154 | + "specified_spkgs": , |
| 155 | + "specified_polyspace_products": , |
| 156 | + "build_scripts": , |
| 157 | + "base_ami_id": , |
| 158 | + "base_ami_name": , |
| 159 | + } |
| 160 | + } |
| 161 | + ], |
| 162 | + "last_run_uuid": "" |
| 163 | +} |
| 164 | +``` |
| 165 | + |
| 166 | +The `artifact_id` section shows the ID of the machine image generated by the most recent Packer build. |
| 167 | + |
| 168 | +The CloudFormation templates provided by MathWorks for releases R2022b onwards include an optional custom machine image ID field, `CustomAmiId`. |
| 169 | +If you do not specify a custom machine image ID, the template |
| 170 | +launches a prebuilt image provided by MathWorks. To launch a custom machine image, |
| 171 | +provide the `artifact_id` from the `manifest.json` file as the `CustomAmiId`. |
| 172 | + |
| 173 | +For AMIs built with an earlier MATLAB release, replace the AMI ID in the |
| 174 | +corresponding CloudFormation template with the AMI ID of your customized image. |
| 175 | + |
| 176 | +If the build has been customized, for example by removing or modifying one or more of the included scripts, |
| 177 | +the resultant machine image **may no longer be compatible** with the provided CloudFormation template. If the AMI has been created from the MATLAB on AWS offering, then the resultant machine image **may not be compatible** due to missing autoscaling scripts, job scheduler setup, and other customisations. |
| 178 | +Compatibility can in some cases be restored by making corresponding modifications to the CloudFormation template. |
| 179 | + |
| 180 | +## Technical Support |
| 181 | +If you require assistance or have a request for additional features or capabilities, contact [MathWorks Technical Support](https://www.mathworks.com/support/contact_us.html). |
| 182 | + |
| 183 | +---- |
| 184 | + |
| 185 | +Copyright 2026 The MathWorks, Inc. |
| 186 | + |
| 187 | +---- |
0 commit comments