Migrate NFS Orka images to OCI format with Harbor

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 the Harbor OCI Storage entry in your firewall’s Credentials section in My Cloud
VPN connection configured per My Cloud
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.

Email support@macstadium.com
Request: “Harbor OCI registry provisioning for Orka 3.5”

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 My Cloud)
Navigate to your Harbor instance URL in your browser
Log in using the Harbor credentials from your firewall’s Credentials section in My Cloud
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 migration-temp-vm --image <NFS_IMAGE_NAME> --cpu 4 --memory 8

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. Without arguments, this lists every image push in progress or recently finished. To check only this one, pass the job name that orka3 vm push prints:

orka3 vm get-push-status

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

How you point an integration at the new OCI image depends on whether it deploys from an image or from a VM config:

GitHub Actions and GitLab deploy every VM from a VM config, so create a VM config that uses the OCI image, then point the integration at that config.
Jenkins and Packer reference the image directly, so replace the NFS image name with the OCI image reference.

For GitHub Actions and GitLab, create the VM config first:

orka3 vm-config create sequoia-oci --image 10.221.189.254/library/sequoia-base:v1.0

GitHub Actions

The Orka GitHub runner deploys runners from the VM config named in ORKA_VM_CONFIG. Update it wherever you set the runner’s environment (your .env file or docker run command), then restart the runner container. Old configuration example:

ORKA_VM_CONFIG=ventura-base-config

New configuration example:

ORKA_VM_CONFIG=sequoia-oci

For all runner settings, see the GitHub Actions integration.

Jenkins

The Orka plugin takes the image from each agent template, not from your Jenkinsfile. Go to Manage Jenkins → Nodes and Clouds → Configure Clouds, open your Orka Cloud, and in each Orka Template set Image to the OCI image reference:

10.221.189.254/library/sequoia-base:v1.0

For permanent agents, update Image in each node’s configuration. For the full field reference, see the Jenkins integration.

GitLab CI

The custom executor deploys VMs from the VM config named in ORKA_CONFIG_NAME. Update it wherever you set it: your GitLab CI/CD variables (Settings → CI/CD → Variables) or your .gitlab-ci.yml. Old .gitlab-ci.yml example:

variables:
  ORKA_CONFIG_NAME: ventura-base-config

New .gitlab-ci.yml example:

variables:
  ORKA_CONFIG_NAME: sequoia-oci

For all executor settings, see the GitLab integration.

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"
}

Also push Packer-built images to Harbor using the new OCI format.

Validation and testing

Example test VM deployment from an OCI image

orka3 vm deploy validation-vm --image 10.221.189.254/library/sequoia-base:v1.0 --cpu 4 --memory 8

Verify the VM boots successfully using

    orka3 vm list validation-vm

Get the VM’s VNC connection information from the IP and VNC columns of orka3 vm list validation-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.

MacStadium

Orka

MacStadium VDI

IaaS

Migrate NFS Orka images to OCI format with Harbor

Prerequisites

Step 1: Upgrade to Orka 3.5+

Step 2: Provision Harbor OCI registry

Step 3: Configure Orka to connect to Harbor

Step 4: Convert NFS images to OCI format

Step 5: Update CI/CD integrations

GitHub Actions

Jenkins

GitLab CI

Packer templates

Validation and testing

Migration best practices

​Prerequisites

​Step 1: Upgrade to Orka 3.5+

​Step 2: Provision Harbor OCI registry

​Step 3: Configure Orka to connect to Harbor

​Step 4: Convert NFS images to OCI format

​Step 5: Update CI/CD integrations

​GitHub Actions

​Jenkins

​GitLab CI

​Packer templates

​Validation and testing

​Migration best practices

Prerequisites

Step 1: Upgrade to Orka 3.5+

Step 2: Provision Harbor OCI registry

Step 3: Configure Orka to connect to Harbor

Step 4: Convert NFS images to OCI format

Step 5: Update CI/CD integrations

GitHub Actions

Jenkins

GitLab CI

Packer templates

Validation and testing

Migration best practices