From 07552b8fdd2028183eb282890e972938f529bfb4 Mon Sep 17 00:00:00 2001 From: jburgh Date: Fri, 17 Apr 2026 17:06:15 -0400 Subject: [PATCH 01/16] Restore branch files removed by merge with main --- docs/before-you-deploy.md | 36 +++ .../assess-your-readiness.md | 115 +++++++++ .../choose-your-configuration.md | 108 +++++++++ .../decision-tree.md | 123 ++++++++++ .../vendor-managed-deployment.md | 35 +++ docs/before-you-deploy/compatibility.md | 32 +++ docs/before-you-deploy/component-reference.md | 47 ++++ .../component-reference/di-api.md | 33 +++ .../nbs-core-components.md | 142 +++++++++++ .../component-reference/rtr.md | 69 ++++++ docs/before-you-deploy/deployment-phases.md | 111 +++++++++ .../before-you-deploy/deployment-scenarios.md | 14 ++ .../large-jurisdiction.md | 55 +++++ .../medium-jurisdiction.md | 55 +++++ .../small-jurisdiction.md | 54 +++++ .../operational-considerations.md | 80 ++++++ .../real-time-reporting/permissions.md | 185 ++++++++++++++ docs/deploy-nbs7/support.md | 73 ++++++ docs/maintain-nbs7/eks-upgrade.md | 228 ++++++++++++++++++ docs/maintain-nbs7/upgrade-nbs7.md | 96 ++++++++ .../upgrade-nbs7/release-notes-7-12.md | 92 +++++++ 21 files changed, 1783 insertions(+) create mode 100644 docs/before-you-deploy.md create mode 100644 docs/before-you-deploy/assess-your-readiness.md create mode 100644 docs/before-you-deploy/choose-your-configuration.md create mode 100644 docs/before-you-deploy/choose-your-configuration/decision-tree.md create mode 100644 docs/before-you-deploy/choose-your-configuration/vendor-managed-deployment.md create mode 100644 docs/before-you-deploy/compatibility.md create mode 100644 docs/before-you-deploy/component-reference.md create mode 100644 docs/before-you-deploy/component-reference/di-api.md create mode 100644 docs/before-you-deploy/component-reference/nbs-core-components.md create mode 100644 docs/before-you-deploy/component-reference/rtr.md create mode 100644 docs/before-you-deploy/deployment-phases.md create mode 100644 docs/before-you-deploy/deployment-scenarios.md create mode 100644 docs/before-you-deploy/deployment-scenarios/large-jurisdiction.md create mode 100644 docs/before-you-deploy/deployment-scenarios/medium-jurisdiction.md create mode 100644 docs/before-you-deploy/deployment-scenarios/small-jurisdiction.md create mode 100644 docs/before-you-deploy/operational-considerations.md create mode 100644 docs/deploy-nbs7/real-time-reporting/permissions.md create mode 100644 docs/deploy-nbs7/support.md create mode 100644 docs/maintain-nbs7/eks-upgrade.md create mode 100644 docs/maintain-nbs7/upgrade-nbs7.md create mode 100644 docs/maintain-nbs7/upgrade-nbs7/release-notes-7-12.md diff --git a/docs/before-you-deploy.md b/docs/before-you-deploy.md new file mode 100644 index 0000000..17b0e1a --- /dev/null +++ b/docs/before-you-deploy.md @@ -0,0 +1,36 @@ +--- +title: Before you deploy +layout: page +nav_order: 2 +has_children: true +description: Evaluation and planning content to help you assess NBS 7 readiness and choose a deployment configuration. +--- + +# Before you deploy NBS 7 + +This section is for STLT IT administrators and technical decision-makers who are evaluating and preparing for NBS 7. It brings together the readiness, compatibility, configuration, and planning information you need before deployment begins. Use it to understand what NBS 7 includes, what decisions your jurisdiction needs to make, and what conditions should be in place before you move into deployment work. It is intended to support an informed decision about whether to proceed with NBS 7 deployment planning. + +## Purpose + +Use this section to: + +- assess whether NBS 7 deployment planning is the right next step for your jurisdiction +- identify the right starting configuration for your jurisdiction, including optional add-ons +- understand the major components, prerequisites, and operational considerations that affect deployment +- support go or no-go decisions before you commit time and resources to deployment + +> Some factors that affect NBS 7 migration extend beyond infrastructure and configuration. For a summary of organizational, financial, and operational considerations, see [Operational considerations](before-you-deploy/operational-considerations.html). +{: .note } + +## How this content fits into the NBS 7 process + +Three main resources support the NBS 6 to NBS 7 transition. Each serves a different purpose: + +| Resource | Purpose | When to use | +|:---|:---|:---| +| **Before you deploy NBS 7** (you are here) | This resource helps IT administrators and leadership evaluate NBS 7, understand hosting requirements, and choose a component configuration | Use first | +| **[NBS 7 Migration Info Sheet](https://nbscentral.cdc.gov/documents/731)** (requires login) | Hosted on NBS Central, this resource guides your jurisdiction through the migration process, including timelines, roles, a compatibility checklist, and cutover planning | Use after confirming NBS 7 is the right fit | +| **[NBS 7 Deployment Guide](deploy-nbs7.html)** | Provides step-by-step deployment instructions for your chosen configuration | Use when ready to deploy | + +{: .note } +NBS 7 is under active development. Component availability and configuration options will change as development continues. Make sure you check this resource for the latest guidance before you begin to plan. diff --git a/docs/before-you-deploy/assess-your-readiness.md b/docs/before-you-deploy/assess-your-readiness.md new file mode 100644 index 0000000..1d4988a --- /dev/null +++ b/docs/before-you-deploy/assess-your-readiness.md @@ -0,0 +1,115 @@ +--- +title: Assess your readiness +layout: page +parent: Before you deploy +nav_order: 2 +description: Covers the technical prerequisites an STLT should meet before beginning NBS 7 migration, including cloud, staffing, and network requirements. +--- + +# Assess your readiness for NBS 7 + +This page helps you assess whether NBS 7 is a viable option for your jurisdiction before you commit to a migration. + +## On this page +{: .no_toc .text-delta } + +1. TOC +{:toc} + +If you work through this page and find that your jurisdiction does not meet one or more prerequisites, you might still be able to move forward. You can address some gaps with planning and lead time, but other gaps might indicate that NBS 7 is not the right fit for your jurisdiction right now. + +For more information on migration planning, staffing, and budget, see [Operational considerations](../before-you-deploy/operational-considerations.html) in this guide, and the [NBS 7 Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) and [NBS 7 Resource Estimator](https://nbscentral.cdc.gov/documents/872) on NBS Central (NBS Central login required). +{: .note } + +## Not sure where to start? + +If you are new to NBS 7 deployment, [Deployment phases](../before-you-deploy/deployment-phases.html) provides an overview of an example rollout and where this readiness assessment fits. + +## State IT security approval + +Has your jurisdiction obtained state IT security approval for cloud hosting and the software technologies that NBS 7 requires, including Kubernetes, Terraform, and Docker? + +- **Yes, or approval is not required**: Continue with the rest of this section. +- **No, or unknown**: Approval timelines vary and can significantly affect your migration schedule. We recommend working with your state IT office while you continue to plan. + +See also: [Operational considerations](../before-you-deploy/operational-considerations.html) and [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html). + +## Cloud infrastructure + +NBS 7 requires a cloud-based environment for deployment. NBS 7 has not been tested for on-premises deployment, and CDC does not plan to support it. To deploy with CDC support, you need an active account with one of the following supported cloud providers: + +**Amazon Web Services (AWS)** + + - **Strategic fit:** Preferred by jurisdictions with established AWS environments or those prioritizing a broad ecosystem of third-party security and data tools. + - **Technical readiness:** Aligns with teams experienced in managing container-native architectures via Amazon Elastic Kubernetes Service (EKS) and mature Terraform workflows. + - **Surveillance context:** Core components are extensively validated in AWS to ensure performance at peak ingestion volumes. + +**Microsoft Azure** + + - **Strategic fit:** Preferred by jurisdictions with significant Microsoft ecosystem investments, such as those using Microsoft Entra ID (formerly Azure Active Directory) or existing Enterprise Agreements. + - **Technical readiness:** Provides a streamlined experience for organizations running Windows-based workloads or requiring integration with Microsoft 365 and Power Platform tools. + - **Surveillance context:** Supported via Terraform for configuration parity with AWS, allowing jurisdictions to meet internal mandates for Azure-hosted health data. + +See also: [Deploy cloud infrastructure on AWS](../deploy-nbs7/deploy-on-aws.html), [Deploy cloud infrastructure on Azure](../deploy-nbs7/deploy-on-azure.html), and [Compatibility matrix](../before-you-deploy/compatibility.html). + +## Technical staff capacity + +NBS 7 uses Kubernetes, a container orchestration platform. To deploy and maintain NBS 7, you need staff who can: + +- Deploy and manage Kubernetes clusters +- Read and modify Terraform configuration files +- Manage cloud networking, storage, and access control +- Monitor system health and respond to alerts + +If your IT team does not have these skills, you have two options: + +- **Building capacity**: Train existing staff or hire staff with these skills before you begin deployment. +- **Working with a vendor**: Contract with a vendor to deploy or manage your NBS 7 infrastructure. See [Vendor-managed deployment](../before-you-deploy/choose-your-configuration/vendor-managed-deployment.html) for guidance on what to look for in a vendor. + +See also: [Operational considerations](../before-you-deploy/operational-considerations.html) and [Choose your configuration](../before-you-deploy/choose-your-configuration.html). + +## Network readiness + +Before deployment, your network must meet the following requirements: + +- **NBS 6 and NBS 7 connectivity**: Each NBS 7 instance requires network connectivity to a corresponding NBS 6 instance. If your NBS 6 runs in a Virtual Private Cloud (VPC), that VPC must be connected to your NBS 7 environment. +- **VM co-location**: Any virtual machines (VMs) that you use for NBS 7 components must exist within the same network. +- **Encryption**: Encryption is required for all virtual network traffic between NBS 6 and NBS 7 components. +- **Outbound access**: Your cloud environment needs outbound internet access to reach CDC systems. +- **TLS/SSL certificate management**: You need a process to provision and renew TLS/SSL certificates for encrypted traffic. + +Your specific network configuration will depend on your cloud provider and the existing infrastructure for your jurisdiction. + +See also: [Architecture and microservices](../deploy-nbs7/architecture-and-microservices.html), [Cluster infrastructure](../deploy-nbs7/cluster-infrastructure.html), and [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html). + +## NBS 6 status + +During migration, NBS 7 components gradually replace NBS 6 functionality while NBS 6 continues to run. This means: + +- Your jurisdiction will run both systems in parallel during the transition. +- Your NBS 6 instance must remain operational and accessible during migration. +- Many jurisdictions provision a separate NBS 6 environment for migration activities and then cut over, rather than deploying NBS 7 changes directly against their primary NBS 6 production server. +- You need to know your current NBS 6 hosting setup before you begin. Specifically, whether it is hosted on-premises or in the cloud, and if in the cloud, which provider. +- **You must be running a compatible NBS 6.x version** before you can install any version of NBS 7. For more information, see [Compatibility matrix](../before-you-deploy/compatibility.html). + +See also: [Deployment phases](../before-you-deploy/deployment-phases.html) and [Operational considerations](../before-you-deploy/operational-considerations.html). + +## Data migration + +NBS 7 uses your existing NBS 6 database and does not require a schema migration. In most cases, no data migration is needed. + +If your current NBS 6 database is hosted on-premises and you plan to move it to the cloud as part of your migration, you will need to copy the data from your existing environment and restore it to the new environment using a standard database backup and restore process. If you are not moving your NBS 6 database, no data migration action is required. + +See also: [Prerequisites for NBS 7 deployment](../deploy-nbs7/prerequisites.html#nbs-6-readiness), [Deployment scenarios](../before-you-deploy/deployment-scenarios.html), and [Deployment phases](../before-you-deploy/deployment-phases.html). + +## CDC coordination + +Reach out to your CDC NBS point of contact before you begin deployment. CDC provides deployment support at no cost and can help you: + +- Validate your technical readiness +- Identify the right configuration for your jurisdiction +- Connect you with other jurisdictions that have already migrated + +See also: [Choose your configuration](../before-you-deploy/choose-your-configuration.html) and [Operational considerations](../before-you-deploy/operational-considerations.html). + +**Contact:** [nbs@cdc.gov](mailto:nbs@cdc.gov) diff --git a/docs/before-you-deploy/choose-your-configuration.md b/docs/before-you-deploy/choose-your-configuration.md new file mode 100644 index 0000000..d133e17 --- /dev/null +++ b/docs/before-you-deploy/choose-your-configuration.md @@ -0,0 +1,108 @@ +--- +title: Choose your configuration +layout: page +parent: Before you deploy +nav_order: 4 +has_children: true +description: Describes NBS 7 and its two optional add-ons — Real-Time Reporting (RTR) and the Data Ingestion (DI) API — and when each is appropriate. +--- + +# Choose your NBS 7 configuration options +{: .no_toc } + +NBS 7 is the base product. Two optional add-ons are available: Real-Time Reporting (RTR) and the Data Ingestion (DI) API. You do not have to deploy add-ons at the outset. Most jurisdictions deploy NBS 7 first, then evaluate add-ons as their team builds confidence with the platform. Starting without add-ons reduces deployment risk and gives your team time to learn the system before taking on additional complexity. + +## On this page +{: .no_toc .text-delta } + +1. TOC +{:toc} + +After you review the available options, use the [decision tree](../before-you-deploy/choose-your-configuration/decision-tree.html) to identify your recommended starting configuration. If your jurisdiction plans to use a vendor, see the [Vendor-managed deployment](../before-you-deploy/choose-your-configuration/vendor-managed-deployment.html) page. + +Before finalizing your configuration, verify that your NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html). + +--- + +## NBS 7 + +The base deployment. NBS 7 gives your jurisdiction NBS 6 feature parity on modern, cloud-based infrastructure, plus foundational improvements such as real-time patient search. + +NBS 7 core components are organized into three layers. For details on what each component does and when you need it, see [NBS 7 core components](../before-you-deploy/component-reference/nbs-core-components.html). + +### Networking layer + +The networking layer manages traffic routing and secure communication between your NBS 6 and NBS 7 environments. + +- DNS infrastructure (Route 53 or equivalent) +- Virtual Private Cloud (VPC) and routing groups +- VPN connectivity between NBS 6 and NBS 7 instances + +### Infrastructure layer + +The infrastructure layer provides the container orchestration platform and cloud services that host and run NBS 7 components. + +- Kubernetes cluster (EKS on AWS, AKS on Azure) +- Traefik Ingress Controller (replaced NGINX as of NBS 7.12) +- AWS or Azure managed services +- Terraform infrastructure automation modules +- Load balancer + +### Application layer + +The application layer contains the NBS 7 services and legacy NBS 6 components that users and administrators directly interact with. + +- [Legacy NBS 6](../before-you-deploy/component-reference/nbs-core-components.html#legacy-nbs-6) +- [NBS Modernization API](../before-you-deploy/component-reference/nbs-core-components.html#nbs-modernization-api) +- [NBS Web UI](../before-you-deploy/component-reference/nbs-core-components.html#nbs-web-ui) +- [NBS Gateway](../before-you-deploy/component-reference/nbs-core-components.html#nbs-gateway) +- [Elasticsearch](../before-you-deploy/component-reference/nbs-core-components.html#elasticsearch) +- [Nifi](../before-you-deploy/component-reference/nbs-core-components.html#nifi) +- [Keycloak](../before-you-deploy/component-reference/nbs-core-components.html#keycloak) +- [Cert Manager, FluentBit](../before-you-deploy/component-reference/nbs-core-components.html#infrastructure-and-networking-layer-components) +- Database (NBS\_ODSE and NBS\_SRTE) + +{: .note-title } +> Best for +> +> The base NBS 7 without add-ons might be suitable for jurisdictions with smaller IT teams, limited cloud experience, or a goal to establish a stable foundation before adding advanced features. + +--- + +## Add-on: Real-Time Reporting (RTR) + +RTR is an optional add-on that replaces the legacy MasterETL batch process with an event-driven reporting pipeline. We recommend that you run RTR alongside MasterETL during transition, with the goal of eventually replacing it. + +**With RTR, data is available within 5 minutes to 1 hour instead of 24 hours.** + +RTR adds the following components to your NBS 7 deployment. For details, see [Add-on: Real-Time Reporting (RTR)](../before-you-deploy/component-reference/rtr.html). + +- [Debezium](../before-you-deploy/component-reference/rtr.html#debezium) +- [Kafka and Kafka Connect](../before-you-deploy/component-reference/rtr.html#kafka-and-kafka-connect) +- [RTR domain services](../before-you-deploy/component-reference/rtr.html#rtr-domain-services) + +{: .note-title } +> Best for +> +> NBS 7 with the RTR add-on might be suitable for jurisdictions with higher case volumes, a need for faster data turnaround, or plans to connect to advanced analytics tools. + +--- + +## Add-on: Data Ingestion (DI) API + +The DI API is an optional add-on that provides a built-in data transit layer. It provides a REST API interface for writing data to NBS, acting as a secure intermediary between your middleware and the database. + +| Integration Method | Rationale | +| :--- | :--- | +| **Direct SQL Write** | Standard for jurisdictions where middleware (Rhapsody) can access the database network directly. | +| **DI API** | Used when security policies prohibit direct database access from third-party tools or when middleware cannot be co-located with NBS. | + +{: .important } +The DI API is not a replacement for middleware. An integration engine like Rhapsody is still required to preprocess and format data before it is sent to the DI API. + +For details, see [Add-on: Data Ingestion (DI) API](../before-you-deploy/component-reference/di-api.html). + +{: .note-title } +> Best for +> +> NBS 7 with the DI API add-on might be suitable for jurisdictions with security constraints that prevent third-party tools from writing directly to the network or database. diff --git a/docs/before-you-deploy/choose-your-configuration/decision-tree.md b/docs/before-you-deploy/choose-your-configuration/decision-tree.md new file mode 100644 index 0000000..a69a073 --- /dev/null +++ b/docs/before-you-deploy/choose-your-configuration/decision-tree.md @@ -0,0 +1,123 @@ +--- +title: Decision tree +layout: page +parent: Choose your configuration +grand_parent: Before you deploy +nav_order: 1 +description: A step-by-step decision tree that guides jurisdictions to a suggested NBS 7 starting configuration based on hosting model, capacity, and case volume. +--- + +# NBS 7 configuration decision tree + +Use this decision tree to determine a baseline deployment model for your jurisdiction. Answer the questions in sequence to identify the suggested architecture for your infrastructure and integration needs. + +## On this page +{: .no_toc .text-delta } + +1. TOC +{:toc} + +{: .important } +The decision tree identifies a potential starting point, not a final answer. CDC provides free pre-deployment consultation to help jurisdictions validate their configuration choice. Connect with the CDC NBS team at [nbs@cdc.gov](mailto:nbs@cdc.gov) before you begin deployment. + +## Step 1: State IT security approval + +Has your jurisdiction obtained state IT security approval for cloud hosting and the required software technologies (Kubernetes, Terraform, Docker)? + +- **Yes, or approval is not required** → Go to [Step 2](#step-2-internal-technical-capacity). +- **No, or unknown** → It's a good idea to begin the approval process now, then continue planning. Approval is typically required before deployment. Go to [Step 2](#step-2-internal-technical-capacity). + +Because NBS handles PII and PHI, state IT might still need to review and approve the deployment, even in vendor-managed models. For more information, see [State IT security approval takes time](../operational-considerations.html#state-it-security-approval-takes-time) on the Operational Considerations page. +{: .note } + +## Step 2: Internal technical capacity + +Does your jurisdiction have IT staff with skills in Kubernetes, Terraform, and cloud infrastructure management, roughly half or more of the required skill set? + +- **Yes** → Go to [Step 3](#step-3-current-nbs-6-hosting). +- **No** → Go to [Step 2a](#step-2a-external-assistance). + +For more information on technical capacity, see [Technical staffing requirements differ from NBS 6](../operational-considerations.html#technical-staffing-requirements-differ-from-nbs-6) on the Operational Considerations page. +{: .note } + +## Step 2a: External assistance + +Will your jurisdiction obtain external assistance from a contractor, vendor, or consultant for deployment and ongoing maintenance? + +- **Yes** → Go to [Step 3](#step-3-current-nbs-6-hosting). Note that your vendor or contractor must be capable of Kubernetes-based deployments on AWS or Azure. See [Vendor-managed deployment](vendor-managed-deployment.html) for what to look for. +- **No** → **Stop.** Build internal capacity or identify a vendor before proceeding. Contact [nbs@cdc.gov](mailto:nbs@cdc.gov) for support resources. + +## Step 3: Current NBS 6 hosting + +Where does your NBS 6 currently run? + +- **Already on AWS or Azure** → Staying on the same provider avoids additional procurement and approval steps. Go to [Step 4](#step-4-reporting-needs). +- **On-premises** → Your migration includes a cloud migration as well as an NBS 7 deployment. Plan for additional time and resources. Go to [Step 4](#step-4-reporting-needs). + +This step is informational and does not impact your suggested deployment configuration. For more information, see [Your cloud provider depends on your existing environment](../operational-considerations.html#your-cloud-provider-depends-on-your-existing-environment) on the Operational Considerations page. +{: .note } + +## Step 4: Reporting needs + +Does your jurisdiction need near-real-time reporting (data available within minutes to hours, rather than 24 hours)? + +- **Yes** → Go to [Step 5a](#step-5a-database-access-requirements-real-time-reporting-path). +- **No** → Go to [Step 5b](#step-5b-database-access-requirements-legacy-batch-reporting-path). + +Real-time reporting adds infrastructure complexity and requires additional cloud resources. For more information, see [Real-Time Reporting adds capability and cost](../operational-considerations.html#real-time-reporting-adds-capability-and-cost) on the Operational Considerations page. +{: .note } + +## Step 5a: Database access requirements (real-time reporting path) + +Some jurisdictions have security policies that prohibit third-party tools from writing directly to the database or require an intermediary layer when middleware and the database cannot be co-located. + +**Does your jurisdiction require an API layer to abstract database access?** + +- **Yes** → Suggested starting point: **NBS 7 + RTR + DI API add-ons**. +- **No** → Suggested starting point: **NBS 7 + RTR add-on**. + +## Step 5b: Database access requirements (legacy batch reporting path) + +Some jurisdictions have security policies that prohibit third-party tools from writing directly to the database or require an intermediary layer when middleware and the database cannot be co-located. + +**Does your jurisdiction require an API layer to abstract database access?** + +- **Yes** → Suggested starting point: **NBS 7 + DI API add-on**. +- **No** → Suggested starting point: **NBS 7 (no add-ons)**. + +For more information, see [The Data Ingestion API adds a secure integration option](../operational-considerations.html#the-data-ingestion-api-adds-a-secure-integration-option) on the Operational Considerations page. +{: .note } + +--- + +## Next steps: Estimate infrastructure costs + +After you determine your deployment model, you can use the jurisdictional sizing criteria provided in this section to identify which resource profile to use in the **NBS 7 Resource Estimator**. The estimator is an Excel-based tool available on NBS Central. It provides baseline values for provisioned resources, including compute (vCPU and Memory), SQL storage, and Kafka brokers. + +The following thresholds help you identify your profile for the estimator: + +| If your jurisdiction has... | And an estimated case volume of... | Use this profile | +| :--- | :--- | :--- | +| **Fewer than 5 million** person records | **Fewer than 200,000** cases | Small STLT | +| **5 million to 15 million** person records | **200,000 to 700,000** cases | Medium STLT | +| **More than 15 million** person records | **More than 700,000** cases | Large STLT | + +>Handling discrepancies +> +>If your metrics fall into different tiers (for example, your person records are "Small" but your case volume is "Medium"), select the **higher tier**. Scaling for the larger metric ensures your infrastructure can handle both the total data volume and the active processing load. +{: .important-title } + +If you don't know number of person records in your system, run the following SQL query against the `NBS_ODSE` database to provide the total: + +```sql +select count(*) from NBS_ODSE.dbo.Person +``` + +To generate a monthly cost estimate for your deployment scenario: + +1. Log in to [NBS Central](https://nbscentral.cdc.gov/) and download the latest **[NBS 7 Resource Estimator](https://nbscentral.cdc.gov/documents/872)**. +1. Identify the tab that matches your jurisdictional size. +1. Input the quantities and suggested SKUs from that tab into the AWS Pricing Calculator or Azure Pricing Calculator. + +{: .note } +Actual resource requirements vary based on data patterns, integration complexity, user activity, and reporting load. Monitoring actual utilization allows for configuration adjustments based on performance metrics. diff --git a/docs/before-you-deploy/choose-your-configuration/vendor-managed-deployment.md b/docs/before-you-deploy/choose-your-configuration/vendor-managed-deployment.md new file mode 100644 index 0000000..917df31 --- /dev/null +++ b/docs/before-you-deploy/choose-your-configuration/vendor-managed-deployment.md @@ -0,0 +1,35 @@ +--- +title: Vendor-managed deployment +layout: page +parent: Choose your configuration +grand_parent: Before you deploy +nav_order: 2 +description: Guidance for jurisdictions using a vendor to host or maintain NBS 7, including what to evaluate in a vendor and how to coordinate with CDC. +--- + +# Vendor-managed deployment +{: .no_toc } + +If you plan to use a vendor to host or maintain NBS 7, confirm that they can: + +- Deploy Kubernetes-based applications on AWS or Azure +- Manage Terraform-based infrastructure provisioning +- Support ongoing cloud infrastructure operations, including monitoring and incident response + +> NBS 7 is a recent system with limited deployment history. Do not expect vendors to have direct NBS 7 experience. Evaluate vendors on their Kubernetes and cloud infrastructure expertise instead. You can share the [component reference](../component-reference.html) section of this guide with vendors to help them scope the work accurately. +{: .important } + +Share the following with your vendor before scoping work: + +- The [component reference](../component-reference.html) section of this guide +- The **NBS 7 Migration Info Sheet** (available from CDC) +- Your current NBS 6 hosting setup and data volumes + +Then: + +1. Contact [nbs@cdc.gov](mailto:nbs@cdc.gov) to let CDC know you are planning a vendor-managed deployment and to access vendor coordination resources. +2. Work with your vendor to complete steps 4–8 of the [decision tree](decision-tree.html) to identify your recommended configuration tier. +3. Return to the [component reference](../component-reference.html) for the configuration parameters your vendor will need. + +> Vendors with Kubernetes and cloud infrastructure expertise can deploy NBS 7, but they will need detailed technical guidance from CDC and from this guide to do it accurately. Plan for a close working relationship between your vendor and the CDC NBS team, especially during initial deployment. Also plan for the funding needed to sustain vendor support beyond initial deployment. Ongoing maintenance costs are a common planning gap. Use the [NBS 7 Resource Estimator (NBS Central login required)](https://nbscentral.cdc.gov/documents/872) to support cloud cost projections. +{: .note } diff --git a/docs/before-you-deploy/compatibility.md b/docs/before-you-deploy/compatibility.md new file mode 100644 index 0000000..24fa30b --- /dev/null +++ b/docs/before-you-deploy/compatibility.md @@ -0,0 +1,32 @@ +--- +title: NBS 6 to 7 compatibility +layout: page +parent: Before you deploy +nav_order: 3 +nav_enabled: true +description: Lists the NBS 6 and NBS 7 version combinations that have been tested and verified to function correctly. +--- + +# NBS 6 and NBS 7 compatibility +{: .no_toc } + +NBS 7 integrates with and is tested against supported versions of NBS 6. Use this table to verify that your NBS 6 version is compatible with your target NBS 7 version before you begin deployment. Running the latest supported version of NBS 6 is recommended for migration. As of the most recent release, that version is **NBS 6.0.19.1**. + +The following table shows which NBS 6 versions have been tested and verified as compatible with each supported NBS 7 version. + +- **✓ Yes** - this version combination has been tested and verified to function correctly. +- **No** - compatibility for this version combination has not been established or verified. + +| NBS 7 version | 6.0.18 | 6.0.17 | 6.0.16.2 | 6.0.16.1 | 6.0.16 | +|:---|:---:|:---:|:---:|:---:|:---:| +| 7.11.1 | ✓ Yes | ✓ Yes | No | No | No | +| 7.10 | No | ✓ Yes | ✓ Yes | No | No | +| 7.9 | No | ✓ Yes | ✓ Yes | No | No | +| 7.8.1 | No | No | ✓ Yes | No | No | +| 7.8.0 | No | No | ✓ Yes | ✓ Yes | No | +| 7.7 | No | No | No | ✓ Yes | No | +| 7.6 | No | No | No | ✓ Yes | No | +| 7.5 | No | No | No | No | ✓ Yes | + +> This table reflects verified compatibility data as of the latest release of NBS 7.x. Compatibility data for versions not listed has not been established. +{: .note } diff --git a/docs/before-you-deploy/component-reference.md b/docs/before-you-deploy/component-reference.md new file mode 100644 index 0000000..53d22d4 --- /dev/null +++ b/docs/before-you-deploy/component-reference.md @@ -0,0 +1,47 @@ +--- +title: Component reference +layout: page +parent: Before you deploy +nav_order: 6 +has_children: true +description: Describes each NBS 7 component — what it does, when it is needed, and how it relates to other components — organized by NBS 7 core components and available add-ons. +--- + +# NBS 7 component reference +{: .no_toc } + +The pages in this section describe each component in NBS 7. Use it to understand what each component does, why it is included in your deployment, and how it relates to other components. + +Components in this reference are organized by deployment scope: + +- [NBS 7 core components](../before-you-deploy/component-reference/nbs-core-components.html) +- [Add-on: Real-Time Reporting (RTR)](../before-you-deploy/component-reference/rtr.html) +- [Add-on: Data Ingestion (DI) API](../before-you-deploy/component-reference/di-api.html) + +For deployment configuration details including configuration parameters, Helm chart values, and step-by-step setup instructions, see the [Deploy NBS 7](../deploy-nbs7.html) section of this guide. + +--- + +## Quick reference + +The following table shows which components are included in NBS 7 and its available add-ons. + +NBS 7 core components are required for all deployments. RTR and DI API are optional add-ons. Components for the add-ons are only required if your jurisdiction chooses to include them. + +| Component | NBS 7 | + RTR add-on | + DI API add-on | +|:---|:---:|:---:|:---:| +| [Legacy NBS 6](../before-you-deploy/component-reference/nbs-core-components.html#legacy-nbs-6) | ✓ | ✓ | ✓ | +| [NBS Modernization API](../before-you-deploy/component-reference/nbs-core-components.html#nbs-modernization-api) | ✓ | ✓ | ✓ | +| [NBS Web UI](../before-you-deploy/component-reference/nbs-core-components.html#nbs-web-ui) | ✓ | ✓ | ✓ | +| [NBS Gateway](../before-you-deploy/component-reference/nbs-core-components.html#nbs-gateway) | ✓ | ✓ | ✓ | +| [Elasticsearch](../before-you-deploy/component-reference/nbs-core-components.html#elasticsearch) | ✓ | ✓ | ✓ | +| [Nifi](../before-you-deploy/component-reference/nbs-core-components.html#nifi) | ✓ | ✓ | ✓ | +| [Keycloak](../before-you-deploy/component-reference/nbs-core-components.html#keycloak) | ✓ | ✓ | ✓ | +| [Database (NBS\_ODSE, NBS\_SRTE)](../before-you-deploy/component-reference/nbs-core-components.html#database-nbs_odse-nbs_srte) | ✓ | ✓ | ✓ | +| [Infrastructure and networking layer](../before-you-deploy/component-reference/nbs-core-components.html#infrastructure-and-networking-layer-components) | ✓ | ✓ | ✓ | +| [Debezium](../before-you-deploy/component-reference/rtr.html#debezium) | | ✓ | | +| [Kafka and Kafka Connect](../before-you-deploy/component-reference/rtr.html#kafka-and-kafka-connect) | | ✓* | | +| [RTR domain services](../before-you-deploy/component-reference/rtr.html#rtr-domain-services) | | ✓ | | +| [DI API](../before-you-deploy/component-reference/di-api.html#di-api) | | | ✓ | + +*Kafka and Kafka Connect are only required for near-real-time RTR reporting. Jurisdictions that deploy RTR but continue with batch reporting might not need Kafka. diff --git a/docs/before-you-deploy/component-reference/di-api.md b/docs/before-you-deploy/component-reference/di-api.md new file mode 100644 index 0000000..ad2b3d8 --- /dev/null +++ b/docs/before-you-deploy/component-reference/di-api.md @@ -0,0 +1,33 @@ +--- +title: "Add-on: Data Ingestion (DI) API" +layout: page +parent: Component reference +grand_parent: Before you deploy +nav_order: 3 +description: Details the Data Ingestion (DI) API add-on component, which provides a REST API layer for routing incoming data into NBS through middleware. +--- + +# Component reference: Data Ingestion (DI) API add-on + +The DI API is a REST API layer built into NBS 7 that accepts incoming public health data and routes it into NBS. Middleware such as Rhapsody or an equivalent integration engine preprocesses and formats the data, then sends it to the DI API instead of writing directly to the NBS database. + +For information on the relationship between the DI API and your existing middleware, see [Operational considerations](../../before-you-deploy/operational-considerations.html). +{: .note } + + + +## DI API + +A REST API layer that accepts incoming public health data in multiple formats and routes it into NBS. + +| Attribute | Description | +|:---|:---| +| What it does in NBS 7 | Accepts Electronic Case Reports (eCR), HL7 v2.x electronic lab reports (ELRs), and Public Health Document Container (PHDC) files through a standard API interface. Middleware preprocesses, enriches, and formats the data, then sends it to the DI API for ingestion into NBS. This supports near-real-time ingestion and gives jurisdictions an option when they do not want middleware or other third-party tools writing directly to the NBS database. | +| When you need it | Use the DI API add-on when your jurisdiction needs an API-based ingestion path instead of direct database access. This is especially useful for jurisdictions with security constraints that prevent middleware from connecting directly to the NBS database. | +| Dependencies | Requires middleware such as Rhapsody or an equivalent integration engine. External senders such as laboratories, EHR systems, and health information exchanges continue to send data through middleware, which then sends the processed payload to the DI API. | diff --git a/docs/before-you-deploy/component-reference/nbs-core-components.md b/docs/before-you-deploy/component-reference/nbs-core-components.md new file mode 100644 index 0000000..41ca7d2 --- /dev/null +++ b/docs/before-you-deploy/component-reference/nbs-core-components.md @@ -0,0 +1,142 @@ +--- +title: NBS 7 core components +layout: page +parent: Component reference +grand_parent: Before you deploy +nav_order: 1 +description: Details each component in NBS 7 — the application, infrastructure, and networking layers required for all NBS 7 deployments. +--- + +# Component reference: NBS 7 core components +{: .no_toc } + +For information on migration planning, staffing, and budget, see [Operational considerations](../../before-you-deploy/operational-considerations.html). +{: .note } + +NBS 7 core components are organized into three layers: the application layer, the infrastructure layer, and the networking layer. The application layer components are documented individually below. [Infrastructure and networking layer components](#infrastructure-and-networking-layer-components) are summarized as a group. + +\[architecture diagram\] + +## On this page +{: .no_toc .text-delta } + +1. TOC +{:toc} + +> The NBS Modernization API, NBS Web UI, and NBS Gateway are deployed together from the [NEDSS-Modernization](https://github.com/CDCgov/NEDSS-Modernization) repository. Each serves a distinct function, but vendors and admins scoping deployment work should be aware that they share a single deployment unit. +{: .important } + +## Legacy NBS 6 + +The existing NBS 6 application. A WildFly-based UI and backend that most STLTs currently run. + +| Attribute | Description | +|:---|:---| +| What it does in NBS 7 | NBS Core does not replace NBS 6 immediately. Instead, it runs alongside it. During migration, the NBS Gateway routes requests between the legacy NBS 6 application and new NBS 7 services. NBS 6 continues to handle all functionality that has not yet been replaced by a modern NBS 7 equivalent. | +| When you need it | Always. An operational NBS 6 instance is a prerequisite for any NBS 7 deployment. You must be running a [compatible NBS 6 version](../../before-you-deploy/compatibility.html) before you can install NBS 7. | +| Dependencies | Required by NBS Gateway, Elasticsearch (via Nifi), and the NBS Modernization API. Must maintain network connectivity to your NBS 7 environment throughout the migration period. | + +## NBS Modernization API + +The modern backend API layer for NBS 7, built to replace NBS 6 functionality incrementally. + +| Attribute | Description | +|:---|:---| +| What it does in NBS 7 | Provides modernized versions of core NBS features including patient search, event search, patient profile, and investigation management. As NBS 7 development progresses, additional NBS 6 features will migrate into this API layer. | +| When you need it | Always. The Modernization API is a core component of NBS 7 and is required for all configurations. | +| Dependencies | Requires Legacy NBS 6 and NBS Gateway. Exposes functionality to the NBS Web UI. | + +## NBS Web UI + +The modern React/TypeScript frontend for NBS 7 features. + +| Attribute | Description | +|:---|:---| +| What it does in NBS 7 | Provides the user interface for modernized NBS 7 functionality. STLT users see a composite interface. Some screens are served by the new NBS Web UI, while others continue to be served by the legacy NBS 6 UI. The NBS Gateway manages which interface handles each request. | +| When you need it | Always. The NBS Web UI is a core component of NBS 7 and is required for all configurations. | +| Dependencies | Requires NBS Gateway and the NBS Modernization API. | + +## NBS Gateway + +A routing service (built on Spring Cloud Gateway) that manages traffic between the legacy NBS 6 application and modern NBS 7 services. + +| Attribute | Description | +|:---|:---| +| What it does in NBS 7 | Implements the strangler fig pattern by routing requests based on path. Requests for modernized features (such as patient search) go to NBS 7 services. All other requests go to Legacy NBS 6. This routing layer is what allows NBS 6 and NBS 7 to run simultaneously during migration without users needing to switch between systems. | +| When you need it | Always. NBS Gateway is a core component of NBS 7 and is required for all configurations. | +| Dependencies | Requires Legacy NBS 6, the NBS Modernization API, and the NBS Web UI. Sits behind the infrastructure layer ingress controller. | + + + +## Elasticsearch + +An open-source search and analytics engine optimized for speed and scalability. + +| Attribute | Description | +|:---|:---| +| What it does in NBS 7 | Powers real-time patient and event search in NBS 7. NBS 6 requires batch processing before search results can reflect recent data, so this is a key improvement. [Nifi](#nifi) populates Elasticsearch indices from the NBS database. | +| When you need it | Always. Elasticsearch is a core component of NBS 7 and is required for all configurations. | +| Dependencies | Requires Nifi to populate its indices from the NBS database. Search functionality in the NBS Web UI and Modernization API depends on Elasticsearch. | + +## Nifi + +An open-source data flow automation tool for moving and transforming data between systems. + +| Attribute | Description | +|:---|:---| +| What it does in NBS 7 | Continuously moves data from the NBS database into Elasticsearch, keeping search indices current. Without Nifi, Elasticsearch indices would not reflect recent changes to patient and investigation records. | +| When you need it | Always. Nifi is a core component of NBS 7 and is required for all configurations. | +| Dependencies | Requires the NBS database (NBS\_ODSE) as its data source and Elasticsearch as its destination. | + +## Keycloak + +An open-source identity and access management platform. + +| Attribute | Description | +|:---|:---| +| What it does in NBS 7 | Handles authentication for NBS 7, including token management and single sign-on (SSO) integration. Keycloak supports OAuth and SAML, which means your jurisdiction can integrate NBS 7 with an existing identity provider such as Okta or Active Directory Federation Services (ADFS) rather than managing a separate set of NBS credentials. | +| When you need it | Always. Keycloak is a core component of NBS 7 and is required for all configurations. | +| Dependencies | Requires network access to your identity provider if you are integrating with an existing SSO system. All NBS 7 services that require authentication depend on Keycloak. | + +> Health department leaders +> +> For guidance on Single Sign-On planning and early coordination requirements, see [Operational considerations](../../before-you-deploy/operational-considerations.html). +{: .note-title } + +## Database (NBS\_ODSE, NBS\_SRTE) + +The core SQL Server databases that store operational and reference data for NBS. + +| Attribute | Description | +|:---|:---| +| What it does in NBS 7 | NBS\_ODSE (Operational Data Store) is the primary transactional database where case, patient, investigation, and event records are stored. NBS\_SRTE (System Reference Tables) stores reference and metadata used across NBS, including LOINC, SNOMED CT, and other code sets used for data validation and mapping. | +| When you need it | Always. Both databases are required for all NBS 7 configurations. | +| Dependencies | Required by Legacy NBS 6, the Modernization API, Nifi, Debezium (if using RTR), and the DI API (if using the DI API add-on). | + +## Infrastructure and networking layer components + +The following components make up the infrastructure and networking layers of NBS 7. They are provisioned and managed primarily through Terraform and Helm, and most do not require configuration decisions from IT admins during the planning phase. They are documented here for awareness. + +Full configuration guidance is in the [Deploy NBS 7](../../deploy-nbs7.html) section of this guide. + +| Component | What it does in NBS 7 | +|:---|:---| +| Kubernetes (EKS/AKS) | Container orchestration platform that hosts and manages all NBS 7 services. EKS is used on AWS; AKS is used on Azure. | +| Traefik Ingress Controller | Manages inbound traffic routing into the Kubernetes cluster. Traefik replaced NGINX as of the NBS 7.12 release. | +| Terraform modules | Infrastructure-as-code tooling that provisions your cloud environment, including VPC, Kubernetes cluster, storage, and managed services. Four modules cover network/VPC, NBS 6 database layer, NBS 7 cluster, and application services. | +| Cert Manager | Automates provisioning and renewal of TLS/SSL certificates for encrypted traffic within and into the NBS 7 environment. | +| FluentBit | Lightweight log forwarding agent that collects and routes logs from NBS 7 services for monitoring and troubleshooting. | +| Linkerd | Service mesh (provisioned via Terraform) that manages encrypted communication between NBS 7 services inside the Kubernetes cluster. | +| DNS (Route 53 or equivalent) | Routes user traffic to your NBS 7 environment. On AWS, Route 53 is the standard option; Azure and on-premises DNS services are also supported. | diff --git a/docs/before-you-deploy/component-reference/rtr.md b/docs/before-you-deploy/component-reference/rtr.md new file mode 100644 index 0000000..e4c0587 --- /dev/null +++ b/docs/before-you-deploy/component-reference/rtr.md @@ -0,0 +1,69 @@ +--- +title: "Add-on: Real-Time Reporting (RTR)" +layout: page +parent: Component reference +grand_parent: Before you deploy +nav_order: 2 +description: "Details the four components added by the Real-Time Reporting (RTR) add-on: Debezium, Kafka, RTR domain services, and RDB_Modern." +nav_enabled: true +--- + +# Component reference: Real-Time Reporting (RTR) add-on + +RTR is an optional add-on that provides an event-driven reporting pipeline for near-real-time reporting. RTR replaces the legacy MasterETL batch process. During validation, both might run briefly in parallel to confirm that RTR output is accurate. Once validation is complete, plan to retire MasterETL. + +The following components are added to your NBS 7 deployment when you choose to deploy the RTR add-on. + +For information on benefits and impact on operating costs, see [Operational considerations](../../before-you-deploy/operational-considerations.html). +{: .note } + +## On this page +{: .no_toc .text-delta } + +1. TOC +{:toc} + +## Debezium + +An open-source Change Data Capture (CDC) platform. + +| Attribute | Description | +|:---|:---| +| What it does in NBS 7 | Monitors the NBS database for changes in real time and streams those changes to Kafka as they occur. Debezium is the entry point for the RTR pipeline. Without it, downstream RTR components have no data to process. | +| Dependencies | Requires the NBS database (NBS\_ODSE) as its source. Streams data to the Kafka cluster. | + +## Kafka and Kafka Connect + +Apache Kafka is an open-source event-streaming platform. Kafka Connect is the framework that moves data between Kafka and other systems. + +If your jurisdiction chooses to use RTR but continue with batch reporting, Kafka is not required for that reporting path. Only near-real-time RTR reporting requires Kafka and Kafka Connect. +{: .note } + +| Attribute | Description | +|:---|:---| +| What it does in NBS 7 | Acts as the message bus for the RTR pipeline. Kafka receives change events from Debezium and delivers them to the RTR domain services. Kafka Connect writes the processed output to RDB\_Modern staging tables for post-processing and reporting. | +| Dependencies | Receives events from Debezium. Delivers messages to RTR domain services. Kafka Connect writes processed data to RDB\_Modern. Requires sufficient cluster resources; Kafka is one of the more operationally demanding components in the RTR stack. | + +## RTR domain services + +A unified Spring Boot service that transforms streaming data from Kafka into reportable public health records. Previously implemented as five separate entity-specific services (investigation, person, observation, organization, and LDF data), NBS 7 consolidates the services into a single `reporting-pipeline-service` application to reduce deployment complexity and operational overhead. + +| Attribute | Description | +|:---|:---| +| What it does in NBS 7 | Consumes Kafka messages for each entity type (investigations, patients, organizations, observations, and LDF data), runs stored procedures to retrieve and format the data, and produces processed records for downstream storage in RDB\_Modern. A post-processing service then populates analytical datamarts and fact tables from the staging data. | +| Dependencies | Requires Kafka (message source) and NBS\_ODSE (operational data store). Populates RDB\_Modern staging tables, which are then consumed by the post-processing service. | + +> The five entity-specific RTR services (investigation-service, person-service, observation-service, organization-service, ldfdata-service) are being consolidated into a single `reporting-pipeline-service` as of early 2026. Check with your CDC NBS point of contact for the current deployment state. +{: .note } + + diff --git a/docs/before-you-deploy/deployment-phases.md b/docs/before-you-deploy/deployment-phases.md new file mode 100644 index 0000000..0404edf --- /dev/null +++ b/docs/before-you-deploy/deployment-phases.md @@ -0,0 +1,111 @@ +--- +title: Deployment overview +layout: page +parent: Before you deploy +nav_order: 1 +description: An overview of the five phases involved in an NBS 7 deployment, from planning through steady state operations. +--- + +# Deployment overview + +NBS 7 deployments vary significantly by jurisdiction. If you are just getting started, this page can help you understand where the [Assess your readiness](assess-your-readiness.html) checklist fits in the overall process. + + + +## Example deployment phases + +The phases in this table represent an example rollout scenario based on deployments to date. Your jurisdiction's timeline, activities, and sequence might differ depending on your infrastructure, staffing, and security requirements. For more information, see [Operational considerations](../before-you-deploy/operational-considerations.html). + +| Phase | Goal | Minimum duration | +|:---|:---|:---| +| [Planning](#planning) | Establish your project team, [assess your readiness](assess-your-readiness.html), and create a customized migration plan | 2-5 months | +| [Install](#install) | Provision cloud environments and deploy NBS 7 based on your [chosen configuration](choose-your-configuration.html) | 3-6 months | +| [Test](#test) | Validate ingestion, egress, and system readiness before go-live | 3-6 months | +| [Go-live](#go-live) | Complete cutover and launch NBS 7 in production | 1-4 months | +| [Steady state](#steady-state) | Monitor live operations and maintain the system ongoing | Ongoing | + +{: .note } +These are minimum estimates based on typical deployments. Actual timelines vary by jurisdiction. Security approval, procurement, and legal review processes are common sources of extended timelines in the Planning and Install phases. + +For detailed checklists and deliverables for each phase, see the [NBS 7 Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) on NBS Central. + +--- + +## Planning + +The Planning phase covers discovery, environment setup, and project preparation. Security approval for cloud hosting and required technologies including Kubernetes, Terraform, and Docker is frequently the longest-lead item in this phase and the most common source of delay across the entire deployment. Starting that process early tends to reduce overall deployment time. + +Before planning detailed timelines, confirm that your current NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html). + +| Activity | Description | Resource | +|:---|:---|:---| +| Readiness check-in | Initial planning and review of frequently asked questions. See [Assess your readiness](../before-you-deploy/assess-your-readiness.html) for the technical checklist and [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html) for version alignment. | [Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) | +| Identify project team | Define roles, responsibilities, and key stakeholders. See [Operational considerations](../before-you-deploy/operational-considerations.html) for staffing guidance | [Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) | +| NBS 7 orientation | Review NBS 7 features with your migration team. See [Component reference](../before-you-deploy/component-reference.html) for a full component overview | [Choose your configuration](../before-you-deploy/choose-your-configuration.html) | +| Create project plan | Draft a customized migration plan from the playbook checklists, including a migration risk registry | [Deployment scenarios](../before-you-deploy/deployment-scenarios.html) | +| Communications plan | Develop and implement a communications plan customized to your timeline and needs | Communications plan | +| Training plan | Implement an NBS 7 training plan customized for your jurisdiction | STLT user training plan | +| Draft test plan | Customize a UAT plan for your requirements | STLT user acceptance test plan | + +--- + +## Install + +The Install phase covers provisioning your cloud environments and deploying NBS 7 across development, staging, and production. This phase has a dependency on security approval processes, which might extend the timeline. + +| Activity | Description | Resource | +|:---|:---|:---| +| Data migration plan | Agree on and review the data migration plan, coordinate the data migration solution and test files | [Assess your readiness: Data migration](../before-you-deploy/assess-your-readiness.html#data-migration) | +| Dev environment deployment | Create and deploy an initial NBS 7 development environment build | [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html) | +| Staging environment deployment | Create and deploy an initial NBS 7 test environment build | [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html) | +| Production environment deployment | Create and deploy an initial NBS 7 production environment build | [Deploy NBS 7 microservices](../deploy-nbs7/deploy-nbs7-microservices.html) | +| Complete database transfer | Complete customizations, user file sharing setup, and integration with your user management system | STLT database refresh procedure | +| Roles and permissions migration | Map user roles and configure permissions in NBS 7 | User migration mapping | +| SSO setup | Review state SSO and login requirements and integrate Keycloak with your existing login tools. See [Operational considerations](../before-you-deploy/operational-considerations.html) for SSO planning guidance | [Enable Keycloak authentication](../deploy-nbs7/keycloak/enable-keycloak-auth.html) | + +--- + +## Test + +The Test phase validates that your NBS 7 environment is ready for production use. This phase also has a dependency on security processes and might run concurrently with some Install activities. + +| Activity | Description | Resource | +|:---|:---|:---| +| Database restore process | Review and test the database restore process in the development environment | STLT database refresh procedure | +| Ingestion and egress validation | Integrate and validate data ingestion and notification pathways to confirm pipelines | [Data ingestion API testing](../deploy-nbs7/microservices-deployment/data-ingestion/api-testing.html) if you are using the DI API | +| ELR and or eCR ingestion testing | Test ingestion for individual ELRs and eCRs and at scale | [Data ingestion smoke test](../deploy-nbs7/microservices-deployment/data-ingestion/smoke-test.html) | +| Notifications testing | Coordinate with the MVPs team to validate notifications readiness | Conditions received successfully | +| Regression testing | Run test scripts across environments to validate readiness for UAT | [Validate the deployment](../deploy-nbs7/validate-the-deployment.html) | +| Cutover and rollback review | Review and approve cutover and rollback plans | Cutover and Rollback Plan | +| UAT | Complete the agreed UAT plan across dev, test, and production environments | UAT test plan | + +--- + +## Go-live + +The Go-live phase covers final preparation, cutover, and launch. This phase is shorter than the others but involves time-sensitive coordination across your team. In many jurisdictions, this cutover follows work in a separate migration environment rather than direct changes on the primary NBS 6 production server. + +| Activity | Description | Resource | +|:---|:---|:---| +| NBS 7 training | Perform scheduled training sessions and share materials with end users | [NBS Visual Reference Guide](https://nbscentral.cdc.gov/documents/863) - NBS Central login required | +| Go/no-go decision | Make the final go-live decision and schedule the cutover date | - | +| Lock database and refresh | Freeze the database backup and finalize the cutover checklist | STLT production cut-over checklist | +| Go-live day | Complete the cutover checklist and launch NBS 7 | - | + +--- + +## Steady state + +After go-live, your jurisdiction enters steady state operations. This phase is ongoing and includes monitoring, support, and periodic upgrades as new NBS 7 releases become available. + +| Activity | Description | Resource | +|:---|:---|:---| +| Monitor live operations | Stand up long-term NBS 7 service desk support, review the NBS Administrator Guide for NBS support SOP, and track system performance | [Support](../deploy-nbs7/support.html) | +| Complete retrospective | Conduct a go-live retrospective to capture lessons learned | - | +| Upgrade to new releases | Test and upgrade to new NBS 7 releases periodically | [Maintain NBS 7](../maintain-nbs7.html) | diff --git a/docs/before-you-deploy/deployment-scenarios.md b/docs/before-you-deploy/deployment-scenarios.md new file mode 100644 index 0000000..a84f89f --- /dev/null +++ b/docs/before-you-deploy/deployment-scenarios.md @@ -0,0 +1,14 @@ +--- +title: Deployment scenarios +layout: page +parent: Before you deploy +nav_order: 5 +has_children: true +description: Presents example NBS 7 deployment scenarios for small, medium, and large jurisdictions to illustrate configuration tradeoffs and real-world decisions. +--- + +# Deployment scenarios + +The pages in this section cover actual NBS 7 deployment scenarios as example use cases. No two jurisdictions have identical infrastructure, staffing, or data needs, so your configuration will not match any of these exactly. Use the examples to identify which profile is closest to your situation and to understand the tradeoffs that other jurisdictions encountered. + +After you have chosen your configuration, use the [**Deploy NBS 7**](../deploy-nbs7.html) guide for step-by-step deployment instructions. diff --git a/docs/before-you-deploy/deployment-scenarios/large-jurisdiction.md b/docs/before-you-deploy/deployment-scenarios/large-jurisdiction.md new file mode 100644 index 0000000..6982dfd --- /dev/null +++ b/docs/before-you-deploy/deployment-scenarios/large-jurisdiction.md @@ -0,0 +1,55 @@ +--- +title: Large jurisdiction, vendor-managed cloud +layout: page +parent: Deployment scenarios +grand_parent: Before you deploy +nav_order: 3 +description: Case study for a large, vendor-managed NBS Complete deployment at enterprise scale, covering high-availability and advanced configuration decisions. +--- + +## Case study: Large jurisdiction, high volume, vendor-managed + +*Based on an enterprise-scale deployment.* + +1. TOC +{:toc} + +--- + +### Profile + +Large STLT with high case volumes, sophisticated analytics needs, and a vendor-managed infrastructure model. This jurisdiction required high-availability configuration and advanced security hardening. + +### Configuration + +| Deployment model | Hosting | +|:---|:---| +| NBS 7 + RTR + DI API | Cloud vendor-managed, or hybrid with significant cloud presence | + +### What was deployed + +| Component | Included | Notes | +|:---|:---|:---| +| NBS 7 | Yes | Full core deployment | +| Real-Time Reporting (RTR) | Yes | Required for high case volume and analytics needs | +| DI API | Yes | Primary path for ELR and eCR ingestion | + + + +> Best for +> +> Might apply to jurisdictions that have a large IT team or vendor support, high case volumes, advanced reporting or analytics needs, and require high-availability infrastructure. +{: .note-title } diff --git a/docs/before-you-deploy/deployment-scenarios/medium-jurisdiction.md b/docs/before-you-deploy/deployment-scenarios/medium-jurisdiction.md new file mode 100644 index 0000000..330e150 --- /dev/null +++ b/docs/before-you-deploy/deployment-scenarios/medium-jurisdiction.md @@ -0,0 +1,55 @@ +--- +title: Medium jurisdiction, hybrid hosting +layout: page +parent: Deployment scenarios +grand_parent: Before you deploy +nav_order: 2 +description: Case study for a medium jurisdiction with existing Rhapsody middleware deploying NBS Core + RTR, based on Kentucky's experience. +--- + +## Case study: Medium jurisdiction, existing middleware, RTR + +*Based on Kentucky's deployment.* + +1. TOC +{:toc} + +--- + +### Profile + +Medium STLT with an existing Rhapsody middleware investment and a need for faster data turnaround than NBS 6 batch processing provides. The jurisdiction retained Rhapsody for data ingestion. + +### Configuration + +| Deployment model | Hosting | +|:---|:---| +| NBS 7 + RTR | Hybrid: cloud-hosted NBS 7, on-premises Rhapsody middleware | + +### What was deployed + +| Component | Included | Notes | +|:---|:---|:---| +| NBS 7 | Yes | Full core deployment | +| Real-Time Reporting (RTR) | Yes | Added for faster reporting turnaround | +| DI API | No | Rhapsody for data ingestion | + + + +> Best for +> +> Might apply to jurisdictions that have existing middleware such as Rhapsody or Mirth Connect that you want to retain, and you need faster reporting turnaround than NBS 6 provides. +{: .note-title } diff --git a/docs/before-you-deploy/deployment-scenarios/small-jurisdiction.md b/docs/before-you-deploy/deployment-scenarios/small-jurisdiction.md new file mode 100644 index 0000000..f75dd1b --- /dev/null +++ b/docs/before-you-deploy/deployment-scenarios/small-jurisdiction.md @@ -0,0 +1,54 @@ +--- +title: Small jurisdiction, self-managed cloud +layout: page +parent: Deployment scenarios +grand_parent: Before you deploy +nav_order: 1 +description: Case study for a small, self-managed AWS deployment based on Montana's experience, covering configuration choices and lessons learned. +--- + +## Case study: Small jurisdiction, self-managed, AWS + +*Based on Montana's deployment.* + +1. TOC +{:toc} + +--- + +### Profile + +Small STLT with limited IT staff and a cloud-first infrastructure strategy. The jurisdiction prioritized simplicity and maintainability over add-on features. + +### Configuration + +| Deployment model | Hosting | +|:---|:---| +| NBS core components only | AWS, STLT-managed | + +### What was deployed + +| Component | Included | Notes | +|:---|:---|:---| +| NBS 7 | Yes | Full core deployment | +| Real-Time Reporting (RTR) | No | Not required at this case volume | +| DI API | No | No existing high-volume ELR or eCR intake | + + + +> Best for +> +> Might apply to jurisdictions that have a small IT team, limited cloud experience, or a goal to get NBS 7 running with minimal complexity before adding advanced features. +{: .note-title } diff --git a/docs/before-you-deploy/operational-considerations.md b/docs/before-you-deploy/operational-considerations.md new file mode 100644 index 0000000..bce82ba --- /dev/null +++ b/docs/before-you-deploy/operational-considerations.md @@ -0,0 +1,80 @@ +--- +title: Operational considerations +layout: page +parent: Before you deploy +nav_order: 0 +description: Summarizes organizational, financial, and operational factors that affect NBS 7 migration planning. +redirect_from: + - /docs/before-you-deploy/operational_considerations.html + - /docs/before-you-deploy/operational_considerations/ +--- + +# Operational considerations + +This page covers organizational, financial, and operational factors that affect NBS 7 migration planning. Some of these factors involve decisions or timelines that extend beyond the technical team and might be worth raising with others in your organization early in your planning process. + +## On this page +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +For technical deployment guidance, refer to [Assess your readiness](../before-you-deploy/assess-your-readiness.html) and the rest of this guide. + +## Migration is gradual, not a cutover + +NBS 7 does not replace NBS 6 in a single switch. Both systems run in parallel during the transition. NBS 7 components gradually take over functionality while NBS 6 continues to operate. The length of this parallel period depends on your jurisdiction's pace of deployment and configuration choices. Planning for the operational complexity and cost of maintaining two systems simultaneously is an integral part of migration preparation. Many jurisdictions provision a separate NBS 6 environment for migration activities and then cut over, rather than making these changes directly on their primary NBS 6 production server. + +See also: [Deployment phases](../before-you-deploy/deployment-phases.html) and [Deployment scenarios](../before-you-deploy/deployment-scenarios.html). + +Version prerequisite: confirm your NBS 6 baseline against the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html) before you finalize migration timelines. + +## State IT security approval takes time + +State IT security approval is often the longest-lead item in an NBS 7 migration. NBS 7 requires approval for cloud hosting and specific technologies including Kubernetes, Terraform, and Docker. Because NBS handles PII and PHI, state IT review is often required even when a vendor manages parts of the deployment. Jurisdictions that start this process early, even when deployment is still months away, might avoid one of the most common causes of migration delays. + +See also: [Assess your readiness](../before-you-deploy/assess-your-readiness.html), [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html), and [Deploy cloud infrastructure on AWS](../deploy-nbs7/deploy-on-aws.html) or [Deploy cloud infrastructure on Azure](../deploy-nbs7/deploy-on-azure.html). + +## Cloud infrastructure requires ongoing budget + +CDC does not support on-premises installations of NBS 7. Your jurisdiction needs an active cloud account (AWS or Azure) and an ongoing budget to sustain cloud infrastructure costs. Cloud hosting costs scale with usage, so budget planning might account for both normal operations and surge scenarios such as outbreak response. Use the [NBS 7 Resource Estimator (NBS Central login required)](https://nbscentral.cdc.gov/documents/872) to project cloud-hosting costs based on your jurisdiction's record volume. + +See also: [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html) and [Deployment scenarios](../before-you-deploy/deployment-scenarios.html). + +## Align cloud provider with jurisdictional strategy + +NBS 7 is fully supported on both Amazon Web Services (AWS) and Microsoft Azure. While the internal microservices and deployment steps are identical across platforms, the initial environment setup depends on your jurisdiction's existing infrastructure and procurement path. + +Choose the provider that best aligns with your organization's current operational state: + +- **Existing Infrastructure:** If your jurisdiction currently runs NBS 6 or other critical systems on a specific cloud platform, remaining on that platform avoids the need for new IT security approvals. +- **Contractual Agreements:** Utilize existing Enterprise Agreements or pre-approved cloud spending to streamline procurement. +- **Staff Expertise:** Align the choice with the existing skills of your cloud engineering or IT administration teams. + +See also: [Assess your readiness > Cloud infrastructure](assess-your-readiness.html/#cloud-infrastructure). + +## Technical staffing requirements differ from NBS 6 + +Migrating to NBS 7 involves skills that might differ from what your current NBS 6 team uses, including Kubernetes, Terraform, and cloud infrastructure management. Jurisdictions that assess their team's capacity early are poised to set more accurate migration timelines. Those without the necessary in-house expertise have typically built capacity or engaged a vendor before deployment. + +See also: [Assess your readiness](../before-you-deploy/assess-your-readiness.html) and [Vendor-managed deployment](../before-you-deploy/choose-your-configuration/vendor-managed-deployment.html). + +## Real-Time Reporting adds capability and cost + +The Real-Time Reporting (RTR) add-on reduces the time for data to appear in reports from up to 24 hours to between 5 minutes and 1 hour. For jurisdictions managing active outbreaks or time-sensitive disease investigations, this improvement can meaningfully affect response time. RTR also adds infrastructure complexity and requires additional cloud resources. The reporting speed benefit and the additional operating cost are both worth weighing against your jurisdiction's case volume and reporting needs. + +See also: [RTR component reference](../before-you-deploy/component-reference/rtr.html), [Real-time reporting deployment](../deploy-nbs7/real-time-reporting/real-time-reporting.html), and [Choose your configuration](../before-you-deploy/choose-your-configuration.html). + +## The Data Ingestion API adds a secure integration option + +The Data Ingestion (DI) API is a built-in REST API layer that accepts lab reports and case reports through middleware rather than through direct database access. It does not replace middleware such as Rhapsody or Mirth Connect. Instead, it gives jurisdictions an API-based ingestion path, which is especially useful when security constraints prevent middleware or other third-party tools from connecting directly to the NBS database. Jurisdictions that do not already have middleware will still need it before they can use the DI API. + +See also: [DI API component reference](../before-you-deploy/component-reference/di-api.html) and [Data ingestion microservice](../deploy-nbs7/microservices-deployment/data-ingestion.html). + +## Single Sign-On requires early coordination + +NBS 7 uses Keycloak for identity management. If your jurisdiction uses a centralized identity provider such as Okta or Active Directory, Keycloak can integrate with it, allowing NBS 7 users to log in with their existing jurisdiction credentials. This integration requires coordination between your NBS deployment team and your identity provider administrators. We recommend that you start that coordination early rather than addressing it later in the deployment process. + +See also: [Keycloak installation](../deploy-nbs7/keycloak/keycloak-installation.html) and [Enable Keycloak authentication](../deploy-nbs7/keycloak/enable-keycloak-auth.html). diff --git a/docs/deploy-nbs7/real-time-reporting/permissions.md b/docs/deploy-nbs7/real-time-reporting/permissions.md new file mode 100644 index 0000000..33aaa3a --- /dev/null +++ b/docs/deploy-nbs7/real-time-reporting/permissions.md @@ -0,0 +1,185 @@ +--- +title: Service permissions +layout: page +parent: Real-time reporting (preview) +nav_order: 5 +description: Reference matrix for real-time reporting service roles and required database permissions. +--- + +# RTR service permissions + +This page provides a reference matrix for real-time reporting roles and required permissions. + +## On this page +{: .no_toc .text-delta } + +1. TOC +{:toc} + +## User permissions by service + +Each RTR microservice connects to one or more NBS databases using a dedicated SQL login. The following tables list required permissions grouped by service. + +Jump to service: + +- [Liquibase service](#liquibase) +- [Organization service](#organization) +- [Observation service](#observation) +- [Person service](#person) +- [Investigation service](#investigation) +- [LDF service](#ldf) +- [Post Processing service](#post-processing) +- [Kafka Sync service](#kafka-sync) +- [Debezium service](#debezium) + +### Liquibase + +Liquibase requires elevated permissions during initial onboarding to create service users and enable Change Data Capture (CDC). After onboarding is complete, Liquibase continues to run migration scripts with the same login. + +| Database | Permissions | SQL Login | +|---|---|---| +| `master` | `setupadmin`, `processadmin`, `ALTER ANY CREDENTIAL`, `ALTER ANY LOGIN`, `CREATE ANY DATABASE`, `VIEW SERVER STATE`
**AWS RDS only:** `SELECT` on `msdb.dbo.sysjobs`, `EXECUTE` on `msdb.dbo.rds_cdc_enable_db`, `EXECUTE` on `msdb.dbo.rds_cdc_disable_db`
**On-premises or Azure only:** `ALTER SERVER ROLE`, `EXECUTE` on `sys.sp_cdc_enable_db`, `EXECUTE` on `sys.sp_cdc_disable_db` | `db_deploy_admin` | +| `NBS_ODSE` | `db_owner` | `db_deploy_admin` | +| `NBS_SRTE` | `db_owner` | `db_deploy_admin` | +| `NBS_MSGOUTE` | `db_owner` | `db_deploy_admin` | +| `RDB` | `db_owner` | `db_deploy_admin` | +| `rdb_modern` | `db_owner` | `db_deploy_admin` | + +### Organization + +The Organization service queries organization data and related context from `NBS_ODSE` and writes it to the Kafka broker. + +| Database | Permissions | SQL Login | +|---|---|---| +| `NBS_ODSE` | `db_datareader`, `EXECUTE sp_organization_event`, `EXECUTE sp_place_event` | `organization_service_rdb` | +| `NBS_SRTE` | `db_datareader` | `organization_service_rdb` | +| `RDB` | `public`, `INSERT` on `job_flow_log` | `organization_service_rdb` | +| `rdb_modern` | `public`, `INSERT` on `job_flow_log` | `organization_service_rdb` | + +### Observation + +The Observation service queries observation data and related context from `NBS_ODSE` and writes it to the Kafka broker. + +| Database | Permissions | SQL Login | +|---|---|---| +| `NBS_ODSE` | `db_datareader`, `EXECUTE sp_observation_event` | `observation_service_rdb` | +| `NBS_SRTE` | `db_datareader` | `observation_service_rdb` | +| `RDB` | `public`, `INSERT` on `job_flow_log` | `observation_service_rdb` | +| `rdb_modern` | `public`, `INSERT` on `job_flow_log` | `observation_service_rdb` | + +### Person + +The Person service queries person data and related context from `NBS_ODSE` and writes it to the Kafka broker. + +| Database | Permissions | SQL Login | +|---|---|---| +| `NBS_ODSE` | `db_datareader`, `EXECUTE sp_patient_event`, `EXECUTE sp_patient_race_event`, `EXECUTE sp_provider_event`, `EXECUTE sp_auth_user_event` | `person_service_rdb` | +| `NBS_SRTE` | `db_datareader` | `person_service_rdb` | +| `RDB` | `public`, `INSERT` on `job_flow_log` | `person_service_rdb` | +| `rdb_modern` | `public`, `INSERT` on `job_flow_log` | `person_service_rdb` | + +### Investigation + +The Investigation service queries case data and related context from `NBS_ODSE` and writes it to the Kafka broker. It also updates `publichealthcasefact` datamart tables, which was previously performed by the `PHCmartETL.bat` job. + +| Database | Permissions | SQL Login | +|---|---|---| +| `NBS_ODSE` | `db_datareader`, `db_datawriter` | `investigation_service_rdb` | +| `NBS_SRTE` | `db_datareader` | `investigation_service_rdb` | +| `RDB` | `db_datareader`, `db_datawriter` | `investigation_service_rdb` | +| `rdb_modern` | `db_datareader`, `db_datawriter` | `investigation_service_rdb` | + +### LDF + +The LDF service queries locally defined field (LDF) data and related context from `NBS_ODSE` and writes it to the Kafka broker. + +| Database | Permissions | SQL Login | +|---|---|---| +| `NBS_ODSE` | `db_datareader`, `EXECUTE sp_ldf_data_event`, `EXECUTE sp_ldf_patient_event`, `EXECUTE sp_ldf_provider_event`, `EXECUTE sp_ldf_organization_event`, `EXECUTE sp_ldf_observation_event`, `EXECUTE sp_ldf_phc_event`, `EXECUTE sp_ldf_intervention_event` | `ldf_service_rdb` | +| `NBS_SRTE` | `db_datareader` | `ldf_service_rdb` | +| `RDB` | `public`, `INSERT` on `job_flow_log` | `ldf_service_rdb` | +| `rdb_modern` | `db_datareader`, `INSERT` on `job_flow_log` | `ldf_service_rdb` | + +### Post Processing + +The Post Processing service listens for completion events from upstream RTR services and executes stored procedures to update fact, dimension, and datamart tables with data from the `nrt` staging tables. It requires access to either `RDB` or `rdb_modern` depending on your deployment stage. Use `RDB` if you are live with RTR, or `rdb_modern` if you are evaluating or testing RTR deployment. + +| Database | Permissions | SQL Login | +|---|---|---| +| `NBS_ODSE` | `db_datareader` | `post_processing_service_rdb` | +| `NBS_SRTE` | `db_datareader` | `post_processing_service_rdb` | +| `RDB` (production RTR only) | `db_owner` | `post_processing_service_rdb` | +| `rdb_modern` (dev RTR only) | `db_owner` | `post_processing_service_rdb` | + +### Kafka Sync + +The Kafka Sync service stores data received from RTR services into `nrt` staging tables, similar to the staging table concept in MasterETL. It requires access to either `RDB` or `rdb_modern` depending on your deployment stage. Use `RDB` if you are live with RTR, or `rdb_modern` if you are evaluating or testing RTR deployment. + +| Database | Permissions | SQL Login | +|---|---|---| +| `RDB` (production RTR only) | `db_datareader`, `db_datawriter` | `kafka_sync_connector_service_rdb` | +| `rdb_modern` (dev RTR only) | `db_datareader`, `db_datawriter` | `kafka_sync_connector_service_rdb` | + +### Debezium + +The Debezium service monitors `NBS_ODSE` and `NBS_SRTE` tables for row-level changes and writes those changes to the Kafka broker. + +| Database | Permissions | SQL Login | +|---|---|---| +| `NBS_ODSE` | `db_datareader` | `debezium_service_rdb` | +| `NBS_SRTE` | `db_datareader` | `debezium_service_rdb` | + +## Stored procedures by service + +The following stored procedures must be executable by their respective service users. These are granted individually rather than through a role. + + + +Jump to stored procedures: + +- [Organization service](#organization-stored-procedures) +- [Observation service](#observation-stored-procedures) +- [Person service](#person-stored-procedures) +- [Investigation service](#investigation-stored-procedures) +- [LDF service](#ldf-stored-procedures) + +### Organization service - `NBS_ODSE` +{: #organization-stored-procedures } + +- `sp_organization_event` +- `sp_place_event` + +### Observation service - `NBS_ODSE` +{: #observation-stored-procedures } + +- `sp_observation_event` + +### Person service - `NBS_ODSE` +{: #person-stored-procedures } + +- `sp_patient_event` +- `sp_patient_race_event` +- `sp_provider_event` +- `sp_auth_user_event` + +### Investigation service - `NBS_ODSE` +{: #investigation-stored-procedures } + +- `sp_investigation_event` +- `sp_contact_record_event` +- `sp_interview_event` +- `sp_notification_event` +- `sp_treatment_event` +- `sp_vaccination_event` +- `sp_public_health_case_fact_datamart_event` + +### LDF service - `NBS_ODSE` +{: #ldf-stored-procedures } + +- `sp_ldf_data_event` +- `sp_ldf_patient_event` +- `sp_ldf_provider_event` +- `sp_ldf_organization_event` +- `sp_ldf_observation_event` +- `sp_ldf_phc_event` +- `sp_ldf_intervention_event` diff --git a/docs/deploy-nbs7/support.md b/docs/deploy-nbs7/support.md new file mode 100644 index 0000000..2817ed9 --- /dev/null +++ b/docs/deploy-nbs7/support.md @@ -0,0 +1,73 @@ +--- +title: Get support +layout: page +nav_order: 5 +description: Explains when to contact CDC for NBS 7 planning, deployment, and maintenance support and what information to include in a support request. +redirect_from: + - /docs/support.html + - /docs/support/ +--- + +# Get support for NBS 7 + +Use this page to understand when to contact CDC for help with NBS 7 planning, deployment, validation, and ongoing maintenance. Start with the guidance in this admin guide when it covers your issue, then contact CDC if you need clarification, encounter a blocker, or cannot find the procedure you need. + +## On this page +{: .no_toc .text-delta } + +1. TOC +{:toc} + +## When to contact CDC + +CDC provides deployment support at no cost. Reach out if your jurisdiction needs help with any of the following: + +- evaluating whether NBS 7 is the right next step for your jurisdiction +- choosing a starting configuration or optional add-ons +- resolving a deployment blocker during cloud, cluster, or microservices setup +- troubleshooting validation failures before go-live +- identifying the right maintenance procedure after go-live +- locating documentation that is not yet covered in this guide + +## Start with the right resource + +Use the resource that best matches where you are in the process. + +| If you need help with... | Start here | +|:---|:---| +| Readiness, staffing, cloud prerequisites, or go or no-go planning | [Before you deploy NBS 7](../before-you-deploy.html) | +| Deployment steps for infrastructure, microservices, identity, or validation | [Deploy NBS 7](../deploy-nbs7.html) | +| Post-go-live operations, upgrades, or runtime configuration | [Maintain NBS 7](../maintain-nbs7.html) | + +If the guide does not answer your question, contact [nbs@cdc.gov](mailto:nbs@cdc.gov). + +## Before you contact CDC + +Include enough context for the support team to understand where you are in the process and what has already been tried. When possible, include: + +- your jurisdiction name +- your NBS 6 version and target NBS 7 version +- your cloud provider and deployment configuration +- the deployment phase you are in, such as planning, install, test, or steady state +- the page or procedure you were following when the issue occurred +- the exact error message, affected component, and time of failure +- relevant logs, screenshots, or command output with sensitive information removed +- a short summary of what changed immediately before the issue started + +## Common support scenarios + +The most common questions usually fall into one of these areas: + +- **Planning and readiness**: questions about staffing, cloud prerequisites, security review, or whether a vendor-managed deployment is the better fit +- **Configuration decisions**: questions about optional add-ons such as Real-time reporting or the Data Ingestion API +- **Deployment troubleshooting**: issues during Terraform, Kubernetes, Keycloak, or microservices setup +- **Validation and cutover**: help interpreting smoke test results, validating data flow, or confirming readiness for go-live +- **Ongoing maintenance**: questions about upgrades, operational procedures, or newly documented maintenance tasks + +## Release and documentation updates + +This guide reflects the currently documented deployment and maintenance procedures, but NBS 7 is under active development. For the latest documented procedures: + +- review the relevant sections in this guide before starting work +- check the repository for newly published guidance and release-related updates +- contact [nbs@cdc.gov](mailto:nbs@cdc.gov) if you need a procedure that is not yet documented diff --git a/docs/maintain-nbs7/eks-upgrade.md b/docs/maintain-nbs7/eks-upgrade.md new file mode 100644 index 0000000..ee3cd78 --- /dev/null +++ b/docs/maintain-nbs7/eks-upgrade.md @@ -0,0 +1,228 @@ +--- +title: Update EKS control plane +layout: page +parent: Maintain NBS 7 +nav_order: 2 +--- + +# Update the EKS control plane + +You can use Terraform to upgrade the Amazon Elastic Kubernetes Service (EKS) control plane and node groups for your NBS 7 deployment. Perform a control plane upgrade when AWS releases a new Kubernetes version or when your current version approaches end-of-support. + +## On this page +{: .no_toc .text-delta } + +1. TOC +{:toc} + +## Considerations + +AWS supports each Kubernetes minor version for up to 26 months after its release in EKS. That period comprises 14 months of standard support, followed by 12 months of extended support. Plan your upgrades before your current version exits standard support. For more information, see [Understand the Kubernetes version lifecycle on EKS \- Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html). + +* **Cost impact:** Amazon EKS clusters on extended support versions incur additional cost when they are running on a version in extended support. For more information, see [Amazon EKS extended support for Kubernetes version pricing](https://aws.amazon.com/blogs/containers/amazon-eks-extended-support-for-kubernetes-versions-pricing) on the AWS blog and the Amazon EKS [pricing page](https://aws.amazon.com/eks/pricing/). +* **Forced upgrades:** When a version exits extended support, [AWS automatically upgrades the control plane to the oldest supported version](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html#extended-support-faqs). Automatic upgrades do not account for workload compatibility, add-on versions, or your deployment schedule. To maintain control over your upgrade timing, complete upgrades before the extended support window closes. +* **One minor version at a time:** You must upgrade the control plane one minor version at a time. You cannot skip versions. If you are multiple versions behind, you will need to repeat this procedure for each version hop. For more information, see [Update existing cluster to new Kubernetes version](https://docs.aws.amazon.com/eks/latest/userguide/update-cluster.html#_step_2_review_upgrade_considerations) in the AWS documentation. +* **EKS control plane upgrades are irreversible:** You cannot downgrade a cluster to a previous Kubernetes version. If the upgrade causes unexpected issues, your recovery options are limited to debugging the upgraded cluster or restoring from a full environment backup. Ensure you have a tested backup and a rollback plan for your workloads before you begin. + +> Did you know? +> +>To receive advance notice of upcoming version deprecations and end-of-support dates, check the **Your account health** page in the [AWS Health Dashboard](https://health.aws.amazon.com/health/home) regularly. You can also subscribe to the [EKS Kubernetes release calendar](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html#kubernetes-release-calendar) to track upcoming release and retirement dates. +{: .note-title } + +## Prerequisites + +Before you begin, confirm the following: + +### Access and tooling + +* You have IAM permissions to modify EKS clusters and node groups. Required actions include `eks:UpdateClusterVersion`, `eks:UpdateNodegroupVersion`, and `eks:DescribeCluster`. For the full list, see [Amazon EKS identity-based policy examples](https://docs.aws.amazon.com/eks/latest/userguide/security_iam_id-based-policy-examples.html) in the AWS documentation. +* You have installed Terraform and configured it with access to your NBS 7 state backend. +* You have installed the AWS CLI and `kubectl` and authenticated to your cluster. + +### Pre-upgrade checks + +* You have backed up your Terraform state backend. +* Your cluster is in a healthy state. All nodes are in `Ready` status and no pods are in a failed state. +* You have verified that your target Kubernetes version is compatible with all EKS managed add-ons currently installed on your cluster. Note that Amazon EKS automatically installs self-managed add-ons such as the Amazon VPC CNI plugin, kube-proxy, and CoreDNS. For more information, see [Amazon EKS add-ons](https://docs.aws.amazon.com/eks/latest/userguide/eks-add-ons.html) and [Update an Amazon EKS add-on](https://docs.aws.amazon.com/eks/latest/userguide/updating-an-add-on.html) in the AWS documentation. + +You must upgrade one minor version at a time. You cannot skip versions. If you are multiple versions behind your target, plan to run this procedure once for each version hop. +{: .important } + +## Steps to complete + +To minimize risk and ensure a clean state at each version hop, this procedure uses targeted Terraform **applies**. + +### Step 1: Identify target resources in Terraform state + +Before you run any targeted **applies**, identify the EKS resource addresses in your Terraform state. + +Bash: + +```bash +terraform state list | grep -E "aws_eks_cluster|aws_eks_node_group" +``` + +PowerShell: + +```powershell +terraform state list | Select-String "aws_eks_cluster|aws_eks_node_group" +``` + +For a standard NBS 7 deployment, the output should include: + +```text +module.eks.aws_eks_cluster.this +module.eks.aws_eks_node_group.workers +``` + +These are the target addresses to use in the next steps. If your deployment uses a customized module structure and returns different addresses, substitute those addresses in the `-target` flags in Steps 2 and 3. + +### Step 2: Upgrade the control plane + +Repeat the following steps for each minor version between your current version and your target version. Do not proceed to the next version until the cluster reaches `ACTIVE` status at the current version. + +1. In your Terraform configuration, update the `cluster_version` variable to the next minor version: + + ```terraform + cluster_version = "" + ``` + +1. Run a targeted apply against the cluster resource: + + ```bash + terraform apply -target="module.eks.aws_eks_cluster.this" + ``` + +1. Confirm the cluster has reached `ACTIVE` status at the new version before you continue: + + ```bash + aws eks describe-cluster --name \ + --query "cluster.{Version:version,Status:status}" + ``` + + The output should show the new version and `ACTIVE` status. Do not proceed until you have confirmed both values. + +1. Repeat steps 1–3 in this section for each remaining minor version until the cluster reaches the target version. + +### Step 3: Upgrade node groups + +After the control plane reaches the target version, upgrade your node groups. + +1. Run a targeted apply against the node group resource: + + ```bash + terraform apply -target="module.eks.aws_eks_node_group.workers" + ``` + +1. Confirm new nodes have joined the cluster and reached `Ready` status: + + ```bash + kubectl get nodes + ``` + +All nodes should show `Ready` in the `STATUS` column. + +### Step 4: Upgrade EKS managed add-ons + +After the node groups reach `Ready` status, upgrade your EKS managed add-ons to versions that are compatible with the new Kubernetes version. If you skip this step, you risk leaving add-ons running on incompatible versions, which might cause networking or DNS failures. + +1. List the add-ons installed on your cluster and their current versions: + + ```bash + aws eks list-addons --cluster-name + ``` + +1. For each add-on, check which versions are compatible with your target Kubernetes version: + + ```bash + aws eks describe-addon-versions \ + --addon-name \ + --kubernetes-version \ + --query "addons[].addonVersions[].addonVersion" + ``` + +1. Update each add-on to the latest compatible version: + + ```bash + aws eks update-addon \ + --cluster-name \ + --addon-name \ + --addon-version \ + --resolve-conflicts OVERWRITE + ``` + + The `--resolve-conflicts OVERWRITE` flag allows the update to proceed even if you’ve customized your add-on configuration from the AWS default. If your deployment includes custom add-on configurations you need to preserve, use `--resolve-conflicts PRESERVE` instead. With `PRESERVE`, the update will fail rather than overwrite local changes, and you will need to resolve conflicts manually. If you are unsure which flag to use, check with your infrastructure team. + {: .important } + +1. Repeat the previous step for each add-on in your cluster. +1. Confirm each add-on reaches `ACTIVE` status before you move on: + + ```bash + aws eks describe-addon \ + --cluster-name \ + --addon-name \ + --query "addon.{Version:addonVersion,Status:status}" + ``` + +### Step 5: Reconcile configuration + +After all targeted **applies** are complete, run a full **plan** and **apply** to resolve any remaining configuration drift. Targeted **applies** do not update all dependent resources. This step ensures your infrastructure state is fully reconciled. + +```bash +terraform plan +terraform apply +``` + +Review the plan output before applying. Confirm that no unexpected changes are included. + +If Linkerd unexpectedly stops during the upgrade, see [Known issue: Linkerd and mTLS](#known-issue-linkerd-and-mtls) for troubleshooting guidance. +{: .note } + +### Step 6: Verify the upgrade + +After completing steps 1 - 4, confirm the upgrade was successful. + +1. Verify the control plane version: + + ```bash + aws eks describe-cluster --name \ + --query "cluster.version" + ``` + +1. Verify all nodes are running the target version and are in `Ready` status: + + ```bash + kubectl get nodes -o wide + ``` + +1. Verify all pods are running: + + ```bash + kubectl get pods --all-namespaces + ``` + +No pods should be in `Error`, `CrashLoopBackOff`, or `Pending` status. + +## Known issue: Linkerd and mTLS {#known-issue-linkerd-and-mtls} + +During node group upgrades, Linkerd might unexpectedly stop. When this occurs, mTLS connections between NBS services are interrupted. + +**Required action:** After the node upgrade completes, restart all NBS services to reset mTLS state and restore full connectivity. + +1. Identify the namespace where NBS services are running: + + ```bash + kubectl get namespaces + ``` + +1. Confirm the deployments in that namespace before restarting: + + ```bash + kubectl get deployments -n + ``` + +1. Restart all deployments in the namespace: + + ```bash + kubectl rollout restart deployment -n + ``` diff --git a/docs/maintain-nbs7/upgrade-nbs7.md b/docs/maintain-nbs7/upgrade-nbs7.md new file mode 100644 index 0000000..1a0bbef --- /dev/null +++ b/docs/maintain-nbs7/upgrade-nbs7.md @@ -0,0 +1,96 @@ +--- +title: Upgrade NBS 7 +layout: page +parent: Maintain NBS 7 +nav_order: 1 +has_children: true +description: Walks through the standard NBS 7 upgrade process and links to version-specific release notes for additional required steps. +--- + +# Upgrade NBS 7 + +Use this page for the standard procedure to upgrade an existing NBS 7 deployment. Before you begin, review the release notes for the version you are installing. Some releases include additional steps that fall outside the standard procedure. + +## On this page +{: .no_toc .text-delta } + +1. TOC +{:toc} + +> Review the release notes for the version you are installing before you start the upgrade. Version-specific release notes identify prerequisite changes, dependency updates, and extra steps that are not part of the standard procedure. +{: .important } + +## Before you upgrade + +Confirm the following before you begin: + +- You have reviewed the release notes for your target version. +- Your current NBS 6 version is compatible with the NBS 7 version you plan to install. See [Compatibility matrix](../before-you-deploy/compatibility.html). +- You have a tested backup or recovery point for the environment you are upgrading. +- You have scheduled a maintenance window and notified affected stakeholders. +- You have upgraded a non-production environment first and verified expected behavior before scheduling production. + +## Upgrade NBS 7 + +To apply a standard NBS 7 upgrade: + +1. Download the release artifacts for the version you are installing. + + Release artifacts can include updated Terraform infrastructure code, Helm charts, release notes, and other release-specific materials. Depending on the release, some artifacts might be distributed through the release-specific collaboration space on [NBS Central](https://nbscentral.cdc.gov) and some through GitHub release pages such as [CDCgov/NEDSS-Helm releases](https://github.com/CDCgov/NEDSS-Helm/releases). + +1. Sign in to the cloud environment, Kubernetes cluster, and tooling used to administer your NBS 7 deployment. + +1. Review the release notes and compare your existing configuration files with the versions supplied in the release artifacts. + + Not every release changes the same values. Update only the parameters that apply to your environment and target version. + +1. Run Terraform to preview and apply infrastructure changes that are part of the release. + + ```bash + terraform plan + terraform apply + ``` + + Review the plan output before you apply it. Confirm that the changes match the release notes and your target environment. + +1. Merge any local Helm chart customizations into the chart values supplied with the release before deploying updated services. + +1. Run Helm to deploy the updated containers. + + ```bash + helm upgrade --install + ``` + +1. Validate the upgraded environment. + + Confirm that: + + - The application is accessible. + - Core workflows are functioning as expected. + - Data ingestion and downstream processing are functioning as expected for your deployment. + +## Release-specific steps + +Some NBS 7 releases include infrastructure or dependency changes that require additional work beyond the standard procedure. Use the release notes for your target version to identify those steps. + +| Component or change area | Where to find instructions | +|---|---| +| EKS control plane updates | [Update EKS control plane](eks-upgrade.html) | +| Elasticsearch version changes | Release notes for the applicable version | +| Ingress controller changes | Release notes for the applicable version | + +> Component-level instructions in release notes are version-specific. Use this page for the repeatable baseline procedure and use the release notes for steps that apply only to a specific release. +{: .note } + +## Release notes + +Use the child pages in this section for version-specific upgrade guidance. + +- [NBS 7.12 release notes](upgrade-nbs7/release-notes-7-12.html) describe the release-specific prerequisites and infrastructure changes for NBS 7.12. + +## Get help + +If you encounter issues during an upgrade: + +- [Open a ticket on NBS Central](https://nbscentral.cdc.gov/issues/new) +- Email [nbs@cdc.gov](mailto:nbs@cdc.gov) diff --git a/docs/maintain-nbs7/upgrade-nbs7/release-notes-7-12.md b/docs/maintain-nbs7/upgrade-nbs7/release-notes-7-12.md new file mode 100644 index 0000000..ca217f7 --- /dev/null +++ b/docs/maintain-nbs7/upgrade-nbs7/release-notes-7-12.md @@ -0,0 +1,92 @@ +--- +title: NBS 7.12 release notes +layout: page +parent: Upgrade NBS 7 +grand_parent: Maintain NBS 7 +nav_order: 7120 +description: Summarizes release-specific prerequisites, infrastructure changes, and required actions for upgrading to NBS 7.12. +--- + +# NBS 7.12 release notes + +This page summarizes the release-specific prerequisites and required actions for NBS 7.12. Use it with [Upgrade NBS 7](../upgrade-nbs7.html) before you begin the upgrade. + +## On this page +{: .no_toc .text-delta } + +1. TOC +{:toc} + +## Release summary + +- Release date: March 2026 +- Release type: Patch +- Scope: Infrastructure updates for core dependencies that affect security, search functionality, and Kubernetes support + +## Prerequisites + +Before you install NBS 7.12, confirm the following: + +- Your NBS 6 deployment is running version 6.0.18.1 or later. See [Compatibility matrix](../../before-you-deploy/compatibility.html). +- Required NBS 6 dependencies remain in place, including Rhapsody routes, SAS 9.4 reporting, and authentication configured with a standards-based identity protocol such as OpenID Connect (OIDC), SAML, OAuth 2.0, or Active Directory. + +## What changed in 7.12 + +| Component | Change | Action required | +|---|---|---| +| Elasticsearch | Upgraded from 7.17.1 to 9 | Yes. See [Elasticsearch upgrade](#elasticsearch-upgrade). | +| Ingress controller | Replaced Ingress NGINX with Traefik | Yes. See [Ingress controller migration: NGINX to Traefik](#ingress-controller-migration-nginx-to-traefik). | +| Kubernetes | Control plane updated to version 1.35 | Yes if your cluster is running 1.32 or earlier. See [Kubernetes control plane update](#kubernetes-control-plane-update). | + +## Infrastructure changes + +### Elasticsearch upgrade + +NBS 7.11 included Elasticsearch 7.17.1, which reached end-of-life in January 2026. NBS 7.12 upgrades Elasticsearch to version 9, which is supported through 2029. + +You cannot upgrade directly from version 7 to version 9. Depending on your current version, you might need to upgrade from 7 to 8 first, then from 8 to 9. + +> Step-by-step Elasticsearch upgrade instructions for NBS 7.12 are in the 7.12 collaboration space on NBS Central. Retrieve those instructions before you begin because this version transition includes index migration steps that are not part of the standard upgrade procedure. +{: .important } + +To access those instructions: + +1. Sign in to [NBS Central](https://nbscentral.cdc.gov). +1. Open the 7.12 collaboration space. +1. Download the Elasticsearch upgrade instructions from the release artifacts. + +### Ingress controller migration: NGINX to Traefik + +NBS 7.12 replaces Ingress NGINX with [Traefik](https://traefik.io/traefik) as the required ingress controller. + +> Migration instructions for this change are in the 7.12 collaboration space on NBS Central. This release replaces a core infrastructure component and requires steps beyond the standard Terraform and Helm upgrade procedure. +{: .important } + +To access those instructions: + +1. Sign in to [NBS Central](https://nbscentral.cdc.gov). +1. Open the 7.12 collaboration space. +1. Download the NGINX to Traefik migration guide from the release artifacts. + +If you encounter issues during the migration, open a ticket on [NBS Central](https://nbscentral.cdc.gov/issues/new) with the subject line "Traefik migration issues." + +### Kubernetes control plane update + +NBS 7.12 updates the Kubernetes control plane to version 1.35. Clusters running version 1.32 reached end-of-support on March 31, 2026. + +For Amazon Elastic Kubernetes Service (EKS) environments, follow [Update EKS control plane](../eks-upgrade.html). That procedure covers version-by-version upgrades using Terraform and applies to this release. + +## Standard upgrade steps + +After you complete any release-specific steps in this page, follow [Upgrade NBS 7](../upgrade-nbs7.html) to apply the 7.12 Terraform scripts and Helm charts. + +## Known issues + +No new known issues were introduced in NBS 7.12. + +For a full list of active known issues, see the [NBS Central defects log](https://nbscentral.cdc.gov/projects/def/issues). + +## Get help + +- [Open a ticket on NBS Central](https://nbscentral.cdc.gov/issues/new) +- Email [nbs@cdc.gov](mailto:nbs@cdc.gov) From 22116621cdb0757a18fb0b0a3fe38b2268be3710 Mon Sep 17 00:00:00 2001 From: jburgh Date: Fri, 17 Apr 2026 17:26:00 -0400 Subject: [PATCH 02/16] Restore stashed pages and uncomment cross links --- .../choose-your-configuration/decision-tree.md | 2 +- docs/before-you-deploy/operational-considerations.md | 2 +- docs/deploy-nbs7.md | 2 -- docs/deploy-nbs7/deploy-on-aws.md | 2 -- docs/deploy-nbs7/deploy-on-aws/prerequisites.md | 2 +- docs/deploy-nbs7/deploy-on-azure.md | 4 +--- docs/deploy-nbs7/prerequisites.md | 4 +--- docs/deploy-nbs7/quickstart.md | 2 -- docs/maintain-nbs7.md | 8 +++----- index.md | 2 -- 10 files changed, 8 insertions(+), 22 deletions(-) diff --git a/docs/before-you-deploy/choose-your-configuration/decision-tree.md b/docs/before-you-deploy/choose-your-configuration/decision-tree.md index a69a073..068d255 100644 --- a/docs/before-you-deploy/choose-your-configuration/decision-tree.md +++ b/docs/before-you-deploy/choose-your-configuration/decision-tree.md @@ -54,7 +54,7 @@ Where does your NBS 6 currently run? - **Already on AWS or Azure** → Staying on the same provider avoids additional procurement and approval steps. Go to [Step 4](#step-4-reporting-needs). - **On-premises** → Your migration includes a cloud migration as well as an NBS 7 deployment. Plan for additional time and resources. Go to [Step 4](#step-4-reporting-needs). -This step is informational and does not impact your suggested deployment configuration. For more information, see [Your cloud provider depends on your existing environment](../operational-considerations.html#your-cloud-provider-depends-on-your-existing-environment) on the Operational Considerations page. +This step is informational and does not impact your suggested deployment configuration. For more information, see [Align cloud provider with jurisdictional strategy](../operational-considerations.html#align-cloud-provider-with-jurisdictional-strategy) on the Operational Considerations page. {: .note } ## Step 4: Reporting needs diff --git a/docs/before-you-deploy/operational-considerations.md b/docs/before-you-deploy/operational-considerations.md index bce82ba..fe06e3a 100644 --- a/docs/before-you-deploy/operational-considerations.md +++ b/docs/before-you-deploy/operational-considerations.md @@ -53,7 +53,7 @@ Choose the provider that best aligns with your organization's current operationa - **Contractual Agreements:** Utilize existing Enterprise Agreements or pre-approved cloud spending to streamline procurement. - **Staff Expertise:** Align the choice with the existing skills of your cloud engineering or IT administration teams. -See also: [Assess your readiness > Cloud infrastructure](assess-your-readiness.html/#cloud-infrastructure). +See also: [Assess your readiness > Cloud infrastructure](assess-your-readiness.html#cloud-infrastructure). ## Technical staffing requirements differ from NBS 6 diff --git a/docs/deploy-nbs7.md b/docs/deploy-nbs7.md index f300330..ee6581a 100644 --- a/docs/deploy-nbs7.md +++ b/docs/deploy-nbs7.md @@ -10,9 +10,7 @@ description: Step-by-step instructions for deploying NBS 7 in an AWS environment This section covers the full NBS 7 deployment process, from prerequisites and infrastructure setup through microservices deployment and go-live. - NBS 7 deployment comprises four main phases that you should complete in order: diff --git a/docs/deploy-nbs7/deploy-on-aws.md b/docs/deploy-nbs7/deploy-on-aws.md index 45cd8b9..32e57ab 100644 --- a/docs/deploy-nbs7/deploy-on-aws.md +++ b/docs/deploy-nbs7/deploy-on-aws.md @@ -14,9 +14,7 @@ redirect_from: This section walks you through provisioning the AWS cloud environment for NBS 7. You will verify that your AWS account, hardware, software, and network requirements are in place, then use Terraform to provision the VPC, EKS cluster, and supporting AWS services. Complete both steps in order before moving on to [Deploy cluster infrastructure](../deploy-nbs7/cluster-infrastructure.html). - ## What gets provisioned diff --git a/docs/deploy-nbs7/deploy-on-aws/prerequisites.md b/docs/deploy-nbs7/deploy-on-aws/prerequisites.md index d28f94e..48967da 100644 --- a/docs/deploy-nbs7/deploy-on-aws/prerequisites.md +++ b/docs/deploy-nbs7/deploy-on-aws/prerequisites.md @@ -27,7 +27,7 @@ Before you deploy NBS 7, make sure your environment meets the requirements in ea Your AWS environment must: -- Contain a pre-existing AWS account that contains a production instance of NBS 6 that is listed in the NBS 6 and NBS 7 compatibility matrix page (temporarily unpublished), plus related third-party products such as Rhapsody and SAS +- Contain a pre-existing AWS account that contains a production instance of NBS 6 that is listed in the [NBS 6 and NBS 7 compatibility matrix](../../before-you-deploy/compatibility.html), plus related third-party products such as Rhapsody and SAS - Have a properly configured DNS routing infrastructure - Be configured to enable you to create security groups and IAM roles - Provide access to NBS 6 databases that are located on an MS SQL Server instance (RDS or EC2) diff --git a/docs/deploy-nbs7/deploy-on-azure.md b/docs/deploy-nbs7/deploy-on-azure.md index 935aaec..2571a27 100644 --- a/docs/deploy-nbs7/deploy-on-azure.md +++ b/docs/deploy-nbs7/deploy-on-azure.md @@ -11,9 +11,7 @@ description: Provision the Azure cloud environment for NBS 7. Deployment guide c Azure deployment documentation is in progress. For assistance with Azure deployments, contact [nbs@cdc.gov](mailto:nbs@cdc.gov). - +Before provisioning infrastructure, verify that your NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html). ## In this section diff --git a/docs/deploy-nbs7/prerequisites.md b/docs/deploy-nbs7/prerequisites.md index 80e69ea..9d2c9d5 100644 --- a/docs/deploy-nbs7/prerequisites.md +++ b/docs/deploy-nbs7/prerequisites.md @@ -20,7 +20,7 @@ Before you begin deployment on any cloud provider, confirm that your jurisdictio Your NBS 6 instance is the foundation for NBS 7. Confirm the following: - +- **Compatible version:** Your NBS 6 version must be compatible with your target NBS 7 version. Check the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html) before you begin. - **Database access and refresh:** If your current NBS 6 database is hosted on-premises and you plan to move it to the cloud, you must complete a database refresh and ensure that the database is accessible from your test environment. This is typically a jurisdiction-managed procedure using your organization's standard database backup and restore process. - **Database server access:** Your cloud environment must have network access to your NBS 6 database server (either on-premises RDS or EC2 instance, depending on your hosting setup). If the database is on-premises, network connectivity must be established before deployment begins. - **Related applications:** Any third-party products integrated with NBS 6, such as Rhapsody or SAS, must remain operational during the NBS 7 migration. Confirm that these systems will remain accessible from your NBS 7 environment. @@ -76,12 +76,10 @@ Your deployment team should include at least one person who has: - Familiarity with your organization's cloud provider (AWS or Azure) and cloud networking concepts - Understanding of SQL Server database administration, including backup and restore procedures - ## Software versions diff --git a/docs/deploy-nbs7/quickstart.md b/docs/deploy-nbs7/quickstart.md index a6be3e5..6078c7d 100644 --- a/docs/deploy-nbs7/quickstart.md +++ b/docs/deploy-nbs7/quickstart.md @@ -23,9 +23,7 @@ This page provides a streamlined path to deploy NBS 7 infrastructure and core mi This guide is not intended for production deployment. For full production steps and guidance, see [Deploy NBS 7](../deploy-nbs7.html). {: .important } - This quick start installs and configures the following resources. diff --git a/docs/maintain-nbs7.md b/docs/maintain-nbs7.md index ebb41df..9aaa538 100644 --- a/docs/maintain-nbs7.md +++ b/docs/maintain-nbs7.md @@ -12,13 +12,11 @@ This section covers the operational tasks that keep your NBS 7 environment healt Use this section for recurring maintenance work such as upgrades, infrastructure version changes, and operational configuration updates. Work through the pages that match the change you need to make. - \ No newline at end of file +{: .note } \ No newline at end of file diff --git a/index.md b/index.md index 1f3400c..7653322 100644 --- a/index.md +++ b/index.md @@ -18,13 +18,11 @@ The NBS 7 System Administration guide helps you prepare for NBS 7, deploy the pl The content is centered on system administration. It covers readiness and planning work before deployment, phased deployment guidance for NBS 7 infrastructure and services, and maintenance topics for operating environments after go-live. - ## Runtime environment support From 233434766453dd6bb32322fc9d3e5e0bd280cb73 Mon Sep 17 00:00:00 2001 From: jburgh Date: Tue, 21 Apr 2026 14:02:18 -0400 Subject: [PATCH 03/16] Remove support and maintenance pages for clean Before You Deploy branch --- docs/deploy-nbs7/support.md | 73 ------ docs/maintain-nbs7.md | 2 + docs/maintain-nbs7/eks-upgrade.md | 228 ------------------ docs/maintain-nbs7/upgrade-nbs7.md | 96 -------- .../upgrade-nbs7/release-notes-7-12.md | 92 ------- 5 files changed, 2 insertions(+), 489 deletions(-) delete mode 100644 docs/deploy-nbs7/support.md delete mode 100644 docs/maintain-nbs7/eks-upgrade.md delete mode 100644 docs/maintain-nbs7/upgrade-nbs7.md delete mode 100644 docs/maintain-nbs7/upgrade-nbs7/release-notes-7-12.md diff --git a/docs/deploy-nbs7/support.md b/docs/deploy-nbs7/support.md deleted file mode 100644 index 2817ed9..0000000 --- a/docs/deploy-nbs7/support.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Get support -layout: page -nav_order: 5 -description: Explains when to contact CDC for NBS 7 planning, deployment, and maintenance support and what information to include in a support request. -redirect_from: - - /docs/support.html - - /docs/support/ ---- - -# Get support for NBS 7 - -Use this page to understand when to contact CDC for help with NBS 7 planning, deployment, validation, and ongoing maintenance. Start with the guidance in this admin guide when it covers your issue, then contact CDC if you need clarification, encounter a blocker, or cannot find the procedure you need. - -## On this page -{: .no_toc .text-delta } - -1. TOC -{:toc} - -## When to contact CDC - -CDC provides deployment support at no cost. Reach out if your jurisdiction needs help with any of the following: - -- evaluating whether NBS 7 is the right next step for your jurisdiction -- choosing a starting configuration or optional add-ons -- resolving a deployment blocker during cloud, cluster, or microservices setup -- troubleshooting validation failures before go-live -- identifying the right maintenance procedure after go-live -- locating documentation that is not yet covered in this guide - -## Start with the right resource - -Use the resource that best matches where you are in the process. - -| If you need help with... | Start here | -|:---|:---| -| Readiness, staffing, cloud prerequisites, or go or no-go planning | [Before you deploy NBS 7](../before-you-deploy.html) | -| Deployment steps for infrastructure, microservices, identity, or validation | [Deploy NBS 7](../deploy-nbs7.html) | -| Post-go-live operations, upgrades, or runtime configuration | [Maintain NBS 7](../maintain-nbs7.html) | - -If the guide does not answer your question, contact [nbs@cdc.gov](mailto:nbs@cdc.gov). - -## Before you contact CDC - -Include enough context for the support team to understand where you are in the process and what has already been tried. When possible, include: - -- your jurisdiction name -- your NBS 6 version and target NBS 7 version -- your cloud provider and deployment configuration -- the deployment phase you are in, such as planning, install, test, or steady state -- the page or procedure you were following when the issue occurred -- the exact error message, affected component, and time of failure -- relevant logs, screenshots, or command output with sensitive information removed -- a short summary of what changed immediately before the issue started - -## Common support scenarios - -The most common questions usually fall into one of these areas: - -- **Planning and readiness**: questions about staffing, cloud prerequisites, security review, or whether a vendor-managed deployment is the better fit -- **Configuration decisions**: questions about optional add-ons such as Real-time reporting or the Data Ingestion API -- **Deployment troubleshooting**: issues during Terraform, Kubernetes, Keycloak, or microservices setup -- **Validation and cutover**: help interpreting smoke test results, validating data flow, or confirming readiness for go-live -- **Ongoing maintenance**: questions about upgrades, operational procedures, or newly documented maintenance tasks - -## Release and documentation updates - -This guide reflects the currently documented deployment and maintenance procedures, but NBS 7 is under active development. For the latest documented procedures: - -- review the relevant sections in this guide before starting work -- check the repository for newly published guidance and release-related updates -- contact [nbs@cdc.gov](mailto:nbs@cdc.gov) if you need a procedure that is not yet documented diff --git a/docs/maintain-nbs7.md b/docs/maintain-nbs7.md index 9aaa538..4e83e3c 100644 --- a/docs/maintain-nbs7.md +++ b/docs/maintain-nbs7.md @@ -12,11 +12,13 @@ This section covers the operational tasks that keep your NBS 7 environment healt Use this section for recurring maintenance work such as upgrades, infrastructure version changes, and operational configuration updates. Work through the pages that match the change you need to make. + > Additional maintenance procedures are added to this section as they are documented. If the procedure you need is not yet covered here, contact [nbs@cdc.gov](mailto:nbs@cdc.gov). {: .note } \ No newline at end of file diff --git a/docs/maintain-nbs7/eks-upgrade.md b/docs/maintain-nbs7/eks-upgrade.md deleted file mode 100644 index ee3cd78..0000000 --- a/docs/maintain-nbs7/eks-upgrade.md +++ /dev/null @@ -1,228 +0,0 @@ ---- -title: Update EKS control plane -layout: page -parent: Maintain NBS 7 -nav_order: 2 ---- - -# Update the EKS control plane - -You can use Terraform to upgrade the Amazon Elastic Kubernetes Service (EKS) control plane and node groups for your NBS 7 deployment. Perform a control plane upgrade when AWS releases a new Kubernetes version or when your current version approaches end-of-support. - -## On this page -{: .no_toc .text-delta } - -1. TOC -{:toc} - -## Considerations - -AWS supports each Kubernetes minor version for up to 26 months after its release in EKS. That period comprises 14 months of standard support, followed by 12 months of extended support. Plan your upgrades before your current version exits standard support. For more information, see [Understand the Kubernetes version lifecycle on EKS \- Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html). - -* **Cost impact:** Amazon EKS clusters on extended support versions incur additional cost when they are running on a version in extended support. For more information, see [Amazon EKS extended support for Kubernetes version pricing](https://aws.amazon.com/blogs/containers/amazon-eks-extended-support-for-kubernetes-versions-pricing) on the AWS blog and the Amazon EKS [pricing page](https://aws.amazon.com/eks/pricing/). -* **Forced upgrades:** When a version exits extended support, [AWS automatically upgrades the control plane to the oldest supported version](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html#extended-support-faqs). Automatic upgrades do not account for workload compatibility, add-on versions, or your deployment schedule. To maintain control over your upgrade timing, complete upgrades before the extended support window closes. -* **One minor version at a time:** You must upgrade the control plane one minor version at a time. You cannot skip versions. If you are multiple versions behind, you will need to repeat this procedure for each version hop. For more information, see [Update existing cluster to new Kubernetes version](https://docs.aws.amazon.com/eks/latest/userguide/update-cluster.html#_step_2_review_upgrade_considerations) in the AWS documentation. -* **EKS control plane upgrades are irreversible:** You cannot downgrade a cluster to a previous Kubernetes version. If the upgrade causes unexpected issues, your recovery options are limited to debugging the upgraded cluster or restoring from a full environment backup. Ensure you have a tested backup and a rollback plan for your workloads before you begin. - -> Did you know? -> ->To receive advance notice of upcoming version deprecations and end-of-support dates, check the **Your account health** page in the [AWS Health Dashboard](https://health.aws.amazon.com/health/home) regularly. You can also subscribe to the [EKS Kubernetes release calendar](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html#kubernetes-release-calendar) to track upcoming release and retirement dates. -{: .note-title } - -## Prerequisites - -Before you begin, confirm the following: - -### Access and tooling - -* You have IAM permissions to modify EKS clusters and node groups. Required actions include `eks:UpdateClusterVersion`, `eks:UpdateNodegroupVersion`, and `eks:DescribeCluster`. For the full list, see [Amazon EKS identity-based policy examples](https://docs.aws.amazon.com/eks/latest/userguide/security_iam_id-based-policy-examples.html) in the AWS documentation. -* You have installed Terraform and configured it with access to your NBS 7 state backend. -* You have installed the AWS CLI and `kubectl` and authenticated to your cluster. - -### Pre-upgrade checks - -* You have backed up your Terraform state backend. -* Your cluster is in a healthy state. All nodes are in `Ready` status and no pods are in a failed state. -* You have verified that your target Kubernetes version is compatible with all EKS managed add-ons currently installed on your cluster. Note that Amazon EKS automatically installs self-managed add-ons such as the Amazon VPC CNI plugin, kube-proxy, and CoreDNS. For more information, see [Amazon EKS add-ons](https://docs.aws.amazon.com/eks/latest/userguide/eks-add-ons.html) and [Update an Amazon EKS add-on](https://docs.aws.amazon.com/eks/latest/userguide/updating-an-add-on.html) in the AWS documentation. - -You must upgrade one minor version at a time. You cannot skip versions. If you are multiple versions behind your target, plan to run this procedure once for each version hop. -{: .important } - -## Steps to complete - -To minimize risk and ensure a clean state at each version hop, this procedure uses targeted Terraform **applies**. - -### Step 1: Identify target resources in Terraform state - -Before you run any targeted **applies**, identify the EKS resource addresses in your Terraform state. - -Bash: - -```bash -terraform state list | grep -E "aws_eks_cluster|aws_eks_node_group" -``` - -PowerShell: - -```powershell -terraform state list | Select-String "aws_eks_cluster|aws_eks_node_group" -``` - -For a standard NBS 7 deployment, the output should include: - -```text -module.eks.aws_eks_cluster.this -module.eks.aws_eks_node_group.workers -``` - -These are the target addresses to use in the next steps. If your deployment uses a customized module structure and returns different addresses, substitute those addresses in the `-target` flags in Steps 2 and 3. - -### Step 2: Upgrade the control plane - -Repeat the following steps for each minor version between your current version and your target version. Do not proceed to the next version until the cluster reaches `ACTIVE` status at the current version. - -1. In your Terraform configuration, update the `cluster_version` variable to the next minor version: - - ```terraform - cluster_version = "" - ``` - -1. Run a targeted apply against the cluster resource: - - ```bash - terraform apply -target="module.eks.aws_eks_cluster.this" - ``` - -1. Confirm the cluster has reached `ACTIVE` status at the new version before you continue: - - ```bash - aws eks describe-cluster --name \ - --query "cluster.{Version:version,Status:status}" - ``` - - The output should show the new version and `ACTIVE` status. Do not proceed until you have confirmed both values. - -1. Repeat steps 1–3 in this section for each remaining minor version until the cluster reaches the target version. - -### Step 3: Upgrade node groups - -After the control plane reaches the target version, upgrade your node groups. - -1. Run a targeted apply against the node group resource: - - ```bash - terraform apply -target="module.eks.aws_eks_node_group.workers" - ``` - -1. Confirm new nodes have joined the cluster and reached `Ready` status: - - ```bash - kubectl get nodes - ``` - -All nodes should show `Ready` in the `STATUS` column. - -### Step 4: Upgrade EKS managed add-ons - -After the node groups reach `Ready` status, upgrade your EKS managed add-ons to versions that are compatible with the new Kubernetes version. If you skip this step, you risk leaving add-ons running on incompatible versions, which might cause networking or DNS failures. - -1. List the add-ons installed on your cluster and their current versions: - - ```bash - aws eks list-addons --cluster-name - ``` - -1. For each add-on, check which versions are compatible with your target Kubernetes version: - - ```bash - aws eks describe-addon-versions \ - --addon-name \ - --kubernetes-version \ - --query "addons[].addonVersions[].addonVersion" - ``` - -1. Update each add-on to the latest compatible version: - - ```bash - aws eks update-addon \ - --cluster-name \ - --addon-name \ - --addon-version \ - --resolve-conflicts OVERWRITE - ``` - - The `--resolve-conflicts OVERWRITE` flag allows the update to proceed even if you’ve customized your add-on configuration from the AWS default. If your deployment includes custom add-on configurations you need to preserve, use `--resolve-conflicts PRESERVE` instead. With `PRESERVE`, the update will fail rather than overwrite local changes, and you will need to resolve conflicts manually. If you are unsure which flag to use, check with your infrastructure team. - {: .important } - -1. Repeat the previous step for each add-on in your cluster. -1. Confirm each add-on reaches `ACTIVE` status before you move on: - - ```bash - aws eks describe-addon \ - --cluster-name \ - --addon-name \ - --query "addon.{Version:addonVersion,Status:status}" - ``` - -### Step 5: Reconcile configuration - -After all targeted **applies** are complete, run a full **plan** and **apply** to resolve any remaining configuration drift. Targeted **applies** do not update all dependent resources. This step ensures your infrastructure state is fully reconciled. - -```bash -terraform plan -terraform apply -``` - -Review the plan output before applying. Confirm that no unexpected changes are included. - -If Linkerd unexpectedly stops during the upgrade, see [Known issue: Linkerd and mTLS](#known-issue-linkerd-and-mtls) for troubleshooting guidance. -{: .note } - -### Step 6: Verify the upgrade - -After completing steps 1 - 4, confirm the upgrade was successful. - -1. Verify the control plane version: - - ```bash - aws eks describe-cluster --name \ - --query "cluster.version" - ``` - -1. Verify all nodes are running the target version and are in `Ready` status: - - ```bash - kubectl get nodes -o wide - ``` - -1. Verify all pods are running: - - ```bash - kubectl get pods --all-namespaces - ``` - -No pods should be in `Error`, `CrashLoopBackOff`, or `Pending` status. - -## Known issue: Linkerd and mTLS {#known-issue-linkerd-and-mtls} - -During node group upgrades, Linkerd might unexpectedly stop. When this occurs, mTLS connections between NBS services are interrupted. - -**Required action:** After the node upgrade completes, restart all NBS services to reset mTLS state and restore full connectivity. - -1. Identify the namespace where NBS services are running: - - ```bash - kubectl get namespaces - ``` - -1. Confirm the deployments in that namespace before restarting: - - ```bash - kubectl get deployments -n - ``` - -1. Restart all deployments in the namespace: - - ```bash - kubectl rollout restart deployment -n - ``` diff --git a/docs/maintain-nbs7/upgrade-nbs7.md b/docs/maintain-nbs7/upgrade-nbs7.md deleted file mode 100644 index 1a0bbef..0000000 --- a/docs/maintain-nbs7/upgrade-nbs7.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Upgrade NBS 7 -layout: page -parent: Maintain NBS 7 -nav_order: 1 -has_children: true -description: Walks through the standard NBS 7 upgrade process and links to version-specific release notes for additional required steps. ---- - -# Upgrade NBS 7 - -Use this page for the standard procedure to upgrade an existing NBS 7 deployment. Before you begin, review the release notes for the version you are installing. Some releases include additional steps that fall outside the standard procedure. - -## On this page -{: .no_toc .text-delta } - -1. TOC -{:toc} - -> Review the release notes for the version you are installing before you start the upgrade. Version-specific release notes identify prerequisite changes, dependency updates, and extra steps that are not part of the standard procedure. -{: .important } - -## Before you upgrade - -Confirm the following before you begin: - -- You have reviewed the release notes for your target version. -- Your current NBS 6 version is compatible with the NBS 7 version you plan to install. See [Compatibility matrix](../before-you-deploy/compatibility.html). -- You have a tested backup or recovery point for the environment you are upgrading. -- You have scheduled a maintenance window and notified affected stakeholders. -- You have upgraded a non-production environment first and verified expected behavior before scheduling production. - -## Upgrade NBS 7 - -To apply a standard NBS 7 upgrade: - -1. Download the release artifacts for the version you are installing. - - Release artifacts can include updated Terraform infrastructure code, Helm charts, release notes, and other release-specific materials. Depending on the release, some artifacts might be distributed through the release-specific collaboration space on [NBS Central](https://nbscentral.cdc.gov) and some through GitHub release pages such as [CDCgov/NEDSS-Helm releases](https://github.com/CDCgov/NEDSS-Helm/releases). - -1. Sign in to the cloud environment, Kubernetes cluster, and tooling used to administer your NBS 7 deployment. - -1. Review the release notes and compare your existing configuration files with the versions supplied in the release artifacts. - - Not every release changes the same values. Update only the parameters that apply to your environment and target version. - -1. Run Terraform to preview and apply infrastructure changes that are part of the release. - - ```bash - terraform plan - terraform apply - ``` - - Review the plan output before you apply it. Confirm that the changes match the release notes and your target environment. - -1. Merge any local Helm chart customizations into the chart values supplied with the release before deploying updated services. - -1. Run Helm to deploy the updated containers. - - ```bash - helm upgrade --install - ``` - -1. Validate the upgraded environment. - - Confirm that: - - - The application is accessible. - - Core workflows are functioning as expected. - - Data ingestion and downstream processing are functioning as expected for your deployment. - -## Release-specific steps - -Some NBS 7 releases include infrastructure or dependency changes that require additional work beyond the standard procedure. Use the release notes for your target version to identify those steps. - -| Component or change area | Where to find instructions | -|---|---| -| EKS control plane updates | [Update EKS control plane](eks-upgrade.html) | -| Elasticsearch version changes | Release notes for the applicable version | -| Ingress controller changes | Release notes for the applicable version | - -> Component-level instructions in release notes are version-specific. Use this page for the repeatable baseline procedure and use the release notes for steps that apply only to a specific release. -{: .note } - -## Release notes - -Use the child pages in this section for version-specific upgrade guidance. - -- [NBS 7.12 release notes](upgrade-nbs7/release-notes-7-12.html) describe the release-specific prerequisites and infrastructure changes for NBS 7.12. - -## Get help - -If you encounter issues during an upgrade: - -- [Open a ticket on NBS Central](https://nbscentral.cdc.gov/issues/new) -- Email [nbs@cdc.gov](mailto:nbs@cdc.gov) diff --git a/docs/maintain-nbs7/upgrade-nbs7/release-notes-7-12.md b/docs/maintain-nbs7/upgrade-nbs7/release-notes-7-12.md deleted file mode 100644 index ca217f7..0000000 --- a/docs/maintain-nbs7/upgrade-nbs7/release-notes-7-12.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: NBS 7.12 release notes -layout: page -parent: Upgrade NBS 7 -grand_parent: Maintain NBS 7 -nav_order: 7120 -description: Summarizes release-specific prerequisites, infrastructure changes, and required actions for upgrading to NBS 7.12. ---- - -# NBS 7.12 release notes - -This page summarizes the release-specific prerequisites and required actions for NBS 7.12. Use it with [Upgrade NBS 7](../upgrade-nbs7.html) before you begin the upgrade. - -## On this page -{: .no_toc .text-delta } - -1. TOC -{:toc} - -## Release summary - -- Release date: March 2026 -- Release type: Patch -- Scope: Infrastructure updates for core dependencies that affect security, search functionality, and Kubernetes support - -## Prerequisites - -Before you install NBS 7.12, confirm the following: - -- Your NBS 6 deployment is running version 6.0.18.1 or later. See [Compatibility matrix](../../before-you-deploy/compatibility.html). -- Required NBS 6 dependencies remain in place, including Rhapsody routes, SAS 9.4 reporting, and authentication configured with a standards-based identity protocol such as OpenID Connect (OIDC), SAML, OAuth 2.0, or Active Directory. - -## What changed in 7.12 - -| Component | Change | Action required | -|---|---|---| -| Elasticsearch | Upgraded from 7.17.1 to 9 | Yes. See [Elasticsearch upgrade](#elasticsearch-upgrade). | -| Ingress controller | Replaced Ingress NGINX with Traefik | Yes. See [Ingress controller migration: NGINX to Traefik](#ingress-controller-migration-nginx-to-traefik). | -| Kubernetes | Control plane updated to version 1.35 | Yes if your cluster is running 1.32 or earlier. See [Kubernetes control plane update](#kubernetes-control-plane-update). | - -## Infrastructure changes - -### Elasticsearch upgrade - -NBS 7.11 included Elasticsearch 7.17.1, which reached end-of-life in January 2026. NBS 7.12 upgrades Elasticsearch to version 9, which is supported through 2029. - -You cannot upgrade directly from version 7 to version 9. Depending on your current version, you might need to upgrade from 7 to 8 first, then from 8 to 9. - -> Step-by-step Elasticsearch upgrade instructions for NBS 7.12 are in the 7.12 collaboration space on NBS Central. Retrieve those instructions before you begin because this version transition includes index migration steps that are not part of the standard upgrade procedure. -{: .important } - -To access those instructions: - -1. Sign in to [NBS Central](https://nbscentral.cdc.gov). -1. Open the 7.12 collaboration space. -1. Download the Elasticsearch upgrade instructions from the release artifacts. - -### Ingress controller migration: NGINX to Traefik - -NBS 7.12 replaces Ingress NGINX with [Traefik](https://traefik.io/traefik) as the required ingress controller. - -> Migration instructions for this change are in the 7.12 collaboration space on NBS Central. This release replaces a core infrastructure component and requires steps beyond the standard Terraform and Helm upgrade procedure. -{: .important } - -To access those instructions: - -1. Sign in to [NBS Central](https://nbscentral.cdc.gov). -1. Open the 7.12 collaboration space. -1. Download the NGINX to Traefik migration guide from the release artifacts. - -If you encounter issues during the migration, open a ticket on [NBS Central](https://nbscentral.cdc.gov/issues/new) with the subject line "Traefik migration issues." - -### Kubernetes control plane update - -NBS 7.12 updates the Kubernetes control plane to version 1.35. Clusters running version 1.32 reached end-of-support on March 31, 2026. - -For Amazon Elastic Kubernetes Service (EKS) environments, follow [Update EKS control plane](../eks-upgrade.html). That procedure covers version-by-version upgrades using Terraform and applies to this release. - -## Standard upgrade steps - -After you complete any release-specific steps in this page, follow [Upgrade NBS 7](../upgrade-nbs7.html) to apply the 7.12 Terraform scripts and Helm charts. - -## Known issues - -No new known issues were introduced in NBS 7.12. - -For a full list of active known issues, see the [NBS Central defects log](https://nbscentral.cdc.gov/projects/def/issues). - -## Get help - -- [Open a ticket on NBS Central](https://nbscentral.cdc.gov/issues/new) -- Email [nbs@cdc.gov](mailto:nbs@cdc.gov) From cddc646dd83fc70a199e35cc67e5039e219d3f65 Mon Sep 17 00:00:00 2001 From: jburgh Date: Wed, 6 May 2026 13:38:41 -0400 Subject: [PATCH 04/16] First round of edits from CDC final review --- docs/before-you-deploy.md | 4 +-- .../assess-your-readiness.md | 14 ++++---- .../choose-your-configuration.md | 10 +++--- .../decision-tree.md | 12 +++---- .../vendor-managed-deployment.md | 2 +- docs/before-you-deploy/component-reference.md | 34 +++++++++---------- .../component-reference/di-api.md | 4 +-- .../component-reference/rtr.md | 8 ++--- docs/before-you-deploy/deployment-phases.md | 16 ++++----- .../large-jurisdiction.md | 4 +-- .../medium-jurisdiction.md | 4 +-- .../small-jurisdiction.md | 4 +-- .../operational-considerations.md | 12 +++---- .../deploy-on-aws/prerequisites.md | 4 +-- index.md | 6 ++-- 15 files changed, 66 insertions(+), 72 deletions(-) diff --git a/docs/before-you-deploy.md b/docs/before-you-deploy.md index 17b0e1a..945759c 100644 --- a/docs/before-you-deploy.md +++ b/docs/before-you-deploy.md @@ -6,7 +6,7 @@ has_children: true description: Evaluation and planning content to help you assess NBS 7 readiness and choose a deployment configuration. --- -# Before you deploy NBS 7 +# Before deploying NBS 7 This section is for STLT IT administrators and technical decision-makers who are evaluating and preparing for NBS 7. It brings together the readiness, compatibility, configuration, and planning information you need before deployment begins. Use it to understand what NBS 7 includes, what decisions your jurisdiction needs to make, and what conditions should be in place before you move into deployment work. It is intended to support an informed decision about whether to proceed with NBS 7 deployment planning. @@ -29,7 +29,7 @@ Three main resources support the NBS 6 to NBS 7 transition. Each serves a differ | Resource | Purpose | When to use | |:---|:---|:---| | **Before you deploy NBS 7** (you are here) | This resource helps IT administrators and leadership evaluate NBS 7, understand hosting requirements, and choose a component configuration | Use first | -| **[NBS 7 Migration Info Sheet](https://nbscentral.cdc.gov/documents/731)** (requires login) | Hosted on NBS Central, this resource guides your jurisdiction through the migration process, including timelines, roles, a compatibility checklist, and cutover planning | Use after confirming NBS 7 is the right fit | +| **[NBS 7 Migration Info Sheet](https://nbscentral.cdc.gov/documents/731)** (requires login; see [Additional resources](../index.html#additional-resources)) | Hosted on NBS Central, this resource guides your jurisdiction through the migration process, including timelines, roles, a compatibility checklist, and cutover planning | Use after confirming NBS 7 is the right fit | | **[NBS 7 Deployment Guide](deploy-nbs7.html)** | Provides step-by-step deployment instructions for your chosen configuration | Use when ready to deploy | {: .note } diff --git a/docs/before-you-deploy/assess-your-readiness.md b/docs/before-you-deploy/assess-your-readiness.md index 665e84c..e6e593a 100644 --- a/docs/before-you-deploy/assess-your-readiness.md +++ b/docs/before-you-deploy/assess-your-readiness.md @@ -18,19 +18,19 @@ This page helps you assess whether NBS 7 is a viable option for your jurisdictio If you work through this page and find that your jurisdiction does not meet one or more prerequisites, you might still be able to move forward. You can address some gaps with planning and lead time, but other gaps might indicate that NBS 7 is not the right fit for your jurisdiction right now. -For more information on migration planning, staffing, and budget, see [Operational considerations](../before-you-deploy/operational-considerations.html) in this guide, and the [NBS 7 Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) and [NBS 7 Resource Estimator](https://nbscentral.cdc.gov/documents/872) on NBS Central (NBS Central login required). +For more information on migration planning, staffing, and budget, see [Operational considerations](../before-you-deploy/operational-considerations.html) in this guide, and the [NBS 7 Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) and [NBS 7 Resource Estimator](https://nbscentral.cdc.gov/documents/872) on NBS Central (NBS Central login required; see [Additional resources](../../index.html#additional-resources)). {: .note } ## Not sure where to start? If you are new to NBS 7 deployment, [Deployment phases](../before-you-deploy/deployment-phases.html) provides an overview of an example rollout and where this readiness assessment fits. -## State IT security approval +## IT security approval -Has your jurisdiction obtained state IT security approval for cloud hosting and the software technologies that NBS 7 requires, including Kubernetes, Terraform, and Docker? +Has your jurisdiction obtained IT security approval for cloud hosting and the software technologies that NBS 7 requires, including Kubernetes, Terraform, and Docker? - **Yes, or approval is not required**: Continue with the rest of this section. -- **No, or unknown**: Approval timelines vary and can significantly affect your migration schedule. We recommend working with your state IT office while you continue to plan. +- **No, or unknown**: Approval timelines vary and can significantly affect your migration schedule. We recommend working with your IT office while you continue to plan. See also: [Operational considerations](../before-you-deploy/operational-considerations.html) and [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html). @@ -52,7 +52,7 @@ NBS 7 requires a cloud-based environment for deployment. NBS 7 has not been test See also: [Deploy cloud infrastructure on AWS](../deploy-nbs7/deploy-on-aws.html), [Deploy cloud infrastructure on Azure](../deploy-nbs7/deploy-on-azure.html), and [Compatibility matrix](../before-you-deploy/compatibility.html). -## Technical staff capacity +## Staff Kubernetes expertise NBS 7 uses Kubernetes, a container orchestration platform. To deploy and maintain NBS 7, you need staff who can: @@ -63,8 +63,8 @@ NBS 7 uses Kubernetes, a container orchestration platform. To deploy and maintai If your IT team does not have these skills, you have two options: -- **Building capacity**: Train existing staff or hire staff with these skills before you begin deployment. -- **Working with a vendor**: Contract with a vendor to deploy or manage your NBS 7 infrastructure. See [Vendor-managed deployment](../before-you-deploy/choose-your-configuration/vendor-managed-deployment.html) for guidance on what to look for in a vendor. +- **Build capacity**: Train existing staff or hire staff with these skills before you begin deployment. +- **Work with a vendor**: Contract with a vendor to deploy or manage your NBS 7 infrastructure. See [Vendor-managed deployment](../before-you-deploy/choose-your-configuration/vendor-managed-deployment.html) for guidance on what to look for in a vendor. See also: [Operational considerations](../before-you-deploy/operational-considerations.html) and [Choose your configuration](../before-you-deploy/choose-your-configuration.html). diff --git a/docs/before-you-deploy/choose-your-configuration.md b/docs/before-you-deploy/choose-your-configuration.md index d133e17..2a59e7b 100644 --- a/docs/before-you-deploy/choose-your-configuration.md +++ b/docs/before-you-deploy/choose-your-configuration.md @@ -26,7 +26,7 @@ Before finalizing your configuration, verify that your NBS 6 version is compatib ## NBS 7 -The base deployment. NBS 7 gives your jurisdiction NBS 6 feature parity on modern, cloud-based infrastructure, plus foundational improvements such as real-time patient search. +The base deployment. NBS 7 gives your jurisdiction NBS 6 feature parity on modern, cloud-based infrastructure, plus foundational improvements such as real-time patient search and ongoing incremental modernized modules and functional areas. NBS 7 core components are organized into three layers. For details on what each component does and when you need it, see [NBS 7 core components](../before-you-deploy/component-reference/nbs-core-components.html). @@ -90,17 +90,17 @@ RTR adds the following components to your NBS 7 deployment. For details, see [Ad ## Add-on: Data Ingestion (DI) API -The DI API is an optional add-on that provides a built-in data transit layer. It provides a REST API interface for writing data to NBS, acting as a secure intermediary between your middleware and the database. +The DI API provides a built-in data transit layer. It provides a REST API interface for writing data to NBS, acting as a secure intermediary between your middleware and the database. | Integration Method | Rationale | | :--- | :--- | -| **Direct SQL Write** | Standard for jurisdictions where middleware (Rhapsody) can access the database network directly. | +| **Direct SQL Write** | Standard for jurisdictions where middleware such as Rhapsody can access the database directly. | | **DI API** | Used when security policies prohibit direct database access from third-party tools or when middleware cannot be co-located with NBS. | {: .important } -The DI API is not a replacement for middleware. An integration engine like Rhapsody is still required to preprocess and format data before it is sent to the DI API. +The DI API is not a replacement for middleware. An integration engine suc as Rhapsody is required to preprocess and format data before it is sent to the DI API. -For details, see [Add-on: Data Ingestion (DI) API](../before-you-deploy/component-reference/di-api.html). +For more information, see [Data Ingestion (DI) API](../before-you-deploy/component-reference/di-api.html) in the Component Reference. {: .note-title } > Best for diff --git a/docs/before-you-deploy/choose-your-configuration/decision-tree.md b/docs/before-you-deploy/choose-your-configuration/decision-tree.md index 133f001..641cc7b 100644 --- a/docs/before-you-deploy/choose-your-configuration/decision-tree.md +++ b/docs/before-you-deploy/choose-your-configuration/decision-tree.md @@ -20,14 +20,14 @@ Use this decision tree to determine a baseline deployment model for your jurisdi {: .important } The decision tree identifies a potential starting point, not a final answer. CDC provides free pre-deployment consultation to help jurisdictions validate their configuration choice. Connect with the CDC NBS team at [nbs@cdc.gov](mailto:nbs@cdc.gov) before you begin deployment. -## Step 1: State IT security approval +## Step 1: IT security approval -Has your jurisdiction obtained state IT security approval for cloud hosting and the required software technologies (Kubernetes, Terraform, Docker)? +Has your jurisdiction obtained the appropriate IT security approval for cloud hosting and the required software technologies (Kubernetes, Terraform, Docker)? - **Yes, or approval is not required** → Go to [Step 2](#step-2-internal-technical-capacity). - **No, or unknown** → It's a good idea to begin the approval process now, then continue planning. Approval is typically required before deployment. Go to [Step 2](#step-2-internal-technical-capacity). -Because NBS handles PII and PHI, state IT might still need to review and approve the deployment, even in vendor-managed models. For more information, see [State IT security approval takes time](../operational-considerations.html#state-it-security-approval-takes-time) on the Operational Considerations page. +Because NBS handles PII and PHI, IT might still need to review and approve the deployment, even in vendor-managed models. For more information, see [IT security approval can take time](../operational-considerations.html#it-security-approval-can-take-time) on the Operational Considerations page. {: .note } ## Step 2: Internal technical capacity @@ -54,7 +54,7 @@ Where does your NBS 6 currently run? - **Already on AWS or Azure** → Staying on the same provider avoids additional procurement and approval steps. Go to [Step 4](#step-4-reporting-needs). - **On-premises** → Your migration includes a cloud migration as well as an NBS 7 deployment. Plan for additional time and resources. Go to [Step 4](#step-4-reporting-needs). -This step is informational and does not impact your suggested deployment configuration. For more information, see [Align cloud provider with jurisdictional strategy](../operational-considerations.html#align-cloud-provider-with-jurisdictional-strategy) on the Operational Considerations page. +This step is informational and does not change your suggested deployment configuration. For more information, see [Align cloud provider with jurisdictional strategy](../operational-considerations.html#align-cloud-provider-with-jurisdictional-strategy) on the Operational Considerations page. {: .note } ## Step 4: Reporting needs @@ -92,7 +92,7 @@ For more information, see [The Data Ingestion API adds a secure integration opti ## Next steps: Estimate infrastructure costs -After you determine your deployment model, you can use the jurisdictional sizing criteria provided in this section to identify which resource profile to use in the **NBS 7 Resource Estimator**. The estimator is an Excel-based tool available on NBS Central. It provides baseline values for provisioned resources, including compute (vCPU and Memory), SQL storage, and Kafka brokers. +After you determine your deployment model, you can use the jurisdictional sizing criteria provided in this section to identify which resource profile to use in the **NBS 7 Resource Estimator**. The estimator is an Excel-based tool available on NBS Central (login required; see [Additional resources](../../../index.html#additional-resources)). It provides baseline values for provisioned resources, including compute (vCPU and Memory), SQL storage, and Kafka brokers. The following thresholds help you identify your profile for the estimator: @@ -115,7 +115,7 @@ select count(*) from NBS_ODSE.dbo.Person To generate a monthly cost estimate for your deployment scenario: -1. Log in to [NBS Central](https://nbscentral.cdc.gov/) and download the latest **[NBS 7 Resource Estimator](https://nbscentral.cdc.gov/documents/872)**. +1. Log in to [NBS Central](https://nbscentral.cdc.gov/) and download the latest **[NBS 7 Resource Estimator](https://nbscentral.cdc.gov/documents/872)**. If you need access, see [Additional resources](../../../index.html#additional-resources). 1. Identify the tab that matches your jurisdictional size. 1. Input the quantities and suggested SKUs from that tab into the AWS Pricing Calculator or Azure Pricing Calculator. diff --git a/docs/before-you-deploy/choose-your-configuration/vendor-managed-deployment.md b/docs/before-you-deploy/choose-your-configuration/vendor-managed-deployment.md index 917df31..24ac221 100644 --- a/docs/before-you-deploy/choose-your-configuration/vendor-managed-deployment.md +++ b/docs/before-you-deploy/choose-your-configuration/vendor-managed-deployment.md @@ -31,5 +31,5 @@ Then: 2. Work with your vendor to complete steps 4–8 of the [decision tree](decision-tree.html) to identify your recommended configuration tier. 3. Return to the [component reference](../component-reference.html) for the configuration parameters your vendor will need. -> Vendors with Kubernetes and cloud infrastructure expertise can deploy NBS 7, but they will need detailed technical guidance from CDC and from this guide to do it accurately. Plan for a close working relationship between your vendor and the CDC NBS team, especially during initial deployment. Also plan for the funding needed to sustain vendor support beyond initial deployment. Ongoing maintenance costs are a common planning gap. Use the [NBS 7 Resource Estimator (NBS Central login required)](https://nbscentral.cdc.gov/documents/872) to support cloud cost projections. +> Vendors with Kubernetes and cloud infrastructure expertise can deploy NBS 7, but they will need detailed technical guidance from CDC and from this guide to do it accurately. Plan for a close working relationship between your vendor and the CDC NBS team, especially during initial deployment. Also plan for the funding needed to sustain vendor support beyond initial deployment. Ongoing maintenance costs are a common planning gap. Use the [NBS 7 Resource Estimator](https://nbscentral.cdc.gov/documents/872) to support cloud cost projections (NBS Central login required; see [Additional resources](../../../index.html#additional-resources)). {: .note } diff --git a/docs/before-you-deploy/component-reference.md b/docs/before-you-deploy/component-reference.md index 53d22d4..ac3719f 100644 --- a/docs/before-you-deploy/component-reference.md +++ b/docs/before-you-deploy/component-reference.md @@ -12,11 +12,11 @@ description: Describes each NBS 7 component — what it does, when it is needed, The pages in this section describe each component in NBS 7. Use it to understand what each component does, why it is included in your deployment, and how it relates to other components. -Components in this reference are organized by deployment scope: +NBS 7 is deployed in phases. Components in this reference are organized by deployment phase: -- [NBS 7 core components](../before-you-deploy/component-reference/nbs-core-components.html) -- [Add-on: Real-Time Reporting (RTR)](../before-you-deploy/component-reference/rtr.html) -- [Add-on: Data Ingestion (DI) API](../before-you-deploy/component-reference/di-api.html) +- [NBS 7 core deployment](../before-you-deploy/component-reference/nbs-core-components.html) +- [Real-Time Reporting (RTR) deployment](../before-you-deploy/component-reference/rtr.html) +- [Data Ingestion (DI) API deployment](../before-you-deploy/component-reference/di-api.html) For deployment configuration details including configuration parameters, Helm chart values, and step-by-step setup instructions, see the [Deploy NBS 7](../deploy-nbs7.html) section of this guide. @@ -24,24 +24,22 @@ For deployment configuration details including configuration parameters, Helm ch ## Quick reference -The following table shows which components are included in NBS 7 and its available add-ons. +The following table shows which components are included in NBS 7. RTR and DI API are deployed separately from the core NBS 7 components. -NBS 7 core components are required for all deployments. RTR and DI API are optional add-ons. Components for the add-ons are only required if your jurisdiction chooses to include them. - -| Component | NBS 7 | + RTR add-on | + DI API add-on | +| Component | NBS 7 | RTR | DI API | |:---|:---:|:---:|:---:| -| [Legacy NBS 6](../before-you-deploy/component-reference/nbs-core-components.html#legacy-nbs-6) | ✓ | ✓ | ✓ | -| [NBS Modernization API](../before-you-deploy/component-reference/nbs-core-components.html#nbs-modernization-api) | ✓ | ✓ | ✓ | -| [NBS Web UI](../before-you-deploy/component-reference/nbs-core-components.html#nbs-web-ui) | ✓ | ✓ | ✓ | -| [NBS Gateway](../before-you-deploy/component-reference/nbs-core-components.html#nbs-gateway) | ✓ | ✓ | ✓ | -| [Elasticsearch](../before-you-deploy/component-reference/nbs-core-components.html#elasticsearch) | ✓ | ✓ | ✓ | -| [Nifi](../before-you-deploy/component-reference/nbs-core-components.html#nifi) | ✓ | ✓ | ✓ | -| [Keycloak](../before-you-deploy/component-reference/nbs-core-components.html#keycloak) | ✓ | ✓ | ✓ | -| [Database (NBS\_ODSE, NBS\_SRTE)](../before-you-deploy/component-reference/nbs-core-components.html#database-nbs_odse-nbs_srte) | ✓ | ✓ | ✓ | -| [Infrastructure and networking layer](../before-you-deploy/component-reference/nbs-core-components.html#infrastructure-and-networking-layer-components) | ✓ | ✓ | ✓ | +| [Legacy NBS 6](../before-you-deploy/component-reference/nbs-core-components.html#legacy-nbs-6) | ✓ | | | +| [NBS Modernization API](../before-you-deploy/component-reference/nbs-core-components.html#nbs-modernization-api) | ✓ | | | +| [NBS Web UI](../before-you-deploy/component-reference/nbs-core-components.html#nbs-web-ui) | ✓ | | | +| [NBS Gateway](../before-you-deploy/component-reference/nbs-core-components.html#nbs-gateway) | ✓ | | | +| [Elasticsearch](../before-you-deploy/component-reference/nbs-core-components.html#elasticsearch) | ✓ | | | +| [Nifi](../before-you-deploy/component-reference/nbs-core-components.html#nifi) | ✓ | | | +| [Keycloak](../before-you-deploy/component-reference/nbs-core-components.html#keycloak) | ✓ | | | +| [Database (NBS\_ODSE, NBS\_SRTE)](../before-you-deploy/component-reference/nbs-core-components.html#database-nbs_odse-nbs_srte) | ✓ | | | +| [Infrastructure and networking layer](../before-you-deploy/component-reference/nbs-core-components.html#infrastructure-and-networking-layer-components) | ✓ | | | | [Debezium](../before-you-deploy/component-reference/rtr.html#debezium) | | ✓ | | | [Kafka and Kafka Connect](../before-you-deploy/component-reference/rtr.html#kafka-and-kafka-connect) | | ✓* | | | [RTR domain services](../before-you-deploy/component-reference/rtr.html#rtr-domain-services) | | ✓ | | | [DI API](../before-you-deploy/component-reference/di-api.html#di-api) | | | ✓ | -*Kafka and Kafka Connect are only required for near-real-time RTR reporting. Jurisdictions that deploy RTR but continue with batch reporting might not need Kafka. +*Jurisdictions that deploy RTR but continue with batch reporting instead of using the real-time benefit might not need Kafka and Kafka Connect. diff --git a/docs/before-you-deploy/component-reference/di-api.md b/docs/before-you-deploy/component-reference/di-api.md index ad2b3d8..e9909a1 100644 --- a/docs/before-you-deploy/component-reference/di-api.md +++ b/docs/before-you-deploy/component-reference/di-api.md @@ -1,5 +1,5 @@ --- -title: "Add-on: Data Ingestion (DI) API" +title: "Data Ingestion (DI) API" layout: page parent: Component reference grand_parent: Before you deploy @@ -7,7 +7,7 @@ nav_order: 3 description: Details the Data Ingestion (DI) API add-on component, which provides a REST API layer for routing incoming data into NBS through middleware. --- -# Component reference: Data Ingestion (DI) API add-on +# Component reference: Data Ingestion (DI) API The DI API is a REST API layer built into NBS 7 that accepts incoming public health data and routes it into NBS. Middleware such as Rhapsody or an equivalent integration engine preprocesses and formats the data, then sends it to the DI API instead of writing directly to the NBS database. diff --git a/docs/before-you-deploy/component-reference/rtr.md b/docs/before-you-deploy/component-reference/rtr.md index e4c0587..1b6e7f5 100644 --- a/docs/before-you-deploy/component-reference/rtr.md +++ b/docs/before-you-deploy/component-reference/rtr.md @@ -1,5 +1,5 @@ --- -title: "Add-on: Real-Time Reporting (RTR)" +title: "Real-Time Reporting (RTR)" layout: page parent: Component reference grand_parent: Before you deploy @@ -8,11 +8,11 @@ description: "Details the four components added by the Real-Time Reporting (RTR) nav_enabled: true --- -# Component reference: Real-Time Reporting (RTR) add-on +# Component reference: Real-Time Reporting (RTR) -RTR is an optional add-on that provides an event-driven reporting pipeline for near-real-time reporting. RTR replaces the legacy MasterETL batch process. During validation, both might run briefly in parallel to confirm that RTR output is accurate. Once validation is complete, plan to retire MasterETL. +RTR provides an event-driven reporting pipeline for near-real-time reporting. RTR replaces the legacy MasterETL batch process. During validation, both might run briefly in parallel to confirm that RTR output is accurate. Once validation is complete, plan to retire MasterETL. -The following components are added to your NBS 7 deployment when you choose to deploy the RTR add-on. +The following components are added to your NBS 7 deployment when you deploy RTR. For information on benefits and impact on operating costs, see [Operational considerations](../../before-you-deploy/operational-considerations.html). {: .note } diff --git a/docs/before-you-deploy/deployment-phases.md b/docs/before-you-deploy/deployment-phases.md index 0404edf..8261e5d 100644 --- a/docs/before-you-deploy/deployment-phases.md +++ b/docs/before-you-deploy/deployment-phases.md @@ -33,20 +33,20 @@ The phases in this table represent an example rollout scenario based on deployme {: .note } These are minimum estimates based on typical deployments. Actual timelines vary by jurisdiction. Security approval, procurement, and legal review processes are common sources of extended timelines in the Planning and Install phases. -For detailed checklists and deliverables for each phase, see the [NBS 7 Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) on NBS Central. +For detailed checklists and deliverables for each phase, see the [NBS 7 Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) on NBS Central (login required; see [Additional resources](../../index.html#additional-resources)). --- ## Planning -The Planning phase covers discovery, environment setup, and project preparation. Security approval for cloud hosting and required technologies including Kubernetes, Terraform, and Docker is frequently the longest-lead item in this phase and the most common source of delay across the entire deployment. Starting that process early tends to reduce overall deployment time. +The Planning phase covers discovery, environment setup, and project preparation. Security approval for cloud-hosting and required technologies including Kubernetes, Terraform, and Docker can be a source of delay across the entire deployment. Starting that process early tends to reduce overall deployment time. Before planning detailed timelines, confirm that your current NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html). | Activity | Description | Resource | |:---|:---|:---| -| Readiness check-in | Initial planning and review of frequently asked questions. See [Assess your readiness](../before-you-deploy/assess-your-readiness.html) for the technical checklist and [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html) for version alignment. | [Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) | -| Identify project team | Define roles, responsibilities, and key stakeholders. See [Operational considerations](../before-you-deploy/operational-considerations.html) for staffing guidance | [Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) | +| Readiness check-in | Initial planning and review of frequently asked questions. See [Assess your readiness](../before-you-deploy/assess-your-readiness.html) for the technical checklist and [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html) for version alignment. | [Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) (NBS Central login required; see [Additional resources](../../index.html#additional-resources)) | +| Identify project team | Define roles, responsibilities, and key stakeholders. See [Operational considerations](../before-you-deploy/operational-considerations.html) for staffing guidance | [Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) (NBS Central login required; see [Additional resources](../../index.html#additional-resources)) | | NBS 7 orientation | Review NBS 7 features with your migration team. See [Component reference](../before-you-deploy/component-reference.html) for a full component overview | [Choose your configuration](../before-you-deploy/choose-your-configuration.html) | | Create project plan | Draft a customized migration plan from the playbook checklists, including a migration risk registry | [Deployment scenarios](../before-you-deploy/deployment-scenarios.html) | | Communications plan | Develop and implement a communications plan customized to your timeline and needs | Communications plan | @@ -67,7 +67,7 @@ The Install phase covers provisioning your cloud environments and deploying NBS | Production environment deployment | Create and deploy an initial NBS 7 production environment build | [Deploy NBS 7 microservices](../deploy-nbs7/deploy-nbs7-microservices.html) | | Complete database transfer | Complete customizations, user file sharing setup, and integration with your user management system | STLT database refresh procedure | | Roles and permissions migration | Map user roles and configure permissions in NBS 7 | User migration mapping | -| SSO setup | Review state SSO and login requirements and integrate Keycloak with your existing login tools. See [Operational considerations](../before-you-deploy/operational-considerations.html) for SSO planning guidance | [Enable Keycloak authentication](../deploy-nbs7/keycloak/enable-keycloak-auth.html) | +| SSO setup | Review jurisdictional SSO and login requirements and integrate Keycloak with your existing login tools. See [Operational considerations](../before-you-deploy/operational-considerations.html) for SSO planning guidance | [Enable Keycloak authentication](../deploy-nbs7/keycloak/enable-keycloak-auth.html) | --- @@ -83,7 +83,7 @@ The Test phase validates that your NBS 7 environment is ready for production use | Notifications testing | Coordinate with the MVPs team to validate notifications readiness | Conditions received successfully | | Regression testing | Run test scripts across environments to validate readiness for UAT | [Validate the deployment](../deploy-nbs7/validate-the-deployment.html) | | Cutover and rollback review | Review and approve cutover and rollback plans | Cutover and Rollback Plan | -| UAT | Complete the agreed UAT plan across dev, test, and production environments | UAT test plan | +| UAT | Complete the agreed UAT plan across dev, staging, and production environments | UAT test plan | --- @@ -93,7 +93,7 @@ The Go-live phase covers final preparation, cutover, and launch. This phase is s | Activity | Description | Resource | |:---|:---|:---| -| NBS 7 training | Perform scheduled training sessions and share materials with end users | [NBS Visual Reference Guide](https://nbscentral.cdc.gov/documents/863) - NBS Central login required | +| NBS 7 training | Perform scheduled training sessions and share materials with end users | [NBS Visual Reference Guide](https://nbscentral.cdc.gov/documents/863) - NBS Central login required; see [Additional resources](../../index.html#additional-resources) | | Go/no-go decision | Make the final go-live decision and schedule the cutover date | - | | Lock database and refresh | Freeze the database backup and finalize the cutover checklist | STLT production cut-over checklist | | Go-live day | Complete the cutover checklist and launch NBS 7 | - | @@ -106,6 +106,6 @@ After go-live, your jurisdiction enters steady state operations. This phase is o | Activity | Description | Resource | |:---|:---|:---| -| Monitor live operations | Stand up long-term NBS 7 service desk support, review the NBS Administrator Guide for NBS support SOP, and track system performance | [Support](../deploy-nbs7/support.html) | +| Monitor live operations | Track system performance and understand your support options | [Get support](../support.html) | | Complete retrospective | Conduct a go-live retrospective to capture lessons learned | - | | Upgrade to new releases | Test and upgrade to new NBS 7 releases periodically | [Maintain NBS 7](../maintain-nbs7.html) | diff --git a/docs/before-you-deploy/deployment-scenarios/large-jurisdiction.md b/docs/before-you-deploy/deployment-scenarios/large-jurisdiction.md index 6982dfd..3478333 100644 --- a/docs/before-you-deploy/deployment-scenarios/large-jurisdiction.md +++ b/docs/before-you-deploy/deployment-scenarios/large-jurisdiction.md @@ -7,9 +7,7 @@ nav_order: 3 description: Case study for a large, vendor-managed NBS Complete deployment at enterprise scale, covering high-availability and advanced configuration decisions. --- -## Case study: Large jurisdiction, high volume, vendor-managed - -*Based on an enterprise-scale deployment.* +## Case study: Enterprise-scale deployment 1. TOC {:toc} diff --git a/docs/before-you-deploy/deployment-scenarios/medium-jurisdiction.md b/docs/before-you-deploy/deployment-scenarios/medium-jurisdiction.md index 330e150..adeb280 100644 --- a/docs/before-you-deploy/deployment-scenarios/medium-jurisdiction.md +++ b/docs/before-you-deploy/deployment-scenarios/medium-jurisdiction.md @@ -7,9 +7,7 @@ nav_order: 2 description: Case study for a medium jurisdiction with existing Rhapsody middleware deploying NBS Core + RTR, based on Kentucky's experience. --- -## Case study: Medium jurisdiction, existing middleware, RTR - -*Based on Kentucky's deployment.* +## Case study: RTR with middleware 1. TOC {:toc} diff --git a/docs/before-you-deploy/deployment-scenarios/small-jurisdiction.md b/docs/before-you-deploy/deployment-scenarios/small-jurisdiction.md index f75dd1b..44cf49e 100644 --- a/docs/before-you-deploy/deployment-scenarios/small-jurisdiction.md +++ b/docs/before-you-deploy/deployment-scenarios/small-jurisdiction.md @@ -7,9 +7,7 @@ nav_order: 1 description: Case study for a small, self-managed AWS deployment based on Montana's experience, covering configuration choices and lessons learned. --- -## Case study: Small jurisdiction, self-managed, AWS - -*Based on Montana's deployment.* +## Case study: Minimal cloud deployment 1. TOC {:toc} diff --git a/docs/before-you-deploy/operational-considerations.md b/docs/before-you-deploy/operational-considerations.md index fe06e3a..9d67188 100644 --- a/docs/before-you-deploy/operational-considerations.md +++ b/docs/before-you-deploy/operational-considerations.md @@ -31,21 +31,21 @@ See also: [Deployment phases](../before-you-deploy/deployment-phases.html) and [ Version prerequisite: confirm your NBS 6 baseline against the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html) before you finalize migration timelines. -## State IT security approval takes time +## IT security approval can take time -State IT security approval is often the longest-lead item in an NBS 7 migration. NBS 7 requires approval for cloud hosting and specific technologies including Kubernetes, Terraform, and Docker. Because NBS handles PII and PHI, state IT review is often required even when a vendor manages parts of the deployment. Jurisdictions that start this process early, even when deployment is still months away, might avoid one of the most common causes of migration delays. +IT security approval is often one of the longest-lead items in an NBS 7 migration, though timelines vary significantly across jurisdictions. NBS 7 requires approval for cloud hosting and specific technologies including Kubernetes, Terraform, and Docker. Because NBS handles PII and PHI, IT review is often required even when a vendor manages parts of the deployment. Jurisdictions that start this process early, even when deployment is still months away, might avoid one of the most common causes of migration delays. -See also: [Assess your readiness](../before-you-deploy/assess-your-readiness.html), [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html), and [Deploy cloud infrastructure on AWS](../deploy-nbs7/deploy-on-aws.html) or [Deploy cloud infrastructure on Azure](../deploy-nbs7/deploy-on-azure.html). +See also: [Assess your readiness](../before-you-deploy/assess-your-readiness.html), [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html), and [Deploy cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html). ## Cloud infrastructure requires ongoing budget -CDC does not support on-premises installations of NBS 7. Your jurisdiction needs an active cloud account (AWS or Azure) and an ongoing budget to sustain cloud infrastructure costs. Cloud hosting costs scale with usage, so budget planning might account for both normal operations and surge scenarios such as outbreak response. Use the [NBS 7 Resource Estimator (NBS Central login required)](https://nbscentral.cdc.gov/documents/872) to project cloud-hosting costs based on your jurisdiction's record volume. +CDC does not support on-premises installations of NBS 7. Your jurisdiction needs an active cloud account with Amazon Web Services (AWS) or Microsoft Azure and an ongoing budget to sustain cloud infrastructure costs. Cloud hosting costs scale with usage, so budget planning might account for both normal operations and surge scenarios such as outbreak response. Use the [NBS 7 Resource Estimator](https://nbscentral.cdc.gov/documents/872) to project cloud-hosting costs based on your jurisdiction's record volume (NBS Central login required; see [Additional resources](../../index.html#additional-resources)). See also: [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html) and [Deployment scenarios](../before-you-deploy/deployment-scenarios.html). ## Align cloud provider with jurisdictional strategy -NBS 7 is fully supported on both Amazon Web Services (AWS) and Microsoft Azure. While the internal microservices and deployment steps are identical across platforms, the initial environment setup depends on your jurisdiction's existing infrastructure and procurement path. +NBS 7 is fully supported on both AWS and Azure. While the internal microservices and deployment steps are identical across platforms, the initial environment setup depends on your jurisdiction's existing infrastructure and procurement path. Choose the provider that best aligns with your organization's current operational state: @@ -69,7 +69,7 @@ See also: [RTR component reference](../before-you-deploy/component-reference/rtr ## The Data Ingestion API adds a secure integration option -The Data Ingestion (DI) API is a built-in REST API layer that accepts lab reports and case reports through middleware rather than through direct database access. It does not replace middleware such as Rhapsody or Mirth Connect. Instead, it gives jurisdictions an API-based ingestion path, which is especially useful when security constraints prevent middleware or other third-party tools from connecting directly to the NBS database. Jurisdictions that do not already have middleware will still need it before they can use the DI API. +The Data Ingestion (DI) API is a built-in REST API layer that accepts lab reports and case reports. It gives jurisdictions an API-based ingestion path, which is useful when security constraints prevent middleware or other third-party tools from connecting directly to the NBS database. See also: [DI API component reference](../before-you-deploy/component-reference/di-api.html) and [Data ingestion microservice](../deploy-nbs7/microservices-deployment/data-ingestion.html). diff --git a/docs/deploy-nbs7/deploy-on-aws/prerequisites.md b/docs/deploy-nbs7/deploy-on-aws/prerequisites.md index f4f466f..763c1c3 100644 --- a/docs/deploy-nbs7/deploy-on-aws/prerequisites.md +++ b/docs/deploy-nbs7/deploy-on-aws/prerequisites.md @@ -101,13 +101,13 @@ robust layer of security. The NBS 7 system will support end user authentication by integrating with a standards-based SSO system. It is designed to be deployed as a protected endpoint within your preexisting SSO ecosystem, and can be configured to work with a wide variety of standards compliant Identity Providers (e.g. Okta, AD). -This is similar to NBS 6. As documented in ["NEDSS Base System Release 4.4.1 Hardening NBS Perimeter Security"](https://nbscentral.cdc.gov/attachments/1995) (requires access on NBS central), NBS 6 does not authenticate users. Instead, it delegates authentication to a security proxy, which each State, Tribal, Local, and Territorial (STLT) must provide in order to deploy NBS. +This is similar to NBS 6. As documented in ["NEDSS Base System Release 4.4.1 Hardening NBS Perimeter Security"](https://nbscentral.cdc.gov/attachments/1995) (requires access on NBS central; see [Additional resources](../../../index.html#additional-resources)), NBS 6 does not authenticate users. Instead, it delegates authentication to a security proxy, which each State, Tribal, Local, and Territorial (STLT) must provide in order to deploy NBS. The NBS 7 release requires that prospective users already have a working NBS 6 instance, and therefore assumes that a user authentication mechanism is already in place. NBS 7 extends functionality that is available to the authenticated user. NBS 7 therefore works alongside the existing authentication mechanism. No additional steps are needed to authenticate users for NBS 7. -To assist those who are integrating NBS into their SSO ecosystem, a proof of concept in which authentication is performed using an Identity Provider (IdP) and a proxy is available on request. To request it, [please create a ticket here](https://nbscentral.cdc.gov/projects/nbs700/issues/new). +To assist those who are integrating NBS into their SSO ecosystem, a proof of concept in which authentication is performed using an Identity Provider (IdP) and a proxy is available on request. To request it, [please create a ticket here](https://nbscentral.cdc.gov/projects/nbs700/issues/new) (NBS Central login required; see [Additional resources](../../../index.html#additional-resources)). ## What to do now diff --git a/index.md b/index.md index 14efee0..2ae778f 100644 --- a/index.md +++ b/index.md @@ -24,7 +24,7 @@ The content is centered on system administration. It covers readiness and planni ## In this guide - [Before you deploy](docs/before-you-deploy.html) covers readiness checks, configuration decisions, compatibility guidance, and pre-deployment planning. -- [Deploy NBS 7](docs/deploy-nbs7.html) covers infrastructure, microservices, optional add-ons, and deployment validation steps. +- [Deploy NBS 7](docs/deploy-nbs7.html) covers infrastructure, microservices, add-ons, and deployment validation steps. - [Maintain NBS 7](docs/maintain-nbs7.html) covers post-deployment administration and maintenance tasks. ## Runtime environment support @@ -35,4 +35,6 @@ NBS 7 supports AWS and Azure as runtime options. The platform uses a cloud-agnos The primary audience is system administrators at state, tribal, local, and territorial health departments who install, operate, and maintain NBS 7. The content assumes familiarity with your cloud platform, Kubernetes, Terraform, Helm, and related administration tasks. You need administrator-level access to your runtime environment and a local system with required prerequisites installed. -For more information on NBS, see the official CDC [National Electronic Disease Surveillance System Base System (NBS)](https://www.cdc.gov/nbs/php/index.html) website. +## Additional resources + +For more information on NBS, see the official CDC [National Electronic Disease Surveillance System Base System (NBS)](https://www.cdc.gov/nbs/php/index.html) website and [NBS Central](https://nbscentral.cdc.gov/login), the community hub for NBS users where you can download software, access technical resources, and participate in user group calls. Access to NBS Central requires a login. To register for an NBS Central account, choose **Register** at the top of the login screen. From 71974caf87a8195a364cc33408ea50a8022961f7 Mon Sep 17 00:00:00 2001 From: jburgh Date: Wed, 6 May 2026 13:40:22 -0400 Subject: [PATCH 05/16] Remove 2 trailing spaces found in lint. --- docs/before-you-deploy/component-reference.md | 2 +- docs/before-you-deploy/operational-considerations.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/before-you-deploy/component-reference.md b/docs/before-you-deploy/component-reference.md index ac3719f..2faa0d5 100644 --- a/docs/before-you-deploy/component-reference.md +++ b/docs/before-you-deploy/component-reference.md @@ -12,7 +12,7 @@ description: Describes each NBS 7 component — what it does, when it is needed, The pages in this section describe each component in NBS 7. Use it to understand what each component does, why it is included in your deployment, and how it relates to other components. -NBS 7 is deployed in phases. Components in this reference are organized by deployment phase: +NBS 7 is deployed in phases. Components in this reference are organized by deployment phase: - [NBS 7 core deployment](../before-you-deploy/component-reference/nbs-core-components.html) - [Real-Time Reporting (RTR) deployment](../before-you-deploy/component-reference/rtr.html) diff --git a/docs/before-you-deploy/operational-considerations.md b/docs/before-you-deploy/operational-considerations.md index 9d67188..09549e0 100644 --- a/docs/before-you-deploy/operational-considerations.md +++ b/docs/before-you-deploy/operational-considerations.md @@ -69,7 +69,7 @@ See also: [RTR component reference](../before-you-deploy/component-reference/rtr ## The Data Ingestion API adds a secure integration option -The Data Ingestion (DI) API is a built-in REST API layer that accepts lab reports and case reports. It gives jurisdictions an API-based ingestion path, which is useful when security constraints prevent middleware or other third-party tools from connecting directly to the NBS database. +The Data Ingestion (DI) API is a built-in REST API layer that accepts lab reports and case reports. It gives jurisdictions an API-based ingestion path, which is useful when security constraints prevent middleware or other third-party tools from connecting directly to the NBS database. See also: [DI API component reference](../before-you-deploy/component-reference/di-api.html) and [Data ingestion microservice](../deploy-nbs7/microservices-deployment/data-ingestion.html). From 699ad965b8feda634a1aa39b5730f1d587162fa5 Mon Sep 17 00:00:00 2001 From: jburgh Date: Wed, 6 May 2026 13:48:00 -0400 Subject: [PATCH 06/16] Make bullets start with capital letter on BYD page. Move NBSC login info to a note. --- docs/before-you-deploy.md | 10 +++++----- index.md | 5 ++++- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/before-you-deploy.md b/docs/before-you-deploy.md index 945759c..aa90153 100644 --- a/docs/before-you-deploy.md +++ b/docs/before-you-deploy.md @@ -8,16 +8,16 @@ description: Evaluation and planning content to help you assess NBS 7 readiness # Before deploying NBS 7 -This section is for STLT IT administrators and technical decision-makers who are evaluating and preparing for NBS 7. It brings together the readiness, compatibility, configuration, and planning information you need before deployment begins. Use it to understand what NBS 7 includes, what decisions your jurisdiction needs to make, and what conditions should be in place before you move into deployment work. It is intended to support an informed decision about whether to proceed with NBS 7 deployment planning. +This section is for STLT IT administrators and technical decision-makers who are evaluating and preparing for NBS 7. It brings together the readiness, compatibility, configuration, and planning information you need before deployment begins. Use it to understand what NBS 7 includes, what decisions your jurisdiction needs to make, and what conditions should be in place before you move into deployment work. It is intended to support an informed decision about how to proceed with NBS 7 deployment planning. ## Purpose Use this section to: -- assess whether NBS 7 deployment planning is the right next step for your jurisdiction -- identify the right starting configuration for your jurisdiction, including optional add-ons -- understand the major components, prerequisites, and operational considerations that affect deployment -- support go or no-go decisions before you commit time and resources to deployment +- Assess whether NBS 7 deployment planning is the right next step for your jurisdiction +- Identify the right starting configuration for your jurisdiction, including optional add-ons +- Understand the major components, prerequisites, and operational considerations that affect deployment +- Support go or no-go decisions before you commit time and resources to deployment > Some factors that affect NBS 7 migration extend beyond infrastructure and configuration. For a summary of organizational, financial, and operational considerations, see [Operational considerations](before-you-deploy/operational-considerations.html). {: .note } diff --git a/index.md b/index.md index 2ae778f..02362fb 100644 --- a/index.md +++ b/index.md @@ -37,4 +37,7 @@ The primary audience is system administrators at state, tribal, local, and terri ## Additional resources -For more information on NBS, see the official CDC [National Electronic Disease Surveillance System Base System (NBS)](https://www.cdc.gov/nbs/php/index.html) website and [NBS Central](https://nbscentral.cdc.gov/login), the community hub for NBS users where you can download software, access technical resources, and participate in user group calls. Access to NBS Central requires a login. To register for an NBS Central account, choose **Register** at the top of the login screen. +For more information on NBS, see the official CDC [National Electronic Disease Surveillance System Base System (NBS)](https://www.cdc.gov/nbs/php/index.html) website and [NBS Central](https://nbscentral.cdc.gov/), the community hub for NBS users where you can download software, access technical resources, and participate in user group calls. + +> Access to **NBS Central** requires a login. To register for an NBS Central account, choose **Register** at the top of the [login screen](https://nbscentral.cdc.gov/login). +{: .note } From ba7466ec953dcdd5029ce4da564072dbdc9ba3c4 Mon Sep 17 00:00:00 2001 From: jburgh Date: Thu, 7 May 2026 15:00:41 -0400 Subject: [PATCH 07/16] Continuing edits from CDC final review --- .../assess-your-readiness.md | 11 +++--- .../component-reference/di-api.md | 4 +-- .../nbs-core-components.md | 4 +-- .../component-reference/rtr.md | 4 +-- ...yment-phases.md => deployment-overview.md} | 35 ++++++++++--------- .../operational-considerations.md | 4 +-- docs/deploy-nbs7.md | 1 - 7 files changed, 31 insertions(+), 32 deletions(-) rename docs/before-you-deploy/{deployment-phases.md => deployment-overview.md} (84%) diff --git a/docs/before-you-deploy/assess-your-readiness.md b/docs/before-you-deploy/assess-your-readiness.md index e6e593a..763d4b5 100644 --- a/docs/before-you-deploy/assess-your-readiness.md +++ b/docs/before-you-deploy/assess-your-readiness.md @@ -23,7 +23,7 @@ For more information on migration planning, staffing, and budget, see [Operation ## Not sure where to start? -If you are new to NBS 7 deployment, [Deployment phases](../before-you-deploy/deployment-phases.html) provides an overview of an example rollout and where this readiness assessment fits. +If you are new to NBS 7 deployment, [Deployment overview](../before-you-deploy/deployment-overview.html) provides example stages in a typical rollout and where this readiness assessment fits. ## IT security approval @@ -40,7 +40,7 @@ NBS 7 requires a cloud-based environment for deployment. NBS 7 has not been test ### Amazon Web Services (AWS) -- **Strategic fit:** Preferred by jurisdictions with established AWS environments or those prioritizing a broad ecosystem of third-party security and data tools. +- **Strategic fit:** Preferred by jurisdictions with established AWS environments or those with existing AWS contract vehicles or organizational policies that standardize on AWS. - **Technical readiness:** Aligns with teams experienced in managing container-native architectures via Amazon Elastic Kubernetes Service (EKS) and mature Terraform workflows. - **Surveillance context:** Core components are extensively validated in AWS to ensure performance at peak ingestion volumes. @@ -73,7 +73,6 @@ See also: [Operational considerations](../before-you-deploy/operational-consider Before deployment, your network must meet the following requirements: - **NBS 6 and NBS 7 connectivity**: Each NBS 7 instance requires network connectivity to a corresponding NBS 6 instance. If your NBS 6 runs in a Virtual Private Cloud (VPC), that VPC must be connected to your NBS 7 environment. -- **VM co-location**: Any virtual machines (VMs) that you use for NBS 7 components must exist within the same network. - **Encryption**: Encryption is required for all virtual network traffic between NBS 6 and NBS 7 components. - **Outbound access**: Your cloud environment needs outbound internet access to reach CDC systems. - **TLS/SSL certificate management**: You need a process to provision and renew TLS/SSL certificates for encrypted traffic. @@ -92,15 +91,15 @@ During migration, NBS 7 components gradually replace NBS 6 functionality while N - You need to know your current NBS 6 hosting setup before you begin. Specifically, whether it is hosted on-premises or in the cloud, and if in the cloud, which provider. - **You must be running a compatible NBS 6.x version** before you can install any version of NBS 7. For more information, see [Compatibility matrix](../before-you-deploy/compatibility.html). -See also: [Deployment phases](../before-you-deploy/deployment-phases.html) and [Operational considerations](../before-you-deploy/operational-considerations.html). +See also: [Deployment overview](../before-you-deploy/deployment-overview.html) and [Operational considerations](../before-you-deploy/operational-considerations.html). ## Data migration -NBS 7 uses your existing NBS 6 database and does not require a schema migration. In most cases, no data migration is needed. +NBS 7 uses your existing NBS 6 database and does not require a schema migration. Unless you choose to move your database from on premises to the cloud, no data migration should be needed. If your current NBS 6 database is hosted on-premises and you plan to move it to the cloud as part of your migration, you will need to copy the data from your existing environment and restore it to the new environment using a standard database backup and restore process. If you are not moving your NBS 6 database, no data migration action is required. -See also: [Prerequisites for NBS 7 deployment](../deploy-nbs7/prerequisites.html#nbs-6-readiness), [Deployment scenarios](../before-you-deploy/deployment-scenarios.html), and [Deployment phases](../before-you-deploy/deployment-phases.html). +See also: [Prerequisites for NBS 7 deployment](../deploy-nbs7/prerequisites.html#nbs-6-readiness), [Deployment scenarios](../before-you-deploy/deployment-scenarios.html), and [Deployment overview](../before-you-deploy/deployment-overview.html). ## CDC coordination diff --git a/docs/before-you-deploy/component-reference/di-api.md b/docs/before-you-deploy/component-reference/di-api.md index e9909a1..859ea48 100644 --- a/docs/before-you-deploy/component-reference/di-api.md +++ b/docs/before-you-deploy/component-reference/di-api.md @@ -4,7 +4,7 @@ layout: page parent: Component reference grand_parent: Before you deploy nav_order: 3 -description: Details the Data Ingestion (DI) API add-on component, which provides a REST API layer for routing incoming data into NBS through middleware. +description: Details the Data Ingestion (DI) API component, which provides a REST API layer for routing incoming data into NBS through middleware. --- # Component reference: Data Ingestion (DI) API @@ -29,5 +29,5 @@ A REST API layer that accepts incoming public health data in multiple formats an | Attribute | Description | |:---|:---| | What it does in NBS 7 | Accepts Electronic Case Reports (eCR), HL7 v2.x electronic lab reports (ELRs), and Public Health Document Container (PHDC) files through a standard API interface. Middleware preprocesses, enriches, and formats the data, then sends it to the DI API for ingestion into NBS. This supports near-real-time ingestion and gives jurisdictions an option when they do not want middleware or other third-party tools writing directly to the NBS database. | -| When you need it | Use the DI API add-on when your jurisdiction needs an API-based ingestion path instead of direct database access. This is especially useful for jurisdictions with security constraints that prevent middleware from connecting directly to the NBS database. | +| When you need it | Use DI API for an API-based ingestion path instead of direct database access. This is especially useful for jurisdictions with security constraints that prevent middleware from connecting directly to the NBS database. | | Dependencies | Requires middleware such as Rhapsody or an equivalent integration engine. External senders such as laboratories, EHR systems, and health information exchanges continue to send data through middleware, which then sends the processed payload to the DI API. | diff --git a/docs/before-you-deploy/component-reference/nbs-core-components.md b/docs/before-you-deploy/component-reference/nbs-core-components.md index 41ca7d2..64fe960 100644 --- a/docs/before-you-deploy/component-reference/nbs-core-components.md +++ b/docs/before-you-deploy/component-reference/nbs-core-components.md @@ -123,11 +123,11 @@ The core SQL Server databases that store operational and reference data for NBS. |:---|:---| | What it does in NBS 7 | NBS\_ODSE (Operational Data Store) is the primary transactional database where case, patient, investigation, and event records are stored. NBS\_SRTE (System Reference Tables) stores reference and metadata used across NBS, including LOINC, SNOMED CT, and other code sets used for data validation and mapping. | | When you need it | Always. Both databases are required for all NBS 7 configurations. | -| Dependencies | Required by Legacy NBS 6, the Modernization API, Nifi, Debezium (if using RTR), and the DI API (if using the DI API add-on). | +| Dependencies | Required by Legacy NBS 6, the Modernization API, Nifi, Debezium (for RTR), and the DI API. | ## Infrastructure and networking layer components -The following components make up the infrastructure and networking layers of NBS 7. They are provisioned and managed primarily through Terraform and Helm, and most do not require configuration decisions from IT admins during the planning phase. They are documented here for awareness. +The following components make up the infrastructure and networking layers of NBS 7. They are provisioned and managed primarily through Terraform and Helm, and most do not require configuration decisions from IT admins during the [planning stage](../../before-you-deploy/deployment-overview.html#planning). They are documented here for awareness. Full configuration guidance is in the [Deploy NBS 7](../../deploy-nbs7.html) section of this guide. diff --git a/docs/before-you-deploy/component-reference/rtr.md b/docs/before-you-deploy/component-reference/rtr.md index 1b6e7f5..df50302 100644 --- a/docs/before-you-deploy/component-reference/rtr.md +++ b/docs/before-you-deploy/component-reference/rtr.md @@ -4,13 +4,13 @@ layout: page parent: Component reference grand_parent: Before you deploy nav_order: 2 -description: "Details the four components added by the Real-Time Reporting (RTR) add-on: Debezium, Kafka, RTR domain services, and RDB_Modern." +description: "Details the four components added by Real-Time Reporting (RTR): Debezium, Kafka, RTR domain services, and RDB_Modern." nav_enabled: true --- # Component reference: Real-Time Reporting (RTR) -RTR provides an event-driven reporting pipeline for near-real-time reporting. RTR replaces the legacy MasterETL batch process. During validation, both might run briefly in parallel to confirm that RTR output is accurate. Once validation is complete, plan to retire MasterETL. +RTR provides an event-driven reporting pipeline for near-real-time reporting. RTR aims to eventually replace the classic MasterETL batch process. During migration, both run in parallel until full feature equivalence is met. The following components are added to your NBS 7 deployment when you deploy RTR. diff --git a/docs/before-you-deploy/deployment-phases.md b/docs/before-you-deploy/deployment-overview.md similarity index 84% rename from docs/before-you-deploy/deployment-phases.md rename to docs/before-you-deploy/deployment-overview.md index 8261e5d..cdaed6a 100644 --- a/docs/before-you-deploy/deployment-phases.md +++ b/docs/before-you-deploy/deployment-overview.md @@ -3,13 +3,16 @@ title: Deployment overview layout: page parent: Before you deploy nav_order: 1 -description: An overview of the five phases involved in an NBS 7 deployment, from planning through steady state operations. +description: An overview of the five stages involved in an NBS 7 deployment, from planning through steady state operations. --- # Deployment overview NBS 7 deployments vary significantly by jurisdiction. If you are just getting started, this page can help you understand where the [Assess your readiness](assess-your-readiness.html) checklist fits in the overall process. +The activity tables on this page include links to resources in this guide and on NBS Central. Resources without links are suggested artifacts that your jurisdiction might create to support your migration. +{: .note } + -## Example deployment phases +## Example deployment stages -The phases in this table represent an example rollout scenario based on deployments to date. Your jurisdiction's timeline, activities, and sequence might differ depending on your infrastructure, staffing, and security requirements. For more information, see [Operational considerations](../before-you-deploy/operational-considerations.html). +The stages in this table represent an example rollout scenario based on deployments to date. Your jurisdiction's timeline, activities, and sequence might differ depending on your infrastructure, staffing, and security requirements. For more information, see [Operational considerations](../before-you-deploy/operational-considerations.html). -| Phase | Goal | Minimum duration | +| Stage | Goal | Minimum duration | |:---|:---|:---| | [Planning](#planning) | Establish your project team, [assess your readiness](assess-your-readiness.html), and create a customized migration plan | 2-5 months | | [Install](#install) | Provision cloud environments and deploy NBS 7 based on your [chosen configuration](choose-your-configuration.html) | 3-6 months | @@ -30,16 +33,14 @@ The phases in this table represent an example rollout scenario based on deployme | [Go-live](#go-live) | Complete cutover and launch NBS 7 in production | 1-4 months | | [Steady state](#steady-state) | Monitor live operations and maintain the system ongoing | Ongoing | -{: .note } -These are minimum estimates based on typical deployments. Actual timelines vary by jurisdiction. Security approval, procurement, and legal review processes are common sources of extended timelines in the Planning and Install phases. - -For detailed checklists and deliverables for each phase, see the [NBS 7 Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) on NBS Central (login required; see [Additional resources](../../index.html#additional-resources)). +These are minimum estimates based on typical deployments. Actual timelines vary by jurisdiction. Security approval, procurement, and legal review processes are common sources of extended timelines in the Planning and Install stages. +{: .important } --- ## Planning -The Planning phase covers discovery, environment setup, and project preparation. Security approval for cloud-hosting and required technologies including Kubernetes, Terraform, and Docker can be a source of delay across the entire deployment. Starting that process early tends to reduce overall deployment time. +The Planning stage covers discovery, environment setup, and project preparation. Security approval for cloud-hosting and required technologies including Kubernetes, Terraform, and Docker can be a source of delay across the entire deployment. Starting that process early tends to reduce overall deployment time. Before planning detailed timelines, confirm that your current NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html). @@ -57,15 +58,15 @@ Before planning detailed timelines, confirm that your current NBS 6 version is c ## Install -The Install phase covers provisioning your cloud environments and deploying NBS 7 across development, staging, and production. This phase has a dependency on security approval processes, which might extend the timeline. +The Install stage covers provisioning your cloud environments and deploying NBS 7 across development, staging, and production. This stage has a dependency on security approval processes, which might extend the timeline. | Activity | Description | Resource | |:---|:---|:---| | Data migration plan | Agree on and review the data migration plan, coordinate the data migration solution and test files | [Assess your readiness: Data migration](../before-you-deploy/assess-your-readiness.html#data-migration) | -| Dev environment deployment | Create and deploy an initial NBS 7 development environment build | [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html) | -| Staging environment deployment | Create and deploy an initial NBS 7 test environment build | [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html) | -| Production environment deployment | Create and deploy an initial NBS 7 production environment build | [Deploy NBS 7 microservices](../deploy-nbs7/deploy-nbs7-microservices.html) | -| Complete database transfer | Complete customizations, user file sharing setup, and integration with your user management system | STLT database refresh procedure | +| Dev environment deployment | Create and deploy an initial NBS 7 development environment build | [Deploy NBS 7](../deploy-nbs7.html) | +| Staging environment deployment | Create and deploy an initial NBS 7 test environment build | [Deploy NBS 7](../deploy-nbs7.html) | +| Production environment deployment | Create and deploy an initial NBS 7 production environment build | [Deploy NBS 7](../deploy-nbs7.html) | +| Complete database transfer | Complete customizations, user file sharing setup, and integration with your user management system | Your own db refresh procedure | | Roles and permissions migration | Map user roles and configure permissions in NBS 7 | User migration mapping | | SSO setup | Review jurisdictional SSO and login requirements and integrate Keycloak with your existing login tools. See [Operational considerations](../before-you-deploy/operational-considerations.html) for SSO planning guidance | [Enable Keycloak authentication](../deploy-nbs7/keycloak/enable-keycloak-auth.html) | @@ -73,7 +74,7 @@ The Install phase covers provisioning your cloud environments and deploying NBS ## Test -The Test phase validates that your NBS 7 environment is ready for production use. This phase also has a dependency on security processes and might run concurrently with some Install activities. +The Test stage validates that your NBS 7 environment is ready for production use. This stage also has a dependency on security processes and might run concurrently with some Install activities. | Activity | Description | Resource | |:---|:---|:---| @@ -89,7 +90,7 @@ The Test phase validates that your NBS 7 environment is ready for production use ## Go-live -The Go-live phase covers final preparation, cutover, and launch. This phase is shorter than the others but involves time-sensitive coordination across your team. In many jurisdictions, this cutover follows work in a separate migration environment rather than direct changes on the primary NBS 6 production server. +The Go-live stage covers final preparation, cutover, and launch. This stage is shorter than the others but involves time-sensitive coordination across your team. In many jurisdictions, this cutover follows work in a separate migration environment rather than direct changes on the primary NBS 6 production server. | Activity | Description | Resource | |:---|:---|:---| @@ -102,7 +103,7 @@ The Go-live phase covers final preparation, cutover, and launch. This phase is s ## Steady state -After go-live, your jurisdiction enters steady state operations. This phase is ongoing and includes monitoring, support, and periodic upgrades as new NBS 7 releases become available. +After go-live, your jurisdiction enters steady state operations. This stage is ongoing and includes monitoring, support, and periodic upgrades as new NBS 7 releases become available. | Activity | Description | Resource | |:---|:---|:---| diff --git a/docs/before-you-deploy/operational-considerations.md b/docs/before-you-deploy/operational-considerations.md index 09549e0..a3bb8ae 100644 --- a/docs/before-you-deploy/operational-considerations.md +++ b/docs/before-you-deploy/operational-considerations.md @@ -11,7 +11,7 @@ redirect_from: # Operational considerations -This page covers organizational, financial, and operational factors that affect NBS 7 migration planning. Some of these factors involve decisions or timelines that extend beyond the technical team and might be worth raising with others in your organization early in your planning process. +This page covers organizational, financial, and operational factors that affect NBS 7 migration planning. Some migration factors involve decisions or timelines that extend beyond the technical team and might be worth raising with others in your organization early in your planning process. ## On this page {: .no_toc .text-delta } @@ -27,7 +27,7 @@ For technical deployment guidance, refer to [Assess your readiness](../before-yo NBS 7 does not replace NBS 6 in a single switch. Both systems run in parallel during the transition. NBS 7 components gradually take over functionality while NBS 6 continues to operate. The length of this parallel period depends on your jurisdiction's pace of deployment and configuration choices. Planning for the operational complexity and cost of maintaining two systems simultaneously is an integral part of migration preparation. Many jurisdictions provision a separate NBS 6 environment for migration activities and then cut over, rather than making these changes directly on their primary NBS 6 production server. -See also: [Deployment phases](../before-you-deploy/deployment-phases.html) and [Deployment scenarios](../before-you-deploy/deployment-scenarios.html). +See also: [Deployment overview](../before-you-deploy/deployment-overview.html) and [Deployment scenarios](../before-you-deploy/deployment-scenarios.html). Version prerequisite: confirm your NBS 6 baseline against the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html) before you finalize migration timelines. diff --git a/docs/deploy-nbs7.md b/docs/deploy-nbs7.md index 3193d49..e4691b9 100644 --- a/docs/deploy-nbs7.md +++ b/docs/deploy-nbs7.md @@ -13,7 +13,6 @@ This section covers the full NBS 7 deployment process, from prerequisites and in > The procedures in this section reflect NBS {{ site.version_latest }}. For earlier releases, see **Previous Versions** in the sidebar. {: .note } - - -> Best for -> -> Might apply to jurisdictions that have a large IT team or vendor support, high case volumes, advanced reporting or analytics needs, and require high-availability infrastructure. -{: .note-title } diff --git a/docs/before-you-deploy/deployment-scenarios/medium-jurisdiction.md b/docs/before-you-deploy/deployment-scenarios/medium-jurisdiction.md deleted file mode 100644 index adeb280..0000000 --- a/docs/before-you-deploy/deployment-scenarios/medium-jurisdiction.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Medium jurisdiction, hybrid hosting -layout: page -parent: Deployment scenarios -grand_parent: Before you deploy -nav_order: 2 -description: Case study for a medium jurisdiction with existing Rhapsody middleware deploying NBS Core + RTR, based on Kentucky's experience. ---- - -## Case study: RTR with middleware - -1. TOC -{:toc} - ---- - -### Profile - -Medium STLT with an existing Rhapsody middleware investment and a need for faster data turnaround than NBS 6 batch processing provides. The jurisdiction retained Rhapsody for data ingestion. - -### Configuration - -| Deployment model | Hosting | -|:---|:---| -| NBS 7 + RTR | Hybrid: cloud-hosted NBS 7, on-premises Rhapsody middleware | - -### What was deployed - -| Component | Included | Notes | -|:---|:---|:---| -| NBS 7 | Yes | Full core deployment | -| Real-Time Reporting (RTR) | Yes | Added for faster reporting turnaround | -| DI API | No | Rhapsody for data ingestion | - - - -> Best for -> -> Might apply to jurisdictions that have existing middleware such as Rhapsody or Mirth Connect that you want to retain, and you need faster reporting turnaround than NBS 6 provides. -{: .note-title } diff --git a/docs/before-you-deploy/deployment-scenarios/small-jurisdiction.md b/docs/before-you-deploy/deployment-scenarios/small-jurisdiction.md deleted file mode 100644 index 44cf49e..0000000 --- a/docs/before-you-deploy/deployment-scenarios/small-jurisdiction.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Small jurisdiction, self-managed cloud -layout: page -parent: Deployment scenarios -grand_parent: Before you deploy -nav_order: 1 -description: Case study for a small, self-managed AWS deployment based on Montana's experience, covering configuration choices and lessons learned. ---- - -## Case study: Minimal cloud deployment - -1. TOC -{:toc} - ---- - -### Profile - -Small STLT with limited IT staff and a cloud-first infrastructure strategy. The jurisdiction prioritized simplicity and maintainability over add-on features. - -### Configuration - -| Deployment model | Hosting | -|:---|:---| -| NBS core components only | AWS, STLT-managed | - -### What was deployed - -| Component | Included | Notes | -|:---|:---|:---| -| NBS 7 | Yes | Full core deployment | -| Real-Time Reporting (RTR) | No | Not required at this case volume | -| DI API | No | No existing high-volume ELR or eCR intake | - - - -> Best for -> -> Might apply to jurisdictions that have a small IT team, limited cloud experience, or a goal to get NBS 7 running with minimal complexity before adding advanced features. -{: .note-title } diff --git a/docs/before-you-deploy/operational-considerations.md b/docs/before-you-deploy/operational-considerations.md index a3bb8ae..a70d300 100644 --- a/docs/before-you-deploy/operational-considerations.md +++ b/docs/before-you-deploy/operational-considerations.md @@ -2,7 +2,7 @@ title: Operational considerations layout: page parent: Before you deploy -nav_order: 0 +nav_order: 3 description: Summarizes organizational, financial, and operational factors that affect NBS 7 migration planning. redirect_from: - /docs/before-you-deploy/operational_considerations.html @@ -65,7 +65,7 @@ See also: [Assess your readiness](../before-you-deploy/assess-your-readiness.htm The Real-Time Reporting (RTR) add-on reduces the time for data to appear in reports from up to 24 hours to between 5 minutes and 1 hour. For jurisdictions managing active outbreaks or time-sensitive disease investigations, this improvement can meaningfully affect response time. RTR also adds infrastructure complexity and requires additional cloud resources. The reporting speed benefit and the additional operating cost are both worth weighing against your jurisdiction's case volume and reporting needs. -See also: [RTR component reference](../before-you-deploy/component-reference/rtr.html), [Real-time reporting deployment](../deploy-nbs7/real-time-reporting/real-time-reporting.html), and [Choose your configuration](../before-you-deploy/choose-your-configuration.html). +See also: [RTR component reference](../before-you-deploy/component-reference/rtr.html), [Real-time reporting deployment](../deploy-nbs7/real-time-reporting/real-time-reporting.html), and [Deployment phases](../before-you-deploy/deployment-phases.html). ## The Data Ingestion API adds a secure integration option diff --git a/docs/before-you-deploy/choose-your-configuration/vendor-managed-deployment.md b/docs/before-you-deploy/vendor-managed-deployment.md similarity index 88% rename from docs/before-you-deploy/choose-your-configuration/vendor-managed-deployment.md rename to docs/before-you-deploy/vendor-managed-deployment.md index 24ac221..731d3d2 100644 --- a/docs/before-you-deploy/choose-your-configuration/vendor-managed-deployment.md +++ b/docs/before-you-deploy/vendor-managed-deployment.md @@ -28,8 +28,8 @@ Share the following with your vendor before scoping work: Then: 1. Contact [nbs@cdc.gov](mailto:nbs@cdc.gov) to let CDC know you are planning a vendor-managed deployment and to access vendor coordination resources. -2. Work with your vendor to complete steps 4–8 of the [decision tree](decision-tree.html) to identify your recommended configuration tier. -3. Return to the [component reference](../component-reference.html) for the configuration parameters your vendor will need. +2. Work with your vendor to review the [NBS 7 deployment phases](deployment-phases.html) to plan your timeline. +3. Refer to the [component reference](../component-reference.html) for the configuration parameters your vendor will need. > Vendors with Kubernetes and cloud infrastructure expertise can deploy NBS 7, but they will need detailed technical guidance from CDC and from this guide to do it accurately. Plan for a close working relationship between your vendor and the CDC NBS team, especially during initial deployment. Also plan for the funding needed to sustain vendor support beyond initial deployment. Ongoing maintenance costs are a common planning gap. Use the [NBS 7 Resource Estimator](https://nbscentral.cdc.gov/documents/872) to support cloud cost projections (NBS Central login required; see [Additional resources](../../../index.html#additional-resources)). {: .note } diff --git a/docs/deploy-nbs7/prerequisites.md b/docs/deploy-nbs7/prerequisites.md index 9d2c9d5..4e9df62 100644 --- a/docs/deploy-nbs7/prerequisites.md +++ b/docs/deploy-nbs7/prerequisites.md @@ -79,7 +79,7 @@ Your deployment team should include at least one person who has: If your team does not have this expertise, you have two options: - **Build internal capacity:** Train existing staff or hire staff with these skills before you begin deployment. -- **Vendor-managed deployment:** Contract with a vendor to deploy or manage your NBS 7 infrastructure. See [Vendor-managed deployment](../before-you-deploy/choose-your-configuration/vendor-managed-deployment.html) for guidance on what to look for in a vendor. +- **Vendor-managed deployment:** Contract with a vendor to deploy or manage your NBS 7 infrastructure. See [Vendor-managed deployment](../before-you-deploy/vendor-managed-deployment.html) for guidance on what to look for in a vendor. ## Software versions @@ -96,5 +96,5 @@ NBS 7 requires specific versions of supporting software. The following table lis After completing these prerequisites: -1. If you are deploying on AWS, complete [Prerequisites for AWS](deploy-on-aws/prerequisites.html). -1. If you are deploying on Azure, complete [Prerequisites for Azure](deploy-on-azure/prerequisites.html). +1. If you are deploying on **AWS**, complete [Prerequisites for AWS](deploy-on-aws/prerequisites.html). +1. If you are deploying on **Azure**, complete [Prerequisites for Azure](deploy-on-azure/prerequisites.html). From 4b2f05e238b194ef612c42bc28442a8c20f7b860 Mon Sep 17 00:00:00 2001 From: jburgh Date: Thu, 14 May 2026 15:43:09 -0400 Subject: [PATCH 10/16] Move vendor-managed deployment to be direct child of BYD --- docs/before-you-deploy/compatibility.md | 2 +- docs/before-you-deploy/component-reference.md | 2 +- docs/before-you-deploy/deployment-phases.md | 2 +- docs/before-you-deploy/vendor-managed-deployment.md | 9 ++++----- 4 files changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/before-you-deploy/compatibility.md b/docs/before-you-deploy/compatibility.md index 1785585..67134a7 100644 --- a/docs/before-you-deploy/compatibility.md +++ b/docs/before-you-deploy/compatibility.md @@ -2,7 +2,7 @@ title: NBS 6 to 7 compatibility layout: page parent: Before you deploy -nav_order: 5 +nav_order: 6 nav_enabled: true description: Lists the NBS 6 and NBS 7 version combinations that have been tested and verified to function correctly. --- diff --git a/docs/before-you-deploy/component-reference.md b/docs/before-you-deploy/component-reference.md index 2faa0d5..edab8a1 100644 --- a/docs/before-you-deploy/component-reference.md +++ b/docs/before-you-deploy/component-reference.md @@ -2,7 +2,7 @@ title: Component reference layout: page parent: Before you deploy -nav_order: 6 +nav_order: 7 has_children: true description: Describes each NBS 7 component — what it does, when it is needed, and how it relates to other components — organized by NBS 7 core components and available add-ons. --- diff --git a/docs/before-you-deploy/deployment-phases.md b/docs/before-you-deploy/deployment-phases.md index f7723c7..64f2e40 100644 --- a/docs/before-you-deploy/deployment-phases.md +++ b/docs/before-you-deploy/deployment-phases.md @@ -2,7 +2,7 @@ title: Deployment phases layout: page parent: Before you deploy -nav_order: 4 +nav_order: 5 has_children: true description: Describes the three NBS 7 deployment phases (the )core deployment, Real-Time Reporting (RTR), and Data Ingestion (DI) API) and when to deploy each. --- diff --git a/docs/before-you-deploy/vendor-managed-deployment.md b/docs/before-you-deploy/vendor-managed-deployment.md index 731d3d2..1bc7841 100644 --- a/docs/before-you-deploy/vendor-managed-deployment.md +++ b/docs/before-you-deploy/vendor-managed-deployment.md @@ -1,13 +1,12 @@ --- -title: Vendor-managed deployment +title: Working with a vendor layout: page -parent: Choose your configuration -grand_parent: Before you deploy -nav_order: 2 +parent: Before you deploy +nav_order: 4 description: Guidance for jurisdictions using a vendor to host or maintain NBS 7, including what to evaluate in a vendor and how to coordinate with CDC. --- -# Vendor-managed deployment +# Vendor-managed NBS 7 deployments {: .no_toc } If you plan to use a vendor to host or maintain NBS 7, confirm that they can: From 18e9f849ec1cf2af50805e8034e25cbd4595cfdd Mon Sep 17 00:00:00 2001 From: jburgh Date: Fri, 15 May 2026 10:49:35 -0400 Subject: [PATCH 11/16] Reorder BYD pages and align file names with page names --- docs/before-you-deploy.md | 2 +- docs/before-you-deploy/assess-your-readiness.md | 12 ++++++------ docs/before-you-deploy/component-reference.md | 2 +- .../component-reference/nbs-core-components.md | 4 ++-- docs/before-you-deploy/deployment-phases.md | 2 +- docs/before-you-deploy/operational-considerations.md | 12 ++++++------ .../{deployment-overview.md => planning.md} | 12 ++++++------ docs/before-you-deploy/vendor-managed-deployment.md | 10 +++++----- docs/{before-you-deploy => }/compatibility.md | 7 +++---- docs/deploy-nbs7.md | 4 ++-- docs/deploy-nbs7/deploy-on-aws.md | 2 +- docs/deploy-nbs7/deploy-on-aws/prerequisites.md | 2 +- docs/deploy-nbs7/deploy-on-azure.md | 2 +- docs/deploy-nbs7/prerequisites.md | 2 +- docs/deploy-nbs7/quickstart.md | 2 +- docs/maintain-nbs7.md | 2 +- docs/revision-history.md | 2 +- 17 files changed, 40 insertions(+), 41 deletions(-) rename docs/before-you-deploy/{deployment-overview.md => planning.md} (92%) rename docs/{before-you-deploy => }/compatibility.md (91%) diff --git a/docs/before-you-deploy.md b/docs/before-you-deploy.md index aa90153..237e108 100644 --- a/docs/before-you-deploy.md +++ b/docs/before-you-deploy.md @@ -1,7 +1,7 @@ --- title: Before you deploy layout: page -nav_order: 2 +nav_order: 3 has_children: true description: Evaluation and planning content to help you assess NBS 7 readiness and choose a deployment configuration. --- diff --git a/docs/before-you-deploy/assess-your-readiness.md b/docs/before-you-deploy/assess-your-readiness.md index 6f6f49d..58fb2a8 100644 --- a/docs/before-you-deploy/assess-your-readiness.md +++ b/docs/before-you-deploy/assess-your-readiness.md @@ -23,7 +23,7 @@ For more information on migration planning, staffing, and budget, see [Operation ## Not sure where to start? -If you are new to NBS 7 deployment, [Deployment overview](../before-you-deploy/deployment-overview.html) provides example stages in a typical rollout and where this readiness assessment fits. +If you are new to NBS 7 deployment, [Deployment overview](../before-you-deploy/planning.html) provides example stages in a typical rollout and where this readiness assessment fits. ## IT security approval @@ -50,7 +50,7 @@ NBS 7 requires a cloud-based environment for deployment. NBS 7 has not been test - **Technical readiness:** Provides a streamlined experience for organizations running Windows-based workloads or requiring integration with Microsoft 365 and Power Platform tools. - **Surveillance context:** Supported via Terraform for configuration parity with AWS, allowing jurisdictions to meet internal mandates for Azure-hosted health data. -See also: [Deploy cloud infrastructure on AWS](../deploy-nbs7/deploy-on-aws.html), [Deploy cloud infrastructure on Azure](../deploy-nbs7/deploy-on-azure.html), and [Compatibility matrix](../before-you-deploy/compatibility.html). +See also: [Deploy cloud infrastructure on AWS](../deploy-nbs7/deploy-on-aws.html), [Deploy cloud infrastructure on Azure](../deploy-nbs7/deploy-on-azure.html), and [Compatibility matrix](../compatibility.html). ## Staff Kubernetes expertise @@ -89,9 +89,9 @@ During migration, NBS 7 components gradually replace NBS 6 functionality while N - Your NBS 6 instance must remain operational and accessible during migration. - Many jurisdictions provision a separate NBS 6 environment for migration activities and then cut over, rather than deploying NBS 7 changes directly against their primary NBS 6 production server. - You need to know your current NBS 6 hosting setup before you begin. Specifically, whether it is hosted on-premises or in the cloud, and if in the cloud, which provider. -- **You must be running a compatible NBS 6.x version** before you can install any version of NBS 7. For more information, see [Compatibility matrix](../before-you-deploy/compatibility.html). +- **You must be running a compatible NBS 6.x version** before you can install any version of NBS 7. For more information, see [Compatibility matrix](../compatibility.html). -See also: [Deployment overview](../before-you-deploy/deployment-overview.html) and [Operational considerations](../before-you-deploy/operational-considerations.html). +See also: [Deployment overview](../before-you-deploy/planning.html) and [Operational considerations](../before-you-deploy/operational-considerations.html). ## Data migration @@ -99,7 +99,7 @@ NBS 7 uses your existing NBS 6 database and does not require a schema migration. If your current NBS 6 database is hosted on-premises and you plan to move it to the cloud as part of your migration, you will need to copy the data from your existing environment and restore it to the new environment using a standard database backup and restore process. If you are not moving your NBS 6 database, no data migration action is required. -See also: [Prerequisites for NBS 7 deployment](../deploy-nbs7/prerequisites.html#nbs-6-readiness), [Deployment scenarios](../before-you-deploy/deployment-scenarios.html), and [Deployment overview](../before-you-deploy/deployment-overview.html). +See also: [Prerequisites for NBS 7 deployment](../deploy-nbs7/prerequisites.html#nbs-6-readiness), [Deployment scenarios](../before-you-deploy/deployment-phases.html), and [Deployment overview](../before-you-deploy/planning.html). ## CDC coordination @@ -109,6 +109,6 @@ Reach out to your CDC NBS point of contact before you begin deployment. CDC prov - Identify the right configuration for your jurisdiction - Connect you with other jurisdictions that have already migrated -See also: [Deployment phases ](../before-you-deploy/deployment-phases.html) and [Operational considerations](../before-you-deploy/operational-considerations.html). +See also: [Deployment phases](../before-you-deploy/deployment-phases.html) and [Operational considerations](../before-you-deploy/operational-considerations.html). **Contact:** [nbs@cdc.gov](mailto:nbs@cdc.gov) diff --git a/docs/before-you-deploy/component-reference.md b/docs/before-you-deploy/component-reference.md index edab8a1..2faa0d5 100644 --- a/docs/before-you-deploy/component-reference.md +++ b/docs/before-you-deploy/component-reference.md @@ -2,7 +2,7 @@ title: Component reference layout: page parent: Before you deploy -nav_order: 7 +nav_order: 6 has_children: true description: Describes each NBS 7 component — what it does, when it is needed, and how it relates to other components — organized by NBS 7 core components and available add-ons. --- diff --git a/docs/before-you-deploy/component-reference/nbs-core-components.md b/docs/before-you-deploy/component-reference/nbs-core-components.md index 64fe960..247163c 100644 --- a/docs/before-you-deploy/component-reference/nbs-core-components.md +++ b/docs/before-you-deploy/component-reference/nbs-core-components.md @@ -33,7 +33,7 @@ The existing NBS 6 application. A WildFly-based UI and backend that most STLTs c | Attribute | Description | |:---|:---| | What it does in NBS 7 | NBS Core does not replace NBS 6 immediately. Instead, it runs alongside it. During migration, the NBS Gateway routes requests between the legacy NBS 6 application and new NBS 7 services. NBS 6 continues to handle all functionality that has not yet been replaced by a modern NBS 7 equivalent. | -| When you need it | Always. An operational NBS 6 instance is a prerequisite for any NBS 7 deployment. You must be running a [compatible NBS 6 version](../../before-you-deploy/compatibility.html) before you can install NBS 7. | +| When you need it | Always. An operational NBS 6 instance is a prerequisite for any NBS 7 deployment. You must be running a [compatible NBS 6 version](../../compatibility.html) before you can install NBS 7. | | Dependencies | Required by NBS Gateway, Elasticsearch (via Nifi), and the NBS Modernization API. Must maintain network connectivity to your NBS 7 environment throughout the migration period. | ## NBS Modernization API @@ -127,7 +127,7 @@ The core SQL Server databases that store operational and reference data for NBS. ## Infrastructure and networking layer components -The following components make up the infrastructure and networking layers of NBS 7. They are provisioned and managed primarily through Terraform and Helm, and most do not require configuration decisions from IT admins during the [planning stage](../../before-you-deploy/deployment-overview.html#planning). They are documented here for awareness. +The following components make up the infrastructure and networking layers of NBS 7. They are provisioned and managed primarily through Terraform and Helm, and most do not require configuration decisions from IT admins during the [planning stage](../../before-you-deploy/planning.html#planning). They are documented here for awareness. Full configuration guidance is in the [Deploy NBS 7](../../deploy-nbs7.html) section of this guide. diff --git a/docs/before-you-deploy/deployment-phases.md b/docs/before-you-deploy/deployment-phases.md index 64f2e40..0745920 100644 --- a/docs/before-you-deploy/deployment-phases.md +++ b/docs/before-you-deploy/deployment-phases.md @@ -20,7 +20,7 @@ NBS 7 is deployed in phases. The first phase is the [core deployment](#phase-1-n After reviewing the phases, see [Assess your readiness](../before-you-deploy/assess-your-readiness.html) to confirm your jurisdiction is ready to begin. If your jurisdiction plans to use a vendor, see the [Vendor-managed deployment](../before-you-deploy/vendor-managed-deployment.html) page. -Before finalizing your configuration, verify that your NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html). +Before finalizing your configuration, verify that your NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](../compatibility.html). --- diff --git a/docs/before-you-deploy/operational-considerations.md b/docs/before-you-deploy/operational-considerations.md index a70d300..4ff6443 100644 --- a/docs/before-you-deploy/operational-considerations.md +++ b/docs/before-you-deploy/operational-considerations.md @@ -2,7 +2,7 @@ title: Operational considerations layout: page parent: Before you deploy -nav_order: 3 +nav_order: 2 description: Summarizes organizational, financial, and operational factors that affect NBS 7 migration planning. redirect_from: - /docs/before-you-deploy/operational_considerations.html @@ -27,9 +27,9 @@ For technical deployment guidance, refer to [Assess your readiness](../before-yo NBS 7 does not replace NBS 6 in a single switch. Both systems run in parallel during the transition. NBS 7 components gradually take over functionality while NBS 6 continues to operate. The length of this parallel period depends on your jurisdiction's pace of deployment and configuration choices. Planning for the operational complexity and cost of maintaining two systems simultaneously is an integral part of migration preparation. Many jurisdictions provision a separate NBS 6 environment for migration activities and then cut over, rather than making these changes directly on their primary NBS 6 production server. -See also: [Deployment overview](../before-you-deploy/deployment-overview.html) and [Deployment scenarios](../before-you-deploy/deployment-scenarios.html). +See also: [Deployment overview](../before-you-deploy/planning.html) and [Deployment scenarios](../before-you-deploy/deployment-phases.html). -Version prerequisite: confirm your NBS 6 baseline against the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html) before you finalize migration timelines. +Version prerequisite: confirm your NBS 6 baseline against the [NBS 6 and NBS 7 compatibility matrix](../compatibility.html) before you finalize migration timelines. ## IT security approval can take time @@ -41,7 +41,7 @@ See also: [Assess your readiness](../before-you-deploy/assess-your-readiness.htm CDC does not support on-premises installations of NBS 7. Your jurisdiction needs an active cloud account with Amazon Web Services (AWS) or Microsoft Azure and an ongoing budget to sustain cloud infrastructure costs. Cloud hosting costs scale with usage, so budget planning might account for both normal operations and surge scenarios such as outbreak response. Use the [NBS 7 Resource Estimator](https://nbscentral.cdc.gov/documents/872) to project cloud-hosting costs based on your jurisdiction's record volume (NBS Central login required; see [Additional resources](../../index.html#additional-resources)). -See also: [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html) and [Deployment scenarios](../before-you-deploy/deployment-scenarios.html). +See also: [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html) and [Deployment scenarios](../before-you-deploy/deployment-phases.html). ## Align cloud provider with jurisdictional strategy @@ -59,7 +59,7 @@ See also: [Assess your readiness > Cloud infrastructure](assess-your-readiness.h Migrating to NBS 7 involves skills that might differ from what your current NBS 6 team uses, including Kubernetes, Terraform, and cloud infrastructure management. Jurisdictions that assess their team's capacity early are poised to set more accurate migration timelines. Those without the necessary in-house expertise have typically built capacity or engaged a vendor before deployment. -See also: [Assess your readiness](../before-you-deploy/assess-your-readiness.html) and [Vendor-managed deployment](../before-you-deploy/choose-your-configuration/vendor-managed-deployment.html). +See also: [Assess your readiness](../before-you-deploy/assess-your-readiness.html) and [Vendor-managed deployment](../before-you-deploy/vendor-managed-deployment.html). ## Real-Time Reporting adds capability and cost @@ -71,7 +71,7 @@ See also: [RTR component reference](../before-you-deploy/component-reference/rtr The Data Ingestion (DI) API is a built-in REST API layer that accepts lab reports and case reports. It gives jurisdictions an API-based ingestion path, which is useful when security constraints prevent middleware or other third-party tools from connecting directly to the NBS database. -See also: [DI API component reference](../before-you-deploy/component-reference/di-api.html) and [Data ingestion microservice](../deploy-nbs7/microservices-deployment/data-ingestion.html). +See also: [DI API component reference](../before-you-deploy/component-reference/di-api.html) and [Data ingestion microservice](../deploy-nbs7/data-ingestion/data-ingestion.html). ## Single Sign-On requires early coordination diff --git a/docs/before-you-deploy/deployment-overview.md b/docs/before-you-deploy/planning.md similarity index 92% rename from docs/before-you-deploy/deployment-overview.md rename to docs/before-you-deploy/planning.md index a8faf72..c69a9ef 100644 --- a/docs/before-you-deploy/deployment-overview.md +++ b/docs/before-you-deploy/planning.md @@ -2,7 +2,7 @@ title: Deployment planning guide layout: page parent: Before you deploy -nav_order: 2 +nav_order: 3 description: An overview of the five stages involved in an NBS 7 deployment, from planning through steady state operations. --- @@ -42,14 +42,14 @@ These are minimum estimates based on typical deployments. Actual timelines vary The Planning stage covers discovery, environment setup, and project preparation. Security approval for cloud-hosting and required technologies including Kubernetes, Terraform, and Docker can be a source of delay across the entire deployment. Starting that process early tends to reduce overall deployment time. -Before planning detailed timelines, confirm that your current NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html). +Before planning detailed timelines, confirm that your current NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](../compatibility.html). | Activity | Description | Resource | |:---|:---|:---| -| Readiness check-in | Initial planning and review of frequently asked questions. See [Assess your readiness](../before-you-deploy/assess-your-readiness.html) for the technical checklist and [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html) for version alignment. | [Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) (NBS Central login required; see [Additional resources](../../index.html#additional-resources)) | +| Readiness check-in | Initial planning and review of frequently asked questions. See [Assess your readiness](../before-you-deploy/assess-your-readiness.html) for the technical checklist and [NBS 6 and NBS 7 compatibility matrix](../compatibility.html) for version alignment. | [Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) (NBS Central login required; see [Additional resources](../../index.html#additional-resources)) | | Identify project team | Define roles, responsibilities, and key stakeholders. See [Operational considerations](../before-you-deploy/operational-considerations.html) for staffing guidance | [Migration Info Sheet](https://nbscentral.cdc.gov/documents/731) (NBS Central login required; see [Additional resources](../../index.html#additional-resources)) | | NBS 7 orientation | Review NBS 7 features with your migration team.| [Component reference](../before-you-deploy/component-reference.html) | -| Create project plan | Draft a customized migration plan from the playbook checklists, including a migration risk registry | [Deployment scenarios](../before-you-deploy/deployment-scenarios.html) | +| Create project plan | Draft a customized migration plan from the playbook checklists, including a migration risk registry | [Deployment scenarios](../before-you-deploy/deployment-phases.html) | | Communications plan | Develop and implement a communications plan customized to your timeline and needs | Communications plan | | Training plan | Implement an NBS 7 training plan customized for your jurisdiction | STLT user training plan | | Draft test plan | Customize a UAT plan for your requirements | STLT user acceptance test plan | @@ -79,8 +79,8 @@ The Test stage validates that your NBS 7 environment is ready for production use | Activity | Description | Resource | |:---|:---|:---| | Database restore process | Review and test the database restore process in the development environment | STLT database refresh procedure | -| Ingestion and egress validation | Integrate and validate data ingestion and notification pathways to confirm pipelines | [Data ingestion API testing](../deploy-nbs7/microservices-deployment/data-ingestion/api-testing.html) if you are using the DI API | -| ELR and or eCR ingestion testing | Test ingestion for individual ELRs and eCRs and at scale | [Data ingestion smoke test](../deploy-nbs7/microservices-deployment/data-ingestion/smoke-test.html) | +| Ingestion and egress validation | Integrate and validate data ingestion and notification pathways to confirm pipelines | [Data ingestion API testing](../deploy-nbs7/data-ingestion/api-testing.html) if you are using the DI API | +| ELR and or eCR ingestion testing | Test ingestion for individual ELRs and eCRs and at scale | [Data ingestion smoke test](../deploy-nbs7/data-ingestion/smoke-test.html) | | Notifications testing | Coordinate with the MVPs team to validate notifications readiness | Conditions received successfully | | Regression testing | Run test scripts across environments to validate readiness for UAT | [Validate the deployment](../deploy-nbs7/validate-the-deployment.html) | | Cutover and rollback review | Review and approve cutover and rollback plans | Cutover and Rollback Plan | diff --git a/docs/before-you-deploy/vendor-managed-deployment.md b/docs/before-you-deploy/vendor-managed-deployment.md index 1bc7841..ab21894 100644 --- a/docs/before-you-deploy/vendor-managed-deployment.md +++ b/docs/before-you-deploy/vendor-managed-deployment.md @@ -15,20 +15,20 @@ If you plan to use a vendor to host or maintain NBS 7, confirm that they can: - Manage Terraform-based infrastructure provisioning - Support ongoing cloud infrastructure operations, including monitoring and incident response -> NBS 7 is a recent system with limited deployment history. Do not expect vendors to have direct NBS 7 experience. Evaluate vendors on their Kubernetes and cloud infrastructure expertise instead. You can share the [component reference](../component-reference.html) section of this guide with vendors to help them scope the work accurately. +> NBS 7 is a recent system with limited deployment history. Do not expect vendors to have direct NBS 7 experience. Evaluate vendors on their Kubernetes and cloud infrastructure expertise instead. You can share the [component reference](../before-you-deploy/component-reference.html) section of this guide with vendors to help them scope the work accurately. {: .important } Share the following with your vendor before scoping work: -- The [component reference](../component-reference.html) section of this guide +- The [component reference](../before-you-deploy/component-reference.html) section of this guide - The **NBS 7 Migration Info Sheet** (available from CDC) - Your current NBS 6 hosting setup and data volumes Then: 1. Contact [nbs@cdc.gov](mailto:nbs@cdc.gov) to let CDC know you are planning a vendor-managed deployment and to access vendor coordination resources. -2. Work with your vendor to review the [NBS 7 deployment phases](deployment-phases.html) to plan your timeline. -3. Refer to the [component reference](../component-reference.html) for the configuration parameters your vendor will need. +2. Work with your vendor to review the [NBS 7 deployment phases](../before-you-deploy/deployment-phases.html) to plan your timeline. +3. Refer to the [component reference](../before-you-deploy/component-reference.html) for the configuration parameters your vendor will need. -> Vendors with Kubernetes and cloud infrastructure expertise can deploy NBS 7, but they will need detailed technical guidance from CDC and from this guide to do it accurately. Plan for a close working relationship between your vendor and the CDC NBS team, especially during initial deployment. Also plan for the funding needed to sustain vendor support beyond initial deployment. Ongoing maintenance costs are a common planning gap. Use the [NBS 7 Resource Estimator](https://nbscentral.cdc.gov/documents/872) to support cloud cost projections (NBS Central login required; see [Additional resources](../../../index.html#additional-resources)). +> Vendors with Kubernetes and cloud infrastructure expertise can deploy NBS 7, but they will need detailed technical guidance from CDC and from this guide to do it accurately. Plan for a close working relationship between your vendor and the CDC NBS team, especially during initial deployment. Also plan for the funding needed to sustain vendor support beyond initial deployment. Ongoing maintenance costs are a common planning gap. Use the [NBS 7 Resource Estimator](https://nbscentral.cdc.gov/documents/872) to support cloud cost projections (NBS Central login required; see [Additional resources](../../index.html#additional-resources)). {: .note } diff --git a/docs/before-you-deploy/compatibility.md b/docs/compatibility.md similarity index 91% rename from docs/before-you-deploy/compatibility.md rename to docs/compatibility.md index 67134a7..fb72326 100644 --- a/docs/before-you-deploy/compatibility.md +++ b/docs/compatibility.md @@ -1,16 +1,15 @@ --- title: NBS 6 to 7 compatibility layout: page -parent: Before you deploy -nav_order: 6 +nav_order: 2 nav_enabled: true -description: Lists the NBS 6 and NBS 7 version combinations that have been tested and verified to function correctly. +description: Lists the NBS 6 and NBS 7 version combinations that have been tested and verified to function together. --- # NBS 6 and NBS 7 compatibility {: .no_toc } -NBS 7 integrates with and is tested against supported versions of NBS 6. Use this table to verify that your NBS 6 version is compatible with your target NBS 7 version before you begin deployment. Running the latest supported version of NBS 6 is recommended for migration. As of the most recent release, that version is **NBS 6.0.19.1**. +NBS 7 integrates with and is tested against supported versions of NBS 6. Use this table to verify that your NBS 6 version is compatible with your target NBS 7 version before you begin deployment. Running the latest supported version of NBS 6 is recommended for migration. The following table shows which NBS 6 versions have been tested and verified as compatible with each supported NBS 7 version. diff --git a/docs/deploy-nbs7.md b/docs/deploy-nbs7.md index f60abb8..3286581 100644 --- a/docs/deploy-nbs7.md +++ b/docs/deploy-nbs7.md @@ -1,7 +1,7 @@ --- title: Deploy NBS 7 layout: page -nav_order: 3 +nav_order: 4 has_children: true description: Step-by-step instructions for deploying NBS 7. --- @@ -13,7 +13,7 @@ This section covers the full NBS 7 deployment process, from prerequisites and in > The procedures in this section reflect NBS {{ site.version_latest }}. For earlier releases, see **Previous Versions** in the sidebar. {: .note } -Before you begin, confirm that your NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](before-you-deploy/compatibility.html). +Before you begin, confirm that your NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](compatibility.html). NBS 7 deployment comprises the following main phases that you should complete in order: diff --git a/docs/deploy-nbs7/deploy-on-aws.md b/docs/deploy-nbs7/deploy-on-aws.md index 1591ced..14440e4 100644 --- a/docs/deploy-nbs7/deploy-on-aws.md +++ b/docs/deploy-nbs7/deploy-on-aws.md @@ -14,7 +14,7 @@ redirect_from: This section walks you through provisioning the AWS cloud environment for NBS 7. You will verify that your AWS account, hardware, software, and network requirements are in place, then use Terraform to provision the VPC, Amazon Elastic Kubernetes Service (Amazon EKS) cluster, and supporting AWS services. Complete both steps in order before moving on to [Deploy cluster infrastructure](../deploy-nbs7/cluster-infrastructure.html). -Before provisioning infrastructure, verify that your NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html). +Before provisioning infrastructure, verify that your NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](../compatibility.html). ## What gets provisioned diff --git a/docs/deploy-nbs7/deploy-on-aws/prerequisites.md b/docs/deploy-nbs7/deploy-on-aws/prerequisites.md index 763c1c3..e0184c5 100644 --- a/docs/deploy-nbs7/deploy-on-aws/prerequisites.md +++ b/docs/deploy-nbs7/deploy-on-aws/prerequisites.md @@ -27,7 +27,7 @@ Before you deploy NBS 7, make sure your environment meets the requirements in ea Your AWS environment must: -- Contain a pre-existing AWS account that contains a production instance of NBS 6 that is listed in the [NBS 6 and NBS 7 compatibility matrix](../../before-you-deploy/compatibility.html), plus related third-party products such as Rhapsody and SAS +- Contain a pre-existing AWS account that contains a production instance of NBS 6 that is listed in the [NBS 6 and NBS 7 compatibility matrix](../../compatibility.html), plus related third-party products such as Rhapsody and SAS - Have a properly configured DNS routing infrastructure - Be configured to enable you to create security groups and IAM roles - Provide access to NBS 6 databases that are located on an MS SQL Server instance (RDS or EC2) diff --git a/docs/deploy-nbs7/deploy-on-azure.md b/docs/deploy-nbs7/deploy-on-azure.md index 2571a27..df0cb6f 100644 --- a/docs/deploy-nbs7/deploy-on-azure.md +++ b/docs/deploy-nbs7/deploy-on-azure.md @@ -11,7 +11,7 @@ description: Provision the Azure cloud environment for NBS 7. Deployment guide c Azure deployment documentation is in progress. For assistance with Azure deployments, contact [nbs@cdc.gov](mailto:nbs@cdc.gov). -Before provisioning infrastructure, verify that your NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html). +Before provisioning infrastructure, verify that your NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](../compatibility.html). ## In this section diff --git a/docs/deploy-nbs7/prerequisites.md b/docs/deploy-nbs7/prerequisites.md index 4e9df62..4fa88c1 100644 --- a/docs/deploy-nbs7/prerequisites.md +++ b/docs/deploy-nbs7/prerequisites.md @@ -20,7 +20,7 @@ Before you begin deployment on any cloud provider, confirm that your jurisdictio Your NBS 6 instance is the foundation for NBS 7. Confirm the following: -- **Compatible version:** Your NBS 6 version must be compatible with your target NBS 7 version. Check the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html) before you begin. +- **Compatible version:** Your NBS 6 version must be compatible with your target NBS 7 version. Check the [NBS 6 and NBS 7 compatibility matrix](../compatibility.html) before you begin. - **Database access and refresh:** If your current NBS 6 database is hosted on-premises and you plan to move it to the cloud, you must complete a database refresh and ensure that the database is accessible from your test environment. This is typically a jurisdiction-managed procedure using your organization's standard database backup and restore process. - **Database server access:** Your cloud environment must have network access to your NBS 6 database server (either on-premises RDS or EC2 instance, depending on your hosting setup). If the database is on-premises, network connectivity must be established before deployment begins. - **Related applications:** Any third-party products integrated with NBS 6, such as Rhapsody or SAS, must remain operational during the NBS 7 migration. Confirm that these systems will remain accessible from your NBS 7 environment. diff --git a/docs/deploy-nbs7/quickstart.md b/docs/deploy-nbs7/quickstart.md index 766f7b4..39716af 100644 --- a/docs/deploy-nbs7/quickstart.md +++ b/docs/deploy-nbs7/quickstart.md @@ -23,7 +23,7 @@ This page provides a streamlined path to deploy NBS 7 infrastructure and core mi This guide is not intended for production deployment. For full production steps and guidance, see [Deploy NBS 7](../deploy-nbs7.html). {: .important } -Before starting this quick start, confirm your NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](../before-you-deploy/compatibility.html). +Before starting this quick start, confirm your NBS 6 version is compatible with your target NBS 7 version in the [NBS 6 and NBS 7 compatibility matrix](../compatibility.html). This quick start installs and configures the following resources. diff --git a/docs/maintain-nbs7.md b/docs/maintain-nbs7.md index f94c4e6..580434b 100644 --- a/docs/maintain-nbs7.md +++ b/docs/maintain-nbs7.md @@ -1,7 +1,7 @@ --- title: Maintain NBS 7 layout: page -nav_order: 4 +nav_order: 5 has_children: true description: Operational guidance for maintaining your NBS 7 deployment after go-live. --- diff --git a/docs/revision-history.md b/docs/revision-history.md index 95a4dec..8ea17d3 100644 --- a/docs/revision-history.md +++ b/docs/revision-history.md @@ -1,7 +1,7 @@ --- title: Revision history layout: page -nav_order: 5 +nav_order: 6 description: A record of significant updates to the NBS 7 System Administrator Guide. --- From 97ad84e3f14f405a59003c00c5f1399cffb6cc67 Mon Sep 17 00:00:00 2001 From: jburgh Date: Fri, 5 Jun 2026 14:27:55 -0400 Subject: [PATCH 12/16] Clean up and revise planning guide based on CDC feedback --- .../assess-your-readiness.md | 2 +- docs/before-you-deploy/deployment-phases.md | 6 +- .../operational-considerations.md | 8 +- docs/before-you-deploy/planning.md | 80 ++++++++++--------- 4 files changed, 50 insertions(+), 46 deletions(-) diff --git a/docs/before-you-deploy/assess-your-readiness.md b/docs/before-you-deploy/assess-your-readiness.md index 58fb2a8..3bf2e39 100644 --- a/docs/before-you-deploy/assess-your-readiness.md +++ b/docs/before-you-deploy/assess-your-readiness.md @@ -36,7 +36,7 @@ See also: [Operational considerations](../before-you-deploy/operational-consider ## Cloud infrastructure -NBS 7 requires a cloud-based environment for deployment. NBS 7 has not been tested for on-premises deployment, and CDC does not plan to support it. To deploy with CDC support, you need an active account with one of the following supported cloud providers: +NBS 7 requires a cloud-based environment for deployment; CDC does not support on-premises installations. To deploy with CDC support, you need an active account with one of the following supported cloud providers: ### Amazon Web Services (AWS) diff --git a/docs/before-you-deploy/deployment-phases.md b/docs/before-you-deploy/deployment-phases.md index 0745920..8ba2d01 100644 --- a/docs/before-you-deploy/deployment-phases.md +++ b/docs/before-you-deploy/deployment-phases.md @@ -26,7 +26,7 @@ Before finalizing your configuration, verify that your NBS 6 version is compatib ## Phase 1: NBS 7 -The first phase is the base deployment. NBS 7 gives your jurisdiction NBS 6 feature parity on modern, cloud-based infrastructure, plus foundational improvements such as real-time patient search and ongoing incremental modernized modules and functional areas. +The first phase is the base deployment. NBS 7 gives your jurisdiction NBS 6 feature parity on modern, cloud-based infrastructure, with foundational improvements such as real-time patient search. Additional modules and functional areas are modernized incrementally across releases. >When to deploy > @@ -75,7 +75,7 @@ RTR is the second deployment phase. It introduces an event-driven reporting pipe >When to deploy > ->Deploy Phase 2 after Phase 1 is stable in production. Jurisdictions with higher case volumes or time-sensitive reporting needs should prioritize this phase early. Jurisdictions with lower volumes can defer it, but RTR is part of the full deployment and should be planned from the start. +>Deploy Phase 2 after Phase 1 is stable. RTR is part of the full deployment and should be planned from the start. {: .note-title } RTR adds the following components to your NBS 7 deployment. For details, see [Add-on: Real-Time Reporting (RTR)](../before-you-deploy/component-reference/rtr.html). @@ -92,7 +92,7 @@ The DI API is the third deployment phase. It provides a built-in data transit la >When to deploy > ->Jurisdictions that need an API-based ingestion path due to security constraints should plan Phase 3 in parallel with or immediately after Phase 2. Jurisdictions using direct SQL writes through Rhapsody can defer Phase 3 until their integration requirements change. +>Jurisdictions that need an API-based ingestion path due to security constraints should plan Phase 3 in parallel with or immediately after Phase 2. {: .note-title } The DI API supports two integration methods. The right choice depends on your jurisdiction's security policies and how your middleware is deployed. diff --git a/docs/before-you-deploy/operational-considerations.md b/docs/before-you-deploy/operational-considerations.md index 4ff6443..4efe732 100644 --- a/docs/before-you-deploy/operational-considerations.md +++ b/docs/before-you-deploy/operational-considerations.md @@ -23,9 +23,9 @@ This page covers organizational, financial, and operational factors that affect For technical deployment guidance, refer to [Assess your readiness](../before-you-deploy/assess-your-readiness.html) and the rest of this guide. -## Migration is gradual, not a cutover +## Plan for parallel operations -NBS 7 does not replace NBS 6 in a single switch. Both systems run in parallel during the transition. NBS 7 components gradually take over functionality while NBS 6 continues to operate. The length of this parallel period depends on your jurisdiction's pace of deployment and configuration choices. Planning for the operational complexity and cost of maintaining two systems simultaneously is an integral part of migration preparation. Many jurisdictions provision a separate NBS 6 environment for migration activities and then cut over, rather than making these changes directly on their primary NBS 6 production server. +Migration from NBS 6 to NBS 7 concludes with a cutover from your existing NBS 6 instance to the new NBS 7 deployment. Both systems run in parallel during the transition, and the length of this parallel period depends on your jurisdiction's pace of deployment and the decisions made along the way. Some jurisdictions opt to provision a separate NBS 6 environment for migration activities before cutting over, rather than making changes directly on their primary NBS 6 production server. Planning for the operational complexity and cost of maintaining two systems simultaneously is an integral part of migration preparation. See also: [Deployment overview](../before-you-deploy/planning.html) and [Deployment scenarios](../before-you-deploy/deployment-phases.html). @@ -61,9 +61,9 @@ Migrating to NBS 7 involves skills that might differ from what your current NBS See also: [Assess your readiness](../before-you-deploy/assess-your-readiness.html) and [Vendor-managed deployment](../before-you-deploy/vendor-managed-deployment.html). -## Real-Time Reporting adds capability and cost +## Real-Time Reporting can be deployed as a follow-on -The Real-Time Reporting (RTR) add-on reduces the time for data to appear in reports from up to 24 hours to between 5 minutes and 1 hour. For jurisdictions managing active outbreaks or time-sensitive disease investigations, this improvement can meaningfully affect response time. RTR also adds infrastructure complexity and requires additional cloud resources. The reporting speed benefit and the additional operating cost are both worth weighing against your jurisdiction's case volume and reporting needs. +The Real-Time Reporting (RTR) pipeline reduces the time for data to appear in reports from up to 24 hours to between 5 minutes and 1 hour. For jurisdictions managing active outbreaks or time-sensitive disease investigations, this improvement can meaningfully affect response time. RTR adds infrastructure complexity and requires additional cloud resources. Jurisdictions that find RTR a significant lift at the time of initial deployment can choose to deploy core NBS 7 functionality first and adopt RTR as a follow-on. The reporting speed benefit and the additional operating cost are both worth weighing against your jurisdiction's case volume and reporting needs. See also: [RTR component reference](../before-you-deploy/component-reference/rtr.html), [Real-time reporting deployment](../deploy-nbs7/real-time-reporting/real-time-reporting.html), and [Deployment phases](../before-you-deploy/deployment-phases.html). diff --git a/docs/before-you-deploy/planning.md b/docs/before-you-deploy/planning.md index c69a9ef..6670c79 100644 --- a/docs/before-you-deploy/planning.md +++ b/docs/before-you-deploy/planning.md @@ -10,7 +10,7 @@ description: An overview of the five stages involved in an NBS 7 deployment, fro NBS 7 deployments vary significantly by jurisdiction. If you are just getting started, this page can help you understand where the [Assess your readiness](assess-your-readiness.html) checklist fits in the overall process. -The activity tables on this page include links to resources in this guide and on NBS Central. Resources without links are suggested artifacts that your jurisdiction might create to support your migration. +The tables on this page link to resources where available. Unlinked resources are suggested artifacts. If they fit your jurisdiction's needs, you would need to create them. {: .note } diff --git a/docs/before-you-deploy/deployment-phases.md b/docs/before-you-deploy/deployment-phases.md index 8ba2d01..d4ca54b 100644 --- a/docs/before-you-deploy/deployment-phases.md +++ b/docs/before-you-deploy/deployment-phases.md @@ -48,7 +48,7 @@ The networking layer manages traffic routing and secure communication between yo The infrastructure layer provides the container orchestration platform and cloud services that host and run NBS 7 components. - Kubernetes cluster (EKS on AWS, AKS on Azure) -- Traefik Ingress Controller (replaced NGINX as of NBS 7.12) +- Traefik Ingress Controller (as of NBS 7.12; formerly NGINX) - AWS or Azure managed services - Terraform infrastructure automation modules - Load balancer diff --git a/docs/before-you-deploy/planning.md b/docs/before-you-deploy/planning.md index 6670c79..b7d22dc 100644 --- a/docs/before-you-deploy/planning.md +++ b/docs/before-you-deploy/planning.md @@ -68,7 +68,7 @@ If security approval is still in progress when Install begins, it might extend t | Activity | Description | Suggested resource or action | |:---|:---|:---| | Deploy NBS 7 | Provision and deploy NBS 7 in your environment. Repeat for each environment in your jurisdiction's setup. | [Deploy NBS 7](../deploy-nbs7.html) | -| Transfer database | Complete customizations, user file sharing setup, and integration with your user management system. [SME REVIEW: confirm what activities this row covers.] | Use your own database refresh procedure | +| Transfer database | Complete customizations, user file sharing setup, and integration with your user management system. | Use your own database refresh procedure | | Migrate user roles and permissions | Map user roles and configure permissions in NBS 7. | Create a user migration map | | Configure SSO | Review SSO and login requirements and integrate Keycloak with your existing login tools. See [Operational considerations](../before-you-deploy/operational-considerations.html) for SSO planning guidance. | [Enable Keycloak authentication](../deploy-nbs7/keycloak/enable-keycloak-auth.html) | From dbdb0ab29e4857c2021be4f024a99d2683e56297 Mon Sep 17 00:00:00 2001 From: jburgh Date: Mon, 8 Jun 2026 17:17:21 -0400 Subject: [PATCH 15/16] Update page name for Planning guide in content. Remove links to scenarios --- docs/before-you-deploy/assess-your-readiness.md | 6 +++--- docs/before-you-deploy/operational-considerations.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/before-you-deploy/assess-your-readiness.md b/docs/before-you-deploy/assess-your-readiness.md index efa7d71..501a365 100644 --- a/docs/before-you-deploy/assess-your-readiness.md +++ b/docs/before-you-deploy/assess-your-readiness.md @@ -23,7 +23,7 @@ For more information on migration planning, staffing, and budget, see [Operation ## Not sure where to start? -If you are new to NBS 7 deployment, [Deployment overview](../before-you-deploy/planning.html) provides example stages in a typical rollout and where this readiness assessment fits. +If you are new to NBS 7 deployment, [Deployment planning guide](../before-you-deploy/planning.html) provides example stages in a typical rollout and where this readiness assessment fits. ## IT security approval @@ -90,7 +90,7 @@ Migration from NBS 6 to NBS 7 concludes with a cutover from your existing NBS 6 - You need to know your current NBS 6 hosting setup before you begin. Specifically, whether it is hosted on-premises or in the cloud, and if in the cloud, which provider. - **You must be running a compatible NBS 6.x version** before you can install any version of NBS 7. For more information, see [Compatibility matrix](../compatibility.html). -See also: [Deployment overview](../before-you-deploy/planning.html) and [Operational considerations](../before-you-deploy/operational-considerations.html). +See also: [Deployment planning guide](../before-you-deploy/planning.html) and [Operational considerations](../before-you-deploy/operational-considerations.html). ## Data migration @@ -98,7 +98,7 @@ NBS 7 uses your existing NBS 6 database and does not require a schema migration. If your current NBS 6 database is hosted on-premises and you plan to move it to the cloud as part of your migration, you will need to copy the data from your existing environment and restore it to the new environment using a standard database backup and restore process. If you are not moving your NBS 6 database, no data migration action is required. -See also: [Prerequisites for NBS 7 deployment](../deploy-nbs7/prerequisites.html#nbs-6-readiness), [Deployment scenarios](../before-you-deploy/deployment-phases.html), and [Deployment overview](../before-you-deploy/planning.html). +See also: [Prerequisites for NBS 7 deployment](../deploy-nbs7/prerequisites.html#nbs-6-readiness) and [Deployment planning guide](../before-you-deploy/planning.html). ## CDC coordination diff --git a/docs/before-you-deploy/operational-considerations.md b/docs/before-you-deploy/operational-considerations.md index 4efe732..d812f9d 100644 --- a/docs/before-you-deploy/operational-considerations.md +++ b/docs/before-you-deploy/operational-considerations.md @@ -27,7 +27,7 @@ For technical deployment guidance, refer to [Assess your readiness](../before-yo Migration from NBS 6 to NBS 7 concludes with a cutover from your existing NBS 6 instance to the new NBS 7 deployment. Both systems run in parallel during the transition, and the length of this parallel period depends on your jurisdiction's pace of deployment and the decisions made along the way. Some jurisdictions opt to provision a separate NBS 6 environment for migration activities before cutting over, rather than making changes directly on their primary NBS 6 production server. Planning for the operational complexity and cost of maintaining two systems simultaneously is an integral part of migration preparation. -See also: [Deployment overview](../before-you-deploy/planning.html) and [Deployment scenarios](../before-you-deploy/deployment-phases.html). +See also: [NBS 7 deployment planning guide](../before-you-deploy/planning.html). Version prerequisite: confirm your NBS 6 baseline against the [NBS 6 and NBS 7 compatibility matrix](../compatibility.html) before you finalize migration timelines. @@ -41,7 +41,7 @@ See also: [Assess your readiness](../before-you-deploy/assess-your-readiness.htm CDC does not support on-premises installations of NBS 7. Your jurisdiction needs an active cloud account with Amazon Web Services (AWS) or Microsoft Azure and an ongoing budget to sustain cloud infrastructure costs. Cloud hosting costs scale with usage, so budget planning might account for both normal operations and surge scenarios such as outbreak response. Use the [NBS 7 Resource Estimator](https://nbscentral.cdc.gov/documents/872) to project cloud-hosting costs based on your jurisdiction's record volume (NBS Central login required; see [Additional resources](../../index.html#additional-resources)). -See also: [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html) and [Deployment scenarios](../before-you-deploy/deployment-phases.html). +See also: [Set up cloud infrastructure](../deploy-nbs7/set-up-cloud-infrastructure.html). ## Align cloud provider with jurisdictional strategy From 45192ec59c9ac3ae4d73631bce0cfc38697d7a73 Mon Sep 17 00:00:00 2001 From: jburgh Date: Tue, 9 Jun 2026 13:52:41 -0400 Subject: [PATCH 16/16] Rename readiness page to 'Assess your technical readiness'. Address final review comments from CRED review. --- docs/before-you-deploy.md | 4 ++-- .../assess-your-readiness.md | 12 +++++------ docs/before-you-deploy/component-reference.md | 3 +-- .../nbs-core-components.md | 4 +--- .../component-reference/rtr.md | 4 ++-- docs/before-you-deploy/deployment-phases.md | 7 +++---- .../operational-considerations.md | 20 +++++++++---------- docs/before-you-deploy/planning.md | 14 ++++++------- .../vendor-managed-deployment.md | 1 - docs/compatibility.md | 1 - 10 files changed, 31 insertions(+), 39 deletions(-) diff --git a/docs/before-you-deploy.md b/docs/before-you-deploy.md index 237e108..bc57e32 100644 --- a/docs/before-you-deploy.md +++ b/docs/before-you-deploy.md @@ -8,14 +8,14 @@ description: Evaluation and planning content to help you assess NBS 7 readiness # Before deploying NBS 7 -This section is for STLT IT administrators and technical decision-makers who are evaluating and preparing for NBS 7. It brings together the readiness, compatibility, configuration, and planning information you need before deployment begins. Use it to understand what NBS 7 includes, what decisions your jurisdiction needs to make, and what conditions should be in place before you move into deployment work. It is intended to support an informed decision about how to proceed with NBS 7 deployment planning. +This section is for STLT IT administrators and technical decision-makers who are evaluating and preparing for migration to NBS 7. It brings together the readiness, compatibility, configuration, and planning information you need before deployment begins. Use it to understand what NBS 7 includes, what decisions your jurisdiction needs to make, and what conditions should be in place before you move into deployment work. It is intended to support an informed decision about how to proceed with NBS 7 deployment planning. ## Purpose Use this section to: - Assess whether NBS 7 deployment planning is the right next step for your jurisdiction -- Identify the right starting configuration for your jurisdiction, including optional add-ons +- Identify the right starting point for your jurisdiction - Understand the major components, prerequisites, and operational considerations that affect deployment - Support go or no-go decisions before you commit time and resources to deployment diff --git a/docs/before-you-deploy/assess-your-readiness.md b/docs/before-you-deploy/assess-your-readiness.md index 501a365..afbcdcd 100644 --- a/docs/before-you-deploy/assess-your-readiness.md +++ b/docs/before-you-deploy/assess-your-readiness.md @@ -6,9 +6,9 @@ nav_order: 1 description: Covers the technical prerequisites an STLT should meet before beginning NBS 7 migration, including cloud, staffing, and network requirements. --- -# Assess your readiness for NBS 7 +# Assess your technical readiness for NBS 7 -This page helps you assess whether NBS 7 is a viable option for your jurisdiction before you commit to a migration. +This page covers the technical conditions your jurisdiction should review before committing to an NBS 7 migration, including cloud infrastructure, staffing, network readiness, and NBS 6 compatibility. ## On this page {: .no_toc .text-delta } @@ -23,7 +23,7 @@ For more information on migration planning, staffing, and budget, see [Operation ## Not sure where to start? -If you are new to NBS 7 deployment, [Deployment planning guide](../before-you-deploy/planning.html) provides example stages in a typical rollout and where this readiness assessment fits. +If you are new to NBS 7 deployment, the [Deployment planning guide](../before-you-deploy/planning.html) provides example stages in a typical rollout and where this readiness assessment fits. ## IT security approval @@ -42,15 +42,13 @@ NBS 7 requires a cloud-based environment for deployment; CDC does not support on - **Strategic fit:** Preferred by jurisdictions with established AWS environments or those with existing AWS contract vehicles or organizational policies that standardize on AWS. - **Technical readiness:** Aligns with teams experienced in managing container-native architectures via Amazon Elastic Kubernetes Service (Amazon EKS) and mature Terraform workflows. -- **Surveillance context:** Core components are extensively validated in AWS to ensure performance at peak ingestion volumes. ### Microsoft Azure - **Strategic fit:** Preferred by jurisdictions with significant Microsoft ecosystem investments, such as those using Microsoft Entra ID (formerly Azure Active Directory) or existing Enterprise Agreements. - **Technical readiness:** Provides a streamlined experience for organizations running Windows-based workloads or requiring integration with Microsoft 365 and Power Platform tools. -- **Surveillance context:** Supported via Terraform, allowing jurisdictions to meet internal mandates for Azure-hosted health data. -See also: [Deploy cloud infrastructure on AWS](../deploy-nbs7/deploy-on-aws.html), [Deploy cloud infrastructure on Azure](../deploy-nbs7/deploy-on-azure.html), and [Compatibility matrix](../compatibility.html). +See also: [Deploy cloud infrastructure on AWS](../deploy-nbs7/deploy-on-aws.html), [Deploy cloud infrastructure on Azure](../deploy-nbs7/deploy-on-azure.html), and the [NBS 6 and NBS 7 compatibility matrix](../compatibility.html). ## Staff Kubernetes expertise @@ -88,7 +86,7 @@ Migration from NBS 6 to NBS 7 concludes with a cutover from your existing NBS 6 - Your NBS 6 instance must remain operational and accessible during migration. - Some jurisdictions provision a separate NBS 6 environment for migration activities and then cut over, rather than deploying NBS 7 changes directly against their primary NBS 6 production server. - You need to know your current NBS 6 hosting setup before you begin. Specifically, whether it is hosted on-premises or in the cloud, and if in the cloud, which provider. -- **You must be running a compatible NBS 6.x version** before you can install any version of NBS 7. For more information, see [Compatibility matrix](../compatibility.html). +- **You must be running a compatible NBS 6.x version** before you can install any version of NBS 7. For more information, see the [NBS 6 and NBS 7 compatibility matrix](../compatibility.html). See also: [Deployment planning guide](../before-you-deploy/planning.html) and [Operational considerations](../before-you-deploy/operational-considerations.html). diff --git a/docs/before-you-deploy/component-reference.md b/docs/before-you-deploy/component-reference.md index b24f469..21a0a38 100644 --- a/docs/before-you-deploy/component-reference.md +++ b/docs/before-you-deploy/component-reference.md @@ -8,7 +8,6 @@ description: Describes each NBS 7 component — what it does, when it is needed, --- # NBS 7 component reference -{: .no_toc } The pages in this section describe each component in NBS 7. Use it to understand what each component does, why it is included in your deployment, and how it relates to other components. @@ -33,7 +32,7 @@ The following table shows which components are included in NBS 7. RTR and DI API | [NBS Web UI](../before-you-deploy/component-reference/nbs-core-components.html#nbs-web-ui) | ✓ | | | | [NBS Gateway](../before-you-deploy/component-reference/nbs-core-components.html#nbs-gateway) | ✓ | | | | [Elasticsearch](../before-you-deploy/component-reference/nbs-core-components.html#elasticsearch) | ✓ | | | -| [Nifi](../before-you-deploy/component-reference/nbs-core-components.html#nifi) | ✓ | | | +| [NiFi](../before-you-deploy/component-reference/nbs-core-components.html#nifi) | ✓ | | | | [Keycloak](../before-you-deploy/component-reference/nbs-core-components.html#keycloak) | ✓ | | | | [Database (NBS\_ODSE, NBS\_SRTE)](../before-you-deploy/component-reference/nbs-core-components.html#database-nbs_odse-nbs_srte) | ✓ | | | | [Infrastructure and networking layer](../before-you-deploy/component-reference/nbs-core-components.html#infrastructure-and-networking-layer-components) | ✓ | | | diff --git a/docs/before-you-deploy/component-reference/nbs-core-components.md b/docs/before-you-deploy/component-reference/nbs-core-components.md index ccef950..bcc0fba 100644 --- a/docs/before-you-deploy/component-reference/nbs-core-components.md +++ b/docs/before-you-deploy/component-reference/nbs-core-components.md @@ -8,7 +8,6 @@ description: Details each component in NBS 7 — the application, infrastructure --- # Component reference: NBS 7 core components -{: .no_toc } For information on migration planning, staffing, and budget, see [Operational considerations](../../before-you-deploy/operational-considerations.html). {: .note } @@ -21,14 +20,13 @@ NBS 7 core components are organized into three layers: the application layer, th 1. TOC {:toc} - ## Legacy NBS 6 The existing NBS 6 application. A WildFly-based UI and backend that most STLTs currently run. | Attribute | Description | |:---|:---| -| What it does in NBS 7 | NBS Core does not replace NBS 6 immediately. Instead, it runs alongside it. During migration, the NBS Gateway routes requests between the legacy NBS 6 application and new NBS 7 services. NBS 6 continues to handle all functionality that has not yet been replaced by a modern NBS 7 equivalent. | +| What it does in NBS 7 | NBS 7 does not replace NBS 6 immediately. Instead, it runs alongside it. During migration, the NBS Gateway routes requests between the legacy NBS 6 application and new NBS 7 services. NBS 6 continues to handle all functionality that has not yet been replaced by a modern NBS 7 equivalent. | | When you need it | Always. An operational NBS 6 instance is a prerequisite for any NBS 7 deployment. You must be running a [compatible NBS 6 version](../../compatibility.html) before you can install NBS 7. | | Dependencies | Required by NBS Gateway, Elasticsearch (through NiFi), and the NBS Modernization API. Must maintain network connectivity to your NBS 7 environment throughout the migration period. | diff --git a/docs/before-you-deploy/component-reference/rtr.md b/docs/before-you-deploy/component-reference/rtr.md index 1067f61..aae023e 100644 --- a/docs/before-you-deploy/component-reference/rtr.md +++ b/docs/before-you-deploy/component-reference/rtr.md @@ -43,14 +43,14 @@ Apache Kafka is an open-source event-streaming platform. Kafka Connect is the fr ## RTR domain services -In NBS 7.12, a unified Spring Boot service that transforms streaming data from Kafka into reportable public health records. In NBS 7.13, implemented as five separate entity-specific services (investigation, person, observation, organization, and LDF data). +In NBS 7.12, five entity-specific Spring Boot services (investigation-service, person-service, observation-service, organization-service, and ldfdata-service) that each transform streaming data from Kafka into reportable public health records. Starting in NBS 7.13, these are consolidated into a single reporting pipeline service. | Attribute | Description | |:---|:---| | What it does in NBS 7 | Consumes Kafka messages for each entity type (investigations, patients, organizations, observations, and LDF data), runs stored procedures to retrieve and format the data, and produces processed records for downstream storage in RDB\_Modern. A post-processing service then populates analytical datamarts and fact tables from the staging data. | | Dependencies | Requires Kafka (message source) and NBS\_ODSE (operational data store). Populates RDB\_Modern staging tables, which are then consumed by the post-processing service. | -> The five entity-specific RTR services (investigation-service, person-service, observation-service, organization-service, ldfdata-service) are being consolidated into a single `reporting-pipeline-service` starting with NBS version 7.13. Check with your CDC NBS point of contact for the current deployment state. +> Starting with NBS version 7.13, the five entity-specific RTR services (investigation-service, person-service, observation-service, organization-service, ldfdata-service) are being consolidated into a single `reporting-pipeline-service`. Check with your CDC NBS point of contact for the current deployment state. {: .note }