# OCI Registry User Guide\n\n**Version**: 1.0.0\n**Date**: 2025-10-06\n**Audience**: Users and Developers\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Quick Start](#quick-start)\n3. [OCI Commands Reference](#oci-commands-reference)\n4. [Dependency Management](#dependency-management)\n5. [Extension Development](#extension-development)\n6. [Registry Setup](#registry-setup)\n7. [Troubleshooting](#troubleshooting)\n\n---\n\n## Overview\n\nThe OCI registry integration enables distribution and management of provisioning extensions as OCI artifacts. This provides:\n\n- **Standard Distribution**: Use industry-standard OCI registries\n- **Version Management**: Proper semantic versioning for all extensions\n- **Dependency Resolution**: Automatic dependency management\n- **Caching**: Efficient caching to reduce downloads\n- **Security**: TLS, authentication, and vulnerability scanning support\n\n### What are OCI Artifacts\n\nOCI (Open Container Initiative) artifacts are packaged files distributed through container registries. Unlike Docker images which contain\napplications, OCI artifacts can contain any type of content - in our case, provisioning extensions (KCL schemas, Nushell scripts, templates, etc.).\n\n---\n\n## Quick Start\n\n### Prerequisites\n\nInstall one of the following OCI tools:\n\n```\n# ORAS (recommended)\nbrew install oras\n\n# Crane (Google's tool)\ngo install github.com/google/go-containerregistry/cmd/crane@latest\n\n# Skopeo (RedHat's tool)\nbrew install skopeo\n```\n\n### 1. Start Local OCI Registry (Development)\n\n```\n# Start lightweight OCI registry (Zot)\nprovisioning oci-registry start\n\n# Verify registry is running\ncurl http://localhost:5000/v2/_catalog\n```\n\n### 2. Pull an Extension\n\n```\n# Pull Kubernetes extension from registry\nprovisioning oci pull kubernetes:1.28.0\n\n# Pull with specific registry\nprovisioning oci pull kubernetes:1.28.0 \\n  --registry harbor.company.com \\n  --namespace provisioning-extensions\n```\n\n### 3. List Available Extensions\n\n```\n# List all extensions\nprovisioning oci list\n\n# Search for specific extension\nprovisioning oci search kubernetes\n\n# Show available versions\nprovisioning oci tags kubernetes\n```\n\n### 4. Configure Workspace to Use OCI\n\nEdit `workspace/config/provisioning.yaml`:\n\n```\ndependencies:\n  extensions:\n    source_type: "oci"\n\n    oci:\n      registry: "localhost:5000"\n      namespace: "provisioning-extensions"\n      tls_enabled: false\n\n    modules:\n      taskservs:\n        - "oci://localhost:5000/provisioning-extensions/kubernetes:1.28.0"\n        - "oci://localhost:5000/provisioning-extensions/containerd:1.7.0"\n```\n\n### 5. Resolve Dependencies\n\n```\n# Resolve and install all dependencies\nprovisioning dep resolve\n\n# Check what will be installed\nprovisioning dep resolve --dry-run\n\n# Show dependency tree\nprovisioning dep tree kubernetes\n```\n\n---\n\n## OCI Commands Reference\n\n### Pull Extension\n\n**Download extension from OCI registry**\n\n```\nprovisioning oci pull <artifact>:<version> [OPTIONS]\n\n# Examples:\nprovisioning oci pull kubernetes:1.28.0\nprovisioning oci pull redis:7.0.0 --registry harbor.company.com\nprovisioning oci pull postgres:15.0 --insecure  # Skip TLS verification\n```\n\n**Options**:\n\n- `--registry <endpoint>`: Override registry (default: from config)\n- `--namespace <name>`: Override namespace (default: provisioning-extensions)\n- `--destination <path>`: Local installation path\n- `--insecure`: Skip TLS certificate verification\n\n---\n\n### Push Extension\n\n**Publish extension to OCI registry**\n\n```\nprovisioning oci push <source-path> <name> <version> [OPTIONS]\n\n# Examples:\nprovisioning oci push ./extensions/taskservs/redis redis 1.0.0\nprovisioning oci push ./my-provider aws 2.1.0 --registry localhost:5000\n```\n\n**Options**:\n\n- `--registry <endpoint>`: Target registry\n- `--namespace <name>`: Target namespace\n- `--insecure`: Skip TLS verification\n\n**Prerequisites**:\n\n- Extension must have valid `manifest.yaml`\n- Must be logged in to registry (see `oci login`)\n\n---\n\n### List Extensions\n\n**Show available extensions in registry**\n\n```\nprovisioning oci list [OPTIONS]\n\n# Examples:\nprovisioning oci list\nprovisioning oci list --namespace provisioning-platform\nprovisioning oci list --registry harbor.company.com\n```\n\n**Output**:\n\n```\n┬───────────────┬──────────────────┬─────────────────────────┬─────────────────────────────────────────────┐\n│ name          │ registry         │ namespace               │ reference                                   │\n├───────────────┼──────────────────┼─────────────────────────┼─────────────────────────────────────────────┤\n│ kubernetes    │ localhost:5000   │ provisioning-extensions │ localhost:5000/provisioning-extensions/...  │\n│ containerd    │ localhost:5000   │ provisioning-extensions │ localhost:5000/provisioning-extensions/...  │\n│ cilium        │ localhost:5000   │ provisioning-extensions │ localhost:5000/provisioning-extensions/...  │\n└───────────────┴──────────────────┴─────────────────────────┴─────────────────────────────────────────────┘\n```\n\n---\n\n### Search Extensions\n\n**Search for extensions matching query**\n\n```\nprovisioning oci search <query> [OPTIONS]\n\n# Examples:\nprovisioning oci search kube\nprovisioning oci search postgres\nprovisioning oci search "container-*"\n```\n\n---\n\n### Show Tags (Versions)\n\n**Display all available versions of an extension**\n\n```\nprovisioning oci tags <artifact-name> [OPTIONS]\n\n# Examples:\nprovisioning oci tags kubernetes\nprovisioning oci tags redis --registry harbor.company.com\n```\n\n**Output**:\n\n```\n┬────────────┬─────────┬──────────────────────────────────────────────────────┐\n│ artifact   │ version │ reference                                            │\n├────────────┼─────────┼──────────────────────────────────────────────────────┤\n│ kubernetes │ 1.29.0  │ localhost:5000/provisioning-extensions/kubernetes... │\n│ kubernetes │ 1.28.0  │ localhost:5000/provisioning-extensions/kubernetes... │\n│ kubernetes │ 1.27.0  │ localhost:5000/provisioning-extensions/kubernetes... │\n└────────────┴─────────┴──────────────────────────────────────────────────────┘\n```\n\n---\n\n### Inspect Extension\n\n**Show detailed manifest and metadata**\n\n```\nprovisioning oci inspect <artifact>:<version> [OPTIONS]\n\n# Examples:\nprovisioning oci inspect kubernetes:1.28.0\nprovisioning oci inspect redis:7.0.0 --format json\n```\n\n**Output**:\n\n```\nname: kubernetes\ntype: taskserv\nversion: 1.28.0\ndescription: Kubernetes container orchestration platform\nauthor: Provisioning Team\nlicense: MIT\ndependencies:\n  containerd: ">=1.7.0"\n  etcd: ">=3.5.0"\nplatforms:\n  - linux/amd64\n  - linux/arm64\n```\n\n---\n\n### Login to Registry\n\n**Authenticate with OCI registry**\n\n```\nprovisioning oci login <registry> [OPTIONS]\n\n# Examples:\nprovisioning oci login localhost:5000\nprovisioning oci login harbor.company.com --username admin\nprovisioning oci login registry.io --password-stdin < token.txt\nprovisioning oci login registry.io --token-file ~/.provisioning/tokens/registry\n```\n\n**Options**:\n\n- `--username <user>`: Username (default: `_token`)\n- `--password-stdin`: Read password from stdin\n- `--token-file <path>`: Read token from file\n\n**Note**: Credentials are stored in Docker config (`~/.docker/config.json`)\n\n---\n\n### Logout from Registry\n\n**Remove stored credentials**\n\n```\nprovisioning oci logout <registry>\n\n# Example:\nprovisioning oci logout harbor.company.com\n```\n\n---\n\n### Delete Extension\n\n**Remove extension from registry**\n\n```\nprovisioning oci delete <artifact>:<version> [OPTIONS]\n\n# Examples:\nprovisioning oci delete kubernetes:1.27.0\nprovisioning oci delete redis:6.0.0 --force  # Skip confirmation\n```\n\n**Options**:\n\n- `--force`: Skip confirmation prompt\n- `--registry <endpoint>`: Target registry\n- `--namespace <name>`: Target namespace\n\n**Warning**: This operation is irreversible. Use with caution.\n\n---\n\n### Copy Extension\n\n**Copy extension between registries**\n\n```\nprovisioning oci copy <source> <destination> [OPTIONS]\n\n# Examples:\n# Copy between namespaces in same registry\nprovisioning oci copy \\n  localhost:5000/test/kubernetes:1.28.0 \\n  localhost:5000/production/kubernetes:1.28.0\n\n# Copy between different registries\nprovisioning oci copy \\n  localhost:5000/provisioning-extensions/kubernetes:1.28.0 \\n  harbor.company.com/provisioning/kubernetes:1.28.0\n```\n\n---\n\n### Show OCI Configuration\n\n**Display current OCI settings**\n\n```\nprovisioning oci config\n\n# Output:\n{\n  tool: "oras"\n  registry: "localhost:5000"\n  namespace: {\n    extensions: "provisioning-extensions"\n    platform: "provisioning-platform"\n  }\n  cache_dir: "~/.provisioning/oci-cache"\n  tls_enabled: false\n}\n```\n\n---\n\n## Dependency Management\n\n### Dependency Configuration\n\nDependencies are configured in `workspace/config/provisioning.yaml`:\n\n```\ndependencies:\n  # Core provisioning system\n  core:\n    source: "oci://harbor.company.com/provisioning-core:v3.5.0"\n\n  # Extensions (providers, taskservs, clusters)\n  extensions:\n    source_type: "oci"\n\n    oci:\n      registry: "localhost:5000"\n      namespace: "provisioning-extensions"\n      tls_enabled: false\n      auth_token_path: "~/.provisioning/tokens/oci"\n\n    modules:\n      providers:\n        - "oci://localhost:5000/provisioning-extensions/aws:2.0.0"\n        - "oci://localhost:5000/provisioning-extensions/upcloud:1.5.0"\n\n      taskservs:\n        - "oci://localhost:5000/provisioning-extensions/kubernetes:1.28.0"\n        - "oci://localhost:5000/provisioning-extensions/containerd:1.7.0"\n        - "oci://localhost:5000/provisioning-extensions/etcd:3.5.0"\n\n      clusters:\n        - "oci://localhost:5000/provisioning-extensions/buildkit:0.12.0"\n\n  # Platform services\n  platform:\n    source_type: "oci"\n    oci:\n      registry: "harbor.company.com"\n      namespace: "provisioning-platform"\n```\n\n### Resolve Dependencies\n\n```\n# Resolve and install all configured dependencies\nprovisioning dep resolve\n\n# Dry-run (show what would be installed)\nprovisioning dep resolve --dry-run\n\n# Resolve with specific version constraints\nprovisioning dep resolve --update  # Update to latest versions\n```\n\n### Check for Updates\n\n```\n# Check all dependencies for updates\nprovisioning dep check-updates\n\n# Output:\n┬─────────────┬─────────┬────────┬──────────────────┐\n│ name        │ current │ latest │ update_available │\n├─────────────┼─────────┼────────┼──────────────────┤\n│ kubernetes  │ 1.28.0  │ 1.29.0 │ true             │\n│ containerd  │ 1.7.0   │ 1.7.0  │ false            │\n│ etcd        │ 3.5.0   │ 3.5.1  │ true             │\n└─────────────┴─────────┴────────┴──────────────────┘\n```\n\n### Update Dependency\n\n```\n# Update specific extension to latest version\nprovisioning dep update kubernetes\n\n# Update to specific version\nprovisioning dep update kubernetes --version 1.29.0\n```\n\n### Dependency Tree\n\n```\n# Show dependency tree for extension\nprovisioning dep tree kubernetes\n\n# Output:\nkubernetes:1.28.0\n├── containerd:1.7.0\n│   └── runc:1.1.0\n├── etcd:3.5.0\n└── kubectl:1.28.0\n```\n\n### Validate Dependencies\n\n```\n# Validate dependency graph (check for cycles, conflicts)\nprovisioning dep validate\n\n# Validate specific extension\nprovisioning dep validate kubernetes\n```\n\n---\n\n## Extension Development\n\n### Create New Extension\n\n```\n# Generate extension from template\nprovisioning generate extension taskserv redis\n\n# Directory structure created:\n# extensions/taskservs/redis/\n# ├── schemas/\n# │   ├── manifest.toml\n# │   ├── main.ncl\n# │   ├── version.ncl\n# │   └── dependencies.ncl\n# ├── scripts/\n# │   ├── install.nu\n# │   ├── check.nu\n# │   └── uninstall.nu\n# ├── templates/\n# ├── docs/\n# │   └── README.md\n# ├── tests/\n# └── manifest.yaml\n```\n\n### Extension Manifest\n\nEdit `manifest.yaml`:\n\n```\nname: redis\ntype: taskserv\nversion: 1.0.0\ndescription: Redis in-memory data structure store\nauthor: Your Name\nlicense: MIT\nhomepage: https://redis.io\nrepository: https://gitea.example.com/provisioning-extensions/redis\n\ndependencies:\n  os: ">=1.0.0"  # Required OS taskserv\n\ntags:\n  - database\n  - cache\n  - key-value\n\nplatforms:\n  - linux/amd64\n  - linux/arm64\n\nmin_provisioning_version: "3.0.0"\n```\n\n### Test Extension Locally\n\n```\n# Load extension from local path\nprovisioning module load taskserv workspace_dev redis --source local\n\n# Test installation\nprovisioning taskserv create redis --infra test-env --check\n\n# Run tests\nprovisioning test extension redis\n```\n\n### Validate Extension\n\n```\n# Validate extension structure\nprovisioning oci package validate ./extensions/taskservs/redis\n\n# Output:\n✓ Extension structure valid\nWarnings:\n  - Missing docs/README.md (recommended)\n```\n\n### Package Extension\n\n```\n# Package as OCI artifact\nprovisioning oci package ./extensions/taskservs/redis\n\n# Output: redis-1.0.0.tar.gz\n\n# Inspect package\nprovisioning oci inspect-artifact redis-1.0.0.tar.gz\n```\n\n### Publish Extension\n\n```\n# Login to registry (one-time)\nprovisioning oci login localhost:5000\n\n# Publish extension\nprovisioning oci push ./extensions/taskservs/redis redis 1.0.0\n\n# Verify publication\nprovisioning oci tags redis\n\n# Share with team\necho "Published: oci://localhost:5000/provisioning-extensions/redis:1.0.0"\n```\n\n---\n\n## Registry Setup\n\n### Local Registry (Development)\n\n**Using Zot (lightweight)**:\n\n```\n# Start Zot registry\nprovisioning oci-registry start\n\n# Configuration:\n# - Endpoint: localhost:5000\n# - Storage: ~/.provisioning/oci-registry/\n# - No authentication\n# - TLS disabled\n\n# Stop registry\nprovisioning oci-registry stop\n\n# Check status\nprovisioning oci-registry status\n```\n\n**Manual Zot Setup**:\n\n```\n# Install Zot\nbrew install project-zot/tap/zot\n\n# Create config\ncat > zot-config.json <<EOF\n{\n  "storage": {\n    "rootDirectory": "/tmp/zot"\n  },\n  "http": {\n    "address": "0.0.0.0",\n    "port": "5000"\n  },\n  "log": {\n    "level": "info"\n  }\n}\nEOF\n\n# Run Zot\nzot serve zot-config.json\n```\n\n---\n\n### Remote Registry (Production)\n\n**Using Harbor**:\n\n1. **Deploy Harbor**:\n\n   ```bash\n   # Using Docker Compose\n   wget https://github.com/goharbor/harbor/releases/download/v2.9.0/harbor-offline-installer-v2.9.0.tgz\n   tar xvf harbor-offline-installer-v2.9.0.tgz\n   cd harbor\n   ./install.sh\n   ```\n\n1. **Configure Workspace**:\n\n   ```yaml\n   # workspace/config/provisioning.yaml\n   dependencies:\n     registry:\n       type: "oci"\n       oci:\n         endpoint: "https://harbor.company.com"\n         namespaces:\n           extensions: "provisioning/extensions"\n           platform: "provisioning/platform"\n         tls_enabled: true\n         auth_token_path: "~/.provisioning/tokens/harbor"\n   ```\n\n2. **Login**:\n\n   ```bash\n   provisioning oci login harbor.company.com --username admin\n   ```\n\n---\n\n## Troubleshooting\n\n### No OCI Tool Found\n\n**Error**: "No OCI tool found. Install oras, crane, or skopeo"\n\n**Solution**:\n\n```\n# Install ORAS (recommended)\nbrew install oras\n\n# Or install Crane\ngo install github.com/google/go-containerregistry/cmd/crane@latest\n\n# Or install Skopeo\nbrew install skopeo\n```\n\n---\n\n### Connection Refused\n\n**Error**: "Connection refused to localhost:5000"\n\n**Solution**:\n\n```\n# Check if registry is running\ncurl http://localhost:5000/v2/_catalog\n\n# Start local registry if not running\nprovisioning oci-registry start\n```\n\n---\n\n### TLS Certificate Error\n\n**Error**: "x509: certificate signed by unknown authority"\n\n**Solution**:\n\n```\n# For development, use --insecure flag\nprovisioning oci pull kubernetes:1.28.0 --insecure\n\n# For production, configure TLS properly in workspace config:\n# dependencies:\n#   extensions:\n#     oci:\n#       tls_enabled: true\n#       # Add CA certificate to system trust store\n```\n\n---\n\n### Authentication Failed\n\n**Error**: "unauthorized: authentication required"\n\n**Solution**:\n\n```\n# Login to registry\nprovisioning oci login localhost:5000\n\n# Or provide auth token in config:\n# dependencies:\n#   extensions:\n#     oci:\n#       auth_token_path: "~/.provisioning/tokens/oci"\n```\n\n---\n\n### Extension Not Found\n\n**Error**: "Dependency not found: kubernetes"\n\n**Solutions**:\n\n1. **Check registry endpoint**:\n\n   ```bash\n   provisioning oci config\n   ```\n\n1. **List available extensions**:\n\n   ```bash\n   provisioning oci list\n   ```\n\n2. **Check namespace**:\n\n   ```bash\n   provisioning oci list --namespace provisioning-extensions\n   ```\n\n3. **Verify extension exists**:\n\n   ```bash\n   provisioning oci tags kubernetes\n   ```\n\n---\n\n### Dependency Resolution Failed\n\n**Error**: "Circular dependency detected"\n\n**Solution**:\n\n```\n# Validate dependency graph\nprovisioning dep validate kubernetes\n\n# Check dependency tree\nprovisioning dep tree kubernetes\n\n# Fix circular dependencies in extension manifests\n```\n\n---\n\n## Best Practices\n\n### Version Pinning\n\n✅ **DO**: Pin to specific versions in production\n\n```\nmodules:\n  taskservs:\n    - "oci://registry/kubernetes:1.28.0"  # Specific version\n```\n\n❌ **DON'T**: Use `latest` tag in production\n\n```\nmodules:\n  taskservs:\n    - "oci://registry/kubernetes:latest"  # Unpredictable\n```\n\n---\n\n### Semantic Versioning\n\n✅ **DO**: Follow semver (MAJOR.MINOR.PATCH)\n\n- `1.0.0` → `1.0.1`: Backward-compatible bug fix\n- `1.0.0` → `1.1.0`: Backward-compatible new feature\n- `1.0.0` → `2.0.0`: Breaking change\n\n❌ **DON'T**: Use arbitrary version numbers\n\n- `v1`, `version-2`, `latest-stable`\n\n---\n\n### Dependency Management\n\n✅ **DO**: Specify version constraints\n\n```\ndependencies:\n  containerd: ">=1.7.0"\n  etcd: "^3.5.0"  # 3.5.x compatible\n```\n\n❌ **DON'T**: Leave dependencies unversioned\n\n```\ndependencies:\n  containerd: "*"  # Too permissive\n```\n\n---\n\n### Security\n\n✅ **DO**:\n\n- Use TLS for remote registries\n- Rotate authentication tokens regularly\n- Scan images for vulnerabilities (Harbor)\n- Sign artifacts (cosign)\n\n❌ **DON'T**:\n\n- Use `--insecure` in production\n- Store passwords in config files\n- Skip certificate verification\n\n---\n\n## Related Documentation\n\n- [Multi-Repository Architecture](../architecture/MULTI_REPO_ARCHITECTURE.md) - Overall architecture\n- [Extension Development Guide](extension-development.md) - Create extensions\n- [Dependency Resolution](dependency-resolution.md) - How dependencies work\n- OCI Client Library - Low-level API\n\n---\n\n**Maintained By**: Documentation Team\n**Last Updated**: 2025-10-06\n**Next Review**: 2026-01-06
