Skip to main content
Requires Orka 3.5 or later. If you’re on an earlier version, see the release notes for your version before proceeding.
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, see Using Harbor OCI Storage with the Orka CLI.