Quick deployment of NBS 7.13 in an Amazon Web Services (AWS) environment

This page provides a streamlined path to deploy NBS 7 infrastructure and microservices in an Amazon Web Services (AWS) hosting environment. It is a condensed form of the NBS 7 full deployment, intended for experienced administrators who are familiar with AWS, Kubernetes, Helm, and Terraform. For a detailed walkthrough with an explanation at each step, use the full deployment instead. Both paths create the same infrastructure and services.

Scope and limitations

Before you begin, verify that your NBS 6 version is supported for your target NBS 7 version. See the Supported NBS versions page.

This quick deployment condenses the full procedure and omits most of the validation steps. Use the NBS 7 full deployment for production deployments and for first-time deployments.

Prerequisites

Confirm the general Prerequisites and the Cloud prerequisites before you begin. On your management workstation or in AWS CloudShell, install the following tools:

AWS CLI (the aws command)
Terraform CLI (the terraform command)
Helm CLI (the helm command)
kubectl (the Kubernetes CLI)

You also need an authenticated AWS session and network access to your existing NBS 6 SQL Server database. For version requirements and full details, see the Cloud prerequisites page.

Provision cloud infrastructure

Use Terraform to provision the virtual network, the Amazon Elastic Kubernetes Service (Amazon EKS) cluster, and the supporting AWS services for NBS 7.

Authenticate to your AWS account and confirm the session:
```
aws configure
aws sts get-caller-identity
```
Navigate to the NEDSS-Infrastructure v7.13.0 release page. Under Assets, download the nbs-infrastructure-v7.13.0.zip file, then unzip it.
Create an environment directory and copy the sample layers into it:
```
cd nbs-infrastructure-v7.13.0/terraform/aws
mkdir nbs7-mySTLT-test
cp -pr samples/* ./nbs7-mySTLT-test
cd nbs7-mySTLT-test
```
The samples contain a numbered directory for each Terraform layer: 0-landing-zone, 1-nbs7, and 2-applications. Apply the layers in that numeric order. The README in the NEDSS-Infrastructure repository explains the layered design.
In each layer directory, update the terraform.tfvars and terraform.tf files with your environment-specific values. Then apply each layer in numeric order:
```
terraform init
terraform plan -out=tfplan
terraform apply tfplan
```
Review the full plan output and confirm that the changes match your intention before you apply. Use caution with terraform apply -auto-approve, because it applies changes without review.

Configure kubectl to connect to the provisioned cluster:

aws --region <REGION> eks update-kubeconfig --name <MANAGED_CLUSTER_NAME>

Confirm the cluster is ready. Each core pod should have a STATUS of Running, and each node should have a STATUS of Ready:
```
kubectl get pods --namespace=kube-system
kubectl get nodes
```

Save your nbs7-mySTLT-test directory. You need it for future maintenance of the infrastructure you provisioned.

Enable Linkerd for the default namespace

Linkerd provides mutual Transport Layer Security (mTLS) between the NBS 7 microservices, which deploy into the default Kubernetes namespace. Terraform deploys the Linkerd service during provisioning. Annotate the default namespace so that Linkerd injects a sidecar into each microservice pod:

kubectl annotate namespace default "linkerd.io/inject=enabled"

Verify that the annotation is in place. The output should include "linkerd.io/inject":"enabled":

kubectl get namespace default -o=jsonpath='{.metadata.annotations}'

Deploy core services

Download the Helm charts, then deploy the Traefik ingress controller, cert-manager, and the Cluster Autoscaler.

Navigate to the NEDSS-Helm v7.13.0 release page. Under Assets, download the nbs-helm-v7.13.0.zip file, then unzip it.
Change into the charts directory from the unzipped file. Run all helm commands from this directory:
```
cd <HELM_DIR>/nbs-helm-v7.13.0/charts
```

Deploy the Traefik ingress controller

The Traefik controller creates a Network Load Balancer (NLB) in AWS and routes traffic to the NBS 7 services.

Add the Traefik Helm chart repository and update it:

helm repo add traefik https://traefik.github.io/charts
helm repo update

Deploy the Traefik controller:

helm install traefik traefik/traefik --namespace traefik --create-namespace -f ./traefik/values.yaml

Confirm that the Traefik pod has a STATUS of Running and that the two numbers in the READY column match:
```
kubectl get pods -n traefik
```

Deploy NBS ingress resources

The nbs-ingress chart manages ingress routing between the NBS 7 applications.

In nbs-ingress/values.yaml, search for EXAMPLE and fill in your environment-specific values. The Helm values reference for NBS 7 microservices lists the values to use.

Deploy the ingress resources:

helm install nbs-ingress ./nbs-ingress -n default -f ./nbs-ingress/values.yaml

Configure cert-manager (optional)

Terraform deploys cert-manager during provisioning. It creates and renews Transport Layer Security (TLS) certificates for the Apache NiFi and modernization-api services. Skip this section if you use manual certificates stored in Kubernetes secrets.

In the NEDSS-Helm repository, open k8-manifests/cluster-issuer-prod.yaml and update the email address to a valid operations address.

Apply the manifest:

cd <HELM_DIR>/k8-manifests
kubectl apply -f cluster-issuer-prod.yaml

Verify that the cluster issuer is ready. The letsencrypt-production issuer should have a READY status of True:
```
kubectl get clusterissuer
```

Create DNS records

Create A records in Amazon Route 53 that point to the address of the Traefik load balancer.

Retrieve the load balancer address from the EXTERNAL-IP column:
```
kubectl get svc -n traefik
```

In the AWS Management Console, navigate to Route 53 > Hosted Zones and select your hosted zone. Create an A record as an ALIAS for each hostname in the following table, with Route traffic to set to the hostname of your Traefik load balancer. Replace <DOMAIN_NAME.TLD> with your site and domain names from the Helm values reference for NBS 7 microservices:

Subdomain description	Hostname	Example
NBS application	`app.<DOMAIN_NAME.TLD>`	`app.nbsdemo.com`
Data services	`data.<DOMAIN_NAME.TLD>`	`data.nbsdemo.com`
NiFi (use with caution)	`nifi.<DOMAIN_NAME.TLD>`	`nifi.nbsdemo.com`

Apache NiFi has known security vulnerabilities. Add a NiFi DNS record only if you need to administer NiFi directly. Otherwise, omit it.

Verify that each record resolves without an error such as server can't find. Records typically propagate within 60 seconds:
```
nslookup app.<DOMAIN_NAME.TLD>
```

Install and configure Keycloak

Keycloak is the authentication service that allows users to sign in to the NBS 7 web UI.

Create the Keycloak database and database user. Run the nbs_keycloak.sql script from the NEDSS-Helm repository on your NBS 6 database. Replace EXAMPLE_KCDB_PASS8675309 with a complex password and store it securely. You need it in the Helm values file.
In keycloak/values.yaml, set the admin credentials, the database connection values, and the KC_DB_PASSWORD to match the password you set in the script.
Install the Keycloak Helm chart. This step takes at least 5 minutes while the init container becomes available:
```
helm install keycloak ./keycloak -n default -f keycloak/values.yaml
```
Verify that the Keycloak pod is running:
```
kubectl get pods -n default
```
Set up port forwarding, then navigate to http://127.0.0.1:8080/auth in a browser and select Administration Console. Sign in with the admin credentials from the values file:
```
kubectl port-forward deploy/keycloak-deployment 8080
```
Port forwarding is not supported by AWS CloudShell by default. Run this command from a system that has both network access to your cluster endpoint and a browser.
Create the two NBS 7 realms. For each file, select Create realm, upload the file, and select Create:

Realm Import file

NBS 01-NBS-realm-with-DI-client.json

nbs-users 02-nbs-users-realm.json

All import files are in the keycloak/extra/ directory of the NEDSS-Helm charts.
Import the base users and development clients into the nbs-users realm. Select the realm, navigate to Realm settings > Action > Partial Import, and import each file:
- 03-nbs-users-base-users.json (select the three users: msa, nbs-users-admin, superuser)
- 04-nbs-users-development-clients.json (select the nbs-development client)

Realm	Import file
NBS	`01-NBS-realm-with-DI-client.json`
nbs-users	`02-nbs-users-realm.json`

Import the additional service clients and retrieve their secrets. The NBS realm seeds di-keycloak-client with the realm import, so it needs no separate import. For each client in the following table that requires an import, select the listed realm, navigate to Realm settings > Action > Partial Import, and import the file. Then navigate to Clients, select the client, open the Credentials tab, and store the secret in your organization’s secrets manager, such as AWS Secrets Manager:

Client	Realm	Import needed	Import file
`di-keycloak-client`	NBS	No	Seeded with the NBS realm
`nnd-keycloak-client`	NBS	Yes	`05-nbs-users-nnd-client.json`
`srte-data-keycloak-client`	NBS	Yes	`06-nbs-users-srte-data-client.json`
`case-notification-service`	NBS	Yes	`08-nbs-users-case-notification-service.json`

Verify Traefik and Keycloak together. In a browser, navigate to https://app.<DOMAIN_NAME.TLD>, confirm that the NBS 7 Welcome page is shown, select Login, and confirm that the Keycloak login page is shown.

Deploy NBS 7 microservices

Run each command from the charts directory, in the order shown. Before each command, search the service’s values.yaml file for EXAMPLE and fill in your environment-specific values from the Helm values reference for NBS 7 microservices. Verify that each service starts before you deploy the next one.

Elasticsearch:

helm install elasticsearch -f ./elasticsearch/values.yaml elasticsearch

Modernization API:

helm install "modernization-api" ./modernization-api -f ./modernization-api/values.yaml

Apache NiFi:

helm install "nifi" ./nifi -f ./nifi/values.yaml

NBS Gateway:

helm install "nbs-gateway" ./nbs-gateway -f ./nbs-gateway/values.yaml

Data processing service:

helm install "data-processing-service" ./data-processing-service -f ./data-processing-service/values.yaml

Case notification service. Deploy the Debezium connector first, then the service:

helm install "debezium-case-notification-service-connect" ./debezium-case-notifications -f ./debezium-case-notifications/values.yaml
helm install "case-notification-service" ./case-notification-service -f ./case-notification-service/values.yaml

Data Ingestion API (DI API):

helm install dataingestion-service -f ./dataingestion-service/values.yaml dataingestion-service

Real-time reporting (RTR). Complete the database setup and change data capture (CDC) bootstrap steps on the Deploy real-time reporting page first, then deploy the RTR services in order:

helm install -f ./debezium/values.yaml debezium-connect ./debezium/
helm install -f ./kafka-connect-sink/values.yaml cp-kafka-connect-server ./kafka-connect-sink/
helm install -f reporting-pipeline-service/values.yaml reporting-pipeline-service ./reporting-pipeline-service/

Clean up

To decommission this environment, follow Undeploy NBS 7. That page covers removing DNS entries, removing the Helm ingress resources, emptying the OpenTelemetry (OTEL) collector S3 bucket, and destroying the Terraform-managed infrastructure.

Support

For support, email nbs@cdc.gov.