prvng_core/nulib/lib_provisioning/extensions/QUICKSTART.md

Extension System Quick Start Guide

Get started with the Extension Loading System in 5 minutes.

Prerequisites

1. OCI Registry (optional, for OCI features):

   # Start local registry
   docker run -d -p 5000:5000 --name registry registry:2
   

2. Nushell 0.107+:

   nu --version
   

Quick Start

1. Load an Extension

# Load latest from auto-detected source
provisioning ext load kubernetes

# Load specific version
provisioning ext load kubernetes --version 1.28.0

# Load from specific source
provisioning ext load redis --source oci

2. Search for Extensions

# Search all sources
provisioning ext search kube

# Search OCI registry
provisioning ext search postgres --source oci

3. List Available Extensions

# List all
provisioning ext list

# Filter by type
provisioning ext list --type taskserv

# JSON format
provisioning ext list --format json

4. Manage Cache

# Show cache stats
provisioning ext cache stats

# List cached
provisioning ext cache list

# Clear cache
provisioning ext cache clear --all

5. Publish an Extension

# Create extension
mkdir -p my-extension/{kcl,scripts}

# Create manifest
cat > my-extension/extension.yaml <<EOF
extension:
  name: my-extension
  version: 1.0.0
  type: taskserv
  description: My awesome extension
EOF

# Publish to OCI
provisioning ext publish ./my-extension --version 1.0.0

Configuration

Enable OCI Registry

Edit workspace/config/local-overrides.toml:

[oci]
registry = "localhost:5000"
namespace = "provisioning-extensions"
auth_token_path = "~/.provisioning/oci-token"

[extensions]
source_type = "auto"  # auto, oci, gitea, local

Test OCI Connection

provisioning ext test-oci

Common Workflows

Workflow 1: Install Taskserv from OCI

# Search for taskserv
provisioning ext search kubernetes --source oci

# Load it
provisioning ext load kubernetes --version ^1.28.0

# Use in provisioning
provisioning taskserv create kubernetes

Workflow 2: Develop and Test Locally

# Copy to local path
cp -r my-extension ~/.provisioning-extensions/taskservs/

# Load locally
provisioning ext load my-extension --source local

# Test
provisioning taskserv create my-extension --check

# Publish when ready
provisioning ext publish ./my-extension --version 1.0.0

Workflow 3: Offline Usage

# Pull extensions to cache while online
provisioning ext pull kubernetes --version 1.28.0
provisioning ext pull redis --version 7.0.0
provisioning ext pull postgres --version 15.0.0

# Work offline - uses cache
provisioning ext load kubernetes
provisioning ext load redis

Extension Structure

Minimal extension:

my-extension/
├── extension.yaml       # Required manifest
└── kcl/                # At least one content dir
    └── my-extension.k

Complete extension:

my-extension/
├── extension.yaml       # Manifest
├── kcl/                # KCL schemas
│   ├── my-extension.k
│   └── kcl.mod
├── scripts/            # Installation scripts
│   ├── install.nu
│   └── uninstall.nu
├── templates/          # Config templates
│   └── config.yaml.j2
└── docs/              # Documentation
    └── README.md

Troubleshooting

Extension Not Found

# Discover available extensions
provisioning ext discover

# Search by name
provisioning ext search <name>

# Check specific source
provisioning ext list --source oci

OCI Registry Issues

# Test connection
provisioning ext test-oci

# Check registry is running
curl http://localhost:5000/v2/

# View OCI config
provisioning env | grep OCI

Cache Problems

# Clear and rebuild
provisioning ext cache clear --all

# Pull fresh copy
provisioning ext pull <name> --force

Next Steps

• Read full documentation: README.md
• Explore test suite: tests/run_all_tests.nu
• Check implementation summary: EXTENSION_LOADER_IMPLEMENTATION_SUMMARY.md

Help

# Extension commands help
provisioning ext --help

# Cache commands help
provisioning ext cache --help

# Publish help
nu provisioning/tools/publish_extension.nu --help