From d0f5aa625ee81b0b71cccf66cd7fbbedc45820b1 Mon Sep 17 00:00:00 2001 From: Matthew Montopoli Date: Thu, 18 Sep 2025 19:51:06 +0000 Subject: [PATCH] DOC: Harbor documentation should include a full overview of options Improve documentation on the use case of harbor. Fix grey bar issues. Change-Id: Ib87a6c8ee29952616152c2098853078b7a8de116 Signed-off-by: Matthew Montopoli --- .../harbor-as-system-app-1d1e3ec59823.rst | 288 ++++++++---------- 1 file changed, 128 insertions(+), 160 deletions(-) diff --git a/doc/source/admintasks/kubernetes/harbor-as-system-app-1d1e3ec59823.rst b/doc/source/admintasks/kubernetes/harbor-as-system-app-1d1e3ec59823.rst index dd0982377..b8f488c5e 100644 --- a/doc/source/admintasks/kubernetes/harbor-as-system-app-1d1e3ec59823.rst +++ b/doc/source/admintasks/kubernetes/harbor-as-system-app-1d1e3ec59823.rst @@ -7,17 +7,18 @@ Harbor Container Registry .. rubric:: |context| Harbor is an open-source container registry with a richer and fuller set of -capabilities than the built-in |prod| container registry. |prod| end -users can use Harbor to manage their own application container images. Harbor -secures artifacts with policies and role-based access control, ensures images -are scanned and free from vulnerabilities, and signs images as trusted. Harbor -has been evolved to a complete |OCI| compliant cloud-native artifact registry. +capabilities than the built-in |prod| container registry. |prod| end users can +use Harbor to manage their own application container images. Harbor secures +artifacts with policies and role-based access control, can optionally ensure +images are scanned and free from vulnerabilities, and can optionally sign +images as trusted. Harbor has been evolved to a complete |OCI| compliant +cloud-native artifact registry. -With Harbor V2.0, you can manage images, manifest lists, Helm charts, -|CNABs|, |OPAs| and other artifacts adhering to the |OCI| image specification. -It supports operations such as pulling, pushing, deleting, tagging, -replicating, and scanning these artifacts. Additionally, you can now sign -images and manifest lists. +With Harbor V2, you can manage images, manifest lists, Helm charts, |CNABs|, +|OPAs| and other artifacts adhering to the |OCI| image specification. It +supports operations such as pulling, pushing, deleting, tagging, replicating, +and scanning these artifacts. Additionally, you can now sign images and +manifest lists. Harbor also supports the replication of images between registries and offers advanced security features such as user management, access control, and @@ -35,17 +36,19 @@ Harbor Installation multiple replicas, for |AIO-DX| or Standard configurations, both Harbor replicas can read and write to the registry. -- Create a secret as described below: + - CephRBD backed PVCs ('general' storage class) can be used for |AIO-SX| + configurations. - - Generate certificates and create secret. +- Create a 'harbor' K8S Namespace and a K8S secret containing the server + certificate for the Harbor Registry as described below: - A |CA| cert and server cert creation procedure using cert-manager is - specified below: + - Generate the server certificate for the Harbor Registry. Create the certificate for Harbor using Cert-Manager and using the local |CA|, system-local-ca, as the issuer. Note that the certificate should be created in the ``harbor-tls SECRET`` in the Harbor - ``NAMESPACE``. + ``NAMESPACE`` to be consistent with the helm chart in the application + and the overrides in the following procedure. For example: @@ -122,163 +125,156 @@ Harbor Installation #. Configure the Helm Overrides for Harbor. - #. Expose the Harbor application externally with either nodePort or - Ingress. + #. Specify the Harbor configuration to meet your requirements in + 'values.yaml': - **nodePort** + The following example ``values.yaml`` shows different options for some + common configuration attributes of Harbor. - #. Create Harbor using NodePort to expose the service + The commenting in the example below selects NodePort for exposing the + Harbor Registry and selects the 'general' storage class (CephRBD with + ReadWriteOnce accessmode). See discussion of options after example + ``values.yaml`` file listing. - .. note:: - - The instructions below assume that the NodePorts 30002, 30003, - and 30004 are available (i.e., not used by any other - applications). If these ports are unavailable, please choose - and configure alternative ports that are not in use. - - #. Put the following nodePort overrides in ``values.yaml``: - - .. code-block:: none + .. code-block:: none expose: - type: nodePort # Type should be nodeport + + # TLS & Certificate Info tls: enabled: true certSource: secret - secret: # Certificate Source is secret - secretName: "harbor-tls" # A secret containing tls.crt and tls.key - notarySecretName: "harbor-tls" # A secret containing tls.crt and tls.key + secret: + secretName: "harbor-tls" + notarySecretName: "harbor-tls" + # --- NodePort Option --- (comment if using Ingress) + type: nodePort nodePort: - # The name of NodePort service name: harbor ports: http: - # The service port Harbor listens on when serving HTTP port: 80 - # The node port Harbor listens on when serving HTTP nodePort: 30002 https: - # The service port Harbor listens on when serving HTTPS port: 443 - # The node port Harbor listens on when serving HTTPS nodePort: 30003 - # Only needed when notary.enabled is set to true notary: - # The service port Notary listens on port: 4443 - # The node port Notary listens on nodePort: 30004 - externalURL: https://harbor.yourdomian.com:30003 # URL of harbor listing on 30003 port + externalURL: https://harbor.yourdomain.com:30003 - **Ingress** - - #. Create Harbor using Ingress to expose the service. - - .. note:: - - The instructions below assume that the URL - ``harbor.yourdomain.com`` has been configured in the |DNS| - server owning ``yourdomain.com`` as the ``OAM FLOATING IP - Address`` of |prod|. - - #. Put the following Ingress overrides in ``values.yaml``: - - .. code-block:: none - - expose: - type: ingress # Type should be ingress - tls: - enabled: true - certSource: secret - secret: # Certificate Source is secret - secretName: "harbor-tls" # Above created secret name - notarySecretName: "harbor-tls" # Above created secret name - ingress: - hosts: - core: harbor.yourdomian.com # Harbor Domain name - notary: notary.yourdomian.com # Notary Domain name - annotations: - kubernetes.io/ingress.class: nginx. # Add ingressclass name. It would be "nginx" if you are using default ingress controller. - nginx.org/client-max-body-size: "0" # Add this notation for nginx otherwise nginx will reject the image pull & push - externalURL: https://harbor.yourdomian.com # URL of harbor + # --- Ingress Option (uncomment if using ingress) --- + # + # type: ingress + # ingress: + # hosts: + # core: harbor.yourdomain.com + # notary: notary.yourdomain.com + # annotations: + # kubernetes.io/ingress.class: nginx + # nginx.org/client-max-body-size: "0" + # externalURL: https://harbor.yourdomain.com - #. For |AIO-DX| and Standard setup, add the following ``storageClass`` and - ``accessMode`` overrides for |PVC| used for ``Harbor-Jobservice`` and - ``Harbor-Registry`` microservice. + + # Harbor persistence configuration + + persistence: + enabled: true + resourcePolicy: "keep" + persistentVolumeClaim: + registry: + existingClaim: "" + subPath: "" + size: 100Gi # Adjust registry DB size as required + + # --- ReadWriteOnce Option (comment if using RWM) --- + storageClass: "general" + accessMode: ReadWriteOnce + + # --- ReadWriteMany Option (uncomment if using RWM) --- + # storageClass: "cephfs" + # accessMode: ReadWriteMany + + jobservice: + jobLog: + existingClaim: "" + subPath: "" + size: 1Gi + + # --- ReadWriteOnce Option (comment if using RWM) --- + storageClass: "general" + accessMode: ReadWriteOnce + + # --- ReadWriteMany Option (uncomment if using RWM) --- + # storageClass: "cephfs" + # accessMode: ReadWriteMany + + Where: + + * Expose options + + - NodePort (uncommented in the example above) + + To expose Harbor externally using fixed ports (e.g. 30002–30004), if + these ports are unavailable, please choose and configure alternative + ports that are not in use. + + Useful for smaller or single-node |AIO-SX| configurations. + + The main advantage here is that this can be used regardless of + whether you have a |FQDN| for your system or not. + + - Ingress (commented out in the example above) + + This option provides more user friendly/readable URLs for harbor. + However, this option is ONLY usable if yourdomain.com and + subdomains like harbor.yourdomain.com and notary.yourdomain.com are + configured in a |DNS| server as the OAM FLOATING IP Address of + |prod|. + + * Persistence options + + - general (CephRBD) / ``ReadWriteOnce`` + + Uses the CephRBD storage class. Default and typically appropriate + for |AIO-SX| configurations where only a single replica of Harbor + would be used. + + - CephFS / ``ReadWriteMany`` + + Allows multi-pod access to shared storage. Use for |AIO-DX| and + Standard setups where you would most likely configure Harbor with + multiple replicas. + + * Registry DB Size (``persistence:persistentVolumeClaim:registry:size``) + + Default size, if not specified, is 5 GiB. Increase (e.g. size: 100Gi) + based on the expected number and size of images stored. .. note:: - Set the registry size according to your requirements - considering the number and size of images that you will have in - this registry. - - Example for nodePort: - - .. code-block:: none - - persistence: - enabled: true - resourcePolicy: "keep" - persistentVolumeClaim: - registry: - existingClaim: "" - storageClass: "cephfs" - subPath: "" - accessMode: ReadWriteMany - size: 100Gi - jobservice: - jobLog: - existingClaim: "" - storageClass: "cephfs" - subPath: "" - accessMode: ReadWriteMany - size: 1Gi - - Example for Ingress: - - .. code-block:: none - - persistence: - enabled: true - resourcePolicy: "keep" - persistentVolumeClaim: - registry: - existingClaim: "" - storageClass: "cephfs" - subPath: "" - accessMode: ReadWriteMany - size: 100Gi - jobservice: - jobLog: - existingClaim: "" - storageClass: "cephfs" - subPath: "" - accessMode: ReadWriteMany - size: 1Gi + For all supported attributes, refer to the upstream Harbor Helm chart + ``values.yaml`` in + `https://github.com/goharbor/harbor-helm/blob/v1.12.0/values.yaml + `__. #. Update the Helm overrides. .. code-block:: none - ~(keystone_admin)]$ system helm-override-update harbor harbor harbor --values values.yaml + ~(keystone_admin)]$ system helm-override-update harbor harbor harbor --values values.yaml - #. Execute Helm overrides. - - .. code-block:: none - - ~(keystone_admin)]$ system helm-override-update harbor harbor harbor --values values.yaml - -#. Apply/Create the Harbor system application. +#. Create the Harbor system application with the previously specified helm + overrides. .. code-block:: none ~(keystone_admin)]$ system application-apply harbor - ------------------------------------------------- Configure LDAP Authentication for Harbor Registry ------------------------------------------------- @@ -484,34 +480,6 @@ Trivy is installed and configured as a default scanner. .. image:: figures/interrogation-services.png :width: 800 ------------------------------ -Configure Size of Registry DB ------------------------------ - -#. Registry DB size can be configured by setting following in ``values.yaml`` - under: - - .. code-block:: none - - persistence: - registry: - size: 5Gi - jobservice: - jobLog: - size: 1Gi - -#. Set the the value (Default set to 5Gi). - - .. code-block:: none - - system helm-override-update harbor harbor harbor --values values.yaml - -#. Apply the change: - - .. code-block:: none - - system application-apply harbor - ------------------------------------------------------ Enforcement of Image Security Policies Using Portieris ------------------------------------------------------