From 1bc9d21ab8f036cedab5aed9a10137f7b27810e9 Mon Sep 17 00:00:00 2001 From: Elisamara Aoki Goncalves Date: Mon, 26 Aug 2024 17:22:02 +0000 Subject: [PATCH] Doc Update for Harbor Support Address comments made in https://review.opendev.org/c/starlingx/docs/+/920096 Change-Id: Iac7a50cd4ad6df506b34366d6f20dbc8d599772a Signed-off-by: Elisamara Aoki Goncalves --- .../harbor-as-system-app-1d1e3ec59823.rst | 446 +++++++++--------- .../index-admintasks-kub-ebc55fefc368.rst | 6 +- 2 files changed, 232 insertions(+), 220 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 77222d8dc..378699e70 100644 --- a/doc/source/admintasks/kubernetes/harbor-as-system-app-1d1e3ec59823.rst +++ b/doc/source/admintasks/kubernetes/harbor-as-system-app-1d1e3ec59823.rst @@ -1,25 +1,27 @@ .. _harbor-as-system-app-1d1e3ec59823: -============================ -Harbor as System Application -============================ +========================= +Harbor Container Registry +========================= .. rubric:: |context| -Harbor is an open-source registry that 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. +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. -With Harbor V2.0, users can manage images, manifest lists, Helm charts, -|CNABs|, |OPAs| among others which all adhere to the |OCI| image specification. -It also allows for pulling, pushing, deleting, tagging, replicating, and -scanning such kinds of artifacts. Signing images and manifest list are also -possible now. +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. -Harbor supports replication of images between registries, and offers advanced -security features such as user management, access control and activity -auditing. +Harbor also supports the replication of images between registries, and offers +advanced replication of images between registries, and offers advanced security +features such as user management, access control and activity auditing. See https://goharbor.io/docs/2.0.0/ for more details on Harbor. @@ -56,28 +58,34 @@ Harbor Installation apiVersion: cert-manager.io/v1 kind: Certificate metadata: - name: harbor-certificate - namespace: harbor + name: harbor-certificate + namespace: harbor spec: - secretName: harbor-tls - issuerRef: + secretName: harbor-tls + issuerRef: name: system-local-ca kind: ClusterIssuer - duration: 2160h # 90 days - renewBefore: 360h # 15 days - commonName: < oam floating IP Address or FQDN > - subject: + duration: 2160h # 90 days + renewBefore: 360h # 15 days + commonName: < oam floating IP Address or FQDN > + subject: organizations: - - ABC-Company - organizationalUnits: - - StarlingX-harbor - ipAddresses: - - < oam floating IP address > - dnsNames: - - < harbor dns> # e.g. harbor.yourdomian.com - - < notary dns > # optional, required only if exposed on ingress e.g. notary.yourdomian.com + - ABC-Company + organizationalUnits: + - StarlingX-harbor + ipAddresses: + - < oam floating IP address > + dnsNames: + - < harbor dns> # e.g. harbor.yourdomian.com + - < notary dns > # optional, required only if exposed on ingress e.g. notary.yourdomian.com EOF + #. Create the Harbor namespace: + + .. code-block:: none + + ~(keystone_admin)]$ kubectl create namespace harbor + #. Apply the configuration: .. code-block:: none @@ -93,49 +101,56 @@ Harbor Installation After successful configuration, the certificate's Ready status will be True. - - nodePort +.. rubric:: |proc| + +#. Locate the Harbor system application tarball in + ``/usr/local/share/applications/helm``. + + For example: + + .. code-block:: none + + /usr/local/share/applications/helm/harbor-.tgz + +#. Upload the Harbor application. + + .. code-block:: none + + ~(keystone_admin)]$ system application-upload /usr/local/share/applications/helm/harbor-.tgz + + .. _configure-helm-harbor-step: + +#. Configure the Helm Overrides for Harbor. + + #. Expose the Harbor application externally with either nodePort or + Ingress. + + **nodePort** #. Create Harbor using NodePort to expose the service .. note:: - The instructions below assume that the NodePorts 30102, 30103 - and 30104 are available; i.e. not used by any other - applications. + 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. - #. Locate the Harbor system application tarball in - ``/usr/local/share/applications/helm``. - - For example: - - .. code-block:: none - - /usr/local/share/applications/helm/harbor-.tgz - - #. Upload the Harbor application. - - .. code-block:: none - - ~(keystone_admin)]$ system application-upload /usr/local/share/applications/helm/harbor-.tgz - - #. Configure the Helm Overrides for Harbor. - - Below values need to be configured for nodePort: + #. Put the following nodePort overrides in ``values.yaml``: .. code-block:: none expose: + type: nodePort # Type should be nodeport + 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 - type: nodePort # Type should be nodeport - 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 - - nodePort: + nodePort: # The name of NodePort service name: harbor ports: @@ -155,158 +170,141 @@ Harbor Installation port: 4443 # The node port Notary listens on nodePort: 30004 + externalURL: https://harbor.yourdomian.com:30003 # URL of harbor listing on 30003 port + + **Ingress** - externalURL: https://harbor.yourdomian.com:30003 # URL of harbor listing on 30003 port + #. Create Harbor using Ingress to expose the service. - For |AIO-DX| and standard setup, add below ``storageClass`` and - ``accessModes`` override. + .. note:: - Underlying PVCs pre-requisistes: ``Harbor-Jobservice`` and - ``Harbor-Registry`` microservice. + 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|. - For example: + #. Put the following Ingress overrides in ``values.yaml``: .. code-block:: none - persistence: - enabled: true - resourcePolicy: "keep" - persistentVolumeClaim: - registry: - existingClaim: "" - storageClass: "cephfs" - subPath: "" - accessMode: ReadWriteMany - size: 5Gi - annotations: {} - jobservice: - jobLog: - existingClaim: "" - storageClass: "cephfs" - subPath: "" - accessMode: ReadWriteMany - size: 1Gi - annotations: {} + 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 - #. Execute Helm overrides. - .. code-block:: none - - ~(keystone_admin)]$ system helm-override-update harbor harbor harbor --values values.yaml - - #. Apply/Create the Harbor system application. - - .. code-block:: none - - ~(keystone_admin)]$ system application-apply harbor - - - Ingress - - Create Harbor using Ingress to expose the service. + #. For |AIO-DX| and Standard setup, add the following ``storageClass`` and + ``accessMode`` overrides for |PVC| used for ``Harbor-Jobservice`` and + ``Harbor-Registry`` microservice. .. 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|. + Set the registry size according to your requirements + considering the number and size of images that you will have in + this registry. - #. Locate the Harbor system application tarball in - ``/usr/local/share/applications/helm``. + Example for nodePort: - For example: + .. code-block:: none - .. code-block:: none + persistence: + enabled: true + resourcePolicy: "keep" + persistentVolumeClaim: + registry: + existingClaim: "" + storageClass: "cephfs" + subPath: "" + accessMode: ReadWriteMany + size: 100Gi + annotations: {} + jobservice: + jobLog: + existingClaim: "" + storageClass: "cephfs" + subPath: "" + accessMode: ReadWriteMany + size: 1Gi + annotations: {} + + Example for Ingress: - /usr/local/share/applications/helm/harbor-.tgz + .. code-block:: none - #. Upload the Harbor application. + persistence: + enabled: true + resourcePolicy: "keep" + persistentVolumeClaim: + registry: + existingClaim: "" + storageClass: "cephfs" + subPath: "" + accessMode: ReadWriteMany + size: 100Gi + annotations: {} + jobservice: + jobLog: + existingClaim: "" + storageClass: "cephfs" + subPath: "" + accessMode: ReadWriteMany + size: 1Gi + annotations: {} - .. code-block:: none + #. Update the Helm overrides. - ~(keystone_admin)]$ system application-upload /usr/local/share/applications/helm/harbor-.tgz + .. code-block:: none - #. Configure the Helm overrides for Harbor configuration. + ~(keystone_admin)]$ system helm-override-update harbor harbor harbor --values values.yaml - The values below need to be configured for ingress in the - ``values.yaml`` file. + #. Execute Helm overrides. - .. code-block:: none + .. 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 + ~(keystone_admin)]$ system helm-override-update harbor harbor harbor --values values.yaml +#. Apply/Create the Harbor system application. - For |AIO-DX| and standard setup, add below ``storageClass`` and - ``accessModes`` override for |PVC| used for ``Harbor-Jobservice`` - and ``Harbor-Registry`` microservice. + .. code-block:: none - For example: - - .. code-block:: none - - persistence: - enabled: true - resourcePolicy: "keep" - persistentVolumeClaim: - registry: - existingClaim: "" - storageClass: "cephfs" - subPath: "" - accessMode: ReadWriteMany - size: 5Gi - annotations: {} - jobservice: - jobLog: - existingClaim: "" - storageClass: "cephfs" - subPath: "" - accessMode: ReadWriteMany - size: 1Gi - annotations: {} - - Update the Helm overrides. - - .. code-block:: none - - ~(keystone_admin)]$ system helm-override-update harbor harbor harbor --values values.yaml - - #. Apply/Create the Harbor system application. - - .. code-block:: none - - ~(keystone_admin)]$ system application-apply harbor + ~(keystone_admin)]$ system application-apply harbor ------------------------------------------------- Configure LDAP Authentication for Harbor Registry ------------------------------------------------- +.. rubric:: |prereq| + +- The URL for accessing the Harbor web interface is the ``externalURL`` set in + the Helm override above in the step :ref:`Configure Helm Overrides for Harbor + `. + +- The default admin username is 'admin', and the password is 'Harbor12345'. + To configure Harbor to use |prod| Local |LDAP| for authentication, follow the instructions in `Configure LDAP/Active Directory Authentication `__ -with the following values: +with the following values. For |prod| local |LDAP|: .. code-block:: none - LDP URL: ldap://controller + LDAP URL: ldap://controller LDAP search DN: cn=ldapadmin,dc=cgcs,dc=local @@ -316,11 +314,16 @@ For |prod| local |LDAP|: LDAP UID: cn +You can find ```` in ``/etc/ldap/slapd.conf.backup``. + -------------------------------------- Push an Image to a in Harbor -------------------------------------- -#. Run :command:`sudo su` before Docker login. +.. note:: + + Depending on your docker setup, you may be required to run all of the + following commands with 'sudo'. #. Docker Login. @@ -328,10 +331,12 @@ Push an Image to a in Harbor docker login -u - .. note:: + Where ```` is either: - Replace ```` with actual harborURL and replace - ```` with your actual username. + - for 'Ingress' expose: `harbor.yourdomian.com` + + - for 'NodePort' expose: `https:// :30003` and + ```` is your actual username #. Tag the image. @@ -359,7 +364,7 @@ Where ```` is either: - for ``'Ingress' expose: harbor.yourdomian.com`` -- for ``'NodePort' expose: https:// :30103`` +- for ``'NodePort' expose: https:// :30003`` ---------------------------------- Push a Helm Chart as an OCI Object @@ -487,20 +492,29 @@ Trivy is installed and configured as a default scanner. Configure Size of Registry DB ----------------------------- -Registry DB size can be configured by setting following in ``values.yaml`` -under: +#. Registry DB size can be configured by setting following in ``values.yaml`` + under: -.. code-block:: none + .. code-block:: none - persistence: - registry: - size: 5Gi - jobservice: - jobLog: - size: 1Gi + persistence: + registry: + size: 5Gi + jobservice: + jobLog: + size: 1Gi -Use :command:`system helm-override` command to set the value (Default set to -5Gi). +#. 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 @@ -519,21 +533,6 @@ To use portieris, an administrator needs to follow below steps: #. Install portieris as specified in :ref:`install-portieris`. -#. Create a ``docker-registry`` secret. - - .. code-block:: none - - kubectl create secret docker-registry \ - -n harbor harbor-registry-secret \ - --docker-server=:port \ - --docker-username=admin \ - --docker-password=Test@123 - - .. note:: - - If the pod creation with the above secret fails, the user should try - with new secret with ``--docker-server`` as ````. - #. Configure image policy to allow images from Harbor registry + notary as specified :ref:`portieris-clusterimagepolicy-and-imagepolicy-configuration`. Below @@ -545,17 +544,30 @@ To use portieris, an administrator needs to follow below steps: kind: ImagePolicy metadata: name: allow-custom - - .. code-block:: none - namespace: harbor spec: repositories: - - name: ":30003/*" + - name: ":30003/*" policy: trust: enabled: true - trustServer: "https://:30004" # Optional, custom trust server for repository + trustServer: "https://:30004" # Optional, custom trust server for repository + +#. Create a SECRET with a Harbor username and password, to use as an + ImagePullSecret in a POD spec. + + .. code-block:: none + + kubectl create secret docker-registry \ + -n harbor harbor-registry-secret \ + --docker-server=:port \ + --docker-username=admin \ + --docker-password=Test@123 + + .. note:: + + If the pod creation with the above secret fails, the user should try + with new secret with ``--docker-server`` as ````. #. Pull a signed image from Harbor registry in a pod using ``harbor-secret`` created above. Please note that image policy and pod should be created in @@ -566,21 +578,21 @@ To use portieris, an administrator needs to follow below steps: apiVersion: v1 kind: Pod metadata: - name: test-pod-public + name: test-pod-public spec: - containers: - - command: + containers: + - command: - sleep - '3600' - image: :30003/public-demo/redis:latest + image: :30003/public-demo/redis:latest imagePullPolicy: Always name: test-pod - tolerations: - - key: "node-role.kubernetes.io/master" + tolerations: + - key: "node-role.kubernetes.io/master" operator: "Exists" effect: "NoSchedule" - imagePullSecrets: - - name: harbor-registry-secret + imagePullSecrets: + - name: harbor-registry-secret ---------- Limitation diff --git a/doc/source/admintasks/kubernetes/index-admintasks-kub-ebc55fefc368.rst b/doc/source/admintasks/kubernetes/index-admintasks-kub-ebc55fefc368.rst index 4230bba61..c0f4e6fb1 100644 --- a/doc/source/admintasks/kubernetes/index-admintasks-kub-ebc55fefc368.rst +++ b/doc/source/admintasks/kubernetes/index-admintasks-kub-ebc55fefc368.rst @@ -77,9 +77,9 @@ O-RAN O2 Interface oran-o2-application-b50a0c899e66 --------------------- -Harbor as System App --------------------- +------------------------- +Harbor Container Registry +------------------------- .. toctree:: :maxdepth: 1