Installing and Configuring VMware Harbor Registry

This topic describes how to install and configure VMware Harbor Registry using Pivotal Ops Manager for use with Enterprise Pivotal Container Service (Enterprise PKS) and Pivotal Application Service (PAS).

For more information about Enterprise PKS, see the Enterprise Pivotal Container Service (Enterprise PKS) documentation.

For more information about PAS, see PAS Concepts in the Pivotal documentation.

Note: This documentation supports the Harbor v1.8 release.

Prerequisites

You must have installed Enterprise PKS. For more information, see Installing Enterprise PKS in the Enterprise PKS documentation.

Import Harbor Tile to Ops Manager

  1. Download the Harbor tile from Pivotal Network.
  2. Log in to the Ops Manager Installation Dashboard.
  3. Click Import a Product and upload the Harbor tile.
  4. Below the Import a Product button, click the + next to the VMware Harbor Registry version number to add the tile to your staging area.
  5. Click the Harbor tile to begin the configuration process.

    Add and Configure Harbor Tile View a larger version of this image.

Assign AZs and Networks

  1. In the Harbor tile, select Assign AZs and Networks.
  2. In the Assign AZs and Networks pane, under Place singleton jobs in, select the availability zone (AZ) where you want to run singleton jobs. VMware Harbor is a singleton job and is placed on this network.
  3. Under balance other jobs in, select the AZ where you want to balance other jobs. For Enterprise PKS, this is the same AZ as the one that you selected for Place singleton jobs in.
  4. Under Network, select the network where you want to deploy Harbor. For Enterprise PKS, this is the management network where you deploy the Ops Manager, BOSH Director, and Enterprise PKS virtual machines (VMs).
  5. Click Save to preserve your changes. Assign AZs and Networks for Harbor

Configure General Settings

  1. In the Harbor tile, select General. Configure General Settings for Harbor
  2. Under Hostname, enter the FDQN of a host to access the Harbor administration UI and registry service. The hostname must include a domain and must be able to resolve to the IP address of the Harbor instance VM by an external DNS server.

    Kubernetes worker nodes can resolve the Harbor FQDN through the local BOSH DNS server. To enable Docker clients external to Kubernetes worker nodes to resolve the Harbor FQDN, you must provide a Harbor FQDN that can be resolved by an external DNS server. When Harbor is successfully deployed, you must update the Harbor external DNS record with the IP address of the Harbor VM.
  3. Under Static IP Address, enter the static IP address that you want to use for the Harbor web interface.

    Create a DNS record that maps the Harbor FQDN to the static IP address, or to the custom load balancer if you are using one. This is the public IP address of the Harbor server.
  4. By default Docker assigns each running container a private IP address. To use the default container network settings, select Keep the default container network settings.
  5. To customize the container network settings, select Specify customized container network settings.

    Configure Custom Settings for Harbor

    If you select Specify customized container network settings, you must specify at least one address pool base and size. When a Docker container starts, the Docker daemon (dockerd) selects an IP address from the address pool and allocates it to the container.

    Because the smallest network in Docker private network is a.b.c.d/28, if you input only one pool, the smallest CIDR block is a.b.c.d/25. If input two pools, the smallest CIDR block is a.b.c.d/26.

    Note: There are 10 networks in the Harbor VM. Make sure there are enough subnetworks in the specified CIDR. If there are not enough subnets in the network, the Harbor server fails to start.

    For example, if you select this option, for the Address pool1 base you might enter 172.31.0.0/26, and for the Address pool1 size you might enter 28. Additional entry pairs are optional.
  6. Click Save.

Configure SSL Certificate and Key

On the Certificate pane, you configure the SSL certificate and private key for Harbor. You can generate the certificate and private key or provide a custom signed certificate and private key. Additionally, you must provide the Certificate Authority (CA) certificate, which is used to sign the Harbor certificate. The domain name used to generate RSA certificate in the Harbor Tile can be different than the domain name used to generate the RSA certificate in the Enterprise PKS or PAS tile.

Use Generated Certificate

To use a certificate that Ops Manager generates automatically, follow the steps below.

  1. In the Harbor tile, select Certificate.
  2. Click Generate RSA Certificate.
  3. Enter the domain for your Harbor instance in the Generate RSA Certificate field. This can be a standard FQDN or a wildcard domain. The domain must match the DNS resolvable domain name that you used when you specified the hostname for Harbor.
  4. Click Generate.
  5. Click Save.

    Generate RSA Certificate for Harbor

Use Custom Certificate

To use a custom signed certificate from a third-party CA, follow the steps below.

  1. In the Harbor tile, select Certificate.
  2. Copy the contents of your certificate file into the Certificate Authority (CA) field. Certificates must be in PEM-encoded format. The certificate CN or SAN must match the DNS-resolvable domain name that you used as the hostname for Harbor.
  3. Copy the contents of the corresponding key (PEM) into the Private Key PEM field.
  4. Enter the Certificate Authority (CA) for the server certificate, which is used to sign the Harbor certificate. If you use a self-signed certificate, copy the corresponding CA here. Leave this field empty if you are using the root CA of Ops Manager.
  5. Click Save.

    Configure SSL certificate and private key for Harbor

Configure Harbor Credentials

Configure Initial Credentials

  1. Select Credentials.
  2. Enter the password for the Harbor system administrator account. The default Harbor user name is admin. Both the user name and password can be changed after installation using the Harbor web interface. See instructions below.
  3. Click Save.

    Configure Harbor Credentials

Update Harbor Credentials

You cannot change the Harbor administrator password in Ops Manager after you set it during installation. You must use the Harbor interface to make subsequent changes to the password after deployment.

  1. Update the Harbor system administrator password using the Harbor web interface.
  2. In the Credentials tab of the Harbor tile, enter the new password in the Admin Password to run smoke test field.
  3. Apply changes to the Harbor tile and redeploy Harbor using Ops Manager for the updated password to take effect.

Configure Harbor Authentication Mode

On the Authentication pane in Ops Manager you select an authentication mode. You use the Harbor web console to configure detailed settings for the selected authentication mode. For more information, see Managing authentication in the Harbor User Guide in GitHub.

  1. In the Harbor tile, select Authentication.
  2. Choose one of the following Authentication Modes:
    • Internal (default): Harbor user credentials are stored in a local database
    • LDAP: LDAP authentication
    • UAA in Enterprise PKS: User Account and Authentication with Enterprise PKS
    • UAA in Pivotal Application Service: User Account and Authentication with PAS
  3. Click Save.

Configure Container Registry Storage

On the Container Registry Storage pane you specify the type of file storage to use for storing container images.

  1. In the Harbor tile, select Container Registry Storage.
  2. Choose one of the following as your desired storage for container images.

    See the sections below for configuration instructions.

  3. Click Save.

Remote NFS Server Configuration

If you choose Remote NFS Server, provide the NFS Server Address in the form nfs_server_ip:/path/to/export_directory. For example: 192.0.2.0:/harbor/registry/export.

The user/group ID (UID) for the owner of the export directory on the NFS Server must be 10000:10000, where 10000 is the UID used by the Harbor Registry container.

NFS Server configuration for Harbor

AWS S3 Configuration

If you choose AWS S3, configure the following settings:

  • Access Key: The access key for your S3 bucket.
  • Secret Key: The secret key for your S3 bucket.
  • Region: The AWS region where your S3 bucket is located.
  • Endpoint URL of your S3-compatible file store: The URL of your S3-compatible filestore.
  • Bucket Name: The name you gave your S3 bucket when you created it.
  • Root Directory in the Bucket: The root directory of your S3 bucket. This field is optional.
  • Chunk Size: The default value is 5242880 (5 MB).
  • Enable v4auth: Access to your S3 bucket is authenticated by default. Deselect this checkbox for anonymous access.
  • Secure Mode: Access to your S3 bucket is secure by default. Deselect this checkbox to disable secure mode.

    AWS S3 configuration for Harbor

Note: When using Harbor with an S3-compatible object store, the object store must be configured with a TLS cipher suite supported by the Docker client. If the S3 bucket is not configured with a compatible cipher suite, when performing a docker push command to the Harbor Registry, you receive the following: “remote error: tls: handshake failure”. The Harbor Registry redirects the connection from the Docker client to the S3-compatible object store. The TLS handshake is between the Docker client and the S3-compatible object store. To address this error, you must determine the cipher suites supported by the Docker client and S3-compatible object store, and ensure that there is at least one common cipher suite between them.

Google Cloud Storage Configuration

If you selected Google Cloud Storage, configure the following settings:

  • Bucket Name: The name you gave your bucket when you created it.
  • Root Directory in the Bucket: The root directory of your bucket. This field is optional.
  • Chunk Size: The default value is 5242880 (5 MB).
  • Key File: The service account key for your bucket.

    Google Cloud Storage configuration for Harbor

Configure Container Vulnerability Scanning Using Clair

Clair is an open-source project for the static analysis of vulnerabilities in Docker and appc containers. For more information about Clair, see the Clair repository in GitHub.

Harbor provides the ability to install and use Clair for vulnerability scanning of container images. Clair can be configured to update its Common Vulnerabilities and Exposures (CVE) databases from the Internet by setting the Updater Interval. In an intranet network environment, configure a proxy to access the Internet.

Note: You must change the default Updater interval (Hours) field to ensure that the Clair CVE databases are kept current. See instructions below.

  1. In the Harbor tile, select Clair Settings.
  2. To enable container image vulnerability scanning, ensure Install Clair is selected. If you deselect this checkbox, Clair is not installed.
  3. (Optional) In the HTTP Proxy field, enter the URL to proxy HTTP traffic to the Clair service. For example: http://my.proxy.com:3128.

  4. (Optional) In the HTTPS Proxy field, enter the URL to proxy HTTPS traffic to the Clair service. For example: http://my.proxy.com:3128.

    Note: To use basic authentication with the HTTP/S proxy for Clair, include the user name and password in the proxy host URL, for example: http://user:password@myproxy.internal.domain:8080.

  5. In the No Proxy field, specify the endpoints that will bypass the proxy host. This field is required if Clair is installed. The required values, 127.0.0.1,localhost,ui,registry, are populated by default.

  6. In the Updater interval (Hours) field, specify when Clair will update its CVE databases for the registered sources. When the updater interval expires, Clair will update its CVE databases. The default updater interval is 0, which means Clair will never update its CVE databases. If you set the updater interval to 24, Clair updates its CVE databases every 24 hours.

    For a list of the CVE databases that Clair uses, see Data Sources for the built-in drivers in the Clair documentation.

  7. Click Save.

    Clair configuration for Harbor

Configure Container Signing Using Docker Notary

Harbor provides Docker Notary for container signing and trust. Notary is installed by default. For more information about Docker Notary, see Getting started with Docker Notary in the Docker documentation.

  1. In the Harbor tile, select Notary Settings.
  2. By default, Install Notary is selected. Deselect to not install Notary.
  3. Click Save.

(Optional) Configure VM Monitor Settings

Wavefront is a high-performance streaming analytics platform that helps you monitor and optimize your environment. To use Wavefront monitoring with Harbor, you enable it in the Harbor tile and configure a few parameters.

  1. Go to www.wavefront.com and sign up. You will receive an API server and a token.
  2. In the Harbor tile, for the Choose monitor for VM option, select Enable VM monitor with Wavefront.
  3. Configure the following three parameters:
    1. Wavefront URL: Enter the Wavefront API server URL where the performance metrics are sent to.
    2. Wavefront Token: Enter the token to access the Wavefront API server.
    3. Hostname (optional): All metrics sen to the Wavefront API server are categorized to a hostname. Keep this field blank if you want to use the same hostname that was used for the Harbor FQDN.
  4. Click Save. Harbor Monitoring using Wavefront

Note: To monitor the Harbor VM with Wavefront, you will need to deploy the Wavefront dashboard. See Monitor Harbor with Wavefront for details.

Configure BOSH Deployment Errands

Deployment errands are BOSH scripts that run at designated points during an installation using Ops Manager.

  1. In the Harbor tile, select Errands.
  2. For Post-deploy Errands, select the smoke-testing errand:
    • On (default)
    • Off
  3. For Pre-delete Errands, select the deregister Harbor UAA client errand:
    • On
    • Off (default)
  4. Click Save.

Configure Harbor VM Resources

The Harbor VM runs as a single instance. On the Resource Config pane in Ops Manager you configure the resource settings for the Harbor VM, including disk size and type. If you are deploying Harbor on AWS or GCP, you can specify a load balancer that allows external access to the Harbor VM.

For standard Harbor Registry deployments, the default size and type for the Harbor VM are sufficient. The compute and storage capacity of the Harbor VM depends on the size of the images you are deploying to the Harbor registry. Some images are 30 MB, while others are 2 GB. In addition, storage requirements depend on how images are built and what base images are leveraged. In general, if your Harbor instance manages a large number of images, increase the storage size and select a VM type that has greater CPU capacity and more RAM. Using a smaller size VM than the default is not common.

If you are deploying Harbor using BOSH Director for AWS or GCP, and you are fronting the Harbor VM with a load balancer, provide its IP address in the resource settings. AWS and GCP load balancers can be internal or external. The load balancer type dictates whether you need to select or deselect the Internet Connected checkbox. The image below shows the load balancer “scheme” options for the AWS classic load balancer. For more information, see the following topics:

To configure the Harbor VM resources, follow the instructions below.

  1. In the Harbor tile, click Resource Config.
  2. To change the configuration of the harbor-app VM, edit the following properties:
    • Instances: This value cannot be changed. PCF supports one Harbor instance only.
    • Persistent Disk Type: Increase or decrease the storage capacity of the Harbor disk.
    • VM Type: Select a VM type with more CPU capacity and RAM depending on your storage requirements.
  3. To change the configuration of the smoke-testing VM, specify the desired VM Type. This is an ephemeral VM deployed and used by BOSH to test the deployment of the Harbor VM. Typically, the default size is sufficient. However, if you change the size of the harbor-app VM from the default, you may need to adjust the size of the smoke-testing VM accordingly.
  4. For AWS and GCP environments, specify the name of the load balancer that allows external access to the Harbor VM. If you are using an Internet-facing load balancer, select the Internet Connected checkbox. If the load balancer is internal, deselect the checkbox.
  5. Click Save.

    Harbor Configuration with ELB

Update the Stemcell Version

If the version of the Harbor tile that you are installing requires a more recent stemcell version than is currently deployed in Ops Manager, the Harbor tile displays a “Missing stemcell” error message.

Missing stemcell for Harbor

To update the stemcell, follow the steps below.

  1. In Ops Manager, return to the Installation Dashboard.
  2. Click the Harbor tile.
  3. In the Harbor tile, click the Missing stemcell link.
  4. In the Stemcell Library. record the name and version of the required stemcell for Harbor. Required stemcell for Harbor
  5. Log in to Pivotal Network.
  6. Search for Stemcells for PCF (Ubuntu Xenial).
  7. Download the required Harbor stemcell for your platform to the Ops Manager host. For example, if you are using vSphere, download the BOSH stemcell for vSphere that matches the version that you recorded in a previous step.
  8. In Ops Manager, return to the Installation Dashboard.
  9. On the Harbor tile, click the Missing stemcell link.
  10. Click Import Stemcell, navigate to the stemcell you downloaded, and click Open to import the stemcell. Import required stemcell for Harbor
  11. When prompted, apply the imported stemcell to the Harbor product.

Deploy Harbor Registry

  1. Return to the Ops Manager Installation Dashboard.
  2. Click Apply Changes to deploy Harbor. Deploy Harbor

View Harbor VM Information

When the deployment finishes, verify the deployment by checking the Harbor instance information the Harbor tile in Ops Manager.

  1. Select the Status tab to see the IP address of the Harbor host and status information about the Harbor VM.
  2. Select the Credentials tab to see Harbor credentials, including the Harbor administrator account for SSH access to the VM and the Clair database credentials.
  3. Select the Logs tab to collect Harbor log files and generate and download the Harbor log bundle.

    Get Harbor IP

Next Steps

After you install and configure Harbor, you must update the DNS entry for Harbor and provide the Harbor CA certificate to Ops Manager. If you use Enterprise PKS with NSX-T, define a NAT rule to the Harbor IP address.

  • Update the DNS entry for the Harbor hostname with the IP address of the Harbor VM assigned by BOSH. See Update DNS for Harbor in Integrating VMware Harbor Registry with Enterprise PKS.
  • Obtain the Harbor CA certificate and provide it to Ops Manager:
  • If you are using Harbor with Enterprise PKS with NSX-T in NAT mode, you must create a DNAT rule to access the Harbor UI. See Create DNAT Rule (NSX-T) in Integrating VMware Harbor Registry with Enterprise PKS.
  • Start Harbor and log in. See Starting Harbor in Using VMware Harbor Registry.
  • Use Harbor. See Using Harbor in Using VMware Harbor Registry.
Create a pull request or raise an issue on the source for this page in GitHub