Initial commit: Comprehensive Debian bootc documentation
- Complete documentation for all bootc commands and subcommands - Debian-specific adaptations and workarounds - Manual installation methods to bypass bootc reliability issues - Technical guides with Rust source code analysis - Flowcharts and external command references - Hidden command documentation (bootc internals, state, etc.) - Composefs integration analysis - Base image creation guides (with and without bootc binary) - Management scripts and automation - Comprehensive troubleshooting and examples
This commit is contained in:
robojerk
commit
526f1c1afd
67 changed files with 34174 additions and 0 deletions
616
image/bootc-image-technical-guide.md
Normal file
616
image/bootc-image-technical-guide.md
Normal file
|
|
@ -0,0 +1,616 @@
|
|||
# bootc image - Technical Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc image` is a command for managing container images in the bootc storage system. It provides operations for listing, copying, and managing container images that are distinct from the standard `podman` image storage. The command operates on bootc's own container storage and provides integration with the broader container ecosystem.
|
||||
|
||||
## Purpose
|
||||
|
||||
The image command serves several critical functions:
|
||||
|
||||
1. **Image Listing**: List images stored in bootc storage
|
||||
2. **Image Copying**: Copy images between storage systems
|
||||
3. **Storage Management**: Manage bootc's container storage
|
||||
4. **Podman Integration**: Provide wrapper commands for podman operations
|
||||
5. **Image Discovery**: Discover and manage host and logical images
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc image <COMMAND> [OPTIONS...]
|
||||
```
|
||||
|
||||
### Available Commands
|
||||
|
||||
| Command | Description | Purpose |
|
||||
|---------|-------------|---------|
|
||||
| `list` | List fetched images stored in bootc storage | Display available images |
|
||||
| `copy-to-storage` | Copy image from bootc storage to containers-storage | Export images |
|
||||
| `pull-from-default-storage` | Copy image from default containers-storage to bootc storage | Import images |
|
||||
| `cmd` | Wrapper for selected podman image subcommands | Podman integration |
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### 1. Image Command Structure
|
||||
|
||||
```rust
|
||||
pub(crate) enum ImageOpts {
|
||||
List {
|
||||
list_type: ImageListType,
|
||||
list_format: ImageListFormat,
|
||||
},
|
||||
CopyToStorage {
|
||||
source: Option<String>,
|
||||
target: Option<String>,
|
||||
},
|
||||
PullFromDefaultStorage {
|
||||
image: String,
|
||||
},
|
||||
Cmd(ImageCmdOpts),
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Image List Types
|
||||
|
||||
```rust
|
||||
pub(crate) enum ImageListType {
|
||||
All, // List all images
|
||||
Logical, // List only logically bound images
|
||||
Host, // List only host images
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Image List Formats
|
||||
|
||||
```rust
|
||||
pub(crate) enum ImageListFormat {
|
||||
Table, // Human readable table format
|
||||
Json, // JSON format
|
||||
}
|
||||
```
|
||||
|
||||
## Image Listing
|
||||
|
||||
### 1. List Command
|
||||
|
||||
```bash
|
||||
# List all images
|
||||
bootc image list
|
||||
|
||||
# List with specific type
|
||||
bootc image list --type=host
|
||||
|
||||
# List in JSON format
|
||||
bootc image list --format=json
|
||||
```
|
||||
|
||||
### 2. Image Types
|
||||
|
||||
#### Host Images
|
||||
- **Source**: Images stored in OSTree repository
|
||||
- **Location**: `/sysroot/ostree/repo`
|
||||
- **Purpose**: Images used by bootc deployments
|
||||
- **Management**: Managed by bootc upgrade/switch
|
||||
|
||||
#### Logical Images
|
||||
- **Source**: Images referenced by deployments
|
||||
- **Location**: Bound image references
|
||||
- **Purpose**: Images that can be deployed
|
||||
- **Management**: Referenced but not necessarily stored locally
|
||||
|
||||
### 3. List Implementation
|
||||
|
||||
```rust
|
||||
pub(crate) async fn list_images(list_type: ImageListType) -> Result<Vec<ImageOutput>> {
|
||||
let rootfs = cap_std::fs::Dir::open_ambient_dir("/", cap_std::ambient_authority())?;
|
||||
let sysroot = if ostree_booted()? {
|
||||
Some(crate::cli::get_storage().await?)
|
||||
} else {
|
||||
None
|
||||
};
|
||||
|
||||
Ok(match (list_type, sysroot) {
|
||||
(ImageListType::All, None) => list_logical_images(&rootfs)?,
|
||||
(ImageListType::All, Some(sysroot)) => list_host_images(&sysroot)?
|
||||
.into_iter()
|
||||
.chain(list_logical_images(&rootfs)?)
|
||||
.collect(),
|
||||
(ImageListType::Logical, _) => list_logical_images(&rootfs)?,
|
||||
(ImageListType::Host, None) => {
|
||||
bail!("Listing host images requires a booted bootc system")
|
||||
}
|
||||
(ImageListType::Host, Some(sysroot)) => list_host_images(&sysroot)?,
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
## Image Copying
|
||||
|
||||
### 1. Copy to Storage
|
||||
|
||||
```bash
|
||||
# Copy current booted image to containers-storage
|
||||
bootc image copy-to-storage
|
||||
|
||||
# Copy specific image to containers-storage
|
||||
bootc image copy-to-storage --source=quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Copy to specific target
|
||||
bootc image copy-to-storage --target=localhost/myimage:latest
|
||||
```
|
||||
|
||||
**Purpose**: Export images from bootc storage to standard container storage
|
||||
**Use Cases**:
|
||||
- Making images available to podman
|
||||
- Sharing images with other tools
|
||||
- Backup and migration
|
||||
|
||||
### 2. Pull from Default Storage
|
||||
|
||||
```bash
|
||||
# Pull image from default containers-storage
|
||||
bootc image pull-from-default-storage quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
**Purpose**: Import images from standard container storage to bootc storage
|
||||
**Use Cases**:
|
||||
- Importing images built with podman
|
||||
- Migrating images from other systems
|
||||
- Testing with locally built images
|
||||
|
||||
### 3. Copy Implementation
|
||||
|
||||
```rust
|
||||
pub(crate) async fn push_entrypoint(
|
||||
source: Option<&str>,
|
||||
target: Option<&str>,
|
||||
) -> Result<()> {
|
||||
let sysroot = get_storage().await?;
|
||||
let imgstore = sysroot.get_ensure_imgstore()?;
|
||||
|
||||
let source = source.unwrap_or_else(|| {
|
||||
// Get current booted image
|
||||
get_current_booted_image(&sysroot)
|
||||
});
|
||||
|
||||
let target = target.unwrap_or(IMAGE_DEFAULT);
|
||||
|
||||
// Copy image from bootc storage to containers-storage
|
||||
imgstore.copy_to_containers_storage(&source, &target).await?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Podman Integration
|
||||
|
||||
### 1. Command Wrapper
|
||||
|
||||
```bash
|
||||
# List images using podman
|
||||
bootc image cmd list
|
||||
|
||||
# Build image using podman
|
||||
bootc image cmd build -t myimage:latest .
|
||||
|
||||
# Pull image using podman
|
||||
bootc image cmd pull quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Push image using podman
|
||||
bootc image cmd push myimage:latest
|
||||
```
|
||||
|
||||
### 2. Supported Commands
|
||||
|
||||
| Command | Description | Podman Equivalent |
|
||||
|---------|-------------|-------------------|
|
||||
| `list` | List images | `podman image list` |
|
||||
| `build` | Build image | `podman image build` |
|
||||
| `pull` | Pull image | `podman image pull` |
|
||||
| `push` | Push image | `podman image push` |
|
||||
|
||||
### 3. Command Implementation
|
||||
|
||||
```rust
|
||||
pub(crate) async fn imgcmd_entrypoint(
|
||||
imgstore: &CStorage,
|
||||
cmd: &str,
|
||||
args: &[OsString],
|
||||
) -> Result<()> {
|
||||
let mut cmd = imgstore.new_image_cmd()?;
|
||||
cmd.arg(cmd);
|
||||
cmd.args(args);
|
||||
|
||||
let status = cmd.status()?;
|
||||
if !status.success() {
|
||||
std::process::exit(status.code().unwrap_or(1));
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Storage Management
|
||||
|
||||
### 1. Bootc Storage
|
||||
|
||||
**Location**: `/var/lib/bootc/containers/`
|
||||
**Purpose**: Bootc's dedicated container storage
|
||||
**Features**:
|
||||
- Isolated from system podman storage
|
||||
- Optimized for bootc operations
|
||||
- Integrated with OSTree
|
||||
|
||||
### 2. Storage Operations
|
||||
|
||||
#### List Images
|
||||
```rust
|
||||
pub(crate) async fn list_images(&self) -> Result<Vec<ImageListEntry>> {
|
||||
let mut cmd = self.new_image_cmd()?;
|
||||
cmd.args(["list", "--format=json"]);
|
||||
cmd.stdin(Stdio::null());
|
||||
|
||||
let mut stdout = tempfile::tempfile()?;
|
||||
cmd.stdout(stdout.try_clone()?);
|
||||
|
||||
let status = cmd.status()?;
|
||||
if !status.success() {
|
||||
// Handle error
|
||||
}
|
||||
|
||||
// Parse JSON output
|
||||
stdout.rewind()?;
|
||||
let images: Vec<ImageListEntry> = serde_json::from_reader(stdout)?;
|
||||
Ok(images)
|
||||
}
|
||||
```
|
||||
|
||||
#### Check Image Exists
|
||||
```rust
|
||||
pub(crate) async fn exists(&self, image: &str) -> Result<bool> {
|
||||
let mut cmd = AsyncCommand::from(self.new_image_cmd()?);
|
||||
cmd.args(["exists", image]);
|
||||
Ok(cmd.status().await?.success())
|
||||
}
|
||||
```
|
||||
|
||||
#### Pull Image
|
||||
```rust
|
||||
pub(crate) async fn pull(&self, image: &str, mode: PullMode) -> Result<bool> {
|
||||
match mode {
|
||||
PullMode::IfNotExists => {
|
||||
if self.exists(image).await? {
|
||||
return Ok(false);
|
||||
}
|
||||
}
|
||||
PullMode::Always => {}
|
||||
};
|
||||
|
||||
let mut cmd = self.new_image_cmd()?;
|
||||
cmd.args(["pull", image]);
|
||||
|
||||
let status = cmd.status()?;
|
||||
Ok(status.success())
|
||||
}
|
||||
```
|
||||
|
||||
## Image Types and Sources
|
||||
|
||||
### 1. Host Images
|
||||
|
||||
**Definition**: Images stored in the OSTree repository
|
||||
**Location**: `/sysroot/ostree/repo`
|
||||
**Management**: Managed by bootc operations
|
||||
**Use Cases**: Deployed images, system images
|
||||
|
||||
```rust
|
||||
fn list_host_images(sysroot: &crate::store::Storage) -> Result<Vec<ImageOutput>> {
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let repo = ostree.repo();
|
||||
let images = ostree_ext::container::store::list_images(&repo)?;
|
||||
|
||||
Ok(images
|
||||
.into_iter()
|
||||
.map(|img| ImageOutput {
|
||||
image_type: ImageListTypeColumn::Host,
|
||||
image: img,
|
||||
})
|
||||
.collect())
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Logical Images
|
||||
|
||||
**Definition**: Images referenced by deployments but not necessarily stored
|
||||
**Location**: Bound image references
|
||||
**Management**: Referenced by deployment configurations
|
||||
**Use Cases**: Available for deployment, referenced images
|
||||
|
||||
```rust
|
||||
fn list_logical_images(rootfs: &Dir) -> Result<Vec<ImageOutput>> {
|
||||
let bound_images = query_bound_images(rootfs)?;
|
||||
|
||||
Ok(bound_images
|
||||
.into_iter()
|
||||
.map(|img| ImageOutput {
|
||||
image_type: ImageListTypeColumn::Logical,
|
||||
image: img.image,
|
||||
})
|
||||
.collect())
|
||||
}
|
||||
```
|
||||
|
||||
## Image Operations
|
||||
|
||||
### 1. Image Copying Process
|
||||
|
||||
```rust
|
||||
pub(crate) async fn copy_to_containers_storage(
|
||||
&self,
|
||||
source: &str,
|
||||
target: &str,
|
||||
) -> Result<()> {
|
||||
// 1. Verify source image exists
|
||||
if !self.exists(source).await? {
|
||||
bail!("Source image not found: {}", source);
|
||||
}
|
||||
|
||||
// 2. Create target storage if needed
|
||||
self.ensure_storage_exists()?;
|
||||
|
||||
// 3. Copy image using podman
|
||||
let mut cmd = self.new_image_cmd()?;
|
||||
cmd.args(["tag", source, target]);
|
||||
|
||||
let status = cmd.status()?;
|
||||
if !status.success() {
|
||||
bail!("Failed to copy image: {}", source);
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Image Pulling Process
|
||||
|
||||
```rust
|
||||
pub(crate) async fn pull_from_host_storage(&self, image: &str) -> Result<()> {
|
||||
let mut cmd = Command::new("podman");
|
||||
cmd.stdin(Stdio::null());
|
||||
cmd.stdout(Stdio::null());
|
||||
|
||||
// Set up storage roots
|
||||
let temp_runroot = TempDir::new(cap_std::ambient_authority())?;
|
||||
bind_storage_roots(&mut cmd, &self.storage_root, &temp_runroot)?;
|
||||
|
||||
// Copy from host storage to bootc storage
|
||||
let storage_dest = &format!(
|
||||
"containers-storage:[overlay@{}+/proc/self/fd/{}]",
|
||||
STORAGE_ALIAS_DIR, STORAGE_RUN_FD
|
||||
);
|
||||
|
||||
cmd.args(["tag", image, storage_dest]);
|
||||
|
||||
let status = cmd.status()?;
|
||||
if !status.success() {
|
||||
bail!("Failed to pull image from host storage: {}", image);
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Common Errors
|
||||
|
||||
#### Image Not Found
|
||||
```bash
|
||||
Error: Source image not found: quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
**Solution**: Verify image exists in bootc storage
|
||||
```bash
|
||||
bootc image list
|
||||
```
|
||||
|
||||
#### Storage Not Available
|
||||
```bash
|
||||
Error: Bootc storage not available
|
||||
```
|
||||
|
||||
**Solution**: Check storage initialization
|
||||
```bash
|
||||
bootc status
|
||||
```
|
||||
|
||||
#### Permission Denied
|
||||
```bash
|
||||
Error: Permission denied
|
||||
```
|
||||
|
||||
**Solution**: Run with appropriate privileges
|
||||
```bash
|
||||
sudo bootc image list
|
||||
```
|
||||
|
||||
### 2. Error Recovery
|
||||
|
||||
#### Storage Corruption
|
||||
```bash
|
||||
# Reinitialize storage
|
||||
bootc image cmd prune -a
|
||||
|
||||
# Rebuild storage
|
||||
bootc image cmd build --no-cache
|
||||
```
|
||||
|
||||
#### Image Corruption
|
||||
```bash
|
||||
# Remove corrupted image
|
||||
bootc image cmd rmi corrupted-image
|
||||
|
||||
# Re-pull image
|
||||
bootc image cmd pull quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### 1. Development Workflow
|
||||
|
||||
```bash
|
||||
# Build image with podman
|
||||
bootc image cmd build -t myimage:latest .
|
||||
|
||||
# Copy to bootc storage
|
||||
bootc image copy-to-storage --source=myimage:latest
|
||||
|
||||
# Deploy image
|
||||
bootc switch myimage:latest
|
||||
```
|
||||
|
||||
### 2. Production Workflow
|
||||
|
||||
```bash
|
||||
# Pull production image
|
||||
bootc image cmd pull quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Copy to bootc storage
|
||||
bootc image copy-to-storage --source=quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Deploy image
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
### 3. Backup and Migration
|
||||
|
||||
```bash
|
||||
# List all images
|
||||
bootc image list --format=json > images.json
|
||||
|
||||
# Copy images to standard storage
|
||||
bootc image copy-to-storage --source=image1
|
||||
bootc image copy-to-storage --source=image2
|
||||
|
||||
# Export with podman
|
||||
podman save -o backup.tar localhost/bootc
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### 1. Storage Efficiency
|
||||
|
||||
**Image Deduplication**: Bootc storage uses OSTree for efficient storage
|
||||
**Layer Sharing**: Common layers are shared between images
|
||||
**Compression**: Images are compressed for storage efficiency
|
||||
|
||||
### 2. Operation Performance
|
||||
|
||||
**Parallel Operations**: Multiple operations can run in parallel
|
||||
**Caching**: Frequently accessed images are cached
|
||||
**Lazy Loading**: Images are loaded on demand
|
||||
|
||||
### 3. Storage Management
|
||||
|
||||
**Cleanup**: Regular cleanup of unused images
|
||||
**Garbage Collection**: Automatic garbage collection of unused layers
|
||||
**Space Monitoring**: Monitor storage usage
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Image Verification
|
||||
|
||||
**Signature Verification**: Images are verified using container signatures
|
||||
**Integrity Checks**: Image integrity is verified during operations
|
||||
**Access Control**: Proper access control for storage operations
|
||||
|
||||
### 2. Storage Isolation
|
||||
|
||||
**Separate Storage**: Bootc storage is isolated from system storage
|
||||
**Permission Management**: Proper permissions for storage access
|
||||
**Audit Logging**: Operations are logged for audit purposes
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
#### Images Not Listed
|
||||
```bash
|
||||
# Check storage status
|
||||
bootc status
|
||||
|
||||
# Verify storage initialization
|
||||
ls -la /var/lib/bootc/containers/
|
||||
```
|
||||
|
||||
#### Copy Operations Fail
|
||||
```bash
|
||||
# Check source image
|
||||
bootc image list
|
||||
|
||||
# Check target storage
|
||||
podman images
|
||||
```
|
||||
|
||||
#### Podman Commands Fail
|
||||
```bash
|
||||
# Check podman installation
|
||||
podman --version
|
||||
|
||||
# Check storage configuration
|
||||
podman info
|
||||
```
|
||||
|
||||
### 2. Debug Commands
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug bootc image list
|
||||
|
||||
# Check storage details
|
||||
bootc image cmd list --format=json
|
||||
|
||||
# Verify image integrity
|
||||
bootc image cmd inspect image-name
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Image Management
|
||||
|
||||
- **Regular Cleanup**: Clean up unused images regularly
|
||||
- **Image Tagging**: Use meaningful tags for images
|
||||
- **Version Control**: Keep track of image versions
|
||||
- **Backup Strategy**: Implement backup strategy for important images
|
||||
|
||||
### 2. Storage Management
|
||||
|
||||
- **Monitor Usage**: Monitor storage usage regularly
|
||||
- **Optimize Storage**: Use efficient storage configurations
|
||||
- **Cleanup Policies**: Implement cleanup policies
|
||||
- **Backup Storage**: Backup storage configurations
|
||||
|
||||
### 3. Integration
|
||||
|
||||
- **Automation**: Automate image operations where possible
|
||||
- **Monitoring**: Monitor image operations
|
||||
- **Documentation**: Document image management procedures
|
||||
- **Testing**: Test image operations regularly
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Planned Features
|
||||
|
||||
- **Image Signing**: Enhanced image signing capabilities
|
||||
- **Image Encryption**: Image encryption support
|
||||
- **Advanced Filtering**: More advanced image filtering
|
||||
- **Bulk Operations**: Bulk image operations
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
- **Registry Integration**: Better registry integration
|
||||
- **CI/CD Integration**: Enhanced CI/CD integration
|
||||
- **Monitoring Integration**: Better monitoring integration
|
||||
- **API Support**: REST API for image operations
|
||||
|
||||
This technical guide provides comprehensive understanding of the bootc image system's architecture, implementation, and usage patterns.
|
||||
Loading…
Add table
Add a link
Reference in a new issue