jesus/prvng_extensions
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
prvng_extensions/taskservs/container_runtime/podman/README.md

805 lines
23 KiB
Markdown
Raw Normal View History

chore init repo and codebase
2025-10-07 11:05:08 +01:00
# Podman Task Service
## Overview
The Podman task service provides a complete installation and configuration of [Podman](https://podman.io/), a daemonless container engine for developing, managing, and running OCI Containers on Linux systems. Podman provides a Docker-compatible command line interface while running containers without requiring a daemon, offering enhanced security and flexibility.
## Features
### Core Container Features
- **Daemonless Architecture** - No background daemon required for container operations
- **Docker Compatibility** - Drop-in replacement for Docker CLI commands
- **OCI Compliance** - Full Open Container Initiative specification compliance
- **Rootless Containers** - Run containers without root privileges
- **Pod Management** - Kubernetes-style pod support with multiple containers
### Security Features
- **Rootless Operation** - Enhanced security through non-privileged execution
- **User Namespaces** - Isolated user spaces for container processes
- **SELinux Integration** - Native SELinux support for mandatory access control
- **No Daemon Attack Surface** - Reduced security risks without persistent daemon
- **Fork/Exec Model** - Direct process execution without daemon intermediary
### Runtime Support
- **Multiple Runtimes** - Support for crun, runc, youki, and custom runtimes
- **Runtime Selection** - Per-container runtime selection capability
- **Performance Optimization** - Runtime-specific performance tuning
- **OCI Runtime Spec** - Full compliance with OCI runtime specification
- **Custom Runtime Integration** - Easy integration of custom container runtimes
### Advanced Features
- **Systemd Integration** - Native systemd service management
- **Container Images** - Build, pull, push, and manage container images
- **Network Management** - Advanced networking with CNI plugin support
- **Volume Management** - Persistent storage and bind mount support
- **Container Orchestration** - Basic orchestration capabilities
### Development Features
- **Build Support** - Dockerfile and Containerfile support
- **Image Management** - Local and remote image registry support
- **Development Tools** - Debugging and development utilities
- **CI/CD Integration** - Pipeline and automation support
- **Multi-Architecture** - Cross-platform container support
## Configuration
### Basic Configuration
```kcl
podman: Podman = {
name: "podman"
version: "4.7.2"
runtime_default: "crun"
runtimes: "crun,runc"
}
```
### Production Configuration
```kcl
podman: Podman = {
name: "podman"
version: "4.7.2"
runtime_default: "crun"
runtimes: "crun,runc,youki"
configuration: {
containers_conf: {
default_ulimits: [
"nofile=1024:2048",
"nproc=1024:2048"
]
dns_servers: ["8.8.8.8", "8.8.4.4"]
dns_searches: ["company.com"]
dns_options: ["ndots:2", "edns0"]
default_capabilities: [
"CHOWN",
"DAC_OVERRIDE",
"FOWNER",
"FSETID",
"KILL",
"NET_BIND_SERVICE",
"SETFCAP",
"SETGID",
"SETPCAP",
"SETUID",
"SYS_CHROOT"
]
default_sysctls: {
"net.ipv4.ping_group_range": "0 0"
}
}
storage_conf: {
driver: "overlay"
runroot: "/run/containers/storage"
graphroot: "/var/lib/containers/storage"
options: {
overlay: {
mountopt: "nodev,metacopy=on"
size: "10G"
}
}
}
registries_conf: {
unqualified_search_registries: [
"registry.fedoraproject.org",
"registry.access.redhat.com",
"docker.io",
"quay.io"
]
short_name_mode: "enforcing"
}
}
security: {
apparmor_profile: "containers-default-0.46.0"
seccomp_profile: "/usr/share/containers/seccomp.json"
selinux_enabled: true
no_new_privileges: true
}
}
```
### Rootless Configuration
```kcl
podman: Podman = {
name: "podman"
version: "4.7.2"
runtime_default: "crun"
runtimes: "crun,runc"
rootless: {
enabled: true
user: "containers"
uid_range: "100000:65536"
gid_range: "100000:65536"
max_user_namespaces: 15000
enable_linger: true
cgroup_manager: "systemd"
events_logger: "journald"
runtime_supports_json: ["crun", "runc", "youki"]
runtime_supports_kvm: ["crun"]
runtime_supports_nocgroups: ["crun", "youki"]
}
networking: {
default_network: "podman"
default_subnet: "10.88.0.0/16"
default_subnetv6: "fd00::/64"
dns_bind_port: 53
enable_port_reservation: true
network_cmd_options: []
cni_plugin_dirs: [
"/usr/local/libexec/cni",
"/usr/libexec/cni",
"/usr/local/lib/cni",
"/usr/lib/cni",
"/opt/cni/bin"
]
}
}
```
### Multi-Runtime Configuration
```kcl
podman: Podman = {
name: "podman"
version: "4.7.2"
runtime_default: "crun"
runtimes: "crun,runc,youki"
runtime_configs: {
crun: {
runtime_path: "/usr/bin/crun"
runtime_type: "oci"
runtime_root: "/run/crun"
runtime_args: []
supports_json: true
supports_kvm: true
supports_nocgroups: true
}
runc: {
runtime_path: "/usr/bin/runc"
runtime_type: "oci"
runtime_root: "/run/runc"
runtime_args: ["--systemd-cgroup"]
supports_json: true
supports_kvm: false
supports_nocgroups: false
}
youki: {
runtime_path: "/usr/local/bin/youki"
runtime_type: "oci"
runtime_root: "/run/youki"
runtime_args: []
supports_json: true
supports_kvm: false
supports_nocgroups: true
}
}
performance: {
max_parallel_downloads: 3
pull_policy: "missing"
image_default_transport: "docker://"
compression_format: "gzip"
compression_level: 5
}
}
```
### Enterprise Configuration
```kcl
podman: Podman = {
name: "podman"
version: "4.7.2"
runtime_default: "crun"
runtimes: "crun,runc"
enterprise: {
policy_path: "/etc/containers/policy.json"
signature_policy: {
default: [{"type": "insecureAcceptAnything"}]
transports: {
docker: {
"registry.company.com": [
{
type: "signedBy"
keyType: "GPGKeys"
keyPath: "/etc/pki/containers/pubring.gpg"
}
]
"docker.io": [{"type": "insecureAcceptAnything"}]
}
}
}
registries: {
"registry.company.com": {
location: "registry.company.com"
insecure: false
blocked: false
mirror: []
prefix: "registry.company.com"
}
"docker.io": {
location: "docker.io"
insecure: false
blocked: false
mirror: [
{
location: "mirror.company.com"
insecure: false
}
]
}
}
storage: {
driver: "overlay"
runroot: "/run/containers/storage"
graphroot: "/var/lib/containers/storage"
quota: {
size: "100G"
}
}
}
monitoring: {
metrics_enabled: true
metrics_port: 9090
events_logger: "journald"
log_driver: "journald"
log_size_max: "10MB"
log_opts: {
max_size: "10m"
max_file: "3"
}
}
}
```
### Development Configuration
```kcl
podman: Podman = {
name: "podman"
version: "4.7.2"
runtime_default: "crun"
runtimes: "crun,runc,youki"
development: {
buildah_isolation: "oci"
buildah_format: "oci"
pull_policy: "newer"
short_name_mode: "permissive"
helper_binaries_dir: [
"/usr/local/libexec/podman",
"/usr/local/lib/podman",
"/usr/libexec/podman",
"/usr/lib/podman"
]
hooks_dir: [
"/usr/share/containers/oci/hooks.d"
]
image_copy_tmp_dir: "/var/tmp"
tmp_dir: "/tmp"
volume_path: "/var/lib/containers/storage/volumes"
}
testing: {
test_kitchen_enabled: true
bats_enabled: true
integration_tests: true
unit_tests: true
performance_tests: true
}
}
```
## Usage
### Deploy Podman
```bash
./core/nulib/provisioning taskserv create podman --infra <infrastructure-name>
```
### List Available Task Services
```bash
./core/nulib/provisioning taskserv list
```
### SSH to Podman Server
```bash
./core/nulib/provisioning server ssh <podman-server>
```
### Basic Container Operations
```bash
# Check Podman version
podman --version
# Run a container
podman run -d --name nginx -p 8080:80 nginx:latest
# List running containers
podman ps
# List all containers
podman ps -a
# Stop a container
podman stop nginx
# Remove a container
podman rm nginx
# Execute command in container
podman exec -it nginx /bin/bash
```
### Image Management
```bash
# Pull an image
podman pull docker.io/library/nginx:latest
# List images
podman images
# Build an image from Dockerfile
podman build -t myapp:latest .
# Push image to registry
podman push myapp:latest registry.company.com/myapp:latest
# Remove an image
podman rmi nginx:latest
# Search for images
podman search nginx
```
### Pod Management
```bash
# Create a pod
podman pod create --name mypod -p 8080:80
# Add containers to pod
podman run -d --pod mypod --name web nginx:latest
podman run -d --pod mypod --name redis redis:latest
# List pods
podman pod ls
# Start/stop pod
podman pod start mypod
podman pod stop mypod
# Remove pod
podman pod rm mypod
```
### Network Management
```bash
# List networks
podman network ls
# Create a network
podman network create mynetwork
# Inspect network
podman network inspect mynetwork
# Connect container to network
podman network connect mynetwork nginx
# Disconnect container from network
podman network disconnect mynetwork nginx
# Remove network
podman network rm mynetwork
```
### Volume Management
```bash
# Create a volume
podman volume create myvolume
# List volumes
podman volume ls
# Inspect volume
podman volume inspect myvolume
# Use volume in container
podman run -d --name nginx -v myvolume:/data nginx:latest
# Remove volume
podman volume rm myvolume
# Prune unused volumes
podman volume prune
```
### Systemd Integration
```bash
# Generate systemd unit file
podman generate systemd --new --name nginx > ~/.config/systemd/user/nginx.service
# Enable and start service
systemctl --user daemon-reload
systemctl --user enable nginx.service
systemctl --user start nginx.service
# Check service status
systemctl --user status nginx.service
# Generate Kubernetes YAML
podman generate kube nginx > nginx-pod.yaml
```
### Rootless Operations
```bash
# Run rootless container
podman run --rm -it --user 1000:1000 alpine:latest /bin/sh
# Check rootless configuration
podman info --debug
# Setup rootless networking
podman network create --subnet 10.89.0.0/24 rootless-net
# Port mapping in rootless mode
podman run -d --name web -p 8080:80 nginx:latest
# Check user namespaces
podman unshare cat /proc/self/uid_map
```
### Registry Operations
```bash
# Login to registry
podman login registry.company.com
# Pull from private registry
podman pull registry.company.com/myapp:latest
# Push to private registry
podman push myapp:latest registry.company.com/myapp:latest
# Logout from registry
podman logout registry.company.com
# Configure registry mirrors
podman info | grep -A 5 registries
```
## Architecture
### System Architecture
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Applications │────│ Podman CLI │────│ Container │
│ │ │ │ │ Runtime │
│ • User Commands │ │ • Command Parser │ │ │
│ • Scripts │────│ • API Interface │────│ • crun/runc │
│ • Automation │ │ • Image Mgmt │ │ • youki │
│ • CI/CD │ │ • Registry API │ │ • Containers │
└─────────────────┘ └──────────────────┘ └─────────────────┘
```
### Daemonless Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Podman Architecture │
├─────────────────────────────────────────────────────────────┤
│ CLI Commands │ Library Layer │ Runtime Layer │
│ │ │ │
│ • podman run │ • libpod │ • OCI Runtime │
│ • podman build │ • libimage │ • Network CNI │
│ • podman pod │ • storage │ • Storage Driver │
│ • podman network │ • networking │ • Systemd │
├─────────────────────────────────────────────────────────────┤
│ No Background Daemon │
├─────────────────────────────────────────────────────────────┤
│ Host Resources │ User Namespaces │ Security │
│ │ │ │
│ • Storage │ • UID/GID Mapping │ • SELinux │
│ • Network │ • Capabilities │ • AppArmor │
│ • Process Tree │ • Mount NS │ • Seccomp │
└─────────────────────────────────────────────────────────────┘
```
### Runtime Comparison
```
Runtime │ Language │ Performance │ Features │ Security
─────────┼──────────┼─────────────┼───────────────┼──────────
crun │ C │ Fastest │ Full OCI │ High
runc │ Go │ Fast │ Full OCI │ High
youki │ Rust │ Very Fast │ Partial OCI │ High
```
### File Structure
```
/usr/bin/podman # Main podman binary
/etc/containers/ # System configuration
├── containers.conf # Main configuration
├── storage.conf # Storage configuration
├── registries.conf # Registry configuration
├── policy.json # Image signature policy
└── mounts.conf # Additional mount points
~/.config/containers/ # User configuration
├── containers.conf # User-specific config
├── storage.conf # User storage config
└── registries.conf # User registry config
/var/lib/containers/ # System storage
├── storage/ # Container images and data
├── cache/ # Image cache
└── tmp/ # Temporary files
~/.local/share/containers/ # User storage (rootless)
├── storage/ # User container storage
└── cache/ # User image cache
```
## Supported Operating Systems
- Ubuntu 20.04+ / Debian 11+
- CentOS 8+ / RHEL 8+ / Fedora 35+
- Amazon Linux 2+
- SUSE Linux Enterprise 15+
## System Requirements
### Minimum Requirements
- **RAM**: 2GB (4GB+ recommended)
- **Storage**: 20GB (100GB+ for production)
- **CPU**: 2 cores (4+ cores recommended)
- **Kernel**: Linux 4.18+ with user namespaces
### Production Requirements
- **RAM**: 8GB+ (depends on workload)
- **Storage**: 100GB+ SSD
- **CPU**: 4+ cores
- **Network**: High bandwidth for image operations
### Rootless Requirements
- **User Namespaces** - Kernel support for user namespaces
- **UID/GID Mapping** - Proper subuid/subgid configuration
- **Cgroups v2** - For resource management in rootless mode
- **Systemd** - For service management
## Troubleshooting
### Installation Issues
```bash
# Check Podman installation
podman --version
podman info
# Check runtime availability
podman info | grep -A 5 runtimes
# Test basic functionality
podman run --rm hello-world
# Check system requirements
podman system check
```
### Rootless Issues
```bash
# Check user namespace configuration
cat /etc/subuid
cat /etc/subgid
# Check rootless setup
podman unshare cat /proc/self/uid_map
podman unshare cat /proc/self/gid_map
# Fix rootless networking
podman system reset --force
podman network create default
# Check cgroup configuration
cat /proc/cgroups
systemctl --user status
```
### Container Issues
```bash
# Check container logs
podman logs container-name
# Debug container startup
podman run --rm -it --entrypoint /bin/sh image-name
# Check container processes
podman top container-name
# Inspect container configuration
podman inspect container-name
# Check resource usage
podman stats container-name
```
### Image Issues
```bash
# Check image information
podman inspect image-name
# Debug image build
podman build --no-cache -t test .
# Check registry connectivity
podman pull --log-level debug image-name
# Clean up unused images
podman image prune
podman system prune
```
### Network Issues
```bash
# Check network configuration
podman network ls
podman network inspect podman
# Test container networking
podman run --rm --net host alpine ping google.com
# Check port binding
podman port container-name
netstat -tlnp | grep podman
# Debug CNI issues
journalctl -u podman
```
### Storage Issues
```bash
# Check storage configuration
podman info | grep -A 10 store
# Check storage usage
podman system df
# Clean storage
podman system prune -a
# Reset storage (destructive)
podman system reset
# Check permissions
ls -la /var/lib/containers/
```
## Security Considerations
### Rootless Security
- **User Namespace Security** - Containers run in isolated user namespaces
- **No Root Access** - Eliminates many privilege escalation vectors
- **Process Isolation** - Container processes isolated from host
- **Resource Limits** - Automatic resource constraints
### Image Security
- **Image Signing** - Verify image signatures before execution
- **Registry Security** - Use trusted registries and mirrors
- **Vulnerability Scanning** - Regular image vulnerability scanning
- **Minimal Images** - Use minimal base images
### Runtime Security
- **SELinux/AppArmor** - Mandatory access control integration
- **Seccomp Profiles** - System call filtering
- **Capabilities** - Minimize container capabilities
- **No New Privileges** - Prevent privilege escalation
### Network Security
- **Network Isolation** - Isolate container networks
- **Firewall Integration** - Integration with host firewall
- **Port Security** - Careful port mapping and exposure
- **TLS Communication** - Secure registry communication
## Performance Optimization
### Image Optimization
- **Layer Optimization** - Minimize image layers and size
- **Multi-Stage Builds** - Use multi-stage builds for efficiency
- **Image Caching** - Optimize local image caching
- **Registry Mirrors** - Use local registry mirrors
### Runtime Optimization
- **Runtime Selection** - Choose optimal runtime for workload
- **Resource Limits** - Set appropriate resource constraints
- **Storage Driver** - Optimize storage driver selection
- **Network Performance** - Optimize network configuration
### System Optimization
- **Storage Performance** - Use fast storage for container data
- **Memory Management** - Optimize host memory allocation
- **CPU Affinity** - Pin containers to specific CPUs
- **Kernel Parameters** - Tune kernel parameters for containers
### Monitoring Optimization
- **Metrics Collection** - Collect relevant performance metrics
- **Log Management** - Efficient log collection and rotation
- **Health Monitoring** - Monitor container health
- **Resource Monitoring** - Track resource usage
## Integration Examples
### Docker Compose Compatibility
```bash
# Use podman-compose
pip3 install podman-compose
# Run docker-compose.yml
podman-compose up -d
# Alternative: use docker-compose with podman
export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock
systemctl --user enable podman.socket
docker-compose up -d
```
### Kubernetes Integration
```bash
# Generate Kubernetes YAML
podman generate kube mypod > mypod.yaml
# Play Kubernetes YAML
podman play kube mypod.yaml
# Generate systemd services
podman generate systemd --new mypod > mypod.service
```
### CI/CD Integration
```yaml
# GitLab CI example
build:
image: quay.io/podman/stable
script:
- podman build -t myapp:$CI_COMMIT_SHA .
- podman push myapp:$CI_COMMIT_SHA $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
```
### Systemd Service Template
```ini
[Unit]
Description=Podman container-%i.service
Documentation=man:podman-generate-systemd(1)
Wants=network-online.target
After=network-online.target
RequiresMountsFor=%t/containers
[Service]
Environment=PODMAN_SYSTEMD_UNIT=%n
Restart=on-failure
TimeoutStopSec=70
ExecStartPre=/bin/rm -f %t/%n.ctr-id
ExecStart=/usr/bin/podman run --cidfile=%t/%n.ctr-id --cgroups=no-conmon --rm --sdnotify=conmon --replace --name %i $IMAGE
ExecStop=/usr/bin/podman stop --ignore --cidfile=%t/%n.ctr-id
ExecStopPost=/usr/bin/podman rm -f --ignore --cidfile=%t/%n.ctr-id
Type=notify
NotifyAccess=all
[Install]
WantedBy=multi-user.target default.target
```
## Resources
- **Official Documentation**: [docs.podman.io](https://docs.podman.io/)
- **GitHub Repository**: [containers/podman](https://github.com/containers/podman)
- **Community**: [podman.io/community](https://podman.io/community/)
- **Tutorials**: [github.com/containers/podman/tree/main/docs/tutorials](https://github.com/containers/podman/tree/main/docs/tutorials)
- **Troubleshooting**: [github.com/containers/podman/blob/main/troubleshooting.md](https://github.com/containers/podman/blob/main/troubleshooting.md)
Reference in New Issue Copy Permalink