Skip to content

Add Prism tool references for image customization #70

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

Add Prism tool references for image customization #70

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e5fd518
Initial plan for issue
Copilot May 27, 2025
8cdce92
Add Prism tool references for image customization
Copilot May 27, 2025
96921e0
Add Prism tool reference to default_images.md
Copilot May 28, 2025
6c3c2d3
Add reference to custom spec files section in working_with_packages.md
Copilot May 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@

# 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.
# 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.

> **Note:** For customizing Azure Linux images, we recommend using the [Prism tool](https://github.com/microsoft/azure-linux-image-tools), which is the preferred method for building custom images. Please refer to the [Prism Image Customizer documentation](https://microsoft.github.io/azure-linux-image-tools/imagecustomizer/README.html) for details.

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:

Expand Down
2 changes: 2 additions & 0 deletions docs/building/building.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Building

> **Note:** For customizing Azure Linux images, we recommend using the [Prism tool](https://github.com/microsoft/azure-linux-image-tools), which is the preferred method for building custom images. Please refer to the [Prism Image Customizer documentation](https://microsoft.github.io/azure-linux-image-tools/imagecustomizer/README.html) for details. The instructions below are still valid but represent the legacy approach for building custom images.

- [Tutorial: Build a Demo VHD or VHDX](#tutorial-build-a-demo-vhd-or-vhdx)
- [Build Derivate VHD or VHDX](#build-derivate-vhd-or-vhdx)
- [Use Hyper-V to Boot Your Demo Image](#use-hyper-v-to-boot-your-demo-image)
Expand Down
2 changes: 2 additions & 0 deletions docs/getting_started/default_images.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Building

> **Note:** For customizing Azure Linux images, we recommend using the [Prism tool](https://github.com/microsoft/azure-linux-image-tools), which is the preferred method for building custom images. Please refer to the [Prism Image Customizer documentation](https://microsoft.github.io/azure-linux-image-tools/imagecustomizer/README.html) for details. The instructions below are still valid but represent the legacy approach for building custom images.

- [Tutorial: Build the default ISO](#tutorial-build-the-default-iso)
- [Build ISO](#build-iso)
- [Use Hyper-V to Boot Your ISO Installer](#use-hyper-v-to-boot-your-iso-installer)
Expand Down
2 changes: 2 additions & 0 deletions docs/packages/working_with_packages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Working with Packages

> **Note:** For customizing Azure Linux images, we recommend using the [Prism tool](https://github.com/microsoft/azure-linux-image-tools), which is the preferred method for building custom images. Please refer to the [Prism Image Customizer documentation](https://microsoft.github.io/azure-linux-image-tools/imagecustomizer/README.html) for details. The instructions below are still valid but represent the legacy approach for customizing images with packages. If you're creating custom spec files, please see the [Tutorial: Customize your Image with Unsupported Packages](#tutorial-customize-your-image-with-unsupported-packages) section.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file also talks about custom spec files, can you add a visible callout to look there if you are doing that?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added a reference to the custom spec files section in the note at the top of the working_with_packages.md file. The updated note now directs users to the "Tutorial: Customize your Image with Unsupported Packages" section when they're creating custom spec files. Changes are in commit 6c3c2d3.

- [Image Config File](#image-config-file)
- [File Paths](#file-paths)
- [Package Lists](#package-lists)
Expand Down