Skip to main content

Installation on AWS

Sonatype IQ Server can be configured to operate simultaneously on 2 or more Kubernetes nodes with Active-Active Clustering to limit downtime. The HA cluster is limited to a single logical EKS cluster spanning across multiple AZs in a single region.

These requirements are designed to protect your installations on Amazon Web Services (AWS) from scenarios such as:

  1. AWS Availability Zone (AZ) outage within a single AWS region

  2. Node/server (EC2) failures.

  3. IQ Server service/database failures

We have thoroughly tested and verified the functionality and performance of the Sonatype IQ Server with the named third-party tools, technologies, and platforms mentioned in this section. Using other equivalent technologies and platforms may not result in the exact same outcomes, and is not supported by Sonatype.

Requirements for HA Installation on Amazon Web Services (AWS)

In addition to the general requirements, here are the specific requirements for AWS deployments:

Reference Architecture


Steps to Implement the Reference Architecture

Step 1: Amazon Virtual Private Cloud (VPC)

  • Create a VPC to launch the required AWS resources (EKS, EFS, RDS, and ALB) needed.

Step 2: Amazon Aurora PostgreSQL Cluster

Step 3 - Amazon Elastic Kubernetes Service (EKS) Cluster

  • Create an EKS cluster with a node group of at least 2 nodes.

  • Configure the cluster to allow 1 IQ Server pod to run on each node.

  • Pods must have the correct permissions for resources to be used (e.g., RDS, EFS, ALB, Cloudwatch, etc.)

  • Permissions can either be associated with a service account that the pods can use or with the EKS worker nodes.

  • We recommend using security groups associated with the resources to manage the permissions.

Step 4 - Amazon Elastic File System

Step 5 - Amazon Application Load Balancer (ALB)

Install the ALB controller in your cluster. It can be configured in any of the following ways:

  1. The ALB controller automatically provisions a new ALB via an ingress

  2. The ALB controller automatically configures an existing ALB, with no ingress required

You can manually provision and configure an ALB.

Step 6 - Amazon EFS Container Storage Interface (CSI) Driver Controller

Install the EFS CSI driver into your cluster and configure it to effectively manage EFS access.

Step 7 - EFS Storage Class - optional

Install the EFS storage class in the cluster for dynamic provisioning. This is optional; the Helm chart can alternatively use static provisioning, which requires a direct reference to the EFS. It can also use a pre-existing PV/PVC pointing to an EFS.

Step 8 - Kubernetes Secrets Store CSI Driver - optional

  • Install the Kubernetes Secrets Store CSI Driver into your cluster and configure it to enable AWS Secrets Manager access.

  • This is useful if you wish to store the license, the initial admin password, or the database settings in AWS secrets.

  • Alternatively, the license can be passed directly during installation as a file or a reference to a Kubernetes secret, and the passwords can be passed directly during installation as text or as references to Kubernetes secrets.

Step 9 - Kubernetes Namespace - optional

Create a separate Kubernetes namespace for IQ Server HA by using the kubectl tool:

  kubectl create namespace <namespace>

Alternatively, you can use the default namespace.

Step 10 - Install Helm chart

Install the latest Helm chart from the IQ Server HA Helm chart repository, with the recommended overrides.

Step 11 - Prepare the PostgreSQL Server

A user account needs to be provisioned for IQ Server to connect to the database.


CREATE USER sonatypeiq WITH PASSWORD 'the-secret-password';

The above commands will create a user and database named "sonatypeiq", granting that user the needed privileges for IQ Server to function.

Ensure that the database encoding is set to UTF8 to ensure compatibility with the character set used by IQ Server.

Running your Kubernetes Cluster

Follow the steps in the latest README for running the Kubernetes cluster.

Overrides for Helm Chart

Customization or override of some settings in the Helm chart will be required to match IQ Server HA deployment requirements.

Use a –set flag (or set-file) to override the Helm chart settings, as specified in the README.

The list below shows the Helm chart overrides (refer to the README for implementation details):

  1. Required

    1. Database configuration

    2. Shared file system: To share data between IQ Server pods, such as scans, reports, component details, advanced search index, etc.

    3. Load Balancer: A load balancer must be configured to allow and route external requests to IQ Server pods.

    4. Unified logging layer - Fluentd

  2. Optional

    1. Transport Layer Security (TLS) certificate and key

    2. IQ Server configuration parameters

    3. Autoscaling configuration parameters