-
Notifications
You must be signed in to change notification settings - Fork 86
Proposal: Arm64 Support and Multi-Architecture Image Publishing for Harbor #262
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,212 @@ | ||
# Proposal: Arm64 Support and Multi-Architecture Image Publishing for Harbor | ||
|
||
Author: Rani Chowdary Mandepudi, Arm (@ranimandepudi) | ||
|
||
Discussion: https://github.com/goharbor/harbor/pull/21825 | ||
|
||
## Abstract | ||
|
||
This proposal introduces native Arm64 support and multi-architecture image publishing for all Harbor components. The goal is to enable Harbor to run natively on Arm64 hardware, align with CNCF best practices, and enhance Harbor's portability across modern infrastructure environments. | ||
|
||
## Background | ||
|
||
Harbor is a popular cloud-native container registry. While it provides full-featured registry services, its official builds and Docker images target only the Amd64 architecture. The growing adoption of Arm64 in cloud-native and edge computing environments has created demand for native Arm64 support. | ||
|
||
Currently, deploying Harbor on Arm64 requires emulation or custom builds, reducing performance and maintainability. | ||
|
||
## Proposal | ||
|
||
Note: No changes have been made to functionality—this update ensures that the current architecture remains unaffected. | ||
|
||
All Harbor component images have been built and tagged for the Arm64 architecture. These images have been pushed to my DockerHub repository under the namespace ranichowdary/ (replacing the original goharbor/ namespace) for testing and validation purposes. Once the review is complete, the image names can be reverted to the original naming convention. | ||
|
||
Additionally, the Dockerfile paths and image naming conventions have been modified to support multi-architecture builds. This ensures compatibility and seamless operation on both x86 and Arm64 platforms using the same codebase and Docker images. | ||
|
||
These changes allow Harbor to be built, packaged, and installed cleanly on Arm64 hosts such as AWS Graviton and also on x86 as images are multi arch. | ||
|
||
This proposal introduces native Arm64 builds for Harbor components using `Docker Build` and multi-architecture manifests. Each image is tested and published in a way that maintains compatibility with existing Amd64-based deployments. | ||
|
||
## Design Goals | ||
|
||
Build Harbor component images (core, jobservice, registryctl, etc.) for both Arm64 and Amd64 using native compilation per architecture and multi-arch manifest merging. | ||
ranimandepudi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
Published multi-arch images to Docker Hub using unified manifest lists, enabling transparent arch-specific pulls without impacting existing deployments. | ||
|
||
Supported native and cross-platform builds via docker buildx and architecture-specific runners. | ||
|
||
Ensure deterministic and repeatable builds across architectures using consistent Makefile targets and validated build. | ||
|
||
Provide documentation for Arm64 validation, and plan to publish a learning path on learn.arm.com post-upstreaming. | ||
|
||
Integrate Arm64 builds into Harbor’s CI and release workflows using GitHub Actions. This will require coordination with Harbor maintainers—I’m happy to assist or contribute directly as needed. | ||
|
||
## CI changes: | ||
|
||
Multi Arch CI integration on Harbor: | ||
|
||
Objective: | ||
To ensure Harbor's CI system validates code changes across both amd64 and arm64 architectures for pull requests. This enhancement guarantees feature compatibility and stability on both platforms. | ||
|
||
Changes: | ||
* CI.yml | ||
|
||
This file defines main test matrix for harbor on pull requests and pushes. Ensure that Harbor's CI pipeline executed on both arm64 and amd64 architectures for every PR or push | ||
* Enabled Matrix strategy for Architecture: Before jobs like UTTEST, APITEST_DB ran only on `ubuntu-latest` (defauld amd64). With this each job uses: | ||
|
||
stratergy: | ||
matrix: | ||
include: | ||
- arch:amd64 | ||
runner: ubuntu-22.04 | ||
- arch:arm64 | ||
runner: ubuntu-24.04-arm | ||
|
||
Job names updated for architecture clarity. | ||
Unit, API, and UI test logic unchanged, but now dynamically detects platform via `uname -m`. | ||
|
||
* build_package.yml: | ||
* Added matrix to support parallel builds on amd64 and arm64 | ||
* Artifacts now uploaded to `gs://harbor-build/amd64/..` and `gs://harbor-builds/arm64/..` | ||
* Docker images pushed as `docker push ranichowdary/core-harbor:<tag>-arm64` and `docker push ranichowdary/core-harbor:<tag>-amd64` | ||
* Multi-arch manifest created on amd64 runner. | ||
|
||
* publish-release.yml: Matrix used to ensure images pushed for both architectures. Preserved existing functionality. | ||
* conformance_test.yml: Added Matrix strategy for architecture. Architecture specific report upload(report-amd64.html, report-arm64.html) | ||
* docker-compose.yml: Changed images names to multi-arch images | ||
|
||
## Architecture Overview: | ||
|
||
## Image Structure: | ||
|
||
Image tags follow the pattern: goharbor/<component>:<version> | ||
During development and testing, images are published under the ranichowdary/* namespace on Docker Hub (e.g., ranichowdary/core-harbor, ranichowdary/jobservice-harbor). | ||
Finalized multi-arch images will match upstream Harbor naming conventions. | ||
|
||
Images: | ||
MultiArch Images links: | ||
|
||
Nginx: | ||
ranichowdary/nginx-harbor | ||
ranichowdary/nginx-base-harbor | ||
Db: | ||
ranichowdary/db-harbor | ||
ranichowdary/db-base-harbor | ||
Redis: | ||
ranichowdary/redis-harbor | ||
ranichowdary/redis-base-harbor | ||
Log: | ||
ranichowdary/log-harbor | ||
ranichowdary/log-base-harbor | ||
Core: | ||
ranichowdary/core-harbor | ||
ranichowdary/core-base-harbor | ||
Exporter: | ||
ranichowdary/exporter-base-harbor | ||
Jobservice | ||
ranichowdary/jobservice-harbor | ||
ranichowdary/jobservice-base-harbor | ||
Registry: | ||
ranichowdary/registry-harbor | ||
ranimandepudi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
ranichowdary/registry-base-harbor | ||
Registryctl: | ||
ranichowdary/registryctl-harbor | ||
ranichowdary/registryctl-base-harbor | ||
Portal: | ||
ranichowdary/portal-harbor | ||
ranichowdary/portal-base-harbor | ||
Trivy: | ||
ranichowdary/trivy-adapter-harbor | ||
ranichowdary/trivy-base-harbor | ||
|
||
|
||
## Build and Push Workflow (Per Architecture) | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. General comment: This section is a key part of the proposal as it should clearly demonstrate how the solution will be implemented. However, it currently lacks sufficient detail. Would you mind adding more specifics? I think it would be helpful to walk through one image as an example to clarify the process, and give an example of manifest, what it looks like? |
||
|
||
Each image is built and pushed in the following steps: | ||
ranimandepudi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
On Amd64 Host: | ||
- Generated amd64 binary. | ||
- Build image: docker build -t ranichowdary/core-harbor:amd64 . | ||
- Push the docker push ranichowdary/core-harbor:amd64 | ||
On Arm64 Host: | ||
- Run make build-core on Arm64 instance to generate native binary. | ||
- Build image: docker build -t ranichowdary/core-harbor:arm64 . | ||
- Push the docker push ranichowdary/core-harbor:arm64 | ||
|
||
Created manifest to ensure final image : `latest` tag resolves to the correct architecture during image pull based on the target environment. | ||
ranimandepudi marked this conversation as resolved.
Show resolved
Hide resolved
ranimandepudi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
Process Overview: | ||
- Generated amd64-native binary for the components and build the docker image as | ||
`docker build -t ranichowdary/<component>-harbor:amd64 . ` | ||
- Push the image | ||
`docker push ranichowdary/<component>-harbor:amd64` | ||
|
||
- Genarated arm64-native binary for the components and build the docker image as | ||
`make build-<component>` | ||
`docker build -t ranichowdary/<component>-harbor:arm64 . ` | ||
- Push the image | ||
`docker push ranichowdary/<component>-harbor:arm64` | ||
|
||
Finally on amd64 Host (Create and push manifest) | ||
|
||
`docker manifest create ranichowdary/db-harbor:latest ranichowdary/db-harbor:amd64 ranichowdary/db-harbor:arm64` | ||
|
||
`docker manifest push ranichowdary/db-harbor:latest` | ||
|
||
Result: | ||
|
||
This creates a multi-architecture manifest under the tag `latest` that points to the appropriate architecture-specific image. When a user pull the image: | ||
|
||
`docker pull ranichowdary/db-harbor:latest` | ||
Docker will automatically fetch either the amd64 or arm64 version, depending on the user's platform. | ||
|
||
|
||
## Testing | ||
|
||
To validate that our custom-built Harbor instance with Arm64 support works correctly across components and architectures, I performed the following levels of testing: | ||
|
||
- tools/spectral/Dockerfile - Uses arch-specific spectral binary; dynamically selects amd64/arm64 | ||
|
||
- tools/migrate_chart/migrate_chart.sh- this script is architecture-neutral and works on both amd64 and arm64 as long as a compatible `helm` binary is available. | ||
|
||
- tools/migrate_chart/Dockerfile - It currently hardcodes the Helm binary for `linux-amd64` so it is not architecture-neutral and must be updated to support Arm64 by dynamically resolving the appropriate Helm binary for the target architecture. | ||
Made this docker image multi-architecture (`docker pull ranichowdary/migrate-chart:latest`) | ||
|
||
tools/notary-migration-fix.sh - No changes | ||
tools/swagger/Dockerfile - No changes | ||
|
||
- tools/release/release_utils.sh: In getAssets() function adding `arch` parameter because builds are now organized under subfolder like `amd64/` and `arm64/`. Updated GCS `gsutil cp` paths to ensure it looks under the correct architecture folder. Used `mkdir -p` to prevent errors if assetsPath already exists. Also updated `publish_release.yml` where it calls `getAssets`. | ||
I can work on this but this need maintainers to work as we need to deal with few enhancements. | ||
|
||
Container Health Validation: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Since we aim to enable the entire build process through Make, please ensure that all steps required to build the images from scratch are covered. In addition to the source code, please also consider tools that may be architecture-sensitive—for example, https://github.com/goharbor/harbor/blob/main/tools/spectral/Dockerfile. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks for the note — that’s a great point. My plan is to ensure that all Dockerfiles and supporting tools (including those under tools/) are validated for multi-architecture compatibility. I'll audit components like tools/spectral/Dockerfile and any other architecture-sensitive containers, and make the necessary changes to support arm64 where needed. I will update that in the commit. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Mark this as unresolved. Let me give an example: in a previous release, we gracefully added support for ARM64—for instance, by introducing architecture-specific logic in the Dockerfile. https://github.com/goharbor/harbor/blob/main/tools/spectral/Dockerfile What I’m looking for now are the technical details. Similar to how we handled the Dockerfile, how should we manage the source code, tool binaries, and image building—end to end? And how should we trigger the full flow from the make command? |
||
|
||
- Ensuring auxilary tools handled for both `amd64` and `arm64` architectures when building Harbor via the Makefile: | ||
|
||
- Verified all Harbor services (core, registry, jobservice, portal, proxy, etc.) were up and marked as healthy via docker ps. | ||
- Ensured correct images (ranichowdary/*-harbor) were used with linux/arm64 platform and linux/amd64. | ||
|
||
Web UI Access: | ||
|
||
- Loaded the Harbor UI successfully at http://<host>/harbor. | ||
- Confirmed login, project navigation, and artifact listing worked from the browser. | ||
|
||
API-Level Testing: | ||
ranimandepudi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- Used Harbor’s REST API to validate backend services: | ||
- GET /api/v2.0/ping → responded with pong confirming core service health. | ||
- GET /api/v2.0/projects → confirmed API access and project metadata retrieval. | ||
- POST /api/v2.0/projects → tested project creation via API. | ||
- GET /api/v2.0/repositories and /artifacts → verified image metadata retrieval. | ||
|
||
|
||
- Image Push and Pull Tests (Registry Validation) | ||
- Multi-Architecture Image Validation | ||
|
||
These tests confirm that Harbor can function fully on Arm64 & Amd64, including UI, API, registry, and multi-architecture artifact handling. The environment is now ready for use in cloud-native, edge, or hybrid deployments. | ||
|
||
Thanks for reviewing this work! Since I'm the author of this contribution from Arm, I believe this is a high-priority topic within the Harbor community and it could be introduced as a new feature soon. A formal proposal like this document will help align on the design and technical implementation. | ||
|
||
I welcome feedback, collaboration, or questions from the Harbor community | ||
|
||
## References: | ||
|
||
www.arm.com/migrate | ||
https://learn.arm.com/ | ||
https://hub.docker.com/u/ranichowdary |
Uh oh!
There was an error while loading. Please reload this page.