Skip to content

Commit f0b3d3e

Browse files
arodagearodage
committed
made code changes to replace build spec with image template
1 parent 9c7f736 commit f0b3d3e

12 files changed

Lines changed: 869 additions & 312 deletions

File tree

‎README.md‎

Lines changed: 203 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,32 @@ from different Operating System Vendors (OSVs).
1010
The ICT is developed in `golang` and is initially targeting to build custom
1111
images for [EMT](https://github.com/open-edge-platform/edge-microvisor-toolkit)
1212
(Edge Microvisor Toolkit), [Azure Linux](https://github.com/microsoft/azurelinux)
13-
and WindRiver Linux.
13+
and Wind River eLxr.
14+
15+
## Documentation
16+
17+
- [📖 CLI Specification](./image-composer-cli-specification.md) - Complete command-line reference and usage guide
18+
- [🔧 Build Process](./image-composer-build-process.md) - Understanding the five-stage build pipeline
19+
- [⚡ Caching](./image-composer-caching.md) - Package and image caching for performance
20+
- [📋 Templates](./image-composer-templates.md) - Creating and using reusable image templates
21+
22+
## Quick Start
23+
24+
```bash
25+
# Build the tool
26+
go build ./cmd/image-composer
27+
28+
# Or run directly
29+
go run ./cmd/image-composer --help
30+
31+
# Build an image from template
32+
./image-composer build image-templates/azl3-x86_64-edge-raw.yml
33+
34+
# Validate a template
35+
./image-composer validate image-templates/azl3-x86_64-edge-raw.yml
36+
```
37+
38+
For complete usage instructions, see the [CLI Specification](./image-composer-cli-specification.md).
1439

1540
## Get Started
1641

@@ -46,7 +71,7 @@ The Earthly build automatically includes:
4671

4772
### Global Configuration
4873

49-
Image Composer Tool supports global configuration files to set tool-level parameters that apply across all image builds. Image-specific parameters should still be defined in the JSON specification files.
74+
Image Composer Tool supports global configuration files to set tool-level parameters that apply across all image builds. Image-specific parameters are defined in YAML image template files.
5075

5176
#### Configuration File Locations
5277

@@ -86,7 +111,7 @@ logging:
86111
./image-composer config show
87112

88113
# Use specific configuration file
89-
./image-composer --config /path/to/config.yaml build spec.json
114+
./image-composer --config /path/to/config.yaml build template.yml
90115
```
91116

92117
### Usage
@@ -97,14 +122,14 @@ The Image Composer Tool uses a command-line interface with various commands:
97122
# Show help
98123
./image-composer --help
99124

100-
# Build command with spec file as positional argument
101-
./image-composer build testdata/valid.json
125+
# Build command with template file as positional argument
126+
./image-composer build image-templates/azl3-x86_64-edge-raw.yml
102127

103128
# Override config settings with command-line flags
104-
./image-composer build --workers 16 --cache-dir /tmp/cache testdata/valid.json
129+
./image-composer build --workers 16 --cache-dir /tmp/cache image-templates/azl3-x86_64-edge-raw.yml
105130

106-
# Validate a spec file against the schema
107-
./image-composer validate testdata/valid.json
131+
# Validate a template file against the schema
132+
./image-composer validate image-templates/azl3-x86_64-edge-raw.yml
108133

109134
# Display version information
110135
./image-composer version
@@ -119,10 +144,10 @@ The Image Composer Tool provides the following commands:
119144

120145
#### build
121146

122-
Builds a Linux distribution image based on the specified spec file:
147+
Builds a Linux distribution image based on the specified image template file:
123148

124149
```bash
125-
./image-composer build [flags] SPEC_FILE
150+
./image-composer build [flags] TEMPLATE_FILE
126151
```
127152

128153
Flags:
@@ -138,7 +163,7 @@ Flags:
138163
Example:
139164

140165
```bash
141-
./image-composer build --workers 12 --cache-dir ./package-cache testdata/valid.json
166+
./image-composer build --workers 12 --cache-dir ./package-cache image-templates/azl3-x86_64-edge-raw.yml
142167
```
143168

144169
#### config
@@ -155,13 +180,13 @@ Manages global configuration:
155180

156181
#### validate
157182

158-
Validates a JSON spec file against the schema without building an image:
183+
Validates a YAML template file against the schema without building an image:
159184

160185
```bash
161-
./image-composer validate SPEC_FILE
186+
./image-composer validate TEMPLATE_FILE
162187
```
163188

164-
This is useful for verifying configurations before starting the potentially time-consuming build process.
189+
This is useful for verifying template configurations before starting the potentially time-consuming build process.
165190

166191
#### version
167192

@@ -220,99 +245,102 @@ image-composer build --[TAB]
220245

221246
See the [Shell Completion](#shell-completion) section for more details.
222247

223-
### User Input JSON
248+
### Image Template Format
224249

225-
This section provides a detailed explanation of the JSON input structure used to configure and build a Linux-based operating system. The JSON format allows users to define key parameters such as the operating system distribution, version, architecture, software packages, output format, immutability, and kernel configuration. By customizing these parameters, users can create tailored Linux OS builds, including distributions like Ubuntu, Wind River, and Edge Microvisor Toolkits.
250+
Image templates are written in YAML format and define the requirements for building a specific OS image. The template structure allows users to define key parameters such as the operating system distribution, version, architecture, software packages, output format, and kernel configuration.
226251

227-
```json
228-
{
229-
"distro": "eLxr",
230-
"version": "12",
231-
"arch": "x86_64",
232-
"packages": [
233-
"cloud-init",
234-
"cloud-utils-growpart",
235-
"dhcpcd",
236-
"grubby",
237-
"hyperv-daemons",
238-
"netplan",
239-
"python3",
240-
"rsyslog",
241-
"sgx-backwards-compatibility",
242-
"WALinuxAgent",
243-
"wireless-regdb"
244-
],
245-
"immutable": true,
246-
"output": "iso",
247-
"kernel": {
248-
"version": "5.10.0",
249-
"cmdline": "quiet splash"
250-
}
251-
}
252+
```yaml
253+
image:
254+
name: azl3-x86_64-edge
255+
version: "1.0.0"
256+
257+
target:
258+
os: azure-linux # Target OS name
259+
dist: azl3 # Target OS distribution
260+
arch: x86_64 # Target OS architecture
261+
imageType: raw # Image type: raw, iso, img, vhd
262+
263+
systemConfigs:
264+
- name: edge
265+
description: Default configuration for edge image
266+
267+
# Package Configuration
268+
packages:
269+
# Additional packages beyond the base system
270+
- openssh-server # Remote access
271+
- docker-ce # Container runtime
272+
- vim # Text editor
273+
- curl # HTTP client
274+
- wget # File downloader
275+
276+
# Kernel Configuration
277+
kernel:
278+
version: "6.12"
279+
cmdline: "quiet splash"
252280
```
253281
254282
#### Key Components
255283
256-
##### 1. `distro`
257-
258-
**Description:** Specifies the target Linux distribution to be built.
259-
**Examples:**
260-
261-
- `AzureLinux`
262-
- `eLxr`
263-
264-
##### 2. `version`
265-
266-
**Description:** Defines the version of the target operating system.
267-
**Example:** `"12"`
284+
##### 1. `image`
268285

269-
##### 3. `arch`
286+
**Description:** Basic image identification and metadata.
287+
- `name`: Name of the resulting image
288+
- `version`: Version for tracking and naming
270289

271-
**Description:** Specifies the architecture of the target operating system.
272-
**Examples:**
290+
##### 2. `target`
273291

274-
- `x86_64`
275-
- `arm64`
292+
**Description:** Defines the target OS and image configuration.
293+
- `os`: Target operating system (`azure-linux`, `emt`, `elxr`)
294+
- `dist`: Distribution identifier (`azl3`, `emt3`, `elxr12`)
295+
- `arch`: Target architecture (`x86_64`, `aarch64`)
296+
- `imageType`: Output format (`raw`, `iso`, `img`, `vhd`)
276297

277-
##### 4. `packages`
298+
##### 3. `systemConfigs`
278299

279-
**Description:** A list of software packages to be included in the OS build. These packages will be pre-installed in the resulting image.
280-
**Examples:**
300+
**Description:** Array of system configurations that define what goes into the image.
301+
- `name`: Configuration name
302+
- `description`: Human-readable description
303+
- `packages`: List of packages to include in the OS build
304+
- `kernel`: Kernel configuration with version and command-line parameters
281305

282-
- `cloud-init`: Used for initializing cloud instances.
283-
- `python3`: The Python 3 programming language interpreter.
284-
- `rsyslog`: A logging system for Linux.
306+
#### Supported Distributions
285307

286-
##### 5. `immutable`
308+
| OS | Distribution | Version | Provider |
309+
|----|-------------|---------|----------|
310+
| azure-linux | azl3 | 3 | AzureLinux3 |
311+
| emt | emt3 | 3.0 | EMT3.0 |
312+
| elxr | elxr12 | 12 | eLxr12 |
287313

288-
**Description:** Indicates whether the operating system should be immutable.
289-
**Values:**
314+
#### Package Examples
290315

291-
- `true`: The OS is immutable, meaning it cannot be modified after creation.
292-
- `false`: The OS is mutable, allowing modifications after creation.
316+
Common packages that can be included:
317+
- `cloud-init`: Used for initializing cloud instances
318+
- `python3`: The Python 3 programming language interpreter
319+
- `rsyslog`: A logging system for Linux
320+
- `openssh-server`: SSH server for remote access
321+
- `docker-ce`: Docker container runtime
293322

294-
##### 6. `output`
323+
The image template format is validated against a JSON schema to ensure correctness before building.
295324

296-
**Description:** Specifies the format of the output build.
297-
**Values:**
325+
### Legacy JSON Format
298326

299-
- `iso`: The OS will be built as an ISO file, suitable for installation or booting.
300-
- `raw`: The OS will be built as a raw disk image, useful for direct disk writing.
301-
- `vhd`: The OS will be built as a VHD (Virtual Hard Disk) file, commonly used in virtual environments.
327+
**Note:** The tool previously supported JSON build specifications but now exclusively uses YAML image templates. The JSON format has been removed to simplify the architecture and improve maintainability.
302328

303-
##### 7. `kernel`
329+
For reference, the old JSON format looked like this:
304330

305-
**Description:** Defines the kernel version and allows customization of the kernel command line.
306-
**Attributes:**
307-
308-
- `version`: Specifies the kernel version to be used.
309-
**Example:** `"5.10.0"`
310-
- `cmdline`: Provides additional kernel command-line parameters.
311-
**Example:** `"quiet splash"`
331+
```json
332+
{
333+
"distro": "eLxr",
334+
"version": "12",
335+
"arch": "x86_64",
336+
"packages": ["cloud-init", "rsyslog"],
337+
"immutable": true,
338+
"output": "iso",
339+
"kernel": { "version": "5.10.0", "cmdline": "quiet splash" }
340+
}
341+
```
312342

313-
Run the sample JSON files against the defined [schema](schema/os-image-composer.schema.json).
314-
There are two sample JSON files, one [valid](/testdata/valid.json) and one with
315-
[invalid](testdata/invalid.json) content.
343+
This has been replaced with the more flexible and intuitive YAML template format shown above.
316344

317345
### Shell Completion
318346

@@ -385,17 +413,101 @@ build completion config help validate version
385413
./image-composer build --<TAB>
386414
--cache-dir --config --help --log-level --verbose --work-dir --workers
387415
388-
# Tab-complete JSON files for spec file argument
416+
# Tab-complete YAML files for template file argument
389417
./image-composer build <TAB>
390-
# Will show JSON files in the current directory
418+
# Will show YAML files in the current directory
391419
```
392420

393-
The tool is specifically configured to suggest JSON files when completing the spec file argument for the build and validate commands.
421+
The tool is specifically configured to suggest YAML files when completing the template file argument for the build and validate commands.
422+
423+
## Template Examples
424+
425+
### Minimal Edge Device
426+
427+
```yaml
428+
image:
429+
name: minimal-edge
430+
version: "1.0.0"
431+
432+
target:
433+
os: azure-linux
434+
dist: azl3
435+
arch: x86_64
436+
imageType: raw
437+
438+
systemConfigs:
439+
- name: minimal
440+
description: Minimal edge device configuration
441+
packages:
442+
- openssh-server
443+
- ca-certificates
444+
kernel:
445+
version: "6.12"
446+
cmdline: "quiet"
447+
```
448+
449+
### Development Environment
450+
451+
```yaml
452+
image:
453+
name: dev-environment
454+
version: "1.0.0"
455+
456+
target:
457+
os: azure-linux
458+
dist: azl3
459+
arch: x86_64
460+
imageType: raw
461+
462+
systemConfigs:
463+
- name: development
464+
description: Development environment with tools
465+
packages:
466+
- openssh-server
467+
- git
468+
- docker-ce
469+
- vim
470+
- curl
471+
- wget
472+
- python3
473+
kernel:
474+
version: "6.12"
475+
cmdline: "quiet splash"
476+
```
477+
478+
### Edge Microvisor Toolkit
479+
480+
```yaml
481+
image:
482+
name: emt-edge-device
483+
version: "1.0.0"
484+
485+
target:
486+
os: emt
487+
dist: emt3
488+
arch: x86_64
489+
imageType: raw
490+
491+
systemConfigs:
492+
- name: edge
493+
description: Edge Microvisor Toolkit configuration
494+
packages:
495+
- openssh-server
496+
- docker-ce
497+
- edge-runtime
498+
- telemetry-agent
499+
kernel:
500+
version: "6.12"
501+
cmdline: "quiet splash systemd.unified_cgroup_hierarchy=0"
502+
```
394503

395504
## Getting Help
396505

397-
Run `./image-composer --help` to see all available commands and options.
506+
- **Quick Reference**: Run `./image-composer --help` to see all available commands and options
507+
- **Complete Guide**: See the [CLI Specification](./image-composer-cli-specification.md) for detailed documentation
508+
- **Examples**: Check the [template examples](#template-examples) section below
509+
- **Troubleshooting**: Refer to the [Build Process documentation](./image-composer-build-process.md#troubleshooting-build-issues)
398510

399511
## Contributing
400512

401-
## License Information
513+
## License Information

0 commit comments

Comments
 (0)