# OCI Registry Quick Reference\n\n**Version**: 1.0.0 | **Date**: 2025-10-06\n\n---\n\n## Prerequisites\n\n```\n# Install OCI tool (choose one)\nbrew install oras        # Recommended\nbrew install skopeo      # Alternative\ngo install github.com/google/go-containerregistry/cmd/crane@latest  # Alternative\n```\n\n---\n\n## Quick Start (5 Minutes)\n\n```\n# 1. Start local OCI registry\nprovisioning oci-registry start\n\n# 2. Login to registry\nprovisioning oci login localhost:5000\n\n# 3. Pull an extension\nprovisioning oci pull kubernetes:1.28.0\n\n# 4. List available extensions\nprovisioning oci list\n\n# 5. Configure workspace to use OCI\n# Edit: workspace/config/provisioning.yaml\n# Add OCI dependency configuration\n```\n\n---\n\n## Common Commands\n\n### Extension Discovery\n\n```\n# List all extensions\nprovisioning oci list\n\n# Search for extensions\nprovisioning oci search kubernetes\n\n# Show available versions\nprovisioning oci tags kubernetes\n\n# Inspect extension details\nprovisioning oci inspect kubernetes:1.28.0\n```\n\n### Extension Installation\n\n```\n# Pull specific version\nprovisioning oci pull kubernetes:1.28.0\n\n# Pull to custom location\nprovisioning oci pull redis:7.0.0 --destination /path/to/extensions\n\n# Pull from custom registry\nprovisioning oci pull postgres:15.0 \\n  --registry harbor.company.com \\n  --namespace provisioning-extensions\n```\n\n### Extension Publishing\n\n```\n# Login (one-time)\nprovisioning oci login localhost:5000\n\n# Package extension\nprovisioning oci package ./extensions/taskservs/redis\n\n# Publish to registry\nprovisioning oci push ./extensions/taskservs/redis redis 1.0.0\n\n# Verify publication\nprovisioning oci tags redis\n```\n\n### Dependency Management\n\n```\n# Resolve all dependencies\nprovisioning dep resolve\n\n# Check for updates\nprovisioning dep check-updates\n\n# Update specific extension\nprovisioning dep update kubernetes\n\n# Show dependency tree\nprovisioning dep tree kubernetes\n\n# Validate dependencies\nprovisioning dep validate\n```\n\n---\n\n## Configuration Templates\n\n### Workspace OCI Configuration\n\n**File**: `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      auth_token_path: "~/.provisioning/tokens/oci"\n\n    modules:\n      providers:\n        - "oci://localhost:5000/provisioning-extensions/aws:2.0.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\n      clusters:\n        - "oci://localhost:5000/provisioning-extensions/buildkit:0.12.0"\n```\n\n### Extension Manifest\n\n**File**: `extensions/{type}/{name}/manifest.yaml`\n\n```\nname: redis\ntype: taskserv\nversion: 1.0.0\ndescription: Redis in-memory data store\nauthor: Your Name\nlicense: MIT\n\ndependencies:\n  os: ">=1.0.0"\n\ntags:\n  - database\n  - cache\n\nplatforms:\n  - linux/amd64\n\nmin_provisioning_version: "3.0.0"\n```\n\n---\n\n## Extension Development Workflow\n\n```\n# 1. Create extension\nprovisioning generate extension taskserv redis\n\n# 2. Develop extension\n# Edit files in extensions/taskservs/redis/\n\n# 3. Test locally\nprovisioning module load taskserv workspace_dev redis --source local\nprovisioning taskserv create redis --infra test --check\n\n# 4. Validate structure\nprovisioning oci package validate ./extensions/taskservs/redis\n\n# 5. Package\nprovisioning oci package ./extensions/taskservs/redis\n\n# 6. Publish\nprovisioning oci push ./extensions/taskservs/redis redis 1.0.0\n\n# 7. Verify\nprovisioning oci inspect redis:1.0.0\n```\n\n---\n\n## Registry Management\n\n### Local Registry (Development)\n\n```\n# Start\nprovisioning oci-registry start\n\n# Stop\nprovisioning oci-registry stop\n\n# Status\nprovisioning oci-registry status\n\n# Endpoint: localhost:5000\n# Storage: ~/.provisioning/oci-registry/\n```\n\n### Remote Registry (Production)\n\n```\n# Login to Harbor\nprovisioning oci login harbor.company.com --username admin\n\n# Configure in workspace\n# Edit workspace/config/provisioning.yaml:\n# dependencies:\n#   registry:\n#     oci:\n#       endpoint: "https://harbor.company.com"\n#       tls_enabled: true\n```\n\n---\n\n## Migration from Monorepo\n\n```\n# 1. Dry-run migration (preview)\nprovisioning migrate-to-oci workspace_dev --dry-run\n\n# 2. Migrate with publishing\nprovisioning migrate-to-oci workspace_dev --publish\n\n# 3. Validate migration\nprovisioning validate-migration workspace_dev\n\n# 4. Generate report\nprovisioning migration-report workspace_dev\n\n# 5. Rollback if needed\nprovisioning rollback-migration workspace_dev\n```\n\n---\n\n## Troubleshooting\n\n### Registry Not Running\n\n```\n# Check if registry is running\ncurl http://localhost:5000/v2/_catalog\n\n# Start if not running\nprovisioning oci-registry start\n```\n\n### Authentication Failed\n\n```\n# Login again\nprovisioning oci login localhost:5000\n\n# Or use token file\necho "your-token" > ~/.provisioning/tokens/oci\n```\n\n### Extension Not Found\n\n```\n# Check registry connection\nprovisioning oci config\n\n# List available extensions\nprovisioning oci list\n\n# Check namespace\nprovisioning oci list --namespace provisioning-extensions\n```\n\n### Dependency Resolution Failed\n\n```\n# Validate dependencies\nprovisioning dep validate\n\n# Show dependency tree\nprovisioning dep tree kubernetes\n\n# Check for updates\nprovisioning dep check-updates\n```\n\n---\n\n## Best Practices\n\n### Versioning\n\n✅ **DO**: Use semantic versioning (MAJOR.MINOR.PATCH)\n\n```\nversion: 1.2.3\n```\n\n❌ **DON'T**: Use arbitrary versions\n\n```\nversion: latest  # Unpredictable\n```\n\n### Dependencies\n\n✅ **DO**: Specify version constraints\n\n```\ndependencies:\n  containerd: ">=1.7.0"\n  etcd: "^3.5.0"\n```\n\n❌ **DON'T**: Use wildcards\n\n```\ndependencies:\n  containerd: "*"  # Too permissive\n```\n\n### Security\n\n✅ **DO**:\n\n- Use TLS for production registries\n- Rotate authentication tokens\n- Scan for vulnerabilities\n\n❌ **DON'T**:\n\n- Use `--insecure` in production\n- Store passwords in config files\n\n---\n\n## Common Patterns\n\n### Pull and Install\n\n```\n# Pull extension\nprovisioning oci pull kubernetes:1.28.0\n\n# Resolve dependencies (auto-installs)\nprovisioning dep resolve\n\n# Use extension\nprovisioning taskserv create kubernetes\n```\n\n### Update Extensions\n\n```\n# Check for updates\nprovisioning dep check-updates\n\n# Update specific extension\nprovisioning dep update kubernetes\n\n# Update all\nprovisioning dep resolve --update\n```\n\n### Copy Between Registries\n\n```\n# Copy from local to production\nprovisioning oci copy \\n  localhost:5000/provisioning-extensions/kubernetes:1.28.0 \\n  harbor.company.com/provisioning/kubernetes:1.28.0\n```\n\n### Publish Multiple Extensions\n\n```\n# Publish all taskservs\nfor dir in (ls extensions/taskservs); do\n  provisioning oci push $dir.name $dir.name 1.0.0\ndone\n```\n\n---\n\n## Environment Variables\n\n```\n# Override registry\nexport PROVISIONING_OCI_REGISTRY="harbor.company.com"\n\n# Override namespace\nexport PROVISIONING_OCI_NAMESPACE="my-extensions"\n\n# Set auth token\nexport PROVISIONING_OCI_TOKEN="your-token-here"\n```\n\n---\n\n## File Locations\n\n```\n~/.provisioning/\n├── oci-cache/              # OCI artifact cache\n├── oci-registry/           # Local Zot registry data\n└── tokens/\n    └── oci                 # OCI auth token\n\nworkspace/\n├── config/\n│   └── provisioning.yaml   # OCI configuration\n└── extensions/             # Installed extensions\n    ├── providers/\n    ├── taskservs/\n    └── clusters/\n```\n\n---\n\n## Reference Links\n\n- [OCI Registry Guide](user/OCI_REGISTRY_GUIDE.md) - Complete user guide\n- [Multi-Repo Architecture](architecture/MULTI_REPO_ARCHITECTURE.md) - Architecture details\n- [Implementation Summary](../MULTI_REPO_OCI_IMPLEMENTATION_SUMMARY.md) - Technical details\n\n---\n\n**Quick Help**: `provisioning oci --help` | `provisioning dep --help`
