Quick start (AWS)

This page provides a streamlined path to deploy NBS 7 infrastructure and core microservices in AWS. It is intended for experienced administrators familiar with AWS, Kubernetes, Helm, and Terraform.

Scope and limitations

This guide is not intended for production deployment. For full production steps and guidance, see Deploy NBS 7.

This quick start installs and configures the following resources.

Terraform-managed resources

Modern VPC, subnets, and route tables
EKS cluster and nodes
Network load balancer
MSK
Amazon Managed Service for Prometheus
Amazon Managed Grafana
EFS
KMS
S3 bucket

Manual configuration

Route53 updates: create DNS entries in Route53 to point app and data URLs to the network load balancer.

NBS 7 core services

Elasticsearch: Search indexing and query support.
Modernization API: Modern NBS capabilities, including patient and event search.
NiFi: Elasticsearch index population from the NBS database.
NBS Gateway: Routing between modern and legacy NBS.
Data ingestion: HL7 ingestion from labs and other sources.
Keycloak: Primary identity provider (IdP), token management, and SSO integration.

Prerequisites

Install these tools

AWS CLI (v2.15+)
Terraform (v1.5.5)
Helm (v3.12+)
kubectl (v1.27+)
eksctl (optional but recommended)

Environment requirements

AWS Account with NBS 6.0.16 access (or newer)
DNS routing infrastructure: domain information for modernized NBS application URLs (for example, app.site_name.domain.com)
IAM roles for Terraform and Kubernetes
Access to NBS 6 (SQL Server) databases to run scripts
S3 bucket for Terraform state

Set up AWS infrastructure (Terraform)

NBS 7 infrastructure diagram for quick-start deployment on AWS

Prepare the directory

mkdir -p ~/nbs-setup/terraform/aws/nbs7-mySTLT-test
cd ~/nbs-setup/terraform/aws/nbs7-mySTLT-test

Download Terraform configuration

Clone the infrastructure repo:

git clone https://github.com/CDCgov/NEDSS-Infrastructure.git

Copy standard template:

cp -pr terraform/aws/samples/NBS7_standard terraform/aws/nbs7-mySTLT-test

Customize variables

Update the terraform.tfvars and terraform.tf with your environment-specific values by following the instructions here.

Review inbound rules on the security groups attached to your database instance. Ensure the CIDR you intend to use with your NBS 7 VPC (modern-cidr) is allowed to access the database.

Initialize and apply Terraform

terraform init
terraform plan
terraform apply

Validate infrastructure

Confirm VPC, EKS cluster, subnets, and node groups are created.
Verify EKS cluster authentication and running pods & nodes:

aws eks --region us-east-1 update-kubeconfig --name <clustername> e.g. cdc-nbs-sandbox
kubectl get pods --namespace=cert-manager
kubectl get nodes

Deploy core Kubernetes services (Helm)

Install NGINX Ingress

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm install ingress-nginx ingress-nginx/ingress-nginx
kubectl --namespace ingress-nginx get services -o wide -w ingress-nginx-controller
kubectl get pods -n=ingress-nginx

Create DNS entries in Route53

Point the modernized NBS application URL to the new network load balancer in front of your Kubernetes cluster.

app.<site_name>.<domain>.com

Point the data services URL to the new network load balancer in front of your Kubernetes cluster.

data.<site_name>.<domain>.com

Install Cert Manager (optional)

helm repo add jetstack https://charts.jetstack.io
helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --set installCRDs=true

Install and verify Linkerd (optional)

kubectl annotate namespace default "linkerd.io/inject=enabled"
kubectl get namespace default -o=jsonpath='{.metadata.annotations}'

Install Cluster Autoscaler (optional)

helm repo add autoscaler https://kubernetes.github.io/autoscaler
helm install cluster-autoscaler autoscaler/cluster-autoscaler -n kube-system

Verify services are running

kubectl get pods -A

Install Keycloak

Create the Keycloak database. Make sure to update the database password.

use master
    IF NOT EXISTS(SELECT * FROM sys.databases WHERE name = 'keycloak')
    BEGIN
        CREATE DATABASE keycloak
    END
GO
    USE keycloak
GO

BEGIN
    CREATE LOGIN NBS_keycloak WITH PASSWORD = 'EXAMPLE_KCDB_PASS8675309';
    CREATE USER NBS_keycloak FOR LOGIN NBS_keycloak;
    EXEC sp_addrolemember N'db_owner', N'NBS_keycloak'
END

Install Keycloak container

Edit the following parameters in <helm extract directory>/charts/keycloak/values.yml:

kcDbPassword
kcDbUrl
keycloakAdminPassword
efsFileSystemId

helm install keycloak --namespace default --create-namespace -f keycloak/values.yaml

Port forward to access Keycloak admin interface

kubectl --namespace default port-forward "$POD_NAME" 8080;
http://127.0.0.1:8080/auth

Configure realms, users, and clients

Log in as the Keycloak admin user.
Upload <helm extract directory>/charts/keycloak/extra/01-NBS-realm-with-DI-client.json.
Upload <helm extract directory>/charts/keycloak/extra/05-nbs-users-nnd-client.json.
Upload <helm extract directory>/charts/keycloak/extra/02-nbs-users-realm.json.
Run partial import from the nbs-users realm for <helm extract directory>/charts/keycloak/extra/03-nbs-users-base-users.json.
Run partial import from the nbs-users realm for <helm extract directory>/charts/keycloak/extra/04-nbs-users-development-clients.json.

Deploy NBS 7 microservices (Helm)

Deploy the Helm charts in the following order.

elasticsearch-efs
modernization-api
nifi-efs
nbs-gateway
dataingestion-service

Run the following commands from the <helm extract directory>/charts directory.