starlingx/docs
Code Issues Proposed changes

Merge "DOC: Harbor documentation should include a full overview of options" into r/stx.10.0

Browse Source
This commit is contained in:
Zuul
2025-10-29 16:01:33 +00:00
committed by Gerrit Code Review
parent f6b20bb0ba d0f5aa625e
commit c30163178f
1 changed files with 128 additions and 160 deletions
Download Patch File Download Diff File Expand all files Collapse all files

288
doc/source/admintasks/kubernetes/harbor-as-system-app-1d1e3ec59823.rst
View File

@@ -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
<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
------------------------------------------------------