Skip to content

Commit dfef0bf

Browse files
author
Eshan Patel
committed
R2024a release!
1 parent d8b0fc8 commit dfef0bf

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+78778
-20
lines changed

‎README.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@ You need:
2020
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, 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.
2121

2222
# Deployment Steps
23+
By default, the MATLAB reference architectures below launch prebuilt machine images, described in [Architecture and Resources](#architecture-and-resources). Using a prebuilt machine image is the easiest way to deploy a MATLAB reference architecture. Alternatively, to build your own machine image with MATLAB using our build scripts, see [Build and Deploy Your Own Machine Image](#build-and-deploy-your-own-machine-image).
24+
25+
## Deploy Prebuilt Machine Image
2326

2427
To view instructions for deploying the MATLAB reference architecture, select a MATLAB release:
2528

@@ -43,6 +46,9 @@ MathWorks periodically replaces older AMIs with new images.
4346
For more details, see
4447
[When are the MathWorks Amazon Machine Images updated?](#when-are-the-mathWorks-amazon-machine-images-updated)
4548

49+
## Build and Deploy Your Own Machine Image
50+
For details of the scripts which form the basis of the MathWorks Windows AMI build process, see [Build Your Own Machine Image](./packer/v1). You can use these scripts to build your own custom Windows machine image for running MATLAB on Amazon Web Services. You can then deploy this custom image with the MathWorks infrastructure as code (IaC) templates.
51+
4652
## Learn about Architecture
4753

4854
![MATLAB on AWS Reference Architecture](img/aws-matlab-diagram.png)

‎packer/v1/.gitattributes

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Shell scripts are run by the Packer build on the remote Linux machine,
2+
# and so should have LF line endings on checkout.
3+
*.sh text eol=lf
4+
*.ps1 text eol=crlf

‎packer/v1/README.md

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
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®, 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://developer.hashicorp.com/packer/docs/templates#packer-templates).
10+
11+
When you launch a MATLAB instance from your custom image, you might experience a delay in startup speed compared to the prebuilt images. The prebuilt images have additional configurations to enhance startup times.
12+
13+
14+
15+
## **Requirements**
16+
Before starting, you will need:
17+
* A valid Packer installation later than 1.7.0. For more information, see [Install Packer](https://developer.hashicorp.com/packer/install).
18+
* Amazon Web Services (AWS®) credentials with sufficient permission. For more information, see [Packer Authentication](https://developer.hashicorp.com/packer/integrations/hashicorp/amazon#authentication).
19+
20+
## **Costs**
21+
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.
22+
23+
## **Quick Launch Instructions**
24+
This section shows how to build the latest MATLAB machine image in your own AWS account.
25+
26+
Pull the source code and navigate to the Packer folder.
27+
```bash
28+
git clone https://github.com/mathworks-ref-arch/matlab-on-aws-win.git
29+
cd matlab-on-aws-win\\packer\\v1
30+
```
31+
32+
Launch the Packer build with the default settings.
33+
Set the `PACKER_ADMIN_PASSWORD` as a command line parameter.
34+
```bash
35+
packer build -var="PACKER_ADMIN_PASSWORD=<password>" build-matlab-ami.pkr.hcl
36+
```
37+
Packer writes its output, including the ID of the generated machine image, to a `packer_manifest.json` file at the end of the build.
38+
To use the built image with a MathWorks CloudFormation template, see [Deploy Machine Image](#deploy-machine-image).
39+
40+
41+
## **How to Run the Packer Build**
42+
This section describes the complete Packer build process and the different options for launching the build.
43+
44+
45+
### **Build-Time Variables**
46+
The [Packer template](https://github.com/mathworks-ref-arch/matlab-on-aws-win/tree/master/packer/v1/build-matlab-ami.pkr.hcl)
47+
supports these build-time variables.
48+
| Argument Name | Default Value | Description |
49+
|---|---|---|
50+
| [PRODUCTS](#customize-products-to-install)| 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`.<br/>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).|
51+
| PACKER_ADMIN_PASSWORD | *unset*, must be set as a build argument. | 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. |
52+
| BASE_AMI | Default AMI ID refers to Windows_Server-2022-English-Full-Base. | The base AMI upon which the image is built, defaults to the Windows Server 2022 image provided by Microsoft. |
53+
| VPC_ID | *unset* | VPC to assign to the Packer build instance. If no VPC is specified, the default VPC will be used.|
54+
| 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.|
55+
| INSTANCE_TAGS |{Name="Packer Builder", Build="MATLAB"} | Tags to add to the Packer build instance.|
56+
| AMI_TAGS | {Name="Packer Build", Build="MATLAB", Type="matlab-on-aws", Platform = "Windows"} | Tags to add to the machine image.|
57+
58+
For a full list of the variables used in the build, see the description fields in the
59+
[Packer template](https://github.com/mathworks-ref-arch/matlab-on-aws-win/tree/master/packer/v1/build-matlab-ami.pkr.hcl).
60+
61+
62+
63+
### **Customize Packer Build**
64+
#### **Customize Products to Install**
65+
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 with all the available toolboxes.
66+
67+
For example, install the latest version of MATLAB and Deep Learning Toolbox&trade;.
68+
```bash
69+
packer build -var="PRODUCTS=MATLAB Deep_Learning_Toolbox" -var="PACKER_ADMIN_PASSWORD=<password>" build-matlab-ami.pkr.hcl
70+
```
71+
72+
#### **Customize MATLAB Release to Install**
73+
To use an earlier MATLAB release, you must use one of the variable definition files in the [release-config](https://github.com/mathworks-ref-arch/matlab-on-aws-win/tree/master/packer/v1/release-config) folder.
74+
These are available for MATLAB R2020b and later.
75+
76+
For example, install MATLAB R2020b and all available toolboxes.
77+
```bash
78+
packer build -var-file="release-config\R2020b.pkrvars.hcl" -var="PACKER_ADMIN_PASSWORD=<password>" build-matlab-ami.pkr.hcl
79+
```
80+
Command line arguments can also be combined. For example, install MATLAB R2020b and the Parallel Computing Toolbox&trade; only.
81+
```bash
82+
packer build -var-file="release-config\R2020b.pkrvars.hcl" -var="PRODUCTS=MATLAB Parallel_Computing_Toolbox" -var="PACKER_ADMIN_PASSWORD=<password>" build-matlab-ami.pkr.hcl
83+
```
84+
Launch the customized image using the corresponding CloudFormation Template.
85+
For instructions on how to use CloudFormation Templates, see the Deployment Steps
86+
section on [MATLAB on Amazon Web Services](https://github.com/mathworks-ref-arch/matlab-on-aws-win).
87+
#### **Customize Multiple Variables**
88+
You can set multiple variables in a [Variable Definition File](https://developer.hashicorp.com/packer/docs/templates/hcl_templates/variables#standard-variable-definitions-files).
89+
90+
For example, to generate a machine image with the most recent MATLAB installed with additional toolboxes in a custom VPC, create a variable definition file named `custom-variables.pkrvars.hcl` containing these variable definitions.
91+
```
92+
VPC_ID = <any_VPC_id>
93+
PRODUCTS = "MATLAB Deep_Learning_Toolbox Parallel_Computing_Toolbox"
94+
```
95+
96+
To specify a MATLAB release using a variable definition file, modify the variable definition file
97+
in the [release-config](https://github.com/mathworks-ref-arch/matlab-on-aws-win/tree/master/packer/v1/release-config)
98+
folder corresponding to the desired release.
99+
100+
Save the variable definition file and include it in the Packer build command.
101+
```bash
102+
packer build -var-file="custom-variables.pkrvars.hcl" -var="PACKER_ADMIN_PASSWORD=<password>" build-matlab-ami.pkr.hcl
103+
```
104+
105+
### **Installation Scripts**
106+
The Packer build executes scripts on the image builder instance during the build.
107+
These scripts perform tasks such as
108+
installing tools needed by the build,
109+
installing MATLAB and toolboxes on the image using [MATLAB Package Manager](https://github.com/mathworks-ref-arch/matlab-dockerfile/blob/main/MPM.md),
110+
and cleaning up temporary files used by the build.
111+
112+
For the full list of scripts that the Packer build executes during the build, see the `BUILD_SCRIPTS` parameter in the
113+
[Packer template](https://github.com/mathworks-ref-arch/matlab-on-aws-win/tree/master/packer/v1/build-matlab-ami.pkr.hcl).
114+
The prebuilt images that MathWorks provides are built using these scripts as a base, and additionally have support packages installed.
115+
116+
In addition to the build scripts above, the Packer build copies further scripts to the machine image,
117+
to be used during startup and at runtime. These scripts perform tasks such as
118+
mounting available storage and
119+
initializing CloudWatch logging (if this is chosen),
120+
among other utility tasks.
121+
122+
For the full list of startup and runtime scripts, see the `STARTUP_SCRIPTS` and the `RUNTIME_SCRIPTS` parameters in the
123+
[Packer template](https://github.com/mathworks-ref-arch/matlab-on-aws-win/tree/master/packer/v1/build-matlab-ami.pkr.hcl).
124+
125+
126+
## Validate Packer Template
127+
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://developer.hashicorp.com/packer/docs/commands/validate#validate-command).
128+
129+
You can also use command line interfaces provided by Packer to inspect and format the template. For more information, see [Packer Commands (CLI)](https://developer.hashicorp.com/packer/docs/commands).
130+
131+
## Deploy Machine Image
132+
When the build finishes, Packer writes
133+
the output to a `packer_manifest.json` file, which contains these fields:
134+
```json
135+
{
136+
"builds": [
137+
{
138+
"name":,
139+
"builder_type": ,
140+
"build_time": ,
141+
"files": ,
142+
"artifact_id": ,
143+
"packer_run_uuid": ,
144+
"custom_data": {
145+
"build_scripts": ,
146+
"release": ,
147+
"specified_products":
148+
}
149+
}
150+
],
151+
"last_run_uuid": ""
152+
}
153+
```
154+
155+
The `artifact_id` section shows the ID of the machine image generated by the most recent Packer build.
156+
157+
The CloudFormation templates provided by MathWorks for releases R2024a onwards include an optional custom machine image ID field, `CustomAmiId`.
158+
If you do not specify a custom machine image ID, the template
159+
launches a prebuilt image provided by MathWorks. To launch a custom machine image,
160+
provide the `artifact_id` from the `packer_manifest.json` file as the `CustomAmiId`.
161+
162+
For AMIs built with an earlier MATLAB release, replace the AMI ID in the
163+
corresponding CloudFormation template with the AMI ID of your customized image.
164+
165+
If the build has been customized, for example by removing or modifying one or more of the included scripts,
166+
the resultant machine image **may no longer be compatible** with the provided CloudFormation template.
167+
Compatibility can in some cases be restored by making corresponding modifications to the CloudFormation template.
168+
169+
## Help Make MATLAB Even Better
170+
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.
171+
To opt out of this service, remove the [40_Set-DDUX.ps1](https://github.com/mathworks-ref-arch/matlab-on-aws-win/tree/master/packer/v1/startup/40_Set-DDUX.ps1)
172+
script under the `startup` folder.
173+
174+
To learn more, see the documentation: [Help Make MATLAB Even Better - Frequently Asked Questions](https://www.mathworks.com/support/faq/user_experience_information_faq.html).
175+
176+
## Technical Support
177+
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).
178+
179+
----
180+
181+
Copyright 2024 The MathWorks, Inc.
182+
183+
----

0 commit comments

Comments
 (0)