Skip to main content
On April 20th, 2026, we're moving to a new docs site docs.macstadium.com, head there for the most current documentation.
  1. MacStadium
  2. Orka
  3. OCI Images

Orka Self-Service: Migrating NFS Images to OCI with Harbor

This guide walks you through the process of migrating your existing NFS-based images to OCI using Harbor storage in Orka 3.5.

Prerequisites:

  • Orka cluster upgraded to version 3.5.0 or later
  • Harbor instance provisioned by MacStadium
  • Harbor credentials (URL, username, password) from your IP Plan
  • VPN connection configured per your IP plan
  • List of existing NFS images to migrate
  • Inventory of all integrations currently using these images

Step 1: Upgrade to Orka 3.5+

You can verify your Orka version using the Orka3 CLI command orka3 version

If an upgrade is needed:

  •  Contact MacStadium Support to schedule the upgrade
  • Review the Orka v3.5 (or later) release notes to better understand how upgrading may impact you
  • Plan for your scheduled upgrade maintenance window

Step 2: Provision Harbor OCI Registry

Submit a support request for Harbor instance provisioning.

Once the request is complete, you will receive the following:

  • A Harbor instance URL (Usually the last IP in your Orka subnet, e.g., https://10.221.189.254)
  • Harbor metrics URL (e.g., http://10.221.189.254:9090/metrics)
  • Project Admin username + password
  • Default project name (usually this is set to library)

Access the Harbor web interface:

  • Connect to VPN (per your IP plan)
  • Navigate to your Harbor instance URL in your browser
  • Log in using the credentials provided in your IP Plan
  • Verify you can access your project dashboard

Step 3: Configure Orka to Connect to Harbor

  • Add your Harbor registry credentials to Orka using the Orka3 CLI: 
orka3 regcred add \
  -u <OCI.User> \
  -p <OCI.Pass> \
  <OCI.FQDN>
  • Verify your credentials using 
orka3 regcred list
  • Note: Registry credentials are namespace-specific. If you use namespaces other than orka-default, add credentials to each namespace: 
orka3 regcred add \
  -u <user> \
  -p <pass> \
  <FQDN> \
  --namespace <NAMESPACE>

Step 4: Convert NFS Images to OCI Format

  • Confirm the image(s) you'd like to migrate by running orka3 image list and noting the image(s) to convert.
  • Deploy a VM from the specified NFS image: 
orka3 vm deploy \
  --image "<nfs-image-name>" \
  --name "migration-temp-vm" \
  --cpu 4 \
  --memory 8G
  • Wait for the VM to begin running 
orka3 vm list migration-temp-vm

  • Push the VM as an OCI image to Harbor: 

    orka3 vm push migration-temp-vm \
  <Harbor-FQDN>/library/<new-image-name>:<tag>
  • Monitor push status using
orka3 vm get-push-status vm-push-temp-vm
  • After pushing to Harbor, cache the new OCI image on your Orka nodes: 
orka3 imagecache add <Harbor-FQDN>/library/<image-name>:<tag> --all
  • To cache the image on a specific node, run: 
orka3 imagecache add <Harbor-FQDN>/library/<image-name>:<tag> --nodes <node-name>
  • Monitor image caching status: 
orka3 imagecache info <Harbor-FQDN>/library/<image-name>:<tag>
  • Clean up the temporary VM by running: 
orka3 vm delete migration-temp-vm

To do so via the Harbor web UI:

  • Log in to the Harbor web interface
  • Navigate to 'Projects' -> 'Library'
  • Click 'Repositories'
  • Verify your image appears with the correct tag, repeating the process for each NFS image to migrate

Step 5: Update CI/CD Integrations

GitHub Actions

Old workflow example:

name: Run build
uses: macstadium/orka-actions@v1
with:
  image: ventura-base
  cpu: 4

New workflow example:

- name: Run build
  uses: macstadium/orka-actions@v1
  with:
    image: 10.221.189.254/library/sequoia-base:v1.0
    cpu: 4

Jenkins

Old Jenkinsfile example:

orkaVM(image: 'ventura-base', cpu: 4, memory: '8G') { 
// build steps 
}

New Jenkinsfile example:

orkaVM(image: '10.221.189.254/library/sequoia-base:v1.0', cpu: 4, memory: '8G') { 
// build steps 
}

GitLab CI

Old .gitlab-ci.yml example:

variables:
  ORKA_IMAGE: ventura-base

New .gitlab-ci.yml workflow example:

variables:
  ORKA_IMAGE: 10.221.189.254/library/sequoia-base:v1.0

Packer Templates

Old HCL:

source "macstadium-orka" "build" {
  source_image = "sequoia-base"
  image_name   = "custom-build"
}

New HCL:

source "macstadium-orka" "build" {
  source_image = "10.221.189.254/library/sequoia-base:v1.0"
  image_name   = "10.221.189.254/library/custom-build:v1.0"
}

Packer-built images should also be pushed to Harbor using the new OCI format.

Validation and Testing

  • Example test VM deployment from an OCI image
orka3 vm deploy \
  --image "10.221.189.254/library/sequoia-base:v1.0" \
  --name "validation-vm" \
  --cpu 4 \
  --memory 8G

  • Verify the VM boots successfully using 

    orka3 vm list validation-vm
  • Use orka3 vm vnc validation-vm to get the VNC connection information for the VM
  • Run any integration smoke tests your organization uses
  • Monitor Harbor storage

Migration Best Practices

  • Keep NFS images available during transition 
  •  Migrate integrations gradually (not all at once) 
  • Test OCI images thoroughly before removing NFS versions 
  • Maintain rollback capability

  • Use consistent, semantic naming conventions for images, such as: 

    <Harbor-FQDN>/library/<os-version>-<tools>:<semantic-version>
    • (e.g. 10.221.189.254/library/sequoia-xcode16:v1.0)
  • Pre-cache frequently used images on all nodes 
  • Schedule image caching during off-peak hours 

For more information on using Harbor with the Orka3 CLI, review our existing documentation at: https://support.macstadium.com/hc/en-us/articles/41318654531099-Using-Harbor-OCI-Storage-with-the-Orka-CLI

Was this article helpful?