From 71a63da5ac9fe0be6d2bb1e9c68ed9f4561fc14a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 20 May 2025 05:15:13 +0000 Subject: [PATCH 1/4] Initial plan for issue From 082466693758a3a587ea4afa4add2e6d4e9c4c5f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 20 May 2025 05:27:16 +0000 Subject: [PATCH 2/4] Update README.md and build-in-container files Co-authored-by: christopherco <35273088+christopherco@users.noreply.github.com> --- README.md | 62 ++++++++++++++--------------- build-in-container/README.md | 46 ++++++++++----------- build-in-container/scripts/setup.sh | 14 +++---- 3 files changed, 61 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index cd4cd53..87bea46 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,35 @@ -# Introduction - -The [CBL-Mariner](https://github.com/microsoft/CBL-Mariner) repository provides detailed instructions for building CBL-Mariner from end-to-end. While it is possible to clone CBL-Mariner and build packages or images from that environment, for most users, it is _not the recommended approach_. Usually it is best to work in a smaller, problem focused environment where you can quickly build just what you need, and rely on the fact that the curated CBL-Mariner packages are already available in the cloud. In this way, you can customize an image with your preferred disk layout or adding supplemental packages that CBL-Mariner may not provide. If you are building a product based on CBL-Mariner, you may want your own repository with just the minimal set of packages for your business needs. This repo, the CBL-MarinerTutorials repo, provides a basic template for getting started. From here you can create a CBL-Mariner based product (aka a Derivative Image) or you may generate quick experimental or debug builds to try out new ideas. - -When you build an ISO, VHD or VHDX image from this repository, the resulting image will contain additional content unavailable in the CBL-Mariner repo. The CBL-MarinerTutorials repository demonstrates how you can augment CBL-Mariner without forking the CBL-Mariner repository. This repository contains the SPEC file and source for building a simple "Hello World" application. This repository also includes a simple "os-subrelease" package that allows you to add identifying information about your derivative to an /etc/os-subrelease file. - -Follow this decision tree to ensure you are using the correct repository for your use case: - -```mermaid ---- -title: Repo decision tree ---- -flowchart TD - id1{{Do you want to experiment with Mariner or contribute to Mariner?}} - - id2A[Do you want to build locally with Mariner?] - id2B[Do you want to add an unsupported package? \n either a package Mariner has never supported \nor an updated major/minor version of a package Mariner supports] - id2C[Do you want to use Mariner for your project? \n ex. bare metal, IoT, embedded devices, etc.] - id2D[Use the CBL-MarinerTutorials repo] - id1 -->|experiment| id2A - id2A -.-|or| id2B - id2B -.-|or| id2C - id2C -->|yes to any of the above| id2D - - - id3[Do you want to fix an issue in Mariner?] - id3B[Do you want to add a common package? \n either a package supported by another major distro \nor a package used widely across popular open-source projects] - id3C[Do you want to modify a supported Mariner package?] - id3D[Do you want to rebuild Mariner from end-to-end?] - id3E[Use the CBL-Mariner repo] - id1 --> |contribute|id3 +# Introduction + +The [Azure Linux](https://github.com/microsoft/azurelinux) repository provides detailed instructions for building Azure Linux from end-to-end. While it is possible to clone Azure Linux and build packages or images from that environment, for most users, it is _not the recommended approach_. Usually it is best to work in a smaller, problem focused environment where you can quickly build just what you need, and rely on the fact that the curated Azure Linux packages are already available in the cloud. In this way, you can customize an image with your preferred disk layout or adding supplemental packages that Azure Linux may not provide. If you are building a product based on Azure Linux, you may want your own repository with just the minimal set of packages for your business needs. This repo, the azurelinux-tutorials repo, provides a basic template for getting started. From here you can create an Azure Linux based product (aka a Derivative Image) or you may generate quick experimental or debug builds to try out new ideas. + +When you build an ISO, VHD or VHDX image from this repository, the resulting image will contain additional content unavailable in the Azure Linux repo. The azurelinux-tutorials repository demonstrates how you can augment Azure Linux without forking the Azure Linux repository. This repository contains the SPEC file and source for building a simple "Hello World" application. This repository also includes a simple "os-subrelease" package that allows you to add identifying information about your derivative to an /etc/os-subrelease file. + +Follow this decision tree to ensure you are using the correct repository for your use case: + +```mermaid +--- +title: Repo decision tree +--- +flowchart TD + id1{{Do you want to experiment with Azure Linux or contribute to Azure Linux?}} + + id2A[Do you want to build locally with Azure Linux?] + id2B[Do you want to add an unsupported package? \n either a package Azure Linux has never supported \nor an updated major/minor version of a package Azure Linux supports] + id2C[Do you want to use Azure Linux for your project? \n ex. bare metal, IoT, embedded devices, etc.] + id2D[Use the azurelinux-tutorials repo] + id1 -->|experiment| id2A + id2A -.-|or| id2B + id2B -.-|or| id2C + id2C -->|yes to any of the above| id2D + + + id3[Do you want to fix an issue in Azure Linux?] + id3B[Do you want to add a common package? \n either a package supported by another major distro \nor a package used widely across popular open-source projects] + id3C[Do you want to modify a supported Azure Linux package?] + id3D[Do you want to rebuild Azure Linux from end-to-end?] + id3E[Use the Azure Linux repo] + id1 --> |contribute|id3 id3 -.-|or| id3B id3B -.-|or| id3C id3C -.-|or| id3D diff --git a/build-in-container/README.md b/build-in-container/README.md index b08df6a..a32a231 100644 --- a/build-in-container/README.md +++ b/build-in-container/README.md @@ -1,5 +1,5 @@ # Build-in-container -The build-in-container tool provides a developer tool to quickly build Mariner packages. It is easy-to-use, and distribution and platform agnostic. It sets up a build environment in an expedient manner using a container. +The build-in-container tool provides a developer tool to quickly build Azure Linux packages. It is easy-to-use, and distribution and platform agnostic. It sets up a build environment in an expedient manner using a container. Please install docker on your system before using the tool. @@ -8,20 +8,20 @@ The mariner-docker-builder.sh script presents these options 
   -t                        creates container image 

   -b                        creates container, builds specs under [mariner_dir]/SPECS/, & places output under [mariner_dir]/out/ 

-  -i                        creates an interactive Mariner build container 

-  -c                        cleans up Mariner workspace at [mariner_dir], container images and instances 

+  -i                        creates an interactive Azure Linux build container 

+  -c                        cleans up Azure Linux workspace at [mariner_dir], container images and instances 

   --help                    shows help on usage 

 
 Optional arguments 

-  --mariner_dir             directory to use for Mariner artifacts (SPECS, toolkit, ..). Default is the current directory 

+  --mariner_dir             directory to use for Azure Linux artifacts (SPECS, toolkit, ..). Default is the current directory 

   --RPM_repo_file           Path(s) to custom repo file(s) (must end in .repo). Please see [here](./README.md#sample-custom-repo) for sample custom repo file. Provide multiple files with space (" ") as delimiter. Please prefer RPM_repo_file over RPM_container_URL. 

   --RPM_container_URL       URL(s) of Azure blob storage container(s) to install RPMs from. Provide multiple URLs with space (" ") as delimiter 

-  --disable_mariner_repo    disable default setting to use default Mariner package repos on packages.microsoft.com 

+  --disable_mariner_repo    disable default setting to use default Azure Linux package repos on packages.microsoft.com
- 'tool_dir' refers to the directory of the build-in-container tool
-- 'mariner_dir' refers to the directory with Mariner artifacts (SPECS, toolkit, etc.)
-- If mariner_dir is provided, it will be used for all Mariner artifacts like toolkit, SPECS, build, out and logs. Else, current directory will be used.
+- 'mariner_dir' refers to the directory with Azure Linux artifacts (SPECS, toolkit, etc.)
+- If mariner_dir is provided, it will be used for all Azure Linux artifacts like toolkit, SPECS, build, out and logs. Else, current directory will be used.
- Place specs to build under $mariner_dir/SPECS/
- Please find SPEC sample [here](./../SPECS/hello_world_demo/)
- The output from the build will be available under $mariner_dir/out/ (RPMS and SRPMS)
@@ -29,55 +29,55 @@ Optional arguments
``` bash # Setup the container for 1st use -./CBL-MarinerTutorials/build-in-container/mariner-docker-builder.sh -t +./azurelinux-tutorials/build-in-container/mariner-docker-builder.sh -t # Build `SPECS/**/*.spec` automatically -./CBL-MarinerTutorials/build-in-container/mariner-docker-builder.sh -b -ls CBL-MarinerTutorials/build-in-container/out/RPMS/x86_64/ +./azurelinux-tutorials/build-in-container/mariner-docker-builder.sh -b +ls azurelinux-tutorials/build-in-container/out/RPMS/x86_64/ # hello_world_demo-1.0.0-2.cm2.x86_64.rpm hello_world_demo-debuginfo-1.0.0-2.cm2.x86_64.rpm # Invoke the toolkit directly -./CBL-MarinerTutorials/build-in-container/mariner-docker-builder.sh -i +./azurelinux-tutorials/build-in-container/mariner-docker-builder.sh -i # Run the tools manually make build-packages SRPM_PACK_LIST="hello_world_demo" -j$(nproc) # Use optional arguments -## Provide path to Mariner directory. If this option is not used, the current directory is treated as Mariner directory -./CBL-MarinerTutorials/build-in-container/mariner-docker-builder.sh -i --mariner_dir /path/to/CBL-Mariner/ +## Provide path to Azure Linux directory. If this option is not used, the current directory is treated as Azure Linux directory +./azurelinux-tutorials/build-in-container/mariner-docker-builder.sh -i --mariner_dir /path/to/azurelinux/ ## Install RPMs from a custom repo, by providing path to .repo file ## Please ensure that custom repo file ends in '.repo' as per requirements of rpm/yum/tdnf/dnf ## Provide multiple paths with space (" ") as delimiter -./CBL-MarinerTutorials/build-in-container/mariner-docker-builder.sh -i --RPM_repo_file "path/to/custom-repo-file.repo[ path/to/another-custom-repo-file.repo]" +./azurelinux-tutorials/build-in-container/mariner-docker-builder.sh -i --RPM_repo_file "path/to/custom-repo-file.repo[ path/to/another-custom-repo-file.repo]" ## Install RPMs from an Azure blob-storage container storing custom RPMs, by providing URL of the container ## Provide multiple URLs with space (" ") as delimiter -./CBL-MarinerTutorials/build-in-container/mariner-docker-builder.sh -i --RPM_container_URL "https://az-storage-account.blob.core.windows.net/az-container/[ https://az-storage-account.blob.core.windows.net/another-az-container/]" +./azurelinux-tutorials/build-in-container/mariner-docker-builder.sh -i --RPM_container_URL "https://az-storage-account.blob.core.windows.net/az-container/[ https://az-storage-account.blob.core.windows.net/another-az-container/]" -## Disable default setting to use default Mariner package repos on packages.microsoft.com -./CBL-MarinerTutorials/build-in-container/mariner-docker-builder.sh -i --disable_mariner_repo +## Disable default setting to use default Azure Linux package repos on packages.microsoft.com +./azurelinux-tutorials/build-in-container/mariner-docker-builder.sh -i --disable_mariner_repo ``` ## Details on what goes on inside the container: ### Creating container image -'create-container.sh' creates an image that the docker can use to launch the Mariner build container. It downloads a Mariner2.0 container image, and makes suitable modifications to it. The output image is tagged as 'mcr.microsoft.com/mariner-container-build:2.0' +'create-container.sh' creates an image that the docker can use to launch the Azure Linux build container. It downloads an Azure Linux container image, and makes suitable modifications to it. The output image is tagged as 'mcr.microsoft.com/mariner-container-build:2.0' ### Running container in the specified mode 'run-container.sh' starts a docker container using the image produced in Step(1). -In the _build_ mode, it sets up the Mariner build system inside the container, builds all the specs under $mariner_dir/SPECS/ and outputs to $mariner_dir/out/. +In the _build_ mode, it sets up the Azure Linux build system inside the container, builds all the specs under $mariner_dir/SPECS/ and outputs to $mariner_dir/out/. -In the _interactive_ mode, it sets up the Mariner build system inside the container, and starts the container at /mariner/toolkit/. The user can invoke Mariner `make` commands to build packages, images and more. Please see the [section](README.md#sample-make-commands) for sample `make` commands, and visit [Mariner Docs](https://github.com/microsoft/CBL-Mariner/blob/2.0/toolkit/docs/building/building.md) for the complete set of commands. +In the _interactive_ mode, it sets up the Azure Linux build system inside the container, and starts the container at /mariner/toolkit/. The user can invoke Azure Linux `make` commands to build packages, images and more. Please see the [section](README.md#sample-make-commands) for sample `make` commands, and visit [Azure Linux Docs](https://github.com/microsoft/azurelinux/blob/2.0/toolkit/docs/building/building.md) for the complete set of commands. ### Helper scripts -- 'scripts/setup.sh' installs the required pacakges, downloads the Mariner toolkit from GitHub (if missing), downloads Mariner2.0 toolchain RPMs, and sets up the environment variables required for Mariner builds. +- 'scripts/setup.sh' installs the required pacakges, downloads the Azure Linux toolkit from GitHub (if missing), downloads Azure Linux toolchain RPMs, and sets up the environment variables required for Azure Linux builds. -- 'scripts/build.sh' The build starts with cloning the Mariner GitHub repository, and downloading the toolchain. Using the tools from Mariner toolkit, it reads the spec files under SPECS/, installs the build dependepdencies, builds the specs and packages them into an RPM. Each pacakge is built inside a chroot environment. +- 'scripts/build.sh' The build starts with cloning the Azure Linux GitHub repository, and downloading the toolchain. Using the tools from Azure Linux toolkit, it reads the spec files under SPECS/, installs the build dependepdencies, builds the specs and packages them into an RPM. Each pacakge is built inside a chroot environment. ## Advantages: - It is convenient and fast for developement environment -- It gives the user an option to build Mariner without having to go into the details of the build system +- It gives the user an option to build Azure Linux without having to go into the details of the build system ## Disadvantages: - The number of chroots is limited to 12 diff --git a/build-in-container/scripts/setup.sh b/build-in-container/scripts/setup.sh index 6976b09..ada1080 100755 --- a/build-in-container/scripts/setup.sh +++ b/build-in-container/scripts/setup.sh @@ -29,23 +29,23 @@ SOURCE_URL="https://cblmarinerstorage.blob.core.windows.net/sources/core" SPECS_DIR="$MARINER_BASE_DIR/SPECS" USE_CCACHE="y" -# Build Mariner toolkit if not present, by cloning Mariner GitHub repo +# Build Azure Linux toolkit if not present, by cloning Azure Linux GitHub repo # # No arguments # Global variables expected to be defined: BUILD_DIR, CHROOT_DIR, CHROOT_NB, OUT_DIR download_mariner_toolkit() { if [ ! "$(ls -A toolkit)" ]; then - echo "------------ Preparing Mariner toolkit ------------" - if [ ! -d CBL-Mariner ]; then - echo "------------ Cloning Mariner toolkit from github ------------" + echo "------------ Preparing Azure Linux toolkit ------------" + if [ ! -d azurelinux ]; then + echo "------------ Cloning Azure Linux toolkit from github ------------" git clone \ --branch ${MARINER_RELEASE_TAG} \ --depth 1 \ ${CBL_MARINER_GIT_URL} fi - echo "------------ Building Mariner toolkit ------------" + echo "------------ Building Azure Linux toolkit ------------" make -j$(nproc) \ - -C CBL-Mariner/toolkit \ + -C azurelinux/toolkit \ package-toolkit \ BUILD_DIR="$BUILD_DIR" \ CHROOT_DIR="$CHROOT_DIR" \ @@ -54,7 +54,7 @@ download_mariner_toolkit() { LOG_LEVEL=info \ OUT_DIR="$OUT_DIR" \ REBUILD_TOOLS=y && \ - rm -rf CBL-Mariner && \ + rm -rf azurelinux && \ tar -xzvf ${OUT_DIR}/toolkit-*.tar.gz fi } From af70a0f9b8337564655bddf317d00b80a0ebf8d8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 20 May 2025 05:37:47 +0000 Subject: [PATCH 3/4] Update remaining documentation files with Azure Linux naming Co-authored-by: christopherco <35273088+christopherco@users.noreply.github.com> --- SPECS/os-subrelease/os-subrelease.spec | 4 +- docs/kernel/modify_kernel.md | 4 +- docs/packages/working_with_packages.md | 54 +++++++++---------- imaging-from-packer/Create-VM.ps1 | 8 +-- imaging-from-packer/Readme.md | 12 ++--- ...omizeMariner.sh => customizeAzureLinux.sh} | 4 +- 6 files changed, 43 insertions(+), 43 deletions(-) rename imaging-from-packer/provisioners/{customizeMariner.sh => customizeAzureLinux.sh} (74%) diff --git a/SPECS/os-subrelease/os-subrelease.spec b/SPECS/os-subrelease/os-subrelease.spec index 6879eb9..50a0575 100644 --- a/SPECS/os-subrelease/os-subrelease.spec +++ b/SPECS/os-subrelease/os-subrelease.spec @@ -14,11 +14,11 @@ License: Apache License Group: System Environment/Base URL: https://my-company-or-product-url Vendor: My Company Name -Distribution: Mariner +Distribution: Azure Linux BuildArch: noarch %description -This package creates a sample os subrelease file: /etc/os-subrelease. Replace contents as needed for your CBL-Mariner based product information +This package creates a sample os subrelease file: /etc/os-subrelease. Replace contents as needed for your Azure Linux based product information %install rm -rf $RPM_BUILD_ROOT diff --git a/docs/kernel/modify_kernel.md b/docs/kernel/modify_kernel.md index 40d5ff7..8b7d1d6 100644 --- a/docs/kernel/modify_kernel.md +++ b/docs/kernel/modify_kernel.md @@ -15,7 +15,7 @@ The following assumes you have already completed the [Prepare your Environment]( user@machine:~/git$ rsync -a --exclude 'CVE*' azurelinux/SPECS/kernel azurelinux-tutorials/SPECS/ ``` -Next, you will need to download a source tarball from [CBL-Mariner-Linux-Kernel](https://github.com/microsoft/CBL-Mariner-Linux-Kernel). The tags on this repo follow the format `/rolling-lts/mariner<-2 or -3>/`. This translates to +Next, you will need to download a source tarball from [Azure-Linux-Kernel](https://github.com/microsoft/CBL-Mariner-Linux-Kernel). The tags on this repo follow the format `/rolling-lts/mariner<-2 or -3>/`. This translates to * [deprecated] For 1.0 kernels: `/rolling-lts/mariner/5.10.X.1` * For 2.0 kernels: `/rolling-lts/mariner-2/5.15.X.1` * For 3.0 kernels: `/rolling-lts/mariner-3/6.6.X.1` @@ -30,7 +30,7 @@ $ cd azurelinux-tutorials/SPECS/kernel/ $ grep Version: kernel.spec Version: 5.15.102.1 -# Download the associated tar.gz file from https://github.com/microsoft/CBL-Mariner-Linux-Kernel. Be sure to substitute your Mariner version and kernel version. +# Download the associated tar.gz file from https://github.com/microsoft/CBL-Mariner-Linux-Kernel. Be sure to substitute your Azure Linux version and kernel version. $ wget -O kernel-5.15.102.1.tar.gz https://github.com/microsoft/CBL-Mariner-Linux-Kernel/archive/refs/tags/rolling-lts/mariner-2/5.15.102.1.tar.gz ``` diff --git a/docs/packages/working_with_packages.md b/docs/packages/working_with_packages.md index f8e9f88..df9d8d0 100644 --- a/docs/packages/working_with_packages.md +++ b/docs/packages/working_with_packages.md @@ -36,7 +36,7 @@ The complete package set of an image is defined in the "PackageLists" array of e Each package list defines the set of packages to include in the final image. In this example, there are two, so the resulting demo VHD contains the union of the two package lists. While it is possible to combine both package lists into a single JSON file, the separation adds clarity by grouping related content. In this case, packages originating from packages.microsoft.com are in the core-packages set, and packages built from the local repository are specified in the demo-packages set. -The first package list, core-packages.json, includes a superset-package called [core-packages-base-image](https://github.com/microsoft/CBL-Mariner/blob/-/SPECS/core-packages/core-packages.spec). Core-packages-base-image is common to most derivatives as it contains the common set of packages used in Mariner Core. This bundling is a convenience. It is possible to list each package individually instead. The second package, initramfs, is used for booting CBL-Mariner in either a virtualized or physical hardware environment. Not every image needs it, so it's not included in the `core-packages-base-image` superset. Instead, it's specified separately. +The first package list, core-packages.json, includes a superset-package called [core-packages-base-image](https://github.com/microsoft/azurelinux/blob/-/SPECS/core-packages/core-packages.spec). Core-packages-base-image is common to most derivatives as it contains the common set of packages used in Azure Linux Core. This bundling is a convenience. It is possible to list each package individually instead. The second package, initramfs, is used for booting Azure Linux in either a virtualized or physical hardware environment. Not every image needs it, so it's not included in the `core-packages-base-image` superset. Instead, it's specified separately. ```json { @@ -47,7 +47,7 @@ The first package list, core-packages.json, includes a superset-package called [ } ``` -The second package list, demo-packages.json, contains the Hello World and os-subrelease packages that are unique to the CBL-MarinerTutorials repository: +The second package list, demo-packages.json, contains the Hello World and os-subrelease packages that are unique to the azurelinux-tutorials repository: ```json { @@ -64,7 +64,7 @@ In the previous section we described how the package lists are defined. In this ### Add Latest Pre-Built Package -The Zip package is not included in your demo image by default. Because Zip is already released for CBL-Mariner lets add it to your demo image. Open the [core-packages.json](./imageconfigs/demo_package_lists/core-packages.json) file with your favorite editor, Add zip to the packages array before initramfs. While it's possible to add zip after initramfs, it is currently recommended to insert new packages before initramfs due to a performance quirk in the build system. +The Zip package is not included in your demo image by default. Because Zip is already released for Azure Linux lets add it to your demo image. Open the [core-packages.json](./imageconfigs/demo_package_lists/core-packages.json) file with your favorite editor, Add zip to the packages array before initramfs. While it's possible to add zip after initramfs, it is currently recommended to insert new packages before initramfs due to a performance quirk in the build system. ```json { @@ -78,7 +78,7 @@ The Zip package is not included in your demo image by default. Because Zip is a Save the file. For this tutorial we will continue building the VHD image, but you may rebuild the image of your choice because the ISO, VHD and VHDX all share the same core package list file. ```bash -cd CBL-MarinerTutorials/toolkit +cd azurelinux-tutorials/toolkit sudo make image CONFIG_FILE=../imageconfigs/demo_vhd.json ``` Boot the image and verify that the latest version of zip is now provided: @@ -98,13 +98,13 @@ Boot the image and verify that the latest version of zip is now provided: By default the _latest_ version of any package specified in a package list will be included in your image. It is important to note that each time you rebuild your image it may differ from your previous build as the packages on packages.microsoft.com are periodically updated to resolve security vulnerabilities. This behavior may or may not be desired, but you can always be assured that the most recent build is also the most up to date with respect to CVE's. -If you want to guarantee that your next build will be reproduced the same way at a later time, CBL-Mariner provides some support for this. Each time an image is built, a summary file is generated that lists the explicit packages included in the build. The default location of this file is at: _CBL-MarinerTutorials/build/pkg_artifacts/graph_external_deps.json_. To capture your build's explicit contents and reproduce the build later, it's important to save this file for later use. See [Reproducing a Build](https://github.com/microsoft/CBL-Mariner/blob/-/toolkit/docs/building/building.md#reproducing-a-build) in the CBL-Mariner git repository for advanced details. +If you want to guarantee that your next build will be reproduced the same way at a later time, Azure Linux provides some support for this. Each time an image is built, a summary file is generated that lists the explicit packages included in the build. The default location of this file is at: _Azure LinuxTutorials/build/pkg_artifacts/graph_external_deps.json_. To capture your build's explicit contents and reproduce the build later, it's important to save this file for later use. See [Reproducing a Build](https://github.com/microsoft/Azure Linux/blob/-/toolkit/docs/building/building.md#reproducing-a-build) in the Azure Linux git repository for advanced details. The next section also describes a technique for pinning specific package versions. ### Add Specific Pre-Built Package Version -Occasionally you may need to install a very specific version of a package in your image at build time, rather than the latest version. CBL-Mariner supports this capability. +Occasionally you may need to install a very specific version of a package in your image at build time, rather than the latest version. Azure Linux supports this capability. This time let's add `unzip` version 6.0-19, and the latest dash release for `etcd` version 3.5.1 to your demo image. You do this in the following way: @@ -120,12 +120,12 @@ This time let's add `unzip` version 6.0-19, and the latest dash release for `etc } ``` -**NOTE**: Release fields always have the `.[mariner_release]` suffix (`.cm2` in our case). Specifying only the version without the release number will always get you the latest release for the chosen version. +**NOTE**: Release fields always have the `.[azure_linux_release]` suffix (`.cm2` in our case). Specifying only the version without the release number will always get you the latest release for the chosen version. Save the file and rebuild your image. ```bash -cd CBL-MarinerTutorials/toolkit +cd azurelinux-tutorials/toolkit sudo make image CONFIG_FILE=../imageconfigs/demo_vhd.json ``` @@ -159,11 +159,11 @@ Similarly, `etcd` is version 3.5.1, latest release. ### Add Packages from Other RPM Repositories -It is possible to build your images and packages using pre-built RPMs from repositories other than the default CBL-Mariner ones. In order to inform the toolkit to access them during the build, you have to make use of the [REPO_LIST](https://github.com/microsoft/CBL-Mariner/blob/-/toolkit/docs/building/building.md#repo_list) argument where you specify .repo files pointing to the additional repositories. +It is possible to build your images and packages using pre-built RPMs from repositories other than the default Azure Linux ones. In order to inform the toolkit to access them during the build, you have to make use of the [REPO_LIST](https://github.com/microsoft/Azure Linux/blob/-/toolkit/docs/building/building.md#repo_list) argument where you specify .repo files pointing to the additional repositories. Example: -Let's say your CBL-Mariner 2.0 image requires the `indent` package. This package is available inside the [CBL-Mariner Extended Repository](http://packages.microsoft.com/cbl-mariner/2.0/prod/extended/x86_64/) and the corresponding .repo file pointing to Mariner's official RPM repository hosting its packages is available in the toolkit under `toolkit/repos/mariner-extended.repo`. With that you'll be able to build your image by first adding `indent` to your package list: +Let's say your Azure Linux 2.0 image requires the `indent` package. This package is available inside the [Azure Linux Extended Repository](http://packages.microsoft.com/cbl-mariner/2.0/prod/extended/x86_64/) and the corresponding .repo file pointing to Azure Linux's official RPM repository hosting its packages is available in the toolkit under `toolkit/repos/azure-linux-extended.repo`. With that you'll be able to build your image by first adding `indent` to your package list: ```json { @@ -179,22 +179,22 @@ Let's say your CBL-Mariner 2.0 image requires the `indent` package. This packag and then by running the following command: ```bash -sudo make image CONFIG_FILE=../imageconfigs/demo_vhd.json REPO_LIST=repos/mariner-extended.repo +sudo make image CONFIG_FILE=../imageconfigs/demo_vhd.json REPO_LIST=repos/azure-linux-extended.repo ``` -CBL-Mariner's toolkit provides other .repo files under `toolkit/repos`. Refer to the [REPO_LIST documentation](https://github.com/microsoft/CBL-Mariner/blob/-/toolkit/docs/building/building.md#repo_list) for more details. +Azure Linux's toolkit provides other .repo files under `toolkit/repos`. Refer to the [REPO_LIST documentation](https://github.com/microsoft/Azure Linux/blob/-/toolkit/docs/building/building.md#repo_list) for more details. -> **NOTE:** The core repo contains these repo files in [SPECS/mariner-repos/](https://github.com/microsoft/CBL-Mariner/blob/-/SPECS/mariner-repos/). +> **NOTE:** The core repo contains these repo files in [SPECS/mariner-repos/](https://github.com/microsoft/Azure Linux/blob/-/SPECS/mariner-repos/). ## Tutorial: Customize your Image with Unsupported Packages -In the previous tutorial we described how pre-existing packages can be added to your demo image. In this tutorial we will walk through the process of adding a new package that Mariner does not formally support through the addition of a SPEC file. +In the previous tutorial we described how pre-existing packages can be added to your demo image. In this tutorial we will walk through the process of adding a new package that Azure Linux does not formally support through the addition of a SPEC file. Packages are defined by RPM SPEC files. At its core, a SPEC file contains the instructions for building and installing a package. Most SPEC files contain a pointer to one or more compressed source files, pointers to patch files, and the name, version and licensing information associated with the package. SPEC files also contain references to build and runtime dependencies. The goal of this tutorial is to show the process for adding a SPEC file to the tutorial repo, not to delve into the details of creating a SPEC file. For detailed information on SPEC file syntax and features refer to the [RPM Packaging Guide](https://rpm-packaging-guide.github.io/), the [RPM Reference Manual](https://rpm-software-management.github.io/rpm/manual/), or search the web as needed. -To add a new package to the CBL-MarinerTutorials repo you must take the following actions: +To add a new package to the Azure LinuxTutorials repo you must take the following actions: 1. [Acquire the compressed source file (the tarball) you want to build](#acquire-the-compressed-source-file) 1. [Create a signature meta-data file (a SHA-256 hash of the tarball)](#create-a-signature-meta-data-file) @@ -202,18 +202,18 @@ To add a new package to the CBL-MarinerTutorials repo you must take the followin 1. [Check your .spec file to ensure it is correct](#check-your-spec-file) 1. [Add your package to the .json file](#add-your-package) -For this tutorial we will add the "gnuchess" package to your CBL-MarinerTutorials image. +For this tutorial we will add the "gnuchess" package to your Azure LinuxTutorials image. ### Acquire the Compressed Source File -First, download the source code for gnuchess 6.2.7 [here](https://ftp.gnu.org/gnu/chess/gnuchess-6.2.7.tar.gz). And save it in a new CBL-MarinerTutorials/SPECS/gnuchess folder. Also, download and save the [game data file](http://ftp.gnu.org/pub/gnu/chess/book_1.01.pgn.gz) to the gnuchess folder. +First, download the source code for gnuchess 6.2.7 [here](https://ftp.gnu.org/gnu/chess/gnuchess-6.2.7.tar.gz). And save it in a new Azure LinuxTutorials/SPECS/gnuchess folder. Also, download and save the [game data file](http://ftp.gnu.org/pub/gnu/chess/book_1.01.pgn.gz) to the gnuchess folder. Next, create the SPEC file for gnuchess. This may be created from scratch, but in many cases it's easiest to leverage an open source version as a template. Since the focus of this tutorial is to demonstrate how to quickly add a new package, we will obtain an existing SPEC file [Fedora source rpm for gnuchess](https://src.fedoraproject.org/rpms/gnuchess/blob/master/f/gnuchess.spec). Clone the Fedora gnuchess repo and copy the SPEC and patch files into your gnuchess folder: ```bash -cd CBL-MarinerTutorials/SPECS/gnuchess +cd Azure LinuxTutorials/SPECS/gnuchess git clone https://src.fedoraproject.org/rpms/gnuchess.git /tmp/gnuchess pushd /tmp/gnuchess git checkout 03a6481 @@ -223,12 +223,12 @@ cp /tmp/gnuchess/gnuchess.spec . ### Create a Signature Meta-data File -Now, calculate the SHA-256 hashed for gnuchess-6.2.7.tar.gz and the book_1.01.pgn.gz file The SHA-256 sum is used by the build system as an integrity check to ensure that the tarballs associated with a SPEC file are the expected one. The signature meta-data file can also be automatically created using a specific argument in the command line as seen in the [CBL-Mariner documentation](https://github.com/microsoft/CBL-Mariner/blob/-/toolkit/docs/building/building.md#source-hashes). +Now, calculate the SHA-256 hashed for gnuchess-6.2.7.tar.gz and the book_1.01.pgn.gz file The SHA-256 sum is used by the build system as an integrity check to ensure that the tarballs associated with a SPEC file are the expected one. The signature meta-data file can also be automatically created using a specific argument in the command line as seen in the [Azure Linux documentation](https://github.com/microsoft/Azure Linux/blob/-/toolkit/docs/building/building.md#source-hashes). Calculate the new checksum: ```bash -$ cd CBL-MarinerTutorials/SPECS/gnuchess +$ cd Azure LinuxTutorials/SPECS/gnuchess $ sha256sum gnuchess-6.2.7.tar.gz e536675a61abe82e61b919f6b786755441d9fcd4c21e1c82fb9e5340dd229846 gnuchess-6.2.7.tar.gz $ sha256sum book_1.01.pgn.gz @@ -246,10 +246,10 @@ Using your favorite editor create and save a gnuchess.signatures.json file with } ``` -At this point your CBL-MarinerTutorials/SPECS/gnuchess folder should look similar to this: +At this point your Azure LinuxTutorials/SPECS/gnuchess folder should look similar to this: ```bash -~/CBL-MarinerTutorials/SPECS/gnuchess$ ls -la +~/Azure LinuxTutorials/SPECS/gnuchess$ ls -la total 816 drwxr-xr-x 2 jon jon 4096 Jan 22 14:23 . drwxr-xr-x 5 jon jon 4096 Jan 22 13:43 .. @@ -261,11 +261,11 @@ drwxr-xr-x 5 jon jon 4096 Jan 22 13:43 .. ### Create a .spec File -Now, we need to modify the gnuchess.spec file slightly to build properly for CBL-Mariner by: +Now, we need to modify the gnuchess.spec file slightly to build properly for Azure Linux by: 1. bumping the release number 1. selecting the non-precompiled book -1. patching the BuildRequires for c++ to use the CBL-Mariner package name +1. patching the BuildRequires for c++ to use the Azure Linux package name 1. updating the %changelog and professionally show gratitude to Fedora Your SPEC file should appear similar to this: @@ -310,11 +310,11 @@ Next, you can check your SPEC file to ensure that it conforms with RPM design ru At this point, we can use a shortcut to verify that the gnu chess package compiles by issuing the following command. It will build any packages not already built, but not build the image itself. ```bash -$ cd CBL-MarinerTutorials/toolkit +$ cd azurelinux-tutorials/toolkit $ sudo make build-packages CONFIG_FILE= ``` -If the build fails, inspect the build output for clues and repair any issues. The default location for build logs is in the _CBL-MarinerTutorials/build/logs/pkggen/rpmbuilding/_ folder. There should be one log for each package. +If the build fails, inspect the build output for clues and repair any issues. The default location for build logs is in the _Azure LinuxTutorials/build/logs/pkggen/rpmbuilding/_ folder. There should be one log for each package. ### Add your Package @@ -333,7 +333,7 @@ Finally, we need to add gnuchess to the demo-packages.json file. Save your demo-packages.json file and rebuild your image. ```bash -cd CBL-MarinerTutorials/toolkit +cd azurelinux-tutorials/toolkit sudo make image CONFIG_FILE=../imageconfigs/demo_vhd.json ``` diff --git a/imaging-from-packer/Create-VM.ps1 b/imaging-from-packer/Create-VM.ps1 index afefb2a..f9a38a2 100644 --- a/imaging-from-packer/Create-VM.ps1 +++ b/imaging-from-packer/Create-VM.ps1 @@ -11,10 +11,10 @@ param ( [string] $isoChecksum = "file:https://osrelease.download.prss.microsoft.com/pr/download/Mariner-2.0-x86_64.iso.sha256", - # Name of the CBL-Mariner configuration in the ISO - # Note that default config name for CBL-Mariner ISO is "CBL-Mariner Full" + # Name of the Azure Linux configuration in the ISO + # Note that default config name for Azure Linux ISO is "Azure Linux Full" [string] - $marinerConfigName = 'CBL-Mariner Full', + $marinerConfigName = 'Azure Linux Full', # username used to login [Parameter(mandatory=$true)] @@ -36,7 +36,7 @@ param ( # name of the 'main' provisioner script # this script must be in the provisionner folder [string] - $provisionerScript = 'customizeMariner.sh', + $provisionerScript = 'customizeAzureLinux.sh', # Name of the VM [string] diff --git a/imaging-from-packer/Readme.md b/imaging-from-packer/Readme.md index 993f23b..8d2b5c3 100644 --- a/imaging-from-packer/Readme.md +++ b/imaging-from-packer/Readme.md @@ -1,16 +1,16 @@ -# Automate VHD or VHDX creation from CBL-Mariner ISO image using ['packer']( https://www.packer.io/) (1) -This set of scripts and configuration files can be used to automate VHDX (2) creation and customization from an initial CBL-Mariner ISO image. **These scripts are designed to run on Windows using the Hyper-V builder Packer provides**. They will need to be adapted if another builder is used (e.g. qemu builder). +# Automate VHD or VHDX creation from Azure Linux ISO image using ['packer']( https://www.packer.io/) (1) +This set of scripts and configuration files can be used to automate VHDX (2) creation and customization from an initial Azure Linux ISO image. **These scripts are designed to run on Windows using the Hyper-V builder Packer provides**. They will need to be adapted if another builder is used (e.g. qemu builder). The ISO image can be local or fetched from a server. The original ISO image must contains 'openssh-server' packages, because 'packer' relies on ssh to communicate with the VM once it has been programmatically configured and booted. ![](PackerFlow.png) -This tooling relies on two configuration files: 'packer' configuration [packer_config.json](/imaging-from-packer/packer_config.json) and CBL-Mariner image configuration [mariner_config.json](/imaging-from-packer/mariner_config.json) (aka unattended configuration) that are customized using a PowerShell script [Create-VM.ps1](/imaging-from-packer/Create-VM.ps1). This PowerShell script will also launch 'packer' to create the VHDX. Once the VM has boot and after its initial configuration has been applied 'packer' will use its provisioners (1) to launch customization scripts which can be use to install new packages. +This tooling relies on two configuration files: 'packer' configuration [packer_config.json](/imaging-from-packer/packer_config.json) and Azure Linux image configuration [mariner_config.json](/imaging-from-packer/mariner_config.json) (aka unattended configuration) that are customized using a PowerShell script [Create-VM.ps1](/imaging-from-packer/Create-VM.ps1). This PowerShell script will also launch 'packer' to create the VHDX. Once the VM has boot and after its initial configuration has been applied 'packer' will use its provisioners (1) to launch customization scripts which can be use to install new packages. Notes: - this sample relies on the http server 'packer' will set up to provision the configuration files on the target. Consequently the virtual network switch provided by Hyper-V and that you will instruct 'packer' to use should be configured in such a way that communication between 'packer' http server and the target is possible. If not possible, packer offers other way to provision file onto the target, e.g.: secondary iso, (see 'packer' documentation). - depending on the hardware it run against, the virtual machine Packer creates might be slow to boot and makes Packer injecting its "boot_command" before the virtual machine is ready to accept them. In such a case, use "boot_wait" in Packer config to delay injection of commands indicated in "boot_command". - ``"", -"c",`` commands at the beggining of the "boot_command" section will exit CBL-Mariner attended configuration. +"c",`` commands at the beggining of the "boot_command" section will exit Azure Linux attended configuration. ###### Prerequisits - enable Hyper-V feature on your Windows machine @@ -19,6 +19,6 @@ Notes: ###### Notes (1) For more information about 'packer' see https://www.packer.io/ and more specifically the [hyper-v builder](https://www.packer.io/docs/builders/hyperv/iso) (2) VHD creation just requires to change 1 parameter in the 'packer' configuration file and some changes in mariner configuration file (specifically the boot partition). -See [CBL-Mariner image configuration](https://github.com/microsoft/CBL-Mariner/blob/-/toolkit/docs/formats/imageconfig.md), you may also take a look at [CBL-Mariner core legacy config file](https://github.com/microsoft/CBL-Mariner/blob/-/toolkit/imageconfigs/core-legacy.json) to figure out how the boot partition can be set. -(3) This is available for **CBL-Mariner version 1.0.20210929 and above** +See [Azure Linux image configuration](https://github.com/microsoft/azurelinux/blob/-/toolkit/docs/formats/imageconfig.md), you may also take a look at [Azure Linux core legacy config file](https://github.com/microsoft/azurelinux/blob/-/toolkit/imageconfigs/core-legacy.json) to figure out how the boot partition can be set. +(3) This is available for **Azure Linux version 1.0.20210929 and above** diff --git a/imaging-from-packer/provisioners/customizeMariner.sh b/imaging-from-packer/provisioners/customizeAzureLinux.sh similarity index 74% rename from imaging-from-packer/provisioners/customizeMariner.sh rename to imaging-from-packer/provisioners/customizeAzureLinux.sh index 1d2d191..6e54733 100644 --- a/imaging-from-packer/provisioners/customizeMariner.sh +++ b/imaging-from-packer/provisioners/customizeAzureLinux.sh @@ -2,10 +2,10 @@ set -e -# install additional repositories from where to fetch Mariner packages +# install additional repositories from where to fetch Azure Linux packages echo "-- install additional repositories" echo $USER_PSW | sudo -S tdnf -y install \ - mariner-repos-extras + azure-linux-repos-extras # install packages echo "-- install required packages" From a2a47aae0376091a53cfafc359a21ae6c68fdfdb Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 20 May 2025 05:41:38 +0000 Subject: [PATCH 4/4] Update final documentation files with Azure Linux naming Co-authored-by: christopherco <35273088+christopherco@users.noreply.github.com> --- docs/building/building.md | 18 +++++++++--------- docs/getting_started/boot.md | 4 ++-- docs/packages/working_with_packages.md | 2 +- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/building/building.md b/docs/building/building.md index a3f0eae..14e7706 100644 --- a/docs/building/building.md +++ b/docs/building/building.md @@ -11,19 +11,19 @@ In the previous tutorials, we configured your build machine, walked through how ### Build Derivate VHD or VHDX -Choose an image to build by invoking one of the following build commands from the _CBL-MarinerTutorials/toolkit_ folder. +Choose an image to build by invoking one of the following build commands from the _azurelinux-tutorials/toolkit_ folder. ```bash sudo make image CONFIG_FILE=../imageconfigs/demo_vhd.json sudo make image CONFIG_FILE=../imageconfigs/demo_vhdx.json ``` -The first time make image is invoked the toolkit downloads the necessary toolchain packages from the CBL-Mariner repository at packages.microsoft.com. These toolchain packages are the standard set needed to build any local packages contained in the CBL-MarinerTutorials repo. Once the toolchain is ready, make automatically proceeds to build any local packages. In this case, the [Hello World](./SPECS/hello_world_demo/hello_world_demo.spec) and [OS-Subrelease](./SPECS/os-subrelease/os-subrelease.spec) packages will be compiled. After all local packages are built, make will assemble the packages to build an image. -The resulting binaries (images and rpms) are placed in the CBL-MarinerTutorials/out folder +The first time make image is invoked the toolkit downloads the necessary toolchain packages from the Azure Linux repository at packages.microsoft.com. These toolchain packages are the standard set needed to build any local packages contained in the azurelinux-tutorials repo. Once the toolchain is ready, make automatically proceeds to build any local packages. In this case, the [Hello World](./SPECS/hello_world_demo/hello_world_demo.spec) and [OS-Subrelease](./SPECS/os-subrelease/os-subrelease.spec) packages will be compiled. After all local packages are built, make will assemble the packages to build an image. +The resulting binaries (images and rpms) are placed in the azurelinux-tutorials/out folder - VHDX: `CBL-MarinerTutorials/out/images/demo_vhdx/` - VHD: `CBL-MarinerTutorials/out/images/demo_vhd/` - PACKAGES: `CBL-MarinerTutorials/out/RPMS/x86_64/` + VHDX: `azurelinux-tutorials/out/images/demo_vhdx/` + VHD: `azurelinux-tutorials/out/images/demo_vhd/` + PACKAGES: `azurelinux-tutorials/out/RPMS/x86_64/` ### Use Hyper-V to Boot Your Demo Image @@ -47,16 +47,16 @@ Now show the contents of the os-subrelease file NAME="My Product Name" VERSION="my-version-id" ``` -Congratulations you've built and launched your first CBL-Mariner derivative image! +Congratulations you've built and launched your first Azure Linux derivative image! ## Tutorial: Build a Demo ISO -In the previous tutorial, we learned how to create a simple VHD(X) image. In this tutorial, we will turn our attention to creating a bootable ISO image for installing CBL-Mariner to either a physical machine or virtual hard drive. +In the previous tutorial, we learned how to create a simple VHD(X) image. In this tutorial, we will turn our attention to creating a bootable ISO image for installing Azure Linux to either a physical machine or virtual hard drive. Let's jump right in. Run the following command to build a demo ISO: ```bash -cd CBL-MarinerTutorials/toolkit +cd azurelinux-tutorials/toolkit sudo make iso CONFIG_FILE=../imageconfigs/demo_iso.json ``` diff --git a/docs/getting_started/boot.md b/docs/getting_started/boot.md index 19d66c0..57d1561 100644 --- a/docs/getting_started/boot.md +++ b/docs/getting_started/boot.md @@ -52,7 +52,7 @@ _Note:_ Having Dynamic Memory enabled may lead your app to crash due to integrat 1. Select _Start_. 1. Follow the Installer Prompts to Install your image 1. When installation completes, select restart to reboot the machine. The installation ISO will be automatically ejected. -1. When prompted sign in to your CBL-Mariner system using the user name and password provisioned through the Installer. +1. When prompted sign in to your Azure Linux system using the user name and password provisioned through the Installer. ## Use Hyper-V to Boot Your Offline Image @@ -106,4 +106,4 @@ choose DVD Drive and press Add. 1. Right click your VM and select _Connect..._. 1. Select _Start_. -1. Wait for CBL-Mariner to boot to the login prompt, then sign in with the credentials you provisioned in the meta-user-data.iso file (username/password or username/sshkey pair). +1. Wait for Azure Linux to boot to the login prompt, then sign in with the credentials you provisioned in the meta-user-data.iso file (username/password or username/sshkey pair). diff --git a/docs/packages/working_with_packages.md b/docs/packages/working_with_packages.md index df9d8d0..c770750 100644 --- a/docs/packages/working_with_packages.md +++ b/docs/packages/working_with_packages.md @@ -163,7 +163,7 @@ It is possible to build your images and packages using pre-built RPMs from repos Example: -Let's say your Azure Linux 2.0 image requires the `indent` package. This package is available inside the [Azure Linux Extended Repository](http://packages.microsoft.com/cbl-mariner/2.0/prod/extended/x86_64/) and the corresponding .repo file pointing to Azure Linux's official RPM repository hosting its packages is available in the toolkit under `toolkit/repos/azure-linux-extended.repo`. With that you'll be able to build your image by first adding `indent` to your package list: +Let's say your Azure Linux 2.0 image requires the `indent` package. This package is available inside the [Azure Linux Extended Repository](http://packages.microsoft.com/azurelinux/2.0/prod/extended/x86_64/) and the corresponding .repo file pointing to Azure Linux's official RPM repository hosting its packages is available in the toolkit under `toolkit/repos/azure-linux-extended.repo`. With that you'll be able to build your image by first adding `indent` to your package list: ```json {