particle-os-tools/docs/apt-layer/rpm-ostree/container.md

rpm-ostree Container Integration

Overview

rpm-ostree provides native support for OCI containers, allowing container images to be deployed as part of the immutable filesystem tree. This integration combines the benefits of container technology with the atomic, transactional nature of rpm-ostree.

Container Concepts

Native Container Support

rpm-ostree treats containers as first-class citizens:

• Container images: OCI container images can be deployed directly
• Atomic deployment: Container deployments are atomic and transactional
• Rollback capability: Container deployments can be rolled back
• Integration: Containers integrate seamlessly with the base system

Container Types

1. System Containers: Core system services
2. Application Containers: End-user applications
3. Development Containers: Development environments
4. Infrastructure Containers: Infrastructure components

Container Architecture

Container Storage

/var/lib/rpm-ostree/containers/
├── images/
│   ├── quay.io/
│   │   └── example/
│   │       └── myapp/
│   │           └── latest/
│   └── docker.io/
│       └── library/
│           └── nginx/
│               └── latest/
├── deployments/
│   ├── myapp/
│   │   ├── config.json
│   │   ├── manifest.json
│   │   └── rootfs/
│   └── nginx/
│       ├── config.json
│       ├── manifest.json
│       └── rootfs/
└── metadata/
    ├── containers.json
    └── deployments.json

Container Integration Model

System Layers
├── Base Image (immutable)
├── Container Layer 1
├── Container Layer 2
├── Extension Layer
└── User Packages (layered)

Container Management

Deploying Containers

# Deploy container image
rpm-ostree container deploy quay.io/example/myapp:latest

# Deploy with custom name
rpm-ostree container deploy \
  --name=myapp \
  quay.io/example/myapp:latest

# Deploy with configuration
rpm-ostree container deploy \
  --name=myapp \
  --config=/path/to/config.json \
  quay.io/example/myapp:latest

Container Configuration

{
  "name": "myapp",
  "image": "quay.io/example/myapp:latest",
  "transport": "docker",
  "config": {
    "entrypoint": ["/usr/bin/myapp"],
    "cmd": ["--config=/etc/myapp/config.yaml"],
    "env": [
      "APP_ENV=production",
      "LOG_LEVEL=info"
    ],
    "volumes": [
      "/host/data:/container/data",
      "/host/config:/container/config"
    ],
    "ports": [
      "8080:8080",
      "9090:9090"
    ]
  }
}

Listing Containers

# List deployed containers
rpm-ostree container list

# List with details
rpm-ostree container list --verbose

# List container images
rpm-ostree container images

Updating Containers

# Update container to new version
rpm-ostree container deploy \
  --name=myapp \
  quay.io/example/myapp:v2.0.0

# Update with rollback capability
rpm-ostree container deploy \
  --name=myapp \
  --rollback \
  quay.io/example/myapp:v2.0.0

Removing Containers

# Remove container deployment
rpm-ostree container remove myapp

# Remove with cleanup
rpm-ostree container remove --cleanup myapp

Container Lifecycle

Deployment Process

1. Image Pull: Download container image
2. Validation: Validate image integrity
3. Extraction: Extract image layers
4. Configuration: Apply container configuration
5. Integration: Integrate with system
6. Activation: Start container services

Update Process

1. Check Updates: Check for new image versions
2. Download: Download updated image
3. Validation: Validate updated image
4. Deploy: Deploy updated container
5. Rollback: Rollback if deployment fails

Removal Process

1. Stop Services: Stop container services
2. Unmount: Unmount container filesystems
3. Remove: Remove container deployment
4. Cleanup: Clean up container data

Container Configuration

Basic Configuration

{
  "name": "myapp",
  "image": "quay.io/example/myapp:latest",
  "transport": "docker"
}

Advanced Configuration

{
  "name": "myapp",
  "image": "quay.io/example/myapp:latest",
  "transport": "docker",
  "config": {
    "entrypoint": ["/usr/bin/myapp"],
    "cmd": ["--config=/etc/myapp/config.yaml"],
    "env": [
      "APP_ENV=production",
      "LOG_LEVEL=info",
      "DATABASE_URL=postgresql://user:pass@localhost/db"
    ],
    "volumes": [
      {
        "source": "/host/data",
        "target": "/container/data",
        "readonly": false
      },
      {
        "source": "/host/config",
        "target": "/container/config",
        "readonly": true
      }
    ],
    "ports": [
      {
        "host": "8080",
        "container": "8080",
        "protocol": "tcp"
      }
    ],
    "resources": {
      "memory": "512M",
      "cpu": "0.5"
    },
    "security": {
      "readonly": false,
      "no_new_privileges": true,
      "capabilities": ["CAP_NET_ADMIN"]
    }
  }
}

Environment Variables

{
  "config": {
    "env": [
      "APP_ENV=production",
      "LOG_LEVEL=info",
      "DATABASE_URL=postgresql://user:pass@localhost/db",
      "REDIS_URL=redis://localhost:6379",
      "API_KEY=${API_KEY}"
    ]
  }
}

Volume Mounts

{
  "config": {
    "volumes": [
      {
        "source": "/host/data",
        "target": "/container/data",
        "readonly": false,
        "bind": true
      },
      {
        "source": "/host/config",
        "target": "/container/config",
        "readonly": true,
        "bind": true
      },
      {
        "source": "myapp-data",
        "target": "/container/data",
        "readonly": false,
        "volume": true
      }
    ]
  }
}

Network Configuration

{
  "config": {
    "network": {
      "mode": "bridge",
      "ports": [
        {
          "host": "8080",
          "container": "8080",
          "protocol": "tcp"
        },
        {
          "host": "9090",
          "container": "9090",
          "protocol": "tcp"
        }
      ],
      "dns": ["8.8.8.8", "8.8.4.4"]
    }
  }
}

Container Services

Service Integration

Containers can provide systemd services:

# /etc/systemd/system/myapp-container.service
[Unit]
Description=MyApp Container Service
After=network.target
Requires=rpm-ostree-container-myapp.service

[Service]
Type=notify
ExecStart=/usr/bin/rpm-ostree container run myapp
ExecStop=/usr/bin/rpm-ostree container stop myapp
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Service Management

# Enable container service
systemctl enable myapp-container.service

# Start container service
systemctl start myapp-container.service

# Check service status
systemctl status myapp-container.service

# View service logs
journalctl -u myapp-container.service -f

Container Security

Isolation

Containers are isolated from the host system:

{
  "config": {
    "security": {
      "readonly": true,
      "no_new_privileges": true,
      "capabilities": ["CAP_NET_ADMIN"],
      "seccomp": "/etc/containers/seccomp.json",
      "apparmor": "/etc/containers/apparmor.json"
    }
  }
}

Resource Limits

{
  "config": {
    "resources": {
      "memory": "512M",
      "cpu": "0.5",
      "pids": 100,
      "devices": [
        {
          "path": "/dev/null",
          "permissions": "rwm"
        }
      ]
    }
  }
}

Image Verification

# Verify container image
rpm-ostree container verify quay.io/example/myapp:latest

# Verify with specific key
rpm-ostree container verify \
  --key=/path/to/key.gpg \
  quay.io/example/myapp:latest

Container Examples

Web Application

{
  "name": "webapp",
  "image": "nginx:latest",
  "transport": "docker",
  "config": {
    "entrypoint": ["nginx"],
    "cmd": ["-g", "daemon off;"],
    "env": [
      "NGINX_HOST=localhost",
      "NGINX_PORT=80"
    ],
    "volumes": [
      {
        "source": "/host/webroot",
        "target": "/usr/share/nginx/html",
        "readonly": true
      },
      {
        "source": "/host/nginx.conf",
        "target": "/etc/nginx/nginx.conf",
        "readonly": true
      }
    ],
    "ports": [
      {
        "host": "80",
        "container": "80",
        "protocol": "tcp"
      }
    ]
  }
}

Database Container

{
  "name": "database",
  "image": "postgres:13",
  "transport": "docker",
  "config": {
    "entrypoint": ["postgres"],
    "env": [
      "POSTGRES_DB=myapp",
      "POSTGRES_USER=myapp",
      "POSTGRES_PASSWORD=${DB_PASSWORD}"
    ],
    "volumes": [
      {
        "source": "/host/db-data",
        "target": "/var/lib/postgresql/data",
        "readonly": false
      }
    ],
    "ports": [
      {
        "host": "5432",
        "container": "5432",
        "protocol": "tcp"
      }
    ],
    "resources": {
      "memory": "1G",
      "cpu": "1.0"
    }
  }
}

Monitoring Container

{
  "name": "monitoring",
  "image": "prom/prometheus:latest",
  "transport": "docker",
  "config": {
    "entrypoint": ["/bin/prometheus"],
    "cmd": [
      "--config.file=/etc/prometheus/prometheus.yml",
      "--storage.tsdb.path=/prometheus",
      "--web.console.libraries=/etc/prometheus/console_libraries",
      "--web.console.templates=/etc/prometheus/consoles"
    ],
    "volumes": [
      {
        "source": "/host/prometheus.yml",
        "target": "/etc/prometheus/prometheus.yml",
        "readonly": true
      },
      {
        "source": "/host/prometheus-data",
        "target": "/prometheus",
        "readonly": false
      }
    ],
    "ports": [
      {
        "host": "9090",
        "container": "9090",
        "protocol": "tcp"
      }
    ]
  }
}

Container Management Tools

Command Line Interface

# Container management commands
rpm-ostree container deploy myapp
rpm-ostree container update myapp
rpm-ostree container remove myapp
rpm-ostree container list
rpm-ostree container info myapp
rpm-ostree container logs myapp
rpm-ostree container exec myapp /bin/bash

Configuration Management

# Container configuration
rpm-ostree container config myapp set key=value
rpm-ostree container config myapp get key
rpm-ostree container config myapp list

Monitoring and Health

# Container monitoring
rpm-ostree container status myapp
rpm-ostree container health myapp
rpm-ostree container metrics myapp

Integration with Other Tools

Kubernetes Integration

# Kubernetes deployment using rpm-ostree containers
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: quay.io/example/myapp:latest
        ports:
        - containerPort: 8080

Docker Compose Integration

# docker-compose.yml
version: '3.8'
services:
  myapp:
    image: quay.io/example/myapp:latest
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
    environment:
      - APP_ENV=production

Best Practices

Container Design

1. Minimal images: Use minimal base images
2. Security: Follow security best practices
3. Documentation: Document container configuration
4. Testing: Test containers thoroughly

Container Management

1. Versioning: Use semantic versioning
2. Updates: Regular security updates
3. Monitoring: Monitor container health
4. Backup: Backup container data

Security

1. Image verification: Verify image signatures
2. Resource limits: Set appropriate resource limits
3. Network security: Secure network configuration
4. Access control: Control container access

---

Container integration provides a powerful way to deploy and manage applications on rpm-ostree systems while maintaining the atomic, transactional nature of the platform.