apt-ostree/.notes/oci/rpm-ostree.md

rpm-ostree OCI Container Integration

Overview

rpm-ostree integrates with OCI (Open Container Initiative) containers to provide container-native deployment capabilities. This document explains how rpm-ostree implements OCI container integration.

Core OCI Integration

Container Image Generation

rpm-ostree can generate OCI container images from OSTree commits:

// OCI integration in rpmostree-container.cxx
#include <json-c/json.h>
#include <archive.h>
#include <archive_entry.h>

class RpmOstreeOciManager {
public:
    // Generate OCI container image from OSTree commit
    gboolean generate_oci_image(
        RpmOstreeSysroot *sysroot,
        const char *commit_checksum,
        const char *image_name,
        const char *image_tag,
        GCancellable *cancellable,
        GError **error) {
        
        // 1. Extract OSTree commit to filesystem
        g_autoptr(OstreeRepo) repo = rpmostree_sysroot_get_repo(sysroot);
        g_autoptr(GFile) commit_tree = ostree_repo_read_commit(repo, commit_checksum, NULL, NULL, error);
        
        // 2. Create OCI image layers
        g_autoptr(GPtrArray) layers = create_oci_layers(commit_tree, error);
        
        // 3. Generate OCI manifest
        g_autoptr(json_object) manifest = generate_oci_manifest(layers, image_name, image_tag, error);
        
        // 4. Create OCI image archive
        return create_oci_archive(manifest, layers, image_name, image_tag, error);
    }
    
    // Create OCI layers from filesystem
    GPtrArray* create_oci_layers(
        GFile *filesystem_tree,
        GError **error) {
        
        g_autoptr(GPtrArray) layers = g_ptr_array_new();
        
        // Create layer from filesystem
        g_autofree char *layer_path = create_filesystem_layer(filesystem_tree, error);
        if (!layer_path) {
            return NULL;
        }
        
        // Calculate layer digest
        g_autofree char *layer_digest = calculate_layer_digest(layer_path, error);
        if (!layer_digest) {
            return NULL;
        }
        
        // Create layer descriptor
        g_autoptr(json_object) layer_desc = json_object_new_object();
        json_object_object_add(layer_desc, "mediaType", 
                              json_object_new_string("application/vnd.oci.image.layer.v1.tar+gzip"));
        json_object_object_add(layer_desc, "digest", json_object_new_string(layer_digest));
        json_object_object_add(layer_desc, "size", json_object_new_int64(get_file_size(layer_path)));
        
        g_ptr_array_add(layers, g_steal_pointer(&layer_desc));
        return g_steal_pointer(&layers);
    }
    
    // Generate OCI manifest
    json_object* generate_oci_manifest(
        GPtrArray *layers,
        const char *image_name,
        const char *image_tag,
        GError **error) {
        
        g_autoptr(json_object) manifest = json_object_new_object();
        
        // Add schema version
        json_object_object_add(manifest, "schemaVersion", json_object_new_int(2));
        
        // Add config
        g_autoptr(json_object) config = json_object_new_object();
        json_object_object_add(config, "mediaType", 
                              json_object_new_string("application/vnd.oci.image.config.v1+json"));
        json_object_object_add(config, "digest", json_object_new_string("sha256:config"));
        json_object_object_add(config, "size", json_object_new_int64(0));
        json_object_object_add(manifest, "config", g_steal_pointer(&config));
        
        // Add layers
        g_autoptr(json_object) layers_array = json_object_new_array();
        for (guint i = 0; i < layers->len; i++) {
            json_object *layer = g_ptr_array_index(layers, i);
            json_object_array_add(layers_array, json_object_get(layer));
        }
        json_object_object_add(manifest, "layers", g_steal_pointer(&layers_array));
        
        return g_steal_pointer(&manifest);
    }
};

Container Registry Integration

rpm-ostree integrates with OCI container registries:

// Registry integration in rpmostree-container.cxx
class RpmOstreeRegistryManager {
public:
    // Push OCI image to registry
    gboolean push_oci_image(
        const char *image_path,
        const char *registry_url,
        const char *image_name,
        const char *image_tag,
        GCancellable *cancellable,
        GError **error) {
        
        // Use skopeo for registry operations
        g_autofree char *push_command = g_strdup_printf(
            "skopeo copy --dest-creds=%s:%s oci:%s docker://%s/%s:%s",
            registry_username, registry_password,
            image_path, registry_url, image_name, image_tag);
        
        return rpmostree_sysroot_run_sync(sysroot, push_command, cancellable, error);
    }
    
    // Pull OCI image from registry
    gboolean pull_oci_image(
        const char *registry_url,
        const char *image_name,
        const char *image_tag,
        const char *local_path,
        GCancellable *cancellable,
        GError **error) {
        
        // Use skopeo for registry operations
        g_autofree char *pull_command = g_strdup_printf(
            "skopeo copy --src-creds=%s:%s docker://%s/%s:%s oci:%s",
            registry_username, registry_password,
            registry_url, image_name, image_tag, local_path);
        
        return rpmostree_sysroot_run_sync(sysroot, pull_command, cancellable, error);
    }
};

Bootc Compatibility

Bootc Image Generation

rpm-ostree can generate bootc-compatible images:

// Bootc integration in rpmostree-container.cxx
class RpmOstreeBootcManager {
public:
    // Generate bootc-compatible image
    gboolean generate_bootc_image(
        RpmOstreeSysroot *sysroot,
        const char *commit_checksum,
        const char *image_name,
        const char *image_tag,
        GCancellable *cancellable,
        GError **error) {
        
        // 1. Generate OCI image
        g_autofree char *oci_image_path = generate_oci_image(
            sysroot, commit_checksum, image_name, image_tag, cancellable, error);
        
        // 2. Add bootc-specific metadata
        return add_bootc_metadata(oci_image_path, image_name, image_tag, error);
    }
    
    // Add bootc-specific metadata
    gboolean add_bootc_metadata(
        const char *image_path,
        const char *image_name,
        const char *image_tag,
        GError **error) {
        
        // Create bootc metadata
        g_autoptr(json_object) bootc_metadata = json_object_new_object();
        json_object_object_add(bootc_metadata, "bootc", json_object_new_object());
        
        // Add deployment metadata
        g_autoptr(json_object) deployment = json_object_new_object();
        json_object_object_add(deployment, "type", json_object_new_string("ostree"));
        json_object_object_add(deployment, "ref", json_object_new_string("fedora/39/x86_64/silverblue"));
        json_object_object_add(bootc_metadata, "deployment", g_steal_pointer(&deployment));
        
        // Write metadata to image
        return write_image_metadata(image_path, bootc_metadata, error);
    }
};

Future Enhancements

Planned Features

1. Enhanced OCI Support: Full OCI specification compliance
2. Registry Authentication: Advanced registry authentication methods
3. Image Optimization: Layer optimization and compression
4. Multi-Architecture Support: Support for multiple architectures

Integration Roadmap

• Phase 1: Basic OCI integration (🔄 In Progress)
• Phase 2: Registry integration (📋 Planned)
• Phase 3: Bootc compatibility (📋 Planned)
• Phase 4: Advanced features (📋 Planned)