# 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)