OCI Registry Integration

About OCI Images in Orka

OCI (Open Container Initiative) registry credentials are required to push and pull OCI-compatible Apple silicon-based Orka images to or from private repositories.

Common OCI Registries:

• GitHub Container Registry (ghcr.io)
• Docker Hub
• Harbor
• Private registries

Working with OCI Images:

• To deploy a VM using an OCI image: orka3 vm deploy --image server.com/repository/image:tag
• To push an image to an OCI registry: orka3 vm push VM_NAME server.com/repository/image:tag

Managing Registry Credentials

If --namespace is not set, operations default to the orka-default namespace. The shorthand alias for registrycredential is regcred.

orka3 registrycredential add

Add credentials for the specified OCI registry server in the orka-default namespace or the specified namespace. Use this to add new credentials for a new server, or replace existing credentials for an existing server.

Server Address Requirements:

• Must include the scheme, hostname and (optionally) port
• Examples: https://ghcr.io or https://10.221.188.5:30080

If insecure communication is allowed, requests to the registry server will fall back to HTTP when HTTPS is unavailable (disabled by default).

Syntax:

orka3 registrycredential add SERVER --username USERNAME {--password PASSWORD | --password-stdin} [--replace] [--allow-insecure] [--namespace TARGET_NAMESPACE] [flags]

Options:

--allow-insecure         (Optional) Falls back to HTTP if HTTPS is unavailable
-h, --help               Display help for add
-p, --password string    Password for registry authentication
--password-stdin         Read the password from stdin
--replace                (Optional) Replaces credentials for the specified server
-u, --username string    (Required) Username for registry authentication
-n, --namespace string   (Optional) Namespace scope (default "orka-default")

Examples:

# Add registry credentials for GitHub Packages in a specific namespace
orka3 regcred add https://ghcr.io --username whoami --password ghp_*** --namespace orka-test

# Read the password from stdin
echo -n "$PASSWORD" | orka3 regcred add https://ghcr.io --username whoami --password-stdin

# Read the password from file over stdin
orka3 regcred add https://ghcr.io --username whoami --password-stdin < password.txt

# Add credentials for an insecure server
orka3 regcred add --allow-insecure http://10.221.188.5:30080 --username admin --password p@ssw0rd

# Replace existing credentials for GitHub Packages
orka3 regcred add --replace https://ghcr.io --username whoami --password ghp_***

orka3 registrycredential list

List the OCI registry servers that have stored credentials in the orka-default namespace or the specified namespace.

Syntax:

orka3 registrycredential list [--namespace TARGET_NAMESPACE] [--output wide|json] [flags]

Options:

-h, --help               Display help for list
-o, --output string      (Optional) Output format: table (default)|wide|json
-n, --namespace string   (Optional) Namespace scope (default "orka-default")

Examples:

# List OCI registry servers in the 'orka-default' namespace
orka3 regcred list

# Show additional information about each registry server
orka3 regcred list --output wide --namespace orka-test

orka3 registrycredential remove

Remove the authentication credentials for the specified registry server in the orka-default namespace or the specified namespace.

Syntax:

orka3 registrycredential remove SERVER [--namespace TARGET_NAMESPACE] [flags]

Options:

-h, --help               Display help for remove
-n, --namespace string   (Optional) Namespace scope (default "orka-default")

Examples:

# Remove registry credentials for GitHub Packages in 'orka-default'
orka3 regcred remove https://ghcr.io

# Remove registry credentials for a private server in a specific namespace
orka3 regcred remove http://10.221.188.5:30080 --namespace orka-test

Working with OCI Images

Deploying VMs from OCI Images

When deploying a VM, you can specify an OCI image by its full path:

# Deploy a VM from an OCI-compatible image in GitHub Packages
orka3 vm deploy -i ghcr.io/my-organization/orka-images/orka-arm:latest

# Deploy a VM from a specific tagged version
orka3 vm deploy -i ghcr.io/my-organization/orka-images/orka-arm:14.0

Pushing Images to OCI Registries

The state of a running VM can be saved and pushed to an OCI-compatible registry. This operation is applicable only to Apple silicon-based VMs.

For more information, see the VM Lifecycle Management article.

Caching OCI Images

You can cache OCI images directly on cluster nodes without pulling them to local storage first:

# Cache an OCI image on specific nodes
orka3 imagecache add ghcr.io/my-organization/orka-images/orka-arm:latest --nodes mini-arm-10

# Check caching status of an OCI image
orka3 imagecache info ghcr.io/my-organization/orka-images/orka-arm:latest