mirror of
https://github.com/actions/runner-images.git
synced 2025-12-10 19:16:48 +00:00
Validate and update some documentation (#8959)
This commit is contained in:
Vasilii Polikarpov
committed by
GitHub
GitHub
parent
3a0da34c48
commit
5bd6a16cab
@@ -6,17 +6,17 @@
|
||||
|
||||
Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
|
||||
|
||||
Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [MIT](LICENSE.md).
|
||||
Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [MIT](LICENSE.md) license.
|
||||
|
||||
Please note that this project is released with a [Contributor Code of Conduct][code-of-conduct]. By participating in this project you agree to abide by its terms.
|
||||
Please note that this project is released with a [Contributor Code of Conduct][code-of-conduct]. By participating in this project, you agree to abide by its terms.
|
||||
|
||||
## Submitting a pull request
|
||||
|
||||
1. [Fork][fork] and clone the repository
|
||||
1. Create a new branch: `git checkout -b my-branch-name`
|
||||
1. Make your changes, ensure that they include steps to install, validate post-install and update software report (please see [How to add new tool](CONTRIBUTING.md#how-to-add-new-tool) for details).
|
||||
1. Test your changes by [creating image and deploying a VM](docs/create-image-and-azure-resources.md).
|
||||
1. Push to your fork and [submit a pull request][pr]
|
||||
1. [Fork][fork] and clone the repository.
|
||||
1. Create a new branch: `git checkout -b my-branch-name`.
|
||||
1. Make your changes, ensuring that they include steps to install, validate post-install, and update the software report (please see [How to add a new tool](CONTRIBUTING.md#how-to-add-a-new-tool) for details).
|
||||
1. Test your changes by [creating an image and deploying a VM](docs/create-image-and-azure-resources.md).
|
||||
1. Push to your fork and [submit a pull request][pr].
|
||||
|
||||
Here are a few things you can do that will increase the likelihood of your pull request being accepted:
|
||||
|
||||
@@ -25,18 +25,18 @@ Here are a few things you can do that will increase the likelihood of your pull
|
||||
- Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
|
||||
- Write [good commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
|
||||
- For new tools:
|
||||
- Make sure that the tool satisfies [Software Guidelines](README.md#software-guidelines).
|
||||
- Create an issue and get an approval from us to add this tool to the image before creating the pull request.
|
||||
- Make sure that the tool satisfies the [Software Guidelines](README.md#software-guidelines).
|
||||
- Create an issue and get approval from us to add this tool to the image before creating the pull request.
|
||||
|
||||
## How to add new tool
|
||||
## How to add a new tool
|
||||
|
||||
### General rules
|
||||
|
||||
- For every new tool add validation scripts and update software report script to make sure that it is included to documentation
|
||||
- If the tool is available in other platforms (macOS, Windows, Linux), make sure you include it in as many as possible.
|
||||
- If installing a few versions of the tool, consider putting the list of versions in the corresponding `toolset.json` file. It will help other customers to configure their builds flexibly. See [toolset-windows-2019.json](images/windows/toolsets/toolset-2019.json) as example.
|
||||
- Use consistent naming across all files
|
||||
- Validation scripts should be simple and shouldn't change image content
|
||||
- For every new tool, add validation scripts and update the software report script to ensure that it is included in the documentation.
|
||||
- If the tool is available on multiple platforms (macOS, Windows, Linux), make sure you include it on as many as possible.
|
||||
- If installing multiple versions of the tool, consider putting the list of versions in the corresponding `toolset.json` file. This will help other customers configure their builds flexibly. See [toolset-windows-2019.json](images/windows/toolsets/toolset-2019.json) as an example.
|
||||
- Use consistent naming across all files.
|
||||
- Validation scripts should be simple and shouldn't change the image content.
|
||||
|
||||
### Windows
|
||||
|
||||
@@ -44,21 +44,21 @@ Here are a few things you can do that will increase the likelihood of your pull
|
||||
There are a bunch of helper functions that could simplify your code: `Install-ChocoPackage`, `Install-Binary`, `Install-VSIXFromFile`, `Install-VSIXFromUrl`, `Invoke-DownloadWithRetry`, `Test-IsWin19`, `Test-IsWin22` (find the full list of helpers in [ImageHelpers.psm1](images/windows/scripts/helpers/ImageHelpers.psm1)).
|
||||
- Add a script that will validate the tool installation and put the script in the `scripts/tests` folder.
|
||||
We use [Pester v5](https://github.com/pester/pester) for validation scripts. If the tests for the tool are complex enough, create a separate `*.Tests.ps1`. Otherwise, use `Tools.Tests.ps1` for simple tests.
|
||||
Add `Invoke-PesterTests -TestFile <testFileName> [-TestName <describeName>]` at the end of the installation script to make sure that your tests will be run.
|
||||
Add `Invoke-PesterTests -TestFile <testFileName> [-TestName <describeName>]` at the end of the installation script to ensure that your tests will be run.
|
||||
- Add changes to the software report generator `images/windows/scripts/docs-gen/Generate-SoftwareReport.ps1`. The software report generator is used to generate an image's README file, e.g. [Windows2019-Readme.md](images/windows/Windows2019-Readme.md) and uses [MarkdownPS](https://github.com/Sarafian/MarkdownPS).
|
||||
|
||||
### Ubuntu
|
||||
|
||||
- Add script that will install and validate the tool and put the script in the `scripts/build` folder.
|
||||
- Add a script that will install and validate the tool and put the script in the `scripts/build` folder.
|
||||
Use existing scripts such as [github-cli.sh](images/ubuntu/scripts/build/github-cli.sh) as a starting point.
|
||||
- Use [helpers](images/ubuntu/scripts/helpers/install.sh) to simplify installation process.
|
||||
- Validation part should `exit 1` if any issue with installation.
|
||||
- Use [helpers](images/ubuntu/scripts/helpers/install.sh) to simplify the installation process.
|
||||
- The validation part should `exit 1` if there is any issue with the installation.
|
||||
- Add changes to the software report generator `images/ubuntu/scripts/docs-gen/Generate-SoftwareReport.ps1`. The software report generator is used to generate an image's README file, e.g. [Ubuntu2004-Readme.md](images/ubuntu/Ubuntu2004-README.md) and it uses [MarkdownPS](https://github.com/Sarafian/MarkdownPS).
|
||||
|
||||
### macOS
|
||||
|
||||
macOS source lives in this repository and available for everyone. However, macOS image-generation CI doesn't support external contributions yet so we are not able to accept pull-requests for now.
|
||||
We are in the process of preparing macOS CI to accept contributions. Until then, we appreciate your patience and ask you continue to make tool requests by filing issues.
|
||||
The macOS source lives in this repository and is available for everyone. However, the macOS image-generation CI doesn't support external contributions yet, so we are not able to accept pull requests for now.
|
||||
We are in the process of preparing the macOS CI to accept contributions. Until then, we appreciate your patience and ask that you continue to make tool requests by filing issues.
|
||||
|
||||
## Resources
|
||||
|
||||
|
||||
@@ -2,24 +2,24 @@
|
||||
|
||||
The runner-images project uses [Packer](https://www.packer.io/) to generate disk images for Windows 2019/2022 and Ubuntu 20.04/22.04.
|
||||
|
||||
Each image is configured by a JSON or HCL2 Packer template that specifies where to build the image (Azure in this case)
|
||||
Each image is configured by a JSON or HCL2 Packer template that specifies where to build the image (Azure, in this case),
|
||||
and what steps to run to install software and prepare the disk.
|
||||
|
||||
The Packer process initializes a connection to Azure subscription using Azure CLI and creates temporary resources
|
||||
required for the build process: resource group, network interfaces and virtual machine from the "clean" image specified in the template.
|
||||
The Packer process initializes a connection to the Azure subscription using Azure CLI and creates temporary resources
|
||||
required for the build process: a resource group, network interfaces and a virtual machine from the "clean" image specified in the template.
|
||||
|
||||
If the VM deployment succeeds, Packer connects it using ssh or WinRM and begins executing installation steps from the template one-by-one.
|
||||
If any step fails, image generation is aborted and the temporary VM is terminated.
|
||||
Packer also attempts to cleanup all the temporary resources it created (unless otherwise configured).
|
||||
If the VM deployment succeeds, Packer connects to it using SSH or WinRM and begins executing installation steps from the template one-by-one.
|
||||
If any step fails, image generation is aborted, and the temporary VM is terminated.
|
||||
Packer also attempts to clean up all the temporary resources it created (unless otherwise configured).
|
||||
|
||||
After successful completion of all installation steps Packer creates managed image from the temporary VM's disk and deletes the VM.
|
||||
After successful completion of all installation steps, Packer creates a managed image from the temporary VM's disk and deletes the VM.
|
||||
|
||||
- [Build agent preparation](#build-agent-preparation)
|
||||
- [Build Agent Preparation](#build-agent-preparation)
|
||||
- [Manual image generation](#manual-image-generation)
|
||||
- [Manual image generation customization](#manual-image-generation-customization)
|
||||
- [Network security](#network-security)
|
||||
- [Azure subscription authentication](#azure-subscription-authentication)
|
||||
- [Generated machine deployment](#generated-machine-deployment)
|
||||
- [Manual Image Generation Customization](#manual-image-generation-customization)
|
||||
- [Network Security](#network-security)
|
||||
- [Azure Subscription Authentication](#azure-subscription-authentication)
|
||||
- [Generated Machine Deployment](#generated-machine-deployment)
|
||||
- [Automated image generation](#automated-image-generation)
|
||||
- [Required variables](#required-variables)
|
||||
- [Optional variables](#optional-variables)
|
||||
@@ -27,15 +27,15 @@ After successful completion of all installation steps Packer creates managed ima
|
||||
- [Toolset](#toolset)
|
||||
- [Post-generation scripts](#post-generation-scripts)
|
||||
- [Running scripts](#running-scripts)
|
||||
- [Script details: Ubuntu](#script-details-ubuntu)
|
||||
- [Script details: Windows](#script-details-windows)
|
||||
- [Script Details: Ubuntu](#script-details-ubuntu)
|
||||
- [Script Details: Windows](#script-details-windows)
|
||||
|
||||
## Build agent preparation
|
||||
## Build Agent Preparation
|
||||
|
||||
Build agent is a machine where Packer process will be started.
|
||||
You can use any physical or virtual machine running OS Windows or Linux.
|
||||
Of course you may also use [Azure VM](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/quick-create-cli).
|
||||
In any case you will need these software installed:
|
||||
The build agent is a machine where the Packer process will be started.
|
||||
You can use any physical or virtual machine running Windows or Linux OS.
|
||||
Of course, you may also use an [Azure VM](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/quick-create-cli).
|
||||
In any case, you will need these software installed:
|
||||
|
||||
- Packer 1.8.2 or higher.
|
||||
|
||||
@@ -60,11 +60,12 @@ In any case you will need these software installed:
|
||||
In Windows you already have it.
|
||||
|
||||
For Linux follow instructions [here](https://learn.microsoft.com/en-us/windows-server/administration/linux-package-repository-for-microsoft-software)
|
||||
to add Microsoft's Linux Software Repository and then install package `powershell`.
|
||||
to add Microsoft's Linux Software Repository and then install the `powershell` package.
|
||||
|
||||
- Azure CLI.
|
||||
|
||||
Follow instructions [here](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli).
|
||||
Or if you use Windows you may run this command in Powershell instead:
|
||||
Follow the instructions [here](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli).
|
||||
Or if you use Windows, you may run this command in Powershell instead:
|
||||
|
||||
```powershell
|
||||
Invoke-WebRequest -Uri https://aka.ms/installazurecliwindows -OutFile .\AzureCLI.msi
|
||||
@@ -73,72 +74,72 @@ In any case you will need these software installed:
|
||||
|
||||
## Manual image generation
|
||||
|
||||
This repo bundles script that helps generating images in Azure.
|
||||
All you need are Azure subscription and build agent configured as described above.
|
||||
We suggest starting with building UbuntuMinimal image because it includes only basic software and build in less than 30 minutes.
|
||||
This repository includes a script that assists in generating images in Azure.
|
||||
All you need is an Azure subscription and a build agent configured as described above.
|
||||
We suggest starting with building the UbuntuMinimal image because it includes only basic software and builds in less than 30 minutes.
|
||||
|
||||
All the commands below should be executed in Powershell.
|
||||
All the commands below should be executed in PowerShell.
|
||||
|
||||
First clone runner-images repository and set current directory to it:
|
||||
First, clone the runner-images repository and set the current directory to it:
|
||||
|
||||
```powershell
|
||||
git clone https://github.com/actions/runner-images.git
|
||||
Set-Location runner-images
|
||||
```
|
||||
|
||||
Then import [GenerateResourcesAndImage](../helpers/GenerateResourcesAndImage.ps1) script from `helpers` subdirectory:
|
||||
Then, import the [GenerateResourcesAndImage](../helpers/GenerateResourcesAndImage.ps1) script from the `helpers` subdirectory:
|
||||
|
||||
```powershell
|
||||
Import-Module .\helpers\GenerateResourcesAndImage.ps1
|
||||
```
|
||||
|
||||
Finally, run `GenerateResourcesAndImage` function setting mandatory arguments: image type and where to create resources:
|
||||
Finally, run the `GenerateResourcesAndImage` function, setting the mandatory arguments: image type and where to build and store the resulting managed image:
|
||||
|
||||
- `SubscriptionId` - your Azure Subscription ID
|
||||
- `ResourceGroupName` - name of the resource group that will be created within your subscription (e.g. "imagegen-test")
|
||||
- `AzureLocation` - location where resources will be created (e.g. "East US")
|
||||
- `ImageType` - what image to build (we suggest choosing "UbuntuMinimal" here, other valid options are "Windows2019", "Windows2022", "Ubuntu2004", "Ubuntu2204")
|
||||
- `SubscriptionId` - your Azure Subscription ID;
|
||||
- `ResourceGroupName` - the name of the resource group that will be created within your subscription (e.g., "imagegen-test");
|
||||
- `AzureLocation` - the location where resources will be created (e.g., "East US");
|
||||
- `ImageType` - the type of image to build (we suggest choosing "UbuntuMinimal" here; other valid options are "Windows2019", "Windows2022", "Ubuntu2004", "Ubuntu2204").
|
||||
|
||||
This function automatically creates all required Azure resources and kicks off packer image generation for the selected image type.
|
||||
This function automatically creates all required Azure resources and initiates the Packer image generation for the selected image type.
|
||||
|
||||
When image is ready you may proceed to [deployment](#generated-machine-deployment)
|
||||
When the image is ready, you may proceed to [deployment](#generated-machine-deployment).
|
||||
|
||||
## Manual image generation customization
|
||||
## Manual Image Generation Customization
|
||||
|
||||
Function `GenerateResourcesAndImage` accepts a bunch of arguments that may help you generating image in your specific environment.
|
||||
The `GenerateResourcesAndImage` function accepts a number of arguments that may assist you in generating an image in your specific environment.
|
||||
|
||||
For example, you may want that all the resources involved in image generation process are tagged.
|
||||
In this case pass a HashTable of tags as a value for `Tags` parameter.
|
||||
For example, you may want all the resources involved in the image generation process to be tagged.
|
||||
In this case, pass a HashTable of tags as a value for the `Tags` parameter.
|
||||
|
||||
If you don't want function to authenticate interactively, you should create Service Principal and invoke the function with parameters `AzureClientId`, `AzureClientSecret` and `AzureTenantId`.
|
||||
You can find more details [in corresponding section below](#azure-subscription-authentication).
|
||||
If you don't want the function to authenticate interactively, you should create a Service Principal and invoke the function with the parameters `AzureClientId`, `AzureClientSecret` and `AzureTenantId`.
|
||||
You can find more details in the [corresponding section below](#azure-subscription-authentication).
|
||||
|
||||
Use `get-help GenerateResourcesAndImage -Detailed` for the complete list of parameters available.
|
||||
Use `get-help GenerateResourcesAndImage -Detailed` for the complete list of available parameters.
|
||||
|
||||
### Network security
|
||||
### Network Security
|
||||
|
||||
To connect to a temporary virtual machine Packer uses WinRM or SSH.
|
||||
To connect to a temporary virtual machine, Packer uses WinRM or SSH.
|
||||
|
||||
If your build agent is located outside of the Azure subscription where temporary VM is created, the public network interface and public IP address is used.
|
||||
Make sure that firewalls are configured properly and WinRM (tcp port 5986) and ssh (tcp port 22) connections are allowed both outgoing for build agent and incoming for temporary VM.
|
||||
Also if you don't want temporary VM to be accessible from everywhere, set `RestrictToAgentIpAddress` parameter value to `$true`
|
||||
to setup firewall rules allowing access only from your build agent public IP address.
|
||||
If your build agent is located outside of the Azure subscription where the temporary VM is created, a public network interface and public IP address are used.
|
||||
Make sure that firewalls are configured properly and that WinRM (TCP port 5986) and SSH (TCP port 22) connections are allowed both outgoing for the build agent and incoming for the temporary VM.
|
||||
Also, if you don't want the temporary VM to be accessible from everywhere, set the `RestrictToAgentIpAddress` parameter value to `$true`
|
||||
to set up firewall rules allowing access only from your build agent's public IP address.
|
||||
|
||||
If your build agent and temporary VM are in the same subscription you can configure Packer to connect using private virtual network.
|
||||
To achieve that set proper values for environment variables `VNET_RESOURCE_GROUP`, `VNET_NAME` and `VNET_SUBNET`.
|
||||
If your build agent and temporary VM are in the same subscription, you can configure Packer to connect using a private virtual network.
|
||||
To achieve this, set proper values for the environment variables `VNET_RESOURCE_GROUP`, `VNET_NAME` and `VNET_SUBNET`.
|
||||
|
||||
### Azure subscription authentication
|
||||
### Azure Subscription Authentication
|
||||
|
||||
Packer uses Service Principal to authenticate in Azure infrastructure.
|
||||
For more information about Service Principals refer to
|
||||
Packer uses a Service Principal to authenticate in Azure infrastructure.
|
||||
For more information about Service Principals, refer to the
|
||||
[Azure documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal).
|
||||
|
||||
Function `GenerateResourcesAndImage` is able to create Service Principle to be used by Packer.
|
||||
It uses Connect-AzAccount cmdlet that invokes interactive authentication process by default.
|
||||
If you don't want to use interactive authentication you should create Service Principal with full read-write permissions for selected Azure subscription on your own
|
||||
and provide proper values for parameters `AzureClientId`, `AzureClientSecret` and `AzureTenantId`.
|
||||
The `GenerateResourcesAndImage` function is able to create a Service Principal to be used by Packer.
|
||||
It uses the Connect-AzAccount cmdlet that invokes an interactive authentication process by default.
|
||||
If you don't want to use interactive authentication, you should create a Service Principal with full read-write permissions for the selected Azure subscription on your own
|
||||
and provide proper values for the parameters `AzureClientId`, `AzureClientSecret` and `AzureTenantId`.
|
||||
|
||||
Here is an example of how to create Service Principle using Az Powershell module:
|
||||
Here is an example of how to create a Service Principal using the Az PowerShell module:
|
||||
|
||||
```powershell
|
||||
$credentials = [Microsoft.Azure.PowerShell.Cmdlets.Resources.MSGraph.Models.ApiV10.MicrosoftGraphPasswordCredential]@{
|
||||
@@ -160,9 +161,9 @@ Start-Sleep -Seconds 30
|
||||
}
|
||||
```
|
||||
|
||||
## Generated machine deployment
|
||||
## Generated Machine Deployment
|
||||
|
||||
After the successful image generation, Virtual Machine can be created from the generated image using [CreateAzureVMFromPackerTemplate](../helpers/CreateAzureVMFromPackerTemplate.ps1) script.
|
||||
After successful image generation, a Virtual Machine can be created from the generated image using the [CreateAzureVMFromPackerTemplate](../helpers/CreateAzureVMFromPackerTemplate.ps1) script.
|
||||
|
||||
```powershell
|
||||
Import-Module .\helpers\CreateAzureVMFromPackerTemplate.ps1
|
||||
@@ -172,29 +173,29 @@ CreateAzureVMFromPackerTemplate -SubscriptionId {YourSubscriptionId} -ResourceGr
|
||||
|
||||
Where:
|
||||
|
||||
- `SubscriptionId` - The Azure subscription Id where resources will be created.
|
||||
- `ResourceGroupName` - The Azure resource group name where the Azure virtual machine will be created.
|
||||
- `ManagedImageName` - The name of the managed image to be used for the virtual machine creation.
|
||||
- `VirtualMachineName` - The name of the virtual machine to be generated.
|
||||
- `AdminUserName` - The administrator username for the virtual machine to be created.
|
||||
- `AdminPassword` - The administrator password for the virtual machine to be created.
|
||||
- `AzureLocation` - The location where the Azure virtual machine will be provisioned. Example: "eastus"
|
||||
- `SubscriptionId` - the Azure subscription ID where resources will be created;
|
||||
- `ResourceGroupName` - the Azure resource group name where the Azure virtual machine will be created;
|
||||
- `ManagedImageName` - the name of the managed image to be used for the virtual machine creation;
|
||||
- `VirtualMachineName` - the name of the virtual machine to be generated;
|
||||
- `AdminUserName` - the administrator username for the virtual machine to be created;
|
||||
- `AdminPassword` - the administrator password for the virtual machine to be created;
|
||||
- `AzureLocation` - the location where the Azure virtual machine will be provisioned (e.g., "eastus").
|
||||
|
||||
The function creates an Azure VM and generates network resources in Azure to make the VM accessible.
|
||||
This function creates an Azure VM and generates network resources in Azure to make the VM accessible.
|
||||
|
||||
## Automated image generation
|
||||
|
||||
If you want to generate images automatically (e.g. as a part of CI/CD pipeline)
|
||||
you can use Packer directly. To do that you will need:
|
||||
If you want to generate images automatically (e.g., as a part of a CI/CD pipeline),
|
||||
you can use Packer directly. To do this, you will need:
|
||||
|
||||
- A build agent configured as described in
|
||||
[Build agent preparation](#build-agent-preparation) section.
|
||||
- Azure subscription and Service Principal configured as described in
|
||||
[Azure subscription authentication](#azure-subscription-authentication) section.
|
||||
- Resource group created in your Azure subscription where managed image will be stored.
|
||||
- String to be used as password for the user used to install software (Windows only).
|
||||
- a build agent configured as described in the
|
||||
[Build agent preparation](#build-agent-preparation) section;
|
||||
- an Azure subscription and Service Principal configured as described in the
|
||||
[Azure subscription authentication](#azure-subscription-authentication) section;
|
||||
- a resource group created in your Azure subscription where the managed image will be stored;
|
||||
- a string to be used as a password for the user used to install software (Windows only).
|
||||
|
||||
Then you can invoke Packer in you CI/CD pipeline using the following command:
|
||||
Then, you can invoke Packer in your CI/CD pipeline using the following command:
|
||||
|
||||
```powershell
|
||||
packer build -var "subscription_id=$SubscriptionId" `
|
||||
@@ -210,54 +211,54 @@ packer build -var "subscription_id=$SubscriptionId" `
|
||||
|
||||
Where:
|
||||
|
||||
- `SubscriptionId` - your Azure Subscription ID
|
||||
- `ClientId` and `ClientSecret` - Service Principal credentials
|
||||
- `TenantId` - Azure Tenant ID
|
||||
- `InstallPassword` - password for the user used to install software (Windows only)
|
||||
- `Location` - location where resources will be created (e.g. "East US")
|
||||
- `ImageName` and `ImageResourceGroupName` - name of the resource group where managed image will be stored
|
||||
- `TemplatePath` - path to the Packer template file (e.g. "images/windows/templates/windows-2022.json")
|
||||
- `SubscriptionId` - your Azure Subscription ID;
|
||||
- `ClientId` and `ClientSecret` - Service Principal credentials;
|
||||
- `TenantId` - Azure Tenant ID;
|
||||
- `InstallPassword` - password for the user used to install software (Windows only);
|
||||
- `Location` - location where resources will be created (e.g., "East US");
|
||||
- `ImageName` and `ImageResourceGroupName` - name of the resource group where the managed image will be stored;
|
||||
- `TemplatePath` - path to the Packer template file (e.g., "images/windows/templates/windows-2022.json").
|
||||
|
||||
### Required variables
|
||||
|
||||
The following variables are required to be passed to Packer process:
|
||||
The following variables are required to be passed to the Packer process:
|
||||
|
||||
| Template var | Env var | Description
|
||||
| ------------ | ------- | -----------
|
||||
| `subscription_id` | `ARM_SUBSCRIPTION_ID` | Subscription under which the build will be performed.
|
||||
| `subscription_id` | `ARM_SUBSCRIPTION_ID` | The subscription under which the build will be performed.
|
||||
| `client_id` | `ARM_CLIENT_ID` | The Active Directory service principal associated with your builder.
|
||||
| `client_secret` | `ARM_CLIENT_SECRET` | The password or secret for your service principal; may be omitted if `client_cert_path` is set.
|
||||
| `client_cert_path` | `ARM_CLIENT_CERT_PATH` | The location of a PEM file containing a certificate and private key for service principal; may be omitted if `client_secret` is set.
|
||||
| `location` | `ARM_RESOURCE_LOCATION` | Azure datacenter in which your VM will build.
|
||||
| `managed_image_resource_group_name` | `ARM_RESOURCE_GROUP` | Resource group under which the final artifact will be stored.
|
||||
| `client_cert_path` | `ARM_CLIENT_CERT_PATH` | The location of a PEM file containing a certificate and private key for the service principal; may be omitted if `client_secret` is set.
|
||||
| `location` | `ARM_RESOURCE_LOCATION` | The Azure datacenter in which your VM will be built.
|
||||
| `managed_image_resource_group_name` | `ARM_RESOURCE_GROUP` | The resource group under which the final artifact will be stored.
|
||||
|
||||
### Optional variables
|
||||
|
||||
The following variables are optional:
|
||||
|
||||
- `managed_image_name` - Name of the managed image to create. If not specified, "Runner-Image-{{ImageType}}" will be used.
|
||||
- `build_resource_group_name` - Specify an existing resource group to run the build in it. By default, a temporary resource group will be created and destroyed as part of the build. If you do not have permission to do so, use build_resource_group_name to specify an existing resource group to run the build in it.
|
||||
- `object_id` - The object ID for the AAD SP. Will be derived from the oAuth token if empty.
|
||||
- `tenant_id` - The Active Directory tenant identifier with which your `client_id` and `subscription_id` are associated. If not specified, `tenant_id` will be looked up using `subscription_id`.
|
||||
- `temp_resource_group_name` - Name assigned to the temporary resource group created during the build. If this value is not set, a random value will be assigned. This resource group is deleted at the end of the build.
|
||||
- `private_virtual_network_with_public_ip` - This value allows you to set a `virtual_network_name` and obtain a public IP. If this value is not set and `virtual_network_name` is defined Packer is only allowed to be executed from a host on the same subnet / virtual network.
|
||||
- `virtual_network_name` - Use a pre-existing virtual network for the VM. This option enables private communication with the VM, no public IP address is used or provisioned (unless you set `private_virtual_network_with_public_ip`).
|
||||
- `virtual_network_resource_group_name` - If `virtual_network_name` is set, this value may also be set. If `virtual_network_name` is set, and this value is not set the builder attempts to determine the resource group containing the virtual network. If the resource group cannot be found, or it cannot be disambiguated, this value should be set.
|
||||
- `virtual_network_subnet_name` - If `virtual_network_name` is set, this value may also be set. If `virtual_network_name` is set, and this value is not set the builder attempts to determine the subnet to use with the virtual network. If the subnet cannot be found, or it cannot be disambiguated, this value should be set.
|
||||
- `managed_image_name` - the name of the managed image to create. If not specified, "Runner-Image-{{ImageType}}" will be used;
|
||||
- `build_resource_group_name` - specify an existing resource group to run the build in; by default, a temporary resource group will be created and destroyed as part of the build; if you do not have permission to do so, use `build_resource_group_name` to specify an existing resource group to run the build in;
|
||||
- `object_id` - the object ID for the AAD SP; will be derived from the oAuth token if empty;
|
||||
- `tenant_id` - the Active Directory tenant identifier with which your `client_id` and `subscription_id` are associated; if not specified, `tenant_id` will be looked up using `subscription_id`;
|
||||
- `temp_resource_group_name` - the name assigned to the temporary resource group created during the build; if this value is not set, a random value will be assigned; this resource group is deleted at the end of the build;
|
||||
- `private_virtual_network_with_public_ip` - this value allows you to set a `virtual_network_name` and obtain a public IP; if this value is not set and `virtual_network_name` is defined, Packer is only allowed to be executed from a host on the same subnet / virtual network;
|
||||
- `virtual_network_name` - use a pre-existing virtual network for the VM; this option enables private communication with the VM, no public IP address is used or provisioned (unless you set `private_virtual_network_with_public_ip`);
|
||||
- `virtual_network_resource_group_name` - if `virtual_network_name` is set, this value may also be set; if `virtual_network_name` is set, and this value is not set, the builder attempts to determine the resource group containing the virtual network; if the resource group cannot be found, or it cannot be disambiguated, this value should be set;
|
||||
- `virtual_network_subnet_name` - if `virtual_network_name` is set, this value may also be set; if `virtual_network_name` is set, and this value is not set, the builder attempts to determine the subnet to use with the virtual network; if the subnet cannot be found, or it cannot be disambiguated, this value should be set.
|
||||
|
||||
## Builder variables
|
||||
|
||||
The `builders` section contains variables for the `azure-arm` builder used in the project. Most of the builder variables are inherited from the `user variables` section, however, the variables can be overwritten to adjust image-generation performance.
|
||||
|
||||
- `vm_size` - Size of the VM used for building. This can be changed when you deploy a VM from your image.
|
||||
- `image_os` - Type of OS that will be deployed as a temporary VM.
|
||||
- `image_version` - Specify version of an OS to boot from.
|
||||
- `vm_size` - the size of the VM used for building; this can be changed when you deploy a VM from your image;
|
||||
- `image_os` - the type of OS that will be deployed as a temporary VM;
|
||||
- `image_version` - specify the version of an OS to boot from.
|
||||
|
||||
**Detailed Azure builders documentation can be found in [packer documentation](https://www.packer.io/docs/builders/azure).**
|
||||
**Detailed Azure builders documentation can be found in the [packer documentation](https://www.packer.io/docs/builders/azure).**
|
||||
|
||||
## Toolset
|
||||
|
||||
Configuration for some installed software is located in `toolset.json` files. These files define the list of Ruby, Python, Go versions, the list of PowerShell modules and VS components that will be installed to image. They can be changed if these tools are not required to reduce image generation time or image size.
|
||||
The configuration for some installed software is located in `toolset.json` files. These files define the list of Ruby, Python, Go versions, the list of PowerShell modules and VS components that will be installed on the image. They can be changed if these tools are not required, to reduce image generation time or image size.
|
||||
|
||||
Generated tool versions and details can be found in related projects:
|
||||
|
||||
@@ -267,9 +268,9 @@ Generated tool versions and details can be found in related projects:
|
||||
|
||||
## Post-generation scripts
|
||||
|
||||
> :warning: These scripts are intended to run on a VM deployed in Azure
|
||||
> :warning: These scripts are intended to be run on a VM deployed in Azure
|
||||
|
||||
The user, created during the image generation, does not exist in the result image hence some configuration files related to the user's home directory need to be changed as well as the file permissions for some directories. Scripts for that are located in the `post-gen` folder in the repository:
|
||||
The user, created during the image generation, does not exist in the resulting image. Hence, some configuration files related to the user's home directory need to be changed, as well as the file permissions for some directories. Scripts for that are located in the `post-gen` folder in the repository:
|
||||
|
||||
- Windows: <https://github.com/actions/runner-images/tree/main/images/windows/assets/post-gen>
|
||||
- Linux: <https://github.com/actions/runner-images/tree/main/images/ubuntu/assets/post-gen>
|
||||
@@ -295,16 +296,16 @@ The scripts are copied to the image during the generation process to the followi
|
||||
Get-ChildItem C:\post-generation -Filter *.ps1 | ForEach-Object { & $_.FullName }
|
||||
```
|
||||
|
||||
### Script details: Ubuntu
|
||||
### Script Details: Ubuntu
|
||||
|
||||
- **cleanup-logs.sh** - removes all build process logs from the machine
|
||||
- **environment-variables.sh** - replaces `$HOME` with the default user's home directory for environmental variables related to the default user home directory
|
||||
- **homebrew-permissions.sh** - Resets homebrew repository directory by running `git reset --hard` to make the working tree clean after chmoding /home and changes the repository directory owner to the current user
|
||||
- **rust-permissions.sh** - fixes permissions for the Rust folder. Detailed issue explanation is provided in [runner-images/issues/572](https://github.com/actions/runner-images/issues/572).
|
||||
- **cleanup-logs.sh** - removes all build process logs from the machine;
|
||||
- **environment-variables.sh** - replaces `$HOME` with the default user's home directory for environment variables related to the default user home directory;
|
||||
- **homebrew-permissions.sh** - resets the Homebrew repository directory by running `git reset --hard` to make the working tree clean after changing permissions in /home and changes the repository directory owner to the current user;
|
||||
- **rust-permissions.sh** - fixes permissions for the Rust folder; a detailed issue explanation is provided in [runner-images/issues/572](https://github.com/actions/runner-images/issues/572).
|
||||
|
||||
### Script details: Windows
|
||||
### Script Details: Windows
|
||||
|
||||
- **GenerateIISExpressCertificate.ps1** - generates and imports a certificate to run applications with IIS Express through HTTPS
|
||||
- **InternetExplorerConfiguration** - turns off the Internet Explorer Enhanced Security feature
|
||||
- **Msys2FirstLaunch.ps1** - initializes bash user profile in MSYS2
|
||||
- **VSConfiguration.ps1** - performs initial Visual Studio configuration
|
||||
- **GenerateIISExpressCertificate.ps1** - generates and imports a certificate to run applications with IIS Express through HTTPS;
|
||||
- **InternetExplorerConfiguration.ps1** - turns off the Internet Explorer Enhanced Security feature;
|
||||
- **Msys2FirstLaunch.ps1** - initializes the bash user profile in MSYS2;
|
||||
- **VSConfiguration.ps1** - performs initial Visual Studio configuration.
|
||||
|
||||
Reference in New Issue
Block a user