Skip to main content

Single Data Center On-Premises Resilient Deployment Example Using Kubernetes

Note

Only available in Sonatype Nexus Repository Pro. Interested in a free trial? Start here.

A Helm Chart (GitHub, ArtifactHub) is available for our resiliency and high-availability deployment options. Be sure to read the deployment instructions in the associated README file before using the chart.

This example architecture illustrates how to use a Kubernetes cluster and PostgreSQL database to create a resilient Nexus Repository deployment. To learn more about resiliency and protecting your data in the event of an outage or disaster, see Resiliency and High Availability.

If you already have a Sonatype Nexus Repository instance and want to migrate to a resilient architecture, see our migration documentation.

Nexus_Repository_Resiliency_-_On_-premises_Resiliency_deployment.png

Important Terms

Before proceeding, you should know these important terms:

  • Node - A virtual or physical machine

  • Pod - A group of one or more containers with shared storage and network resources and a specification for how to run containers

  • Container - A package with the program to execute (Nexus Repository) and everything required for it to run (e.g., code, runtime, system libraries)

  • Instance - An instance of Nexus Repository

Use Cases

This reference architecture is designed to protect against the following scenarios:

  • A node/server failure within a data center

  • A Nexus Repository service failure

You would use this architecture if you fit the following profiles:

  • You are a Nexus Repository Pro user looking for a resilient Nexus Repository deployment option on-premises in order to reduce downtime

  • You would like to achieve automatic failover and fault tolerance as part of your deployment goals

  • You already have a Kubernetes cluster set up as part of your deployment pipeline for your other in-house applications and would like to leverage the same for your Nexus Repository deployment

  • You have migrated or set up Nexus Repository with an external PostgreSQL database and want to fully reap the benefits of an externalized database setup

  • You do not need High Availability (HA) active-active mode

Requirements

  • A Nexus Repository Pro license

  • Nexus Repository 3.33.0 or later

  • A tool such as Kops for setting up Kubernetes clusters

  • kubectl command-line tool

  • Kustomize to customize Kubernetes objects

  • Bare metal servers/virtual machines for configuring master and worker nodes

  • A PostgreSQL database

  • A load balancer

  • File storage (Network File System)

Note

If you require your clients to access more than one Docker Repository, you must use an external load balancer (e.g., NGINX) as a reverse proxy instead of the provided ingress for Docker YAML.

Limitations

In this reference architecture, a maximum of one Nexus Repository instance is running at a time. Having more than one Nexus Repository instance replica will not work.

Setting Up the Architecture

Note

Unless otherwise specified, all steps detailed below are still required if you are planning to use the HA/Resiliency Helm Chart (GitHub, ArtifactHub).

Step 1 - Kubernetes Cluster

Kubernetes works by placing containers into pods to run on nodes. You must set up a Kubernetes cluster comprising one master node and one worker node per Sonatype Nexus Repository instance that you wish to run.

  1. See Kops documentation for an example of how to set up a Kubernetes cluster with one master and two worker nodes using Kops..

  2. Attach separate disks (i.e., separate from the root disk) to your worker nodes.

  3. Install the Local Persistence Volume Static Provisioner. Please refer to Local Persistence Volume Static Provisioner documentation.

  4. Use the Local Persistence Volume Static Provisioner to automatically create persistent volumes for your chosen storage class name as documented.

Step 2 - PostgreSQL Database

Set up a PostgreSQL database and ensure the worker nodes can communicate with this database. See Installing Nexus Repository Pro with a PostgreSQL Database for more information.Installing a Pro License in Nexus Repository 2

To avoid single points of failure, we recommend you set up a highly available PostgreSQL cluster.

Step 3 - Licensing

There are two options for managing licensing:

  1. Configure License in Helm Chart - This option is for those using the HA/Resiliency Helm chart

  2. License Configuration Mapping YAML - This option is for those not using the HA/Resiliency Helm chart

Option 1 - Configure License in Helm Chart

  1. In the values.yaml within the HA/Resiliency Helm Chart, locate the license section as shown below.

      license:
    name: nexus-repo-license.lic
    licenseSecret:
      enabled: false
      file: # Specify the license file name with --set-file license.licenseSecret.file="file_name" helm option
      fileContentsBase64: your_license_file_contents_in_base_64
      mountPath: /var/nexus-repo-license

  2. Change the license.licenseSecret.enabled to true.

  3. Do one of the following:

    1. Specify your license file in license.licenseSecret.file with --set-file license.licenseSecret.file="file_name" helm option

    2. Put the base64 representation of your license file as the value for license.licenseSecret.fileContentsBase64.

Option 2 - License Configuration Mapping YAML

Tip

If you plan to use the HA/Resiliency Helm Chart (GitHub, ArtifactHub),use option 1 instead.

If you are not using the HA/Resiliency Helm Chart, you will need to use Kustomize when applying your YAML files and include a completed License Configuration Mapping YAML.

Step 4 - NFS Dynamic Subdir Provisioning

NFS provides a shared location for storing logs. The NFS subdir external provisioner uses your existing NFS server to support dynamic provisioning of Kubernetes Persistent Volumes via Persistent Volume Claims.

Install the Kubernetes NFS subdir external provisioner following the instructions provided in the Kubernetes NFS subdir external provisioner GitHub.

If you are using the Helm chart, you will also need to make updates to your values.yaml before installing the Helm chart. Details about what to update are included in the Helm chart's README file.

Starting Your Deployment

Tip

If you are using the HA/Resiliency Helm Chart (GitHub, ArtifactHub), skip these steps and follow the instructions on GitHub for installing the Helm chart instead. Ensure you update your values.yaml as detailed in the Helm chart's README file.

Step 1 - Create a Kubernetes Namespace

All Kubernetes objects for Sonatype Nexus Repository need to be in one namespace.

There are two ways to create a Kubernetes namespace: manually using the kubectl command-line tool or through a Namespaces YAML.

Option 1 - Manually Create Namespace

  1. Follow the Kubernetes documentation for creating a Kubernetes namespace with the kubectl command-line tool.

  2. You will use the following command to create the namespace:

    kubectl create namespace <namespace>

Option 2 - Use the Namespaces YAML

  1. Fill out a Namespaces YAML with the correct information for your deployment.

  2. Apply your YAML to create a namespace.

Step 2 - Fill Out YAML Files

  1. Use the sample yaml files linked in the Sample YAML Files as a starting point.

  2. Fill out your YAML files with the appropriate information for your deployment.

Step 3 - Apply the YAML Files

You will now apply your YAML Files using one of two methods:

Option 1 - Apply YAML Files Using Kustomize

Follow the steps below to apply all of your completed YAMLs in one command:

  1. Create a Kustomization directory into which you will place your YAML files.

  2. Fill out a License Configuration Mapping YAML and place it in this Kustomization directory.

  3. Place all of your other completed YAML files as well as your Sonatype Nexus Repository license file in the Kustomization directory.

  4. Use the following command where <kustomization_directory> is your Kustomization directory containing all of the YAML files; this will apply all YAML files in that directory:

    kubectl apply -k <kustomization_directory>

    Your Nexus Repository license is passed into the Nexus Repository container by using Kustomize to create a configuration map that is mounted as a volume of the pod running Nexus Repository.

    See Kubernetes documentation for using Kustomize for more information.

Option 2 - Apply YAML Files Manually

Manually run each of your completed YAML files in the order below:

  1. License Configuration Mapping

  2. StatefulSet YAML

  3. Services YAML

  4. Ingress YAML

Explanations of what each file does can be found in the Sample YAML Files reference below.

Sample Kubernetes YAML Files

Warning

The YAML files linked in this section are just examples and cannot be used as-is. You must fill them out with the appropriate information for your deployment to be able to use them.

* If you are using the HA/Resiliency Helm Chart (GitHub, ArtifactHub), do not use this table. Follow the instructions on GitHub for installing the Helm chart instead.

You can use the sample on-premises YAML files from our sample files GitHub repository to help set up the YAMLs you will need for your deployment. Ensure you have filled out the YAML files with appropriate information for your deployment.

File

What it Does

Do I Need This File?*

Namespaces YAML

Creates a namespace into which to install the Kubernetes objects for Sonatype Nexus Repository

Needed only if you are using the YAML method for creating a namespace.

License Configuration Mapping

Creates a config map containing a base64 representation of your license file contents and associates that config map with the specified StatefulSet YAML

Needed only if you are using Kustomize.

StatefulSet YAML

Starts your Sonatype Nexus Repository pods; uses secrets for mounting volumes

Yes

Services YAML

Creates a Kubernetes service through which the Nexus Repository application HTTP port (i.e., 8081) can be reached

Yes

Ingress YAML

Exposes the Nexus Repository service externally so that you can communicate with the pods

Yes

Note

  • Always run your YAML files in the order specified above.

  • The resources created by these YAMLs are not in the default namespace.

  • The sample YAML files are set up to disable the default blob stores and repositories on all instances.