2026-01-14 03:25:20 +00:00
|
|
|
# OCI Registry Integration Guide\n\n## Overview\n\nThe OCI integration module provides OCI Distribution Spec v2 compliant registry integration for pulling KCL packages and extension artifacts.\n\n## Architecture\n\n```{$detected_lang}\n┌──────────────────┐\n│ Orchestrator │\n│ (Rust) │\n└────────┬─────────┘\n │\n ▼\n┌──────────────────┐\n│ OCI Manager │\n│ │\n│ - LRU caching │\n│ - Pull artifacts│\n│ - List packages │\n└────────┬─────────┘\n │\n ▼\n┌──────────────────┐\n│ OCI Client │\n│ (Distribution) │\n└────────┬─────────┘\n │\n ▼\n┌──────────────────┐\n│ OCI Registry │\n│ (HTTP API v2) │\n└──────────────────┘\n```\n\n## Features\n\n### 1. KCL Package Management\n\nPull KCL configuration packages from OCI registry:\n\n```{$detected_lang}\nlet package_path = oci_manager.pull_kcl_package(\n "provisioning-core",\n "1.0.0"\n).await?;\n```\n\n### 2. Extension Artifacts\n\nPull extension artifacts (providers, taskservs, clusters):\n\n```{$detected_lang}\nlet artifact_path = oci_manager.pull_extension_artifact(\n "taskserv", // Extension type\n "kubernetes", // Extension name\n "1.28.0" // Version\n).await?;\n```\n\n### 3. Manifest Caching\n\nManifests are cached using LRU strategy:\n\n- **Cache size**: 100 manifests\n- **Cache key**: `{name}:{version}`\n- **Automatic eviction**: Oldest entries removed when full\n\n### 4. Artifact Listing\n\nList all artifacts in a namespace:\n\n```{$detected_lang}\nlet artifacts = oci_manager.list_oci_artifacts("kcl").await?;\nfor artifact in artifacts {\n println!("{} v{} ({})", artifact.name, artifact.version, artifact.size);\n}\n```\n\n## OCI Distribution Spec v2\n\nImplements OCI Distribution Specification v2:\n\n- **Manifest retrieval**: `GET /v2/{namespace}/{repository}/manifests/{reference}`\n- **Blob download**: `GET /v2/{namespace}/{repository}/blobs/{digest}`\n- **Tag listing**: `GET /v2/{namespace}/{repository}/tags/list`\n- **Artifact existence**: `HEAD /v2/{namespace}/{repository}/manifests/{reference}`\n\n## Configuration\n\nOCI settings in `config.defaults.toml`:\n\n```{$detected_lang}\n[orchestrator.oci]\nregistry_url = "http://localhost:5000"\nnamespace = "provisioning-extensions"\ncache_dir = "{{orchestrator.paths.data_dir}}/oci-cache"\n```\n\n### Configuration Options\n\n- **registry_url**: OCI registry HTTP endpoint\n- **namespace**: Default namespace for artifacts\n- **cache_dir**: Local cache directory for downloaded artifacts\n\n## API Endpoints\n\n### List OCI Artifacts\n\n```{$detected_lang}\nPOST /api/v1/oci/artifacts\nContent-Type: application/json\n\n{\n "namespace": "kcl"\n}\n```\n\n**Response:**\n\n```{$detected_lang}\n{\n "success": true,\n "data": [\n {\n "name": "provisioning-core",\n "version": "1.0.0",\n "digest": "sha256:abc123...",\n "size": 102400,\n "media_type": "application/vnd.oci.image.manifest.v1+json",\n "created_at": "2025-10-06T12:00:00Z"\n }\n ]\n}\n```\n\n## Usage Examples\n\n### Pull KCL Package\n\n```{$detected_lang}\nuse provisioning_orchestrator::oci::OciManager;\nuse std::path::PathBuf;\n\nlet oci_manager = OciManager::new(\n "http://localhost:5000".to_string(),\n "provisioning-extensions".to_string(),\n PathBuf::from("/tmp/oci-cache"),\n);\n\n// Pull KCL package\nlet package_path = oci_manager.pull_kcl_package(\n "provisioning-core",\n "1.0.0"\n).await?;\n\nprintln!("Package downloaded to: {}", package_path.display());\n\n// Extract package\n// tar -xzf package_path\n```\n\n### Pull Extension Artifact\n\n```{$detected_lang}\n// Pull taskserv extension\nlet artifact_path =
|
