diff --git a/toolkit/tools/imagecustomizer/README.md b/toolkit/tools/imagecustomizer/README.md index 84d25477d0..a4bafca69c 100644 --- a/toolkit/tools/imagecustomizer/README.md +++ b/toolkit/tools/imagecustomizer/README.md @@ -3,10 +3,10 @@ The Azure Linux Image Customizer is a tool that can take an existing generic Azure Linux image and modify it to be suited for particular scenario. -MIC uses [chroot](https://en.wikipedia.org/wiki/Chroot) (and loopback block devices) to -customize the image. -This is the same technology used to build the Azure Linux images (along with most other -Linux distros). +The Image Customizer uses [chroot](https://en.wikipedia.org/wiki/Chroot) (and loopback +block devices) to customize the image. +This is the same technology used to build the Azure Linux images, along with most other +Linux distros. This is in contrast to some other image customization tools, like Packer, which customize the image by booting it inside a VM. @@ -22,9 +22,8 @@ Advantages: Disadvantages: -- Not all Linux tools play nicely when run under chroot. (Though most of the most - common tools do play nicely since they are used to build Linux images under chroot.) - So, some customizations aren't possible to do using MIC. +- Not all Linux tools play nicely when run under chroot. + So, some customizations aren't possible using the Image Customizer. (For example, initializing a Kubernetes cluster node.) ## Getting started @@ -83,3 +82,33 @@ Disadvantages: The customized image is placed in the file that you specified with the `--output-image-file` parameter. You can now use this image as you see fit. (For example, boot it in a Hyper-V VM.) + +## Things to avoid + +The Image Customizer tool provides the option to run custom scripts as part of the +customization process. +These can be used to handle scenarios not covered by the Image Customizer tool. +However, these scripts are only run within a chroot environment, which while it is kind +of similar to containers, is very explicitly not a sandbox environment. +So, such scripts have the ability to modify the host build system. + +In particular, you should be very wary of commands that have the ability to change the +runtime kernel settings. +And even commands that only read runtime kernel settings are probably doing the wrong +thing, since the host build system's kernel is likely entirely unrelated to the +customized OS's kernel. + +Examples of commands to avoid: + +- `ip` +- `iptables` +- `iptables-save` +- `ip6tables-save` +- `sysctl` + +Instead, you should you make use of config files that set the runtime kernel settings +during OS boot. + +Example config directories to use instead: + +- `/etc/sysctl.d` (`systemd-sysctl.service`)