provisioning/docs/src/quick-reference/oci.md

OCI Registry Quick Reference

Version: 1.0.0 | Date: 2025-10-06

---

Prerequisites

# Install OCI tool (choose one)
brew install oras        # Recommended
brew install skopeo      # Alternative
go install github.com/google/go-containerregistry/cmd/crane@latest  # Alternative
```plaintext

---

## Quick Start (5 Minutes)

```bash
# 1. Start local OCI registry
provisioning oci-registry start

# 2. Login to registry
provisioning oci login localhost:5000

# 3. Pull an extension
provisioning oci pull kubernetes:1.28.0

# 4. List available extensions
provisioning oci list

# 5. Configure workspace to use OCI
# Edit: workspace/config/provisioning.yaml
# Add OCI dependency configuration
```plaintext

---

## Common Commands

### Extension Discovery

```bash
# List all extensions
provisioning oci list

# Search for extensions
provisioning oci search kubernetes

# Show available versions
provisioning oci tags kubernetes

# Inspect extension details
provisioning oci inspect kubernetes:1.28.0
```plaintext

### Extension Installation

```bash
# Pull specific version
provisioning oci pull kubernetes:1.28.0

# Pull to custom location
provisioning oci pull redis:7.0.0 --destination /path/to/extensions

# Pull from custom registry
provisioning oci pull postgres:15.0 \
  --registry harbor.company.com \
  --namespace provisioning-extensions
```plaintext

### Extension Publishing

```bash
# Login (one-time)
provisioning oci login localhost:5000

# Package extension
provisioning oci package ./extensions/taskservs/redis

# Publish to registry
provisioning oci push ./extensions/taskservs/redis redis 1.0.0

# Verify publication
provisioning oci tags redis
```plaintext

### Dependency Management

```bash
# Resolve all dependencies
provisioning dep resolve

# Check for updates
provisioning dep check-updates

# Update specific extension
provisioning dep update kubernetes

# Show dependency tree
provisioning dep tree kubernetes

# Validate dependencies
provisioning dep validate
```plaintext

---

## Configuration Templates

### Workspace OCI Configuration

**File**: `workspace/config/provisioning.yaml`

```yaml
dependencies:
  extensions:
    source_type: "oci"

    oci:
      registry: "localhost:5000"
      namespace: "provisioning-extensions"
      tls_enabled: false
      auth_token_path: "~/.provisioning/tokens/oci"

    modules:
      providers:
        - "oci://localhost:5000/provisioning-extensions/aws:2.0.0"

      taskservs:
        - "oci://localhost:5000/provisioning-extensions/kubernetes:1.28.0"
        - "oci://localhost:5000/provisioning-extensions/containerd:1.7.0"

      clusters:
        - "oci://localhost:5000/provisioning-extensions/buildkit:0.12.0"
```plaintext

### Extension Manifest

**File**: `extensions/{type}/{name}/manifest.yaml`

```yaml
name: redis
type: taskserv
version: 1.0.0
description: Redis in-memory data store
author: Your Name
license: MIT

dependencies:
  os: ">=1.0.0"

tags:
  - database
  - cache

platforms:
  - linux/amd64

min_provisioning_version: "3.0.0"
```plaintext

---

## Extension Development Workflow

```bash
# 1. Create extension
provisioning generate extension taskserv redis

# 2. Develop extension
# Edit files in extensions/taskservs/redis/

# 3. Test locally
provisioning module load taskserv workspace_dev redis --source local
provisioning taskserv create redis --infra test --check

# 4. Validate structure
provisioning oci package validate ./extensions/taskservs/redis

# 5. Package
provisioning oci package ./extensions/taskservs/redis

# 6. Publish
provisioning oci push ./extensions/taskservs/redis redis 1.0.0

# 7. Verify
provisioning oci inspect redis:1.0.0
```plaintext

---

## Registry Management

### Local Registry (Development)

```bash
# Start
provisioning oci-registry start

# Stop
provisioning oci-registry stop

# Status
provisioning oci-registry status

# Endpoint: localhost:5000
# Storage: ~/.provisioning/oci-registry/
```plaintext

### Remote Registry (Production)

```bash
# Login to Harbor
provisioning oci login harbor.company.com --username admin

# Configure in workspace
# Edit workspace/config/provisioning.yaml:
# dependencies:
#   registry:
#     oci:
#       endpoint: "https://harbor.company.com"
#       tls_enabled: true
```plaintext

---

## Migration from Monorepo

```bash
# 1. Dry-run migration (preview)
provisioning migrate-to-oci workspace_dev --dry-run

# 2. Migrate with publishing
provisioning migrate-to-oci workspace_dev --publish

# 3. Validate migration
provisioning validate-migration workspace_dev

# 4. Generate report
provisioning migration-report workspace_dev

# 5. Rollback if needed
provisioning rollback-migration workspace_dev
```plaintext

---

## Troubleshooting

### Registry Not Running

```bash
# Check if registry is running
curl http://localhost:5000/v2/_catalog

# Start if not running
provisioning oci-registry start
```plaintext

### Authentication Failed

```bash
# Login again
provisioning oci login localhost:5000

# Or use token file
echo "your-token" > ~/.provisioning/tokens/oci
```plaintext

### Extension Not Found

```bash
# Check registry connection
provisioning oci config

# List available extensions
provisioning oci list

# Check namespace
provisioning oci list --namespace provisioning-extensions
```plaintext

### Dependency Resolution Failed

```bash
# Validate dependencies
provisioning dep validate

# Show dependency tree
provisioning dep tree kubernetes

# Check for updates
provisioning dep check-updates
```plaintext

---

## Best Practices

### Versioning

✅ **DO**: Use semantic versioning (MAJOR.MINOR.PATCH)

```yaml
version: 1.2.3
```plaintext

❌ **DON'T**: Use arbitrary versions

```yaml
version: latest  # Unpredictable
```plaintext

### Dependencies

✅ **DO**: Specify version constraints

```yaml
dependencies:
  containerd: ">=1.7.0"
  etcd: "^3.5.0"
```plaintext

❌ **DON'T**: Use wildcards

```yaml
dependencies:
  containerd: "*"  # Too permissive
```plaintext

### Security

✅ **DO**:

- Use TLS for production registries
- Rotate authentication tokens
- Scan for vulnerabilities

❌ **DON'T**:

- Use `--insecure` in production
- Store passwords in config files

---

## Common Patterns

### Pull and Install

```bash
# Pull extension
provisioning oci pull kubernetes:1.28.0

# Resolve dependencies (auto-installs)
provisioning dep resolve

# Use extension
provisioning taskserv create kubernetes
```plaintext

### Update Extensions

```bash
# Check for updates
provisioning dep check-updates

# Update specific extension
provisioning dep update kubernetes

# Update all
provisioning dep resolve --update
```plaintext

### Copy Between Registries

```bash
# Copy from local to production
provisioning oci copy \
  localhost:5000/provisioning-extensions/kubernetes:1.28.0 \
  harbor.company.com/provisioning/kubernetes:1.28.0
```plaintext

### Publish Multiple Extensions

```bash
# Publish all taskservs
for dir in (ls extensions/taskservs); do
  provisioning oci push $dir.name $dir.name 1.0.0
done
```plaintext

---

## Environment Variables

```bash
# Override registry
export PROVISIONING_OCI_REGISTRY="harbor.company.com"

# Override namespace
export PROVISIONING_OCI_NAMESPACE="my-extensions"

# Set auth token
export PROVISIONING_OCI_TOKEN="your-token-here"
```plaintext

---

## File Locations

```plaintext
~/.provisioning/
├── oci-cache/              # OCI artifact cache
├── oci-registry/           # Local Zot registry data
└── tokens/
    └── oci                 # OCI auth token

workspace/
├── config/
│   └── provisioning.yaml   # OCI configuration
└── extensions/             # Installed extensions
    ├── providers/
    ├── taskservs/
    └── clusters/
```plaintext

---

## Reference Links

- [OCI Registry Guide](user/OCI_REGISTRY_GUIDE.md) - Complete user guide
- [Multi-Repo Architecture](architecture/MULTI_REPO_ARCHITECTURE.md) - Architecture details
- [Implementation Summary](../MULTI_REPO_OCI_IMPLEMENTATION_SUMMARY.md) - Technical details

---

**Quick Help**: `provisioning oci --help` | `provisioning dep --help`