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
897
switch/bootc-switch-external-commands.md
Normal file
897
switch/bootc-switch-external-commands.md
Normal file
|
|
@ -0,0 +1,897 @@
|
|||
# bootc switch - External Commands Reference
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive reference for all external commands, system services, and tools that interact with or are used by the `bootc switch` system. Understanding these external dependencies is crucial for troubleshooting, monitoring, and integrating bootc switch into larger systems.
|
||||
|
||||
## Core System Commands
|
||||
|
||||
### 1. bootc Commands
|
||||
|
||||
#### bootc switch
|
||||
**Purpose**: Switch to different container image reference
|
||||
**Usage**: `bootc switch [OPTIONS...] <TARGET>`
|
||||
**External Dependencies**:
|
||||
- `ostree` - For deployment management
|
||||
- `podman` - For container registry access
|
||||
- `systemd` - For service management and reboot
|
||||
|
||||
```bash
|
||||
# Switch to different image version
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Switch and apply immediately
|
||||
bootc switch --apply quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Switch with soft reboot
|
||||
bootc switch --apply --soft-reboot=auto quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Switch with specific transport
|
||||
bootc switch --transport=oci-archive quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
#### bootc status
|
||||
**Purpose**: Check system status and deployment state
|
||||
**Usage**: `bootc status [OPTIONS...]`
|
||||
**External Dependencies**:
|
||||
- `ostree` - For deployment information
|
||||
- `systemd` - For service status
|
||||
|
||||
```bash
|
||||
# Check current status
|
||||
bootc status
|
||||
|
||||
# Check status in JSON format
|
||||
bootc status --json
|
||||
|
||||
# Check specific deployment
|
||||
bootc status --deployment=deployment-id
|
||||
```
|
||||
|
||||
#### bootc upgrade
|
||||
**Purpose**: Update current image to newer version
|
||||
**Usage**: `bootc upgrade [OPTIONS...]`
|
||||
**External Dependencies**:
|
||||
- `ostree` - For deployment management
|
||||
- `podman` - For container registry access
|
||||
|
||||
```bash
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
|
||||
# Download and stage updates
|
||||
bootc upgrade
|
||||
|
||||
# Apply updates and reboot
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
#### bootc rollback
|
||||
**Purpose**: Rollback to previous deployment
|
||||
**Usage**: `bootc rollback [OPTIONS...]`
|
||||
**External Dependencies**:
|
||||
- `ostree` - For deployment switching
|
||||
- `systemd` - For service management
|
||||
|
||||
```bash
|
||||
# Rollback to previous version
|
||||
bootc rollback
|
||||
|
||||
# Rollback to specific deployment
|
||||
bootc rollback --deployment=deployment-id
|
||||
```
|
||||
|
||||
### 2. OSTree Commands
|
||||
|
||||
#### ostree admin status
|
||||
**Purpose**: Check OSTree deployment status
|
||||
**Usage**: `ostree admin status`
|
||||
**Integration**: Used by `bootc status` for deployment information
|
||||
|
||||
```bash
|
||||
# Check deployment status
|
||||
ostree admin status
|
||||
|
||||
# Check specific deployment
|
||||
ostree admin status --deployment=deployment-id
|
||||
```
|
||||
|
||||
#### ostree admin deploy
|
||||
**Purpose**: Deploy new OSTree deployment
|
||||
**Usage**: `ostree admin deploy [OPTIONS...]`
|
||||
**Integration**: Used internally by bootc for staging updates
|
||||
|
||||
```bash
|
||||
# Deploy new deployment
|
||||
ostree admin deploy --os=debian-bootc deployment-id
|
||||
|
||||
# Deploy with specific options
|
||||
ostree admin deploy --os=debian-bootc --karg=console=ttyS0 deployment-id
|
||||
```
|
||||
|
||||
#### ostree admin rollback
|
||||
**Purpose**: Rollback to previous deployment
|
||||
**Usage**: `ostree admin rollback [OPTIONS...]`
|
||||
**Integration**: Used by `bootc rollback` for deployment switching
|
||||
|
||||
```bash
|
||||
# Rollback to previous deployment
|
||||
ostree admin rollback
|
||||
|
||||
# Rollback with specific options
|
||||
ostree admin rollback --deployment=deployment-id
|
||||
```
|
||||
|
||||
#### ostree admin cleanup
|
||||
**Purpose**: Clean up old deployments and free space
|
||||
**Usage**: `ostree admin cleanup [OPTIONS...]`
|
||||
**Integration**: Used for disk space management
|
||||
|
||||
```bash
|
||||
# Clean up old deployments
|
||||
ostree admin cleanup
|
||||
|
||||
# Clean up with specific options
|
||||
ostree admin cleanup --keep=2
|
||||
```
|
||||
|
||||
#### ostree refs
|
||||
**Purpose**: List OSTree references
|
||||
**Usage**: `ostree refs [OPTIONS...]`
|
||||
**Integration**: Used for reference management
|
||||
|
||||
```bash
|
||||
# List all references
|
||||
ostree refs
|
||||
|
||||
# List references for specific remote
|
||||
ostree refs --remote=quay.io
|
||||
|
||||
# List references with details
|
||||
ostree refs --list
|
||||
```
|
||||
|
||||
### 3. Container Registry Commands
|
||||
|
||||
#### podman pull
|
||||
**Purpose**: Pull container images from registry
|
||||
**Usage**: `podman pull [OPTIONS...] IMAGE`
|
||||
**Integration**: Used by bootc for downloading images
|
||||
|
||||
```bash
|
||||
# Pull image from registry
|
||||
podman pull quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Pull with authentication
|
||||
podman pull --creds=username:password quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Pull specific tag
|
||||
podman pull quay.io/myorg/debian-bootc:latest
|
||||
```
|
||||
|
||||
#### podman login
|
||||
**Purpose**: Authenticate with container registry
|
||||
**Usage**: `podman login [OPTIONS...] REGISTRY`
|
||||
**Integration**: Required for private registry access
|
||||
|
||||
```bash
|
||||
# Login to registry
|
||||
podman login quay.io
|
||||
|
||||
# Login with specific credentials
|
||||
podman login --username=myuser --password=mypass quay.io
|
||||
|
||||
# Login with token
|
||||
podman login --authfile=/path/to/auth.json quay.io
|
||||
```
|
||||
|
||||
#### podman inspect
|
||||
**Purpose**: Inspect container image metadata
|
||||
**Usage**: `podman inspect [OPTIONS...] IMAGE`
|
||||
**Integration**: Used for image validation and metadata extraction
|
||||
|
||||
```bash
|
||||
# Inspect image
|
||||
podman inspect quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Inspect specific configuration
|
||||
podman inspect --format='{{.Config.Labels}}' quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Inspect manifest
|
||||
podman inspect --format='{{.Manifest}}' quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
#### podman images
|
||||
**Purpose**: List container images
|
||||
**Usage**: `podman images [OPTIONS...]`
|
||||
**Integration**: Used for image management
|
||||
|
||||
```bash
|
||||
# List all images
|
||||
podman images
|
||||
|
||||
# List images with specific format
|
||||
podman images --format "table {{.Repository}} {{.Tag}} {{.ID}}"
|
||||
|
||||
# List images with filters
|
||||
podman images --filter "reference=quay.io/myorg/*"
|
||||
```
|
||||
|
||||
#### podman rmi
|
||||
**Purpose**: Remove container images
|
||||
**Usage**: `podman rmi [OPTIONS...] IMAGE`
|
||||
**Integration**: Used for image cleanup
|
||||
|
||||
```bash
|
||||
# Remove specific image
|
||||
podman rmi quay.io/myorg/debian-bootc:v1.0
|
||||
|
||||
# Remove image by ID
|
||||
podman rmi abc123def456
|
||||
|
||||
# Remove unused images
|
||||
podman image prune
|
||||
```
|
||||
|
||||
### 4. System Management Commands
|
||||
|
||||
#### systemctl
|
||||
**Purpose**: Control systemd services and units
|
||||
**Usage**: `systemctl [COMMAND] [UNIT...]`
|
||||
**Integration**: Used for service management and reboot coordination
|
||||
|
||||
```bash
|
||||
# Check service status
|
||||
systemctl status bootc-fetch-apply-updates.service
|
||||
|
||||
# Start service
|
||||
systemctl start bootc-fetch-apply-updates.service
|
||||
|
||||
# Enable service
|
||||
systemctl enable bootc-fetch-apply-updates.service
|
||||
|
||||
# Restart service
|
||||
systemctl restart bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
#### reboot
|
||||
**Purpose**: Reboot the system
|
||||
**Usage**: `reboot [OPTIONS...]`
|
||||
**Integration**: Used by `bootc switch --apply` for system restart
|
||||
|
||||
```bash
|
||||
# Reboot system
|
||||
reboot
|
||||
|
||||
# Reboot with specific delay
|
||||
reboot +5
|
||||
|
||||
# Reboot with message
|
||||
reboot "Applying bootc switch"
|
||||
```
|
||||
|
||||
#### shutdown
|
||||
**Purpose**: Shutdown the system
|
||||
**Usage**: `shutdown [OPTIONS...]`
|
||||
**Integration**: Used for controlled shutdown before reboot
|
||||
|
||||
```bash
|
||||
# Shutdown system
|
||||
shutdown -h now
|
||||
|
||||
# Shutdown with delay
|
||||
shutdown -h +5
|
||||
|
||||
# Shutdown with message
|
||||
shutdown -h now "Applying bootc switch"
|
||||
```
|
||||
|
||||
## Network and Registry Commands
|
||||
|
||||
### 1. HTTP Clients
|
||||
|
||||
#### curl
|
||||
**Purpose**: HTTP client for registry communication
|
||||
**Usage**: `curl [OPTIONS...] URL`
|
||||
**Integration**: Used for registry API calls and authentication
|
||||
|
||||
```bash
|
||||
# Test registry connectivity
|
||||
curl -I https://quay.io/v2/
|
||||
|
||||
# Check registry API
|
||||
curl -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
|
||||
https://quay.io/v2/myorg/debian-bootc/manifests/v2.0
|
||||
|
||||
# Authenticate with registry
|
||||
curl -u username:password https://quay.io/v2/token
|
||||
```
|
||||
|
||||
#### wget
|
||||
**Purpose**: Download files from web servers
|
||||
**Usage**: `wget [OPTIONS...] URL`
|
||||
**Integration**: Alternative to curl for registry communication
|
||||
|
||||
```bash
|
||||
# Download registry manifest
|
||||
wget -O manifest.json https://quay.io/v2/myorg/debian-bootc/manifests/v2.0
|
||||
|
||||
# Download with authentication
|
||||
wget --user=username --password=password https://quay.io/v2/token
|
||||
```
|
||||
|
||||
### 2. DNS Resolution
|
||||
|
||||
#### dig
|
||||
**Purpose**: DNS lookup tool
|
||||
**Usage**: `dig [OPTIONS...] DOMAIN`
|
||||
**Integration**: Used for DNS resolution troubleshooting
|
||||
|
||||
```bash
|
||||
# Resolve registry domain
|
||||
dig quay.io
|
||||
|
||||
# Check specific DNS record
|
||||
dig quay.io A
|
||||
|
||||
# Check DNS server
|
||||
dig @8.8.8.8 quay.io
|
||||
```
|
||||
|
||||
#### nslookup
|
||||
**Purpose**: DNS lookup tool
|
||||
**Usage**: `nslookup [OPTIONS...] DOMAIN`
|
||||
**Integration**: Alternative to dig for DNS troubleshooting
|
||||
|
||||
```bash
|
||||
# Resolve registry domain
|
||||
nslookup quay.io
|
||||
|
||||
# Check specific DNS record
|
||||
nslookup -type=A quay.io
|
||||
```
|
||||
|
||||
### 3. Network Troubleshooting
|
||||
|
||||
#### ping
|
||||
**Purpose**: Test network connectivity
|
||||
**Usage**: `ping [OPTIONS...] HOST`
|
||||
**Integration**: Used for testing registry connectivity
|
||||
|
||||
```bash
|
||||
# Test connectivity
|
||||
ping quay.io
|
||||
|
||||
# Test with specific count
|
||||
ping -c 4 quay.io
|
||||
|
||||
# Test with specific interface
|
||||
ping -I eth0 quay.io
|
||||
```
|
||||
|
||||
#### traceroute
|
||||
**Purpose**: Trace network path
|
||||
**Usage**: `traceroute [OPTIONS...] HOST`
|
||||
**Integration**: Used for network path analysis
|
||||
|
||||
```bash
|
||||
# Trace path to registry
|
||||
traceroute quay.io
|
||||
|
||||
# Trace with specific options
|
||||
traceroute -n quay.io
|
||||
```
|
||||
|
||||
## File System Commands
|
||||
|
||||
### 1. File Operations
|
||||
|
||||
#### cat
|
||||
**Purpose**: Display file contents
|
||||
**Usage**: `cat [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for displaying configuration files
|
||||
|
||||
```bash
|
||||
# Display file contents
|
||||
cat /etc/bootc/config.yaml
|
||||
|
||||
# Display with line numbers
|
||||
cat -n /etc/bootc/config.yaml
|
||||
|
||||
# Display non-printing characters
|
||||
cat -v /etc/bootc/config.yaml
|
||||
```
|
||||
|
||||
#### cp
|
||||
**Purpose**: Copy files
|
||||
**Usage**: `cp [OPTIONS...] SOURCE DEST`
|
||||
**Integration**: Used for backing up configuration files
|
||||
|
||||
```bash
|
||||
# Copy file
|
||||
cp /etc/bootc/config.yaml /etc/bootc/config.yaml.backup
|
||||
|
||||
# Copy with preserve attributes
|
||||
cp -p /etc/bootc/config.yaml /etc/bootc/config.yaml.backup
|
||||
|
||||
# Copy recursively
|
||||
cp -r /etc/bootc/ /etc/bootc.backup/
|
||||
```
|
||||
|
||||
#### mv
|
||||
**Purpose**: Move or rename files
|
||||
**Usage**: `mv [OPTIONS...] SOURCE DEST`
|
||||
**Integration**: Used for renaming configuration files
|
||||
|
||||
```bash
|
||||
# Rename file
|
||||
mv /etc/bootc/config.yaml /etc/bootc/config.yaml.old
|
||||
|
||||
# Move file
|
||||
mv /etc/bootc/config.yaml /backup/config.yaml
|
||||
```
|
||||
|
||||
#### rm
|
||||
**Purpose**: Remove files
|
||||
**Usage**: `rm [OPTIONS...] FILE...`
|
||||
**Integration**: Used for cleaning up temporary files
|
||||
|
||||
```bash
|
||||
# Remove file
|
||||
rm /etc/bootc/config.yaml
|
||||
|
||||
# Remove with confirmation
|
||||
rm -i /etc/bootc/config.yaml
|
||||
|
||||
# Remove recursively
|
||||
rm -r /etc/bootc/
|
||||
```
|
||||
|
||||
### 2. Directory Operations
|
||||
|
||||
#### mkdir
|
||||
**Purpose**: Create directories
|
||||
**Usage**: `mkdir [OPTIONS...] DIRECTORY...`
|
||||
**Integration**: Used for creating configuration directories
|
||||
|
||||
```bash
|
||||
# Create directory
|
||||
mkdir -p /etc/bootc
|
||||
|
||||
# Create with specific permissions
|
||||
mkdir -m 755 /etc/bootc
|
||||
```
|
||||
|
||||
#### ls
|
||||
**Purpose**: List directory contents
|
||||
**Usage**: `ls [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for listing configuration files
|
||||
|
||||
```bash
|
||||
# List files
|
||||
ls -la /etc/bootc/
|
||||
|
||||
# List with specific format
|
||||
ls -l --time-style=full-iso /etc/bootc/
|
||||
```
|
||||
|
||||
#### find
|
||||
**Purpose**: Search for files
|
||||
**Usage**: `find [PATH...] [EXPRESSION...]`
|
||||
**Integration**: Used for finding configuration files
|
||||
|
||||
```bash
|
||||
# Find configuration files
|
||||
find /etc -name "*.yaml" -type f
|
||||
|
||||
# Find files modified recently
|
||||
find /etc/bootc -mtime -1 -type f
|
||||
```
|
||||
|
||||
## Logging and Monitoring Commands
|
||||
|
||||
### 1. System Logs
|
||||
|
||||
#### journalctl
|
||||
**Purpose**: Query systemd journal
|
||||
**Usage**: `journalctl [OPTIONS...]`
|
||||
**Integration**: Used for service and system log analysis
|
||||
|
||||
```bash
|
||||
# Check bootc service logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
|
||||
# Check recent logs
|
||||
journalctl -n 100
|
||||
|
||||
# Check logs since boot
|
||||
journalctl -b
|
||||
|
||||
# Follow logs in real-time
|
||||
journalctl -f
|
||||
```
|
||||
|
||||
#### dmesg
|
||||
**Purpose**: Display kernel ring buffer
|
||||
**Usage**: `dmesg [OPTIONS...]`
|
||||
**Integration**: Used for kernel-level troubleshooting
|
||||
|
||||
```bash
|
||||
# Display kernel messages
|
||||
dmesg
|
||||
|
||||
# Display recent messages
|
||||
dmesg -T
|
||||
|
||||
# Display with timestamps
|
||||
dmesg -T | tail -50
|
||||
```
|
||||
|
||||
### 2. File Monitoring
|
||||
|
||||
#### tail
|
||||
**Purpose**: Display last lines of files
|
||||
**Usage**: `tail [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for monitoring log files
|
||||
|
||||
```bash
|
||||
# Follow log file
|
||||
tail -f /var/log/bootc.log
|
||||
|
||||
# Display last lines
|
||||
tail -n 100 /var/log/bootc.log
|
||||
```
|
||||
|
||||
#### head
|
||||
**Purpose**: Display first lines of files
|
||||
**Usage**: `head [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for viewing file headers
|
||||
|
||||
```bash
|
||||
# Display first lines
|
||||
head -n 20 /etc/bootc/config.yaml
|
||||
|
||||
# Display first bytes
|
||||
head -c 100 /etc/bootc/config.yaml
|
||||
```
|
||||
|
||||
## Security Commands
|
||||
|
||||
### 1. Signature Verification
|
||||
|
||||
#### gpg
|
||||
**Purpose**: GNU Privacy Guard
|
||||
**Usage**: `gpg [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Used for signature verification
|
||||
|
||||
```bash
|
||||
# Verify signature
|
||||
gpg --verify signature.asc config.yaml
|
||||
|
||||
# Import public key
|
||||
gpg --import public.key
|
||||
|
||||
# List keys
|
||||
gpg --list-keys
|
||||
```
|
||||
|
||||
#### openssl
|
||||
**Purpose**: OpenSSL command line tool
|
||||
**Usage**: `openssl [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Used for certificate and key management
|
||||
|
||||
```bash
|
||||
# Check certificate
|
||||
openssl x509 -in certificate.crt -text -noout
|
||||
|
||||
# Verify certificate chain
|
||||
openssl verify -CAfile ca.crt certificate.crt
|
||||
|
||||
# Generate key pair
|
||||
openssl genrsa -out private.key 2048
|
||||
```
|
||||
|
||||
### 2. File Permissions
|
||||
|
||||
#### chmod
|
||||
**Purpose**: Change file permissions
|
||||
**Usage**: `chmod [OPTIONS...] MODE FILE...`
|
||||
**Integration**: Used for setting file permissions
|
||||
|
||||
```bash
|
||||
# Set permissions
|
||||
chmod 644 /etc/bootc/config.yaml
|
||||
|
||||
# Set permissions recursively
|
||||
chmod -R 755 /etc/bootc
|
||||
```
|
||||
|
||||
#### chown
|
||||
**Purpose**: Change file ownership
|
||||
**Usage**: `chown [OPTIONS...] OWNER[:GROUP] FILE...`
|
||||
**Integration**: Used for setting file ownership
|
||||
|
||||
```bash
|
||||
# Change ownership
|
||||
chown root:root /etc/bootc/config.yaml
|
||||
|
||||
# Change ownership recursively
|
||||
chown -R root:root /etc/bootc
|
||||
```
|
||||
|
||||
## Performance Monitoring Commands
|
||||
|
||||
### 1. System Resources
|
||||
|
||||
#### top
|
||||
**Purpose**: Display running processes
|
||||
**Usage**: `top [OPTIONS...]`
|
||||
**Integration**: Used for process monitoring
|
||||
|
||||
```bash
|
||||
# Display processes
|
||||
top
|
||||
|
||||
# Display specific process
|
||||
top -p $(pgrep bootc)
|
||||
```
|
||||
|
||||
#### htop
|
||||
**Purpose**: Interactive process viewer
|
||||
**Usage**: `htop [OPTIONS...]`
|
||||
**Integration**: Used for system resource monitoring
|
||||
|
||||
```bash
|
||||
# Start htop
|
||||
htop
|
||||
|
||||
# Monitor specific process
|
||||
htop -p $(pgrep bootc)
|
||||
```
|
||||
|
||||
#### free
|
||||
**Purpose**: Display memory usage
|
||||
**Usage**: `free [OPTIONS...]`
|
||||
**Integration**: Used for memory monitoring
|
||||
|
||||
```bash
|
||||
# Display memory usage
|
||||
free -h
|
||||
|
||||
# Display in specific format
|
||||
free -m
|
||||
```
|
||||
|
||||
### 2. Disk Usage
|
||||
|
||||
#### df
|
||||
**Purpose**: Display filesystem disk space usage
|
||||
**Usage**: `df [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for disk space monitoring
|
||||
|
||||
```bash
|
||||
# Check disk usage
|
||||
df -h
|
||||
|
||||
# Check specific filesystem
|
||||
df -h /sysroot
|
||||
|
||||
# Check inode usage
|
||||
df -i
|
||||
```
|
||||
|
||||
#### du
|
||||
**Purpose**: Display directory space usage
|
||||
**Usage**: `du [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for directory space analysis
|
||||
|
||||
```bash
|
||||
# Check directory usage
|
||||
du -sh /etc/bootc
|
||||
|
||||
# Check OSTree usage
|
||||
du -sh /sysroot/ostree
|
||||
```
|
||||
|
||||
## Container Runtime Commands
|
||||
|
||||
### 1. Podman Commands
|
||||
|
||||
#### podman run
|
||||
**Purpose**: Run container
|
||||
**Usage**: `podman run [OPTIONS...] IMAGE [COMMAND...]`
|
||||
**Integration**: Used for testing container images
|
||||
|
||||
```bash
|
||||
# Run container
|
||||
podman run -it quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Run with specific options
|
||||
podman run --rm quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Run with environment variables
|
||||
podman run -e VAR=value quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
#### podman ps
|
||||
**Purpose**: List containers
|
||||
**Usage**: `podman ps [OPTIONS...]`
|
||||
**Integration**: Used for container management
|
||||
|
||||
```bash
|
||||
# List running containers
|
||||
podman ps
|
||||
|
||||
# List all containers
|
||||
podman ps -a
|
||||
|
||||
# List with specific format
|
||||
podman ps --format "table {{.Names}} {{.Image}} {{.Status}}"
|
||||
```
|
||||
|
||||
#### podman rm
|
||||
**Purpose**: Remove containers
|
||||
**Usage**: `podman rm [OPTIONS...] CONTAINER...`
|
||||
**Integration**: Used for container cleanup
|
||||
|
||||
```bash
|
||||
# Remove specific container
|
||||
podman rm container-id
|
||||
|
||||
# Remove all stopped containers
|
||||
podman container prune
|
||||
|
||||
# Remove with force
|
||||
podman rm -f container-id
|
||||
```
|
||||
|
||||
### 2. Docker Commands (Alternative)
|
||||
|
||||
#### docker
|
||||
**Purpose**: Alternative container runtime
|
||||
**Usage**: `docker [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Alternative to podman
|
||||
|
||||
```bash
|
||||
# List containers
|
||||
docker ps -a
|
||||
|
||||
# List images
|
||||
docker images
|
||||
|
||||
# Run container
|
||||
docker run -it quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
## Backup and Recovery Commands
|
||||
|
||||
### 1. Archive Commands
|
||||
|
||||
#### tar
|
||||
**Purpose**: Archive files
|
||||
**Usage**: `tar [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for backup creation
|
||||
|
||||
```bash
|
||||
# Create backup
|
||||
tar -czf backup.tar.gz /etc/bootc
|
||||
|
||||
# Extract backup
|
||||
tar -xzf backup.tar.gz
|
||||
|
||||
# List archive contents
|
||||
tar -tzf backup.tar.gz
|
||||
```
|
||||
|
||||
#### rsync
|
||||
**Purpose**: Synchronize files
|
||||
**Usage**: `rsync [OPTIONS...] SRC DEST`
|
||||
**Integration**: Used for backup synchronization
|
||||
|
||||
```bash
|
||||
# Synchronize files
|
||||
rsync -av /etc/bootc/ /backup/bootc/
|
||||
|
||||
# Synchronize with remote
|
||||
rsync -av /etc/bootc/ user@host:/backup/bootc/
|
||||
```
|
||||
|
||||
### 2. Version Control
|
||||
|
||||
#### git
|
||||
**Purpose**: Version control system
|
||||
**Usage**: `git [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Used for configuration version control
|
||||
|
||||
```bash
|
||||
# Initialize repository
|
||||
git init
|
||||
|
||||
# Add files
|
||||
git add /etc/bootc/config.yaml
|
||||
|
||||
# Commit changes
|
||||
git commit -m "Update configuration"
|
||||
|
||||
# Check status
|
||||
git status
|
||||
```
|
||||
|
||||
## System Information Commands
|
||||
|
||||
### 1. System Information
|
||||
|
||||
#### uname
|
||||
**Purpose**: Display system information
|
||||
**Usage**: `uname [OPTIONS...]`
|
||||
**Integration**: Used for system identification
|
||||
|
||||
```bash
|
||||
# Display system information
|
||||
uname -a
|
||||
|
||||
# Display kernel version
|
||||
uname -r
|
||||
|
||||
# Display architecture
|
||||
uname -m
|
||||
```
|
||||
|
||||
#### hostname
|
||||
**Purpose**: Display or set hostname
|
||||
**Usage**: `hostname [OPTIONS...] [NAME]`
|
||||
**Integration**: Used for system identification
|
||||
|
||||
```bash
|
||||
# Display hostname
|
||||
hostname
|
||||
|
||||
# Set hostname
|
||||
hostname newhostname
|
||||
```
|
||||
|
||||
#### whoami
|
||||
**Purpose**: Display current user
|
||||
**Usage**: `whoami [OPTIONS...]`
|
||||
**Integration**: Used for user identification
|
||||
|
||||
```bash
|
||||
# Display current user
|
||||
whoami
|
||||
|
||||
# Display user ID
|
||||
id
|
||||
```
|
||||
|
||||
### 2. Hardware Information
|
||||
|
||||
#### lscpu
|
||||
**Purpose**: Display CPU information
|
||||
**Usage**: `lscpu [OPTIONS...]`
|
||||
**Integration**: Used for system resource analysis
|
||||
|
||||
```bash
|
||||
# Display CPU information
|
||||
lscpu
|
||||
|
||||
# Display in specific format
|
||||
lscpu --extended
|
||||
```
|
||||
|
||||
#### lsblk
|
||||
**Purpose**: List block devices
|
||||
**Usage**: `lsblk [OPTIONS...]`
|
||||
**Integration**: Used for storage device identification
|
||||
|
||||
```bash
|
||||
# List all block devices
|
||||
lsblk
|
||||
|
||||
# List with filesystem information
|
||||
lsblk -f
|
||||
|
||||
# List specific device
|
||||
lsblk /dev/sda
|
||||
```
|
||||
|
||||
This comprehensive external commands reference provides all the tools and commands needed to effectively manage, troubleshoot, and integrate with the bootc switch system.
|
||||
381
switch/bootc-switch-flowchart.md
Normal file
381
switch/bootc-switch-flowchart.md
Normal file
|
|
@ -0,0 +1,381 @@
|
|||
# bootc switch - Process Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a visual representation of the `bootc switch` process flow, showing the decision points, operations, and state transitions involved in switching container image references.
|
||||
|
||||
## Main Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc switch │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Parse Target Image │
|
||||
│ │
|
||||
│ • Parse transport type (registry, oci, oci-archive, etc.) │
|
||||
│ • Create ImageReference structure │
|
||||
│ • Configure signature verification policy │
|
||||
│ • Convert to OSTreeImageReference │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Operation Mode │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ In-Place Mutation? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ In-Place ││ │ │ Normal Switch Process ││ │
|
||||
│ │ │ Switch ││ │ │ ││ │
|
||||
│ │ │ • Find ││ │ │ • Get system storage ││ │
|
||||
│ │ │ deployment││ │ │ • Get OSTree repository ││ │
|
||||
│ │ │ • Update ││ │ │ • Get current system status ││ │
|
||||
│ │ │ origin ││ │ │ • Create new specification ││ │
|
||||
│ │ │ • Log ││ │ │ • Check for changes ││ │
|
||||
│ │ │ operation ││ │ │ • Pull and stage image ││ │
|
||||
│ │ └─────────────┘│ │ │ • Update system status ││ │
|
||||
│ │ │ │ │ • Handle soft reboot ││ │
|
||||
│ │ ┌─────────────┐│ │ │ • Apply changes if requested ││ │
|
||||
│ │ │ Return ││ │ └─────────────────────────────────┘│ │
|
||||
│ │ │ Success ││ │ │ │
|
||||
│ │ └─────────────┘│ │ │ │
|
||||
│ └─────────────────┘ │ │ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Get System Status │
|
||||
│ │
|
||||
│ • Get storage interface │
|
||||
│ • Get OSTree repository │
|
||||
│ • Get current system status │
|
||||
│ • Get booted deployment information │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create New Specification │
|
||||
│ │
|
||||
│ • Clone current host specification │
|
||||
│ • Update image reference to target │
|
||||
│ • Preserve other settings (boot order, etc.) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check for Changes │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ new_spec == host.spec? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Print: ││ │ │ Log Switch Operation ││ │
|
||||
│ │ │ "Image ││ │ │ • Log old image reference ││ │
|
||||
│ │ │ specification││ │ │ • Log new image reference ││ │
|
||||
│ │ │ is ││ │ │ • Log transport type ││ │
|
||||
│ │ │ unchanged" ││ │ │ • Log to systemd journal ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ▼ │ │
|
||||
│ │ │ Return ││ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Success ││ │ │ Pull and Stage Image ││ │
|
||||
│ │ └─────────────┘│ │ │ • Authenticate with registry ││ │
|
||||
│ └─────────────────┘ │ │ • Download image layers ││ │
|
||||
│ │ │ • Convert to OSTree format ││ │
|
||||
│ │ │ • Validate image compatibility ││ │
|
||||
│ │ │ • Stage new deployment ││ │
|
||||
│ │ └─────────────────────────────────┘│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Handle Image Retention │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --retain specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Keep ││ │ │ Prune Previous Reference ││ │
|
||||
│ │ │ Previous ││ │ │ • Get booted deployment origin ││ │
|
||||
│ │ │ Image ││ │ │ • Parse OSTree reference ││ │
|
||||
│ │ │ Reference ││ │ │ • Update OSTree reference ││ │
|
||||
│ │ └─────────────┘│ │ │ • Free up disk space ││ │
|
||||
│ └─────────────────┘ │ └─────────────────────────────────┘│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Stage New Deployment │
|
||||
│ │
|
||||
│ • Create new deployment in OSTree │
|
||||
│ • Configure bootloader for new deployment │
|
||||
│ • Update system status │
|
||||
│ • Preserve /etc and /var state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Update System Status │
|
||||
│ │
|
||||
│ • Update system modification time │
|
||||
│ • Refresh system status │
|
||||
│ • Update deployment information │
|
||||
│ • Log configuration changes │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Handle Soft Reboot │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --soft-reboot specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Configure ││ │ │ Skip Soft Reboot ││ │
|
||||
│ │ │ Soft Reboot ││ │ │ ││ │
|
||||
│ │ │ • Check ││ │ │ • Continue to apply check ││ │
|
||||
│ │ │ availability││ │ │ ││ │
|
||||
│ │ │ • Configure ││ │ │ ││ │
|
||||
│ │ │ if needed ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Apply Changes │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --apply specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Reboot ││ │ │ Changes Staged ││ │
|
||||
│ │ │ System ││ │ │ ││ │
|
||||
│ │ │ • Execute ││ │ │ • Changes ready for next boot ││ │
|
||||
│ │ │ reboot ││ │ │ • No immediate action ││ │
|
||||
│ │ │ • Apply ││ │ │ • User can reboot manually ││ │
|
||||
│ │ │ changes ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Image switch completed successfully │
|
||||
│ • New image staged for next boot │
|
||||
│ • System ready for reboot (if --apply) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## In-Place Switch Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ In-Place Switch │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Log Operation │
|
||||
│ │
|
||||
│ • Log to systemd journal with unique message ID │
|
||||
│ • Include image reference and transport type │
|
||||
│ • Mark as in-place switch operation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Find Deployment Directory │
|
||||
│ │
|
||||
│ • Search for deployment directory in /sysroot/ostree/deploy │
|
||||
│ • Locate current booted deployment │
|
||||
│ • Validate deployment structure │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Update Origin File │
|
||||
│ │
|
||||
│ • Read current origin file │
|
||||
│ • Parse origin configuration │
|
||||
│ • Update image reference │
|
||||
│ • Write updated origin file │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Extract Deployment ID │
|
||||
│ │
|
||||
│ • Parse deployment directory name │
|
||||
│ • Extract deployment ID │
|
||||
│ • Return deployment ID for logging │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • In-place switch completed │
|
||||
│ │ • Deployment ID updated │
|
||||
│ │ • Image reference changed │
|
||||
│ │ • System ready for next boot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Classification │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Image │ │ System │ │ Network │ │
|
||||
│ │ Errors │ │ Errors │ │ Errors │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • Invalid │ │ • Not bootc │ │ • Registry │ │
|
||||
│ │ transport │ │ compatible │ │ connectivity │ │
|
||||
│ │ • Image not │ │ • No deployment │ │ • Authentication│ │
|
||||
│ │ found │ │ found │ │ failed │ │
|
||||
│ │ • Signature │ │ • Invalid │ │ • Image pull │ │
|
||||
│ │ verification │ │ state │ │ failed │ │
|
||||
│ │ failed │ │ │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Response │
|
||||
│ │
|
||||
│ • Display error message │
|
||||
│ • Provide context information │
|
||||
│ • Suggest remediation steps │
|
||||
│ • Return appropriate exit code │
|
||||
│ • Clean up any partial state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## State Transitions
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ System States │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Current State │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Image: v1.0 │ │ Image: v1.0 │ │
|
||||
│ │ Boot: normal │ │ Boot: normal │ │
|
||||
│ │ Staged: none │ │ Staged: v2.0 │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Switch Operation │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────────────────────┐ │ │
|
||||
│ │ │ Image │ │ Boot Order │ │ │
|
||||
│ │ │ Change │ │ Change │ │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ │ • Pull new │ │ • Execute rollback │ │ │
|
||||
│ │ │ image │ │ • Update boot order │ │ │
|
||||
│ │ │ • Stage │ │ • Preserve state │ │ │
|
||||
│ │ │ deployment │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ New State │ │ New State │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • Image: v2.0 │ │ • Image: v1.0 │ │
|
||||
│ │ • Boot: normal │ │ • Boot: normal │ │
|
||||
│ │ • Staged: v2.0 │ │ • Rollback: queued │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Transport Type Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Transport Selection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Parse Transport Type │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --transport specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Use ││ │ │ Use Default (registry) ││ │
|
||||
│ │ │ Specified ││ │ │ ││ │
|
||||
│ │ │ Transport ││ │ │ • Set transport to 'registry' ││ │
|
||||
│ │ │ • registry ││ │ │ • Use registry authentication ││ │
|
||||
│ │ │ • oci ││ │ │ • Use HTTPS protocol ││ │
|
||||
│ │ │ • oci- ││ │ │ ││ │
|
||||
│ │ │ archive ││ │ │ ││ │
|
||||
│ │ │ • containers││ │ │ ││ │
|
||||
│ │ │ -storage ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Image Reference │
|
||||
│ │
|
||||
│ • Create ImageReference structure │
|
||||
│ • Set transport type │
|
||||
│ │ • Set image name/tag │
|
||||
│ │ • Configure signature verification │
|
||||
│ │ • Convert to OSTreeImageReference │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This flowchart provides a comprehensive visual representation of the bootc switch process, showing all decision points, operations, and state transitions involved in switching container image references.
|
||||
607
switch/bootc-switch-technical-guide.md
Normal file
607
switch/bootc-switch-technical-guide.md
Normal file
|
|
@ -0,0 +1,607 @@
|
|||
# bootc switch - Technical Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc switch` is a command for changing the container image reference that a bootc-managed system will boot from. It operates similarly to `bootc upgrade` but changes the image source rather than updating the current image. This enables blue/green deployments, A/B testing, and controlled rollouts across different image versions.
|
||||
|
||||
## Purpose
|
||||
|
||||
The switch command serves several critical functions:
|
||||
|
||||
1. **Image Source Management**: Change the container image reference for future boots
|
||||
2. **Blue/Green Deployments**: Switch between different image versions
|
||||
3. **A/B Testing**: Test different image versions on different systems
|
||||
4. **Controlled Rollouts**: Gradually migrate systems to new image versions
|
||||
5. **Rollback Capability**: Switch back to previous image versions
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc switch [OPTIONS...] <TARGET>
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Switch to different image version
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Switch and apply immediately
|
||||
bootc switch --apply quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Switch with soft reboot
|
||||
bootc switch --apply --soft-reboot=auto quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Switch with specific transport
|
||||
bootc switch --transport=oci-archive quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
## Command Options
|
||||
|
||||
### Core Options
|
||||
|
||||
| Option | Description | Default | Required |
|
||||
|--------|-------------|---------|----------|
|
||||
| `TARGET` | Target image to use for next boot | `None` | Yes |
|
||||
| `--apply` | Restart/reboot into new target image | `false` | No |
|
||||
| `--quiet` | Don't display progress | `false` | No |
|
||||
| `--soft-reboot` | Configure soft reboot behavior | `None` | No |
|
||||
|
||||
### Transport Options
|
||||
|
||||
| Option | Description | Default | Values |
|
||||
|--------|-------------|---------|--------|
|
||||
| `--transport` | Container transport type | `registry` | `registry`, `oci`, `oci-archive`, `containers-storage` |
|
||||
|
||||
### Security Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--enforce-container-sigpolicy` | Enforce container signature policy | `false` |
|
||||
|
||||
### Advanced Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--retain` | Retain reference to currently booted image | `false` |
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### 1. Switch Command Structure
|
||||
|
||||
```rust
|
||||
pub(crate) struct SwitchOpts {
|
||||
pub(crate) quiet: bool, // Suppress progress output
|
||||
pub(crate) apply: bool, // Apply and reboot
|
||||
pub(crate) soft_reboot: Option<SoftRebootMode>, // Soft reboot behavior
|
||||
pub(crate) transport: String, // Container transport
|
||||
pub(crate) enforce_container_sigpolicy: bool, // Signature enforcement
|
||||
pub(crate) retain: bool, // Retain current image ref
|
||||
pub(crate) mutate_in_place: bool, // In-place mutation (hidden)
|
||||
pub(crate) progress: ProgressOptions, // Progress reporting
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Switch Process Flow
|
||||
|
||||
```rust
|
||||
async fn switch(opts: SwitchOpts) -> Result<()> {
|
||||
// 1. Parse and validate target image
|
||||
let transport = ostree_container::Transport::try_from(opts.transport.as_str())?;
|
||||
let imgref = ostree_container::ImageReference {
|
||||
transport,
|
||||
name: opts.target.to_string(),
|
||||
};
|
||||
let sigverify = sigpolicy_from_opt(opts.enforce_container_sigpolicy);
|
||||
let target = ostree_container::OstreeImageReference { sigverify, imgref };
|
||||
let target = ImageReference::from(target);
|
||||
|
||||
// 2. Handle in-place mutation (hidden option)
|
||||
if opts.mutate_in_place {
|
||||
let deployid = switch_origin_inplace(&root, &target).await?;
|
||||
println!("Updated {deployid} to pull from {target}");
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
// 3. Get system status
|
||||
let sysroot = &get_storage().await?;
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let repo = &ostree.repo();
|
||||
let (booted_deployment, _deployments, host) =
|
||||
crate::status::get_status_require_booted(ostree)?;
|
||||
|
||||
// 4. Create new specification
|
||||
let new_spec = {
|
||||
let mut new_spec = host.spec.clone();
|
||||
new_spec.image = Some(target.clone());
|
||||
new_spec
|
||||
};
|
||||
|
||||
// 5. Check for changes
|
||||
if new_spec == host.spec {
|
||||
println!("Image specification is unchanged.");
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
// 6. Log switch operation
|
||||
tracing::info!(
|
||||
message_id = SWITCH_JOURNAL_ID,
|
||||
bootc.old_image_reference = old_image,
|
||||
bootc.new_image_reference = &target.image,
|
||||
"Switching from image {} to {}",
|
||||
old_image, target.image
|
||||
);
|
||||
|
||||
// 7. Pull and stage new image
|
||||
let fetched = crate::deploy::pull(repo, &target, None, opts.quiet, prog.clone()).await?;
|
||||
|
||||
// 8. Handle image retention
|
||||
if !opts.retain {
|
||||
// Prune previous ostree ref
|
||||
if let Some(booted_origin) = booted_deployment.origin() {
|
||||
if let Some(ostree_ref) = booted_origin.optional_string("origin", "refspec")? {
|
||||
let (remote, ostree_ref) = ostree::parse_refspec(&ostree_ref)?;
|
||||
repo.set_ref_immediate(remote.as_deref(), &ostree_ref, None, cancellable)?;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 9. Stage new deployment
|
||||
let stateroot = booted_deployment.osname();
|
||||
crate::deploy::stage(sysroot, &stateroot, &fetched, &new_spec, prog.clone()).await?;
|
||||
|
||||
// 10. Update system status
|
||||
sysroot.update_mtime()?;
|
||||
|
||||
// 11. Handle soft reboot
|
||||
if opts.soft_reboot.is_some() {
|
||||
let updated_host = crate::status::get_status(ostree, Some(&booted_deployment))?.1;
|
||||
handle_staged_soft_reboot(ostree, opts.soft_reboot, &updated_host)?;
|
||||
}
|
||||
|
||||
// 12. Apply changes if requested
|
||||
if opts.apply {
|
||||
crate::reboot::reboot()?;
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Image Reference Handling
|
||||
|
||||
### 1. Transport Types
|
||||
|
||||
The switch command supports multiple container transport types:
|
||||
|
||||
#### Registry Transport (default)
|
||||
```bash
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
#### OCI Archive Transport
|
||||
```bash
|
||||
bootc switch --transport=oci-archive /path/to/image.tar
|
||||
```
|
||||
|
||||
#### OCI Transport
|
||||
```bash
|
||||
bootc switch --transport=oci oci:quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
#### Containers Storage Transport
|
||||
```bash
|
||||
bootc switch --transport=containers-storage containers-storage:quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
### 2. Image Reference Parsing
|
||||
|
||||
```rust
|
||||
let transport = ostree_container::Transport::try_from(opts.transport.as_str())?;
|
||||
let imgref = ostree_container::ImageReference {
|
||||
transport,
|
||||
name: opts.target.to_string(),
|
||||
};
|
||||
let sigverify = sigpolicy_from_opt(opts.enforce_container_sigpolicy);
|
||||
let target = ostree_container::OstreeImageReference { sigverify, imgref };
|
||||
```
|
||||
|
||||
**Process**:
|
||||
1. **Transport Parsing**: Convert string to transport enum
|
||||
2. **Image Reference**: Create container image reference
|
||||
3. **Signature Verification**: Configure signature policy
|
||||
4. **OSTree Reference**: Convert to OSTree image reference
|
||||
|
||||
## In-Place Mutation
|
||||
|
||||
### 1. In-Place Switch Implementation
|
||||
|
||||
```rust
|
||||
pub(crate) fn switch_origin_inplace(root: &Dir, imgref: &ImageReference) -> Result<String> {
|
||||
const SWITCH_INPLACE_JOURNAL_ID: &str = "3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7";
|
||||
|
||||
tracing::info!(
|
||||
message_id = SWITCH_INPLACE_JOURNAL_ID,
|
||||
bootc.image.reference = &imgref.image,
|
||||
bootc.image.transport = &imgref.transport,
|
||||
bootc.switch_type = "in_place",
|
||||
"Performing in-place switch to image: {}",
|
||||
imgref
|
||||
);
|
||||
|
||||
// Find deployment directory
|
||||
let deploy_dir = find_deployment_directory(root)?;
|
||||
|
||||
// Update origin file
|
||||
let origin_path = deploy_dir.join("origin");
|
||||
let mut origin = std::fs::read_to_string(&origin_path)?;
|
||||
|
||||
// Update image reference in origin
|
||||
update_origin_image_reference(&mut origin, imgref)?;
|
||||
|
||||
// Write updated origin
|
||||
std::fs::write(&origin_path, origin)?;
|
||||
|
||||
// Extract deployment ID
|
||||
let deploy_id = extract_deployment_id(&deploy_dir)?;
|
||||
|
||||
Ok(deploy_id)
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Directly modify the booted deployment's origin file
|
||||
**Use Cases**:
|
||||
- Anaconda %post scripts
|
||||
- System installation scenarios
|
||||
- Emergency image switching
|
||||
|
||||
## State Management
|
||||
|
||||
### 1. Specification Updates
|
||||
|
||||
```rust
|
||||
let new_spec = {
|
||||
let mut new_spec = host.spec.clone();
|
||||
new_spec.image = Some(target.clone());
|
||||
new_spec
|
||||
};
|
||||
```
|
||||
|
||||
**Process**:
|
||||
1. **Clone Current Spec**: Copy existing host specification
|
||||
2. **Update Image Reference**: Set new target image
|
||||
3. **Preserve Other Settings**: Keep boot order and other settings
|
||||
|
||||
### 2. Change Detection
|
||||
|
||||
```rust
|
||||
if new_spec == host.spec {
|
||||
println!("Image specification is unchanged.");
|
||||
return Ok(());
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Avoid unnecessary operations when no changes are made
|
||||
**Benefits**: Performance optimization, clear user feedback
|
||||
|
||||
### 3. Image Retention
|
||||
|
||||
```rust
|
||||
if !opts.retain {
|
||||
// Prune previous ostree ref
|
||||
if let Some(booted_origin) = booted_deployment.origin() {
|
||||
if let Some(ostree_ref) = booted_origin.optional_string("origin", "refspec")? {
|
||||
let (remote, ostree_ref) = ostree::parse_refspec(&ostree_ref)?;
|
||||
repo.set_ref_immediate(remote.as_deref(), &ostree_ref, None, cancellable)?;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Manage OSTree references for disk space optimization
|
||||
**Behavior**:
|
||||
- **Default**: Remove previous image reference
|
||||
- **With `--retain`**: Keep previous image reference
|
||||
|
||||
## Logging and Monitoring
|
||||
|
||||
### 1. Switch Operation Logging
|
||||
|
||||
```rust
|
||||
const SWITCH_JOURNAL_ID: &str = "7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1";
|
||||
|
||||
tracing::info!(
|
||||
message_id = SWITCH_JOURNAL_ID,
|
||||
bootc.old_image_reference = old_image,
|
||||
bootc.new_image_reference = &target.image,
|
||||
bootc.new_image_transport = &target.transport,
|
||||
"Switching from image {} to {}",
|
||||
old_image, target.image
|
||||
);
|
||||
```
|
||||
|
||||
**Purpose**: Track image switching operations
|
||||
**Fields**:
|
||||
- `message_id`: Unique identifier for switch operations
|
||||
- `bootc.old_image_reference`: Previous image reference
|
||||
- `bootc.new_image_reference`: New image reference
|
||||
- `bootc.new_image_transport`: Transport type used
|
||||
|
||||
### 2. In-Place Switch Logging
|
||||
|
||||
```rust
|
||||
const SWITCH_INPLACE_JOURNAL_ID: &str = "3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7";
|
||||
|
||||
tracing::info!(
|
||||
message_id = SWITCH_INPLACE_JOURNAL_ID,
|
||||
bootc.image.reference = &imgref.image,
|
||||
bootc.image.transport = &imgref.transport,
|
||||
bootc.switch_type = "in_place",
|
||||
"Performing in-place switch to image: {}",
|
||||
imgref
|
||||
);
|
||||
```
|
||||
|
||||
**Purpose**: Track in-place switch operations
|
||||
**Fields**:
|
||||
- `message_id`: Unique identifier for in-place switches
|
||||
- `bootc.image.reference`: Target image reference
|
||||
- `bootc.image.transport`: Transport type used
|
||||
- `bootc.switch_type`: Operation type identifier
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### 1. Blue/Green Deployments
|
||||
|
||||
```bash
|
||||
# Deploy to green environment
|
||||
bootc switch quay.io/myorg/debian-bootc:green
|
||||
|
||||
# Switch back to blue if needed
|
||||
bootc switch quay.io/myorg/debian-bootc:blue
|
||||
```
|
||||
|
||||
### 2. A/B Testing
|
||||
|
||||
```bash
|
||||
# Switch subset of systems to version B
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0-beta
|
||||
|
||||
# Monitor and switch back if issues
|
||||
bootc switch quay.io/myorg/debian-bootc:v1.0-stable
|
||||
```
|
||||
|
||||
### 3. Controlled Rollouts
|
||||
|
||||
```bash
|
||||
# Switch to new version
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Apply immediately
|
||||
bootc switch --apply quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Apply with soft reboot
|
||||
bootc switch --apply --soft-reboot=auto quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
### 4. Emergency Rollbacks
|
||||
|
||||
```bash
|
||||
# Quick rollback to previous version
|
||||
bootc switch quay.io/myorg/debian-bootc:v1.0 --apply
|
||||
|
||||
# Rollback with retention
|
||||
bootc switch --retain quay.io/myorg/debian-bootc:v1.0
|
||||
```
|
||||
|
||||
## Integration with Other Commands
|
||||
|
||||
### 1. Relationship to bootc upgrade
|
||||
|
||||
**Similarities**:
|
||||
- Both pull and stage container images
|
||||
- Both support `--apply` and `--soft-reboot` options
|
||||
- Both use the same deployment staging process
|
||||
|
||||
**Differences**:
|
||||
- `upgrade`: Updates current image to newer version
|
||||
- `switch`: Changes image source to different image
|
||||
|
||||
### 2. Relationship to bootc rollback
|
||||
|
||||
**Complementary**:
|
||||
- `switch`: Change to different image version
|
||||
- `rollback`: Revert to previous deployment
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Switch to new version
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# If issues, rollback
|
||||
bootc rollback
|
||||
```
|
||||
|
||||
### 3. Relationship to bootc status
|
||||
|
||||
**Status Display**:
|
||||
```bash
|
||||
# Check current status
|
||||
bootc status
|
||||
|
||||
# Switch to new image
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Check updated status
|
||||
bootc status
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Image Validation Errors
|
||||
|
||||
```rust
|
||||
// Invalid transport
|
||||
Error: Invalid transport type 'invalid'
|
||||
|
||||
// Image not found
|
||||
Error: Image not found in registry
|
||||
|
||||
// Signature verification failed
|
||||
Error: Signature verification failed
|
||||
```
|
||||
|
||||
### 2. System State Errors
|
||||
|
||||
```rust
|
||||
// System not bootc compatible
|
||||
Error: System is not bootc compatible
|
||||
|
||||
// No changes detected
|
||||
Image specification is unchanged.
|
||||
|
||||
// Deployment not found
|
||||
Error: No deployment directory found
|
||||
```
|
||||
|
||||
### 3. Network and Registry Errors
|
||||
|
||||
```rust
|
||||
// Registry connectivity
|
||||
Error: Failed to connect to registry
|
||||
|
||||
// Authentication failed
|
||||
Error: Authentication failed
|
||||
|
||||
// Image pull failed
|
||||
Error: Failed to pull image
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Signature Verification
|
||||
|
||||
```bash
|
||||
# Enforce signature policy
|
||||
bootc switch --enforce-container-sigpolicy quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
**Purpose**: Ensure image authenticity and integrity
|
||||
**Requirements**: Valid signature policy in `/etc/containers/policy.json`
|
||||
|
||||
### 2. Transport Security
|
||||
|
||||
**Registry Transport**: Uses HTTPS and authentication
|
||||
**OCI Archive**: Local file system access
|
||||
**Containers Storage**: Local container storage
|
||||
|
||||
### 3. Image Validation
|
||||
|
||||
- **Schema Validation**: Validates image configuration
|
||||
- **Compatibility Check**: Ensures image is bootc-compatible
|
||||
- **Signature Verification**: Validates image signatures
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### 1. Image Pulling
|
||||
|
||||
- **Layer Caching**: Reuses existing layers when possible
|
||||
- **Incremental Updates**: Only downloads changed layers
|
||||
- **Parallel Downloads**: Downloads layers in parallel
|
||||
|
||||
### 2. Staging Process
|
||||
|
||||
- **Atomic Staging**: All-or-nothing staging process
|
||||
- **Rollback Capability**: Maintains previous deployment
|
||||
- **Status Updates**: Efficient status management
|
||||
|
||||
### 3. Disk Space Management
|
||||
|
||||
- **Reference Pruning**: Removes old image references by default
|
||||
- **Retention Option**: Keep references with `--retain`
|
||||
- **Cleanup**: Automatic cleanup of unused layers
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
#### Image Not Found
|
||||
```bash
|
||||
# Check image exists
|
||||
podman pull quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Check registry connectivity
|
||||
curl -I https://quay.io/v2/
|
||||
```
|
||||
|
||||
#### Signature Verification Failed
|
||||
```bash
|
||||
# Check signature policy
|
||||
cat /etc/containers/policy.json
|
||||
|
||||
# Verify image signatures
|
||||
podman inspect quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
#### System Not Compatible
|
||||
```bash
|
||||
# Check system status
|
||||
bootc status
|
||||
|
||||
# Check bootc compatibility
|
||||
bootc status --json | jq '.status.booted'
|
||||
```
|
||||
|
||||
### 2. Debug Commands
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
|
||||
# Verify image
|
||||
podman inspect quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Image Management
|
||||
|
||||
- **Use Semantic Versioning**: Clear version numbering
|
||||
- **Test Before Switch**: Validate images in staging
|
||||
- **Monitor After Switch**: Watch for issues post-switch
|
||||
- **Keep Rollback Ready**: Maintain previous versions
|
||||
|
||||
### 2. Deployment Strategy
|
||||
|
||||
- **Blue/Green**: Use different image tags
|
||||
- **Canary Deployments**: Gradual rollout
|
||||
- **A/B Testing**: Compare different versions
|
||||
- **Emergency Procedures**: Quick rollback capability
|
||||
|
||||
### 3. Monitoring and Logging
|
||||
|
||||
- **Track Switch Operations**: Monitor journal logs
|
||||
- **Set Up Alerts**: Notify on switch failures
|
||||
- **Monitor System Health**: Watch for issues
|
||||
- **Document Changes**: Keep change records
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Planned Features
|
||||
|
||||
- **Userspace Restart**: For kernel-unchanged switches
|
||||
- **Rollback Automation**: Automatic rollback on failure
|
||||
- **Switch Scheduling**: Time-based switching
|
||||
- **Health Checks**: Pre/post switch validation
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
- **API Support**: REST API for switching
|
||||
- **Web Interface**: Web-based image management
|
||||
- **Configuration Management**: Declarative switching
|
||||
- **Audit Logging**: Comprehensive audit trails
|
||||
|
||||
This technical guide provides comprehensive understanding of the bootc switch system's architecture, implementation, and usage patterns.
|
||||
Loading…
Add table
Add a link
Reference in a new issue