diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index 55d20a3..b332ce6 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -49,6 +49,11 @@ config: # The first line of body content is typically the TOC block or a paragraph. MD041: false + # MD051 — Link fragments should be valid + # Disabled: Kramdown IAL syntax ({: #anchor-id }) sets custom HTML anchor IDs + # that markdownlint cannot resolve. These are valid Jekyll/Kramdown anchors. + MD051: false + # Glob patterns for files and directories to exclude from linting. # markdownlint-cli2 uses the same glob syntax as .gitignore. ignores: diff --git a/docs/before-you-deploy.md b/docs/before-you-deploy.md new file mode 100644 index 0000000..bc57e32 --- /dev/null +++ b/docs/before-you-deploy.md @@ -0,0 +1,36 @@ +--- +title: Before you deploy +layout: page +nav_order: 3 +has_children: true +description: Evaluation and planning content to help you assess NBS 7 readiness and choose a deployment configuration. +--- + +# Before deploying NBS 7 + +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 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 + +> 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; 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 } +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..afbcdcd --- /dev/null +++ b/docs/before-you-deploy/assess-your-readiness.md @@ -0,0 +1,110 @@ +--- +title: Readiness assessment +layout: page +parent: Before you deploy +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 technical readiness for NBS 7 + +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 } + +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; see [Additional resources](../../index.html#additional-resources)). +{: .note } + +## Not sure where to start? + +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 + +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 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; 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) + +- **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. + +### 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. + +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 + +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: + +- **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/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 [Deployment phases](../before-you-deploy/deployment-phases.html). + +## Network readiness + +Before deployment, your network must meet the following requirements: + +- **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 + +Migration from NBS 6 to NBS 7 concludes with a cutover from your existing NBS 6 instance to the new NBS 7 deployment. This means that: + +- Your jurisdiction will run both systems in parallel during the transition. +- 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 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). + +## Data migration + +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) and [Deployment planning guide](../before-you-deploy/planning.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 +- 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). + +**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 new file mode 100644 index 0000000..21a0a38 --- /dev/null +++ b/docs/before-you-deploy/component-reference.md @@ -0,0 +1,42 @@ +--- +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 + +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 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. + +--- + +## Quick reference + +The following table shows which components are included in NBS 7. RTR and DI API are deployed separately from the core NBS 7 components. + +| 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) | ✓ | | | +| [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) | | | ✓ | 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..859ea48 --- /dev/null +++ b/docs/before-you-deploy/component-reference/di-api.md @@ -0,0 +1,33 @@ +--- +title: "Data Ingestion (DI) API" +layout: page +parent: Component reference +grand_parent: Before you deploy +nav_order: 3 +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 + +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 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 new file mode 100644 index 0000000..bcc0fba --- /dev/null +++ b/docs/before-you-deploy/component-reference/nbs-core-components.md @@ -0,0 +1,136 @@ +--- +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 + +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. + +## On this page +{: .no_toc .text-delta } + +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 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. | + +## 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 (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 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. + +| 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. | +| 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..aae023e --- /dev/null +++ b/docs/before-you-deploy/component-reference/rtr.md @@ -0,0 +1,66 @@ +--- +title: "Real-Time Reporting (RTR)" +layout: page +parent: Component reference +grand_parent: Before you deploy +nav_order: 2 +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 eventually replaces 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. + +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. + +| 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 + +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. | + +> 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 } + + diff --git a/docs/before-you-deploy/deployment-phases.md b/docs/before-you-deploy/deployment-phases.md new file mode 100644 index 0000000..a330ed6 --- /dev/null +++ b/docs/before-you-deploy/deployment-phases.md @@ -0,0 +1,107 @@ +--- +title: Deployment phases +layout: page +parent: Before you deploy +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. +--- + +# NBS 7 technical deployment phases + +This page describes the three NBS 7 deployment phases and covers what each phase includes and when to deploy it. The first phase is the [core deployment](#phase-1-nbs-7), which gives your jurisdiction NBS 6 feature parity on modern cloud infrastructure. [Real-Time Reporting (RTR)](#phase-2-real-time-reporting-rtr) and the [Data Ingestion (DI) API](#phase-3-data-ingestion-di-api) follow as subsequent phases. Separating the phases reduces initial 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 reviewing the phases, see [Assess your technical 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](../compatibility.html). + +--- + +## 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, with foundational improvements such as real-time patient search. Additional modules and functional areas are modernized incrementally across releases. + +>When to deploy +> +>Deploy Phase 1 first. All subsequent phases depend on it. Plan your RTR and DI API timelines before you begin so your team can sequence the phases without gaps. +{: .note-title } + +NBS 7 core components are organized into three layers: [networking](#networking-layer), [infrastructure](#infrastructure-layer), and [application](#application-layer). For details on what each core component does and when you need it, see [NBS 7 core components](../before-you-deploy/component-reference/nbs-core-components.html) in the Component Reference. + +### 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 (as of NBS 7.12; formerly NGINX) +- 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)](../before-you-deploy/component-reference/nbs-core-components.html#database-nbs_odse-nbs_srte) + +--- + +## Phase 2: Real-Time Reporting (RTR) + +RTR is the second deployment phase. It introduces an event-driven reporting pipeline that runs alongside the legacy MasterETL batch process during the transition, with the goal of eventually decommissioning the batch process. + +>When to deploy +> +>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). + +- [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) + +--- + +## Phase 3: Data Ingestion (DI) API + +The DI API is the third deployment phase. It provides a built-in data transit layer and a REST API interface for writing data to NBS. DI API serves as a secure intermediary between your middleware and the database. + +>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. +{: .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. + +| Integration method | Rationale | +| :--- | :--- | +| **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 such as Rhapsody is required to preprocess and format data before it is sent to the DI API. + +For more information, see [Data Ingestion (DI) API](../before-you-deploy/component-reference/di-api.html) in the Component Reference. diff --git a/docs/before-you-deploy/operational-considerations.md b/docs/before-you-deploy/operational-considerations.md new file mode 100644 index 0000000..6eff9f7 --- /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: 2 +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 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 } + +1. TOC +{:toc} + +--- + +For technical deployment guidance, refer to [Assess your technical readiness](../before-you-deploy/assess-your-readiness.html) and the rest of this guide. + +## Plan for parallel operations + +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: [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. + +## IT security approval can take time + +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 technical 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 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). + +## Align cloud provider with jurisdictional strategy + +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: + +- **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 technical readiness > Cloud infrastructure](assess-your-readiness.html#cloud-infrastructure). + +## Technical staffing requirements differ from NBS 6 + +Migrating to NBS 7 requires expertise in Kubernetes, Terraform, and cloud infrastructure management that your current NBS 6 team might not have. 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 technical readiness](../before-you-deploy/assess-your-readiness.html) and [Vendor-managed deployment](../before-you-deploy/vendor-managed-deployment.html). + +## Real-Time Reporting can be deployed as a follow-on + +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). + +## 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. + +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 + +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/before-you-deploy/planning.md b/docs/before-you-deploy/planning.md new file mode 100644 index 0000000..0404908 --- /dev/null +++ b/docs/before-you-deploy/planning.md @@ -0,0 +1,116 @@ +--- +title: Deployment planning guide +layout: page +parent: Before you deploy +nav_order: 3 +description: An overview of the five stages involved in an NBS 7 deployment, from planning through steady state operations. +--- + +# NBS 7 deployment planning guide + +NBS 7 deployments vary significantly by jurisdiction. If you are just getting started, this page can help you understand where the [Assess your technical readiness](assess-your-readiness.html) checklist fits in the overall process. + +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 } + + + +## Example deployment stages + +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). + +| Stage | Goal | Minimum duration | +|:---|:---|:---| +| [Planning](#planning) | Establish your project team, [assess your technical readiness](assess-your-readiness.html), and create a customized migration plan | 2-5 months | +| [Install](#install) | Provision cloud environments and deploy NBS 7 in [phases](deployment-phases.html) | 3-6 months | +| [Test](#test) | Validate ingestion, egress, and system technical 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 | + +These are minimum duration estimates based on typical deployments. Actual timelines will vary by jurisdiction. Security approval, procurement, and legal review processes are common causes of delays in the earlier stages. +{: .important } + +--- + +## Planning + +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. Early contact with your IT security office, before detailed timeline planning begins, might reduce the risk of delays. + +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 | Suggested resource or action | +|:---|:---|:---| +| Review readiness and compatibility | Review technical considerations and confirm your NBS 6 version is compatible with your target NBS 7 version. | [Assess your technical readiness](../before-you-deploy/assess-your-readiness.html), [NBS 6 and NBS 7 compatibility matrix](../compatibility.html), and [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)) | +| Assess current environment | Document your existing NBS 6 setup, including ingestion and egress workflows, integrations, and hosting configuration. | Create a current state assessment | +| Orient migration team to NBS 7 | Review NBS 7 components and features with your migration team. | [Component reference](../before-you-deploy/component-reference.html) | +| Create project plan | Draft a migration plan customized for your jurisdiction. | Create a project plan | +| Plan data migration | Agree on an approach, coordinate the data migration solution, and prepare test files. | Create a data migration plan; see [Assess your technical readiness: Data migration](../before-you-deploy/assess-your-readiness.html#data-migration) | +| Plan user support | Identify how end users will report issues after go-live and document the process. | Create a user support plan | +| Plan user training | Identify training needs and develop materials customized for your jurisdiction. | Create a user training plan | +| Plan communications | Develop a communications plan customized to your timeline and needs. | Create a communications plan | +| Plan user acceptance testing (UAT) | Prepare test scenarios that confirm the system is ready for production. | Create a UAT plan | + +--- + +## Install + +The Install stage covers provisioning your cloud environment and deploying NBS 7. Most jurisdictions deploy across multiple environments and repeat some or all of these activities in each one, typically starting with a lower environment before moving to production. The number of environments, their names, and the level of testing performed in each will vary by jurisdiction. + +If security approval is still in progress when Install begins, it might extend this stage. + +| 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. | 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) | + +--- + +## Test + +The Test stage validates that your NBS 7 environment is ready for production use. Some Test stage activities might be performed within each environment during Install. This stage might also run concurrently with some Install activities. + +| Activity | Description | Suggested resource or action | +|:---|:---|:---| +| Test database restore process | Review and test the database restore process in each environment. | Use your own database refresh procedure | +| Validate ingestion and egress | Integrate and validate data ingestion and notification pathways to confirm pipelines are working. | [Data ingestion API testing](../deploy-nbs7/data-ingestion/api-testing.html) | +| Validate real-time reporting (RTR) | Confirm that RTR streaming updates move into datamart tables. | [Validate the RTR pipeline](../deploy-nbs7/real-time-reporting/pipeline-validation.html) | +| Test ELR and eCR ingestion | Test ingestion for individual ELRs and eCRs and at scale. | [Data ingestion smoke test](../deploy-nbs7/data-ingestion/smoke-test.html) | +| Validate notifications | Validate Case Notifications | Confirm conditions are received successfully | +| Run regression testing | Run test scripts across environments to validate readiness for UAT. | [Validate the deployment](../deploy-nbs7/validate-the-deployment.html) | +| Conduct user acceptance testing (UAT) | Conduct UAT across all environments. | Your UAT test plan | +| Review cutover and rollback plans | Review and approve cutover and rollback plans. | Create a cutover and rollback plan | + +--- + +## Go-live + +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 | Suggested resource or action | +|:---|:---|:---| +| Conduct 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)) | +| Make go/no-go decision | Make the final go-live decision and schedule the cutover date. | No resource required | +| Lock and refresh database | Freeze the database backup and finalize the cutover checklist. | Add to your cutover and rollback plan | +| Execute cutover | Complete the cutover checklist and launch NBS 7. | Your cutover and rollback plan | +| Activate user support channel | Open the support channel to end users. | Your user support plan | + +--- + +## Steady state + +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 | Suggested resource or action | +|:---|:---|:---| +| Monitor live operations | Track system performance and understand your support options. | [Get support](../support.html) | +| Conduct go-live retrospective | Capture lessons learned from the go-live process. | Use a retrospective template | +| 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/vendor-managed-deployment.md b/docs/before-you-deploy/vendor-managed-deployment.md new file mode 100644 index 0000000..74c60a4 --- /dev/null +++ b/docs/before-you-deploy/vendor-managed-deployment.md @@ -0,0 +1,33 @@ +--- +title: Working with a vendor +layout: page +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 NBS 7 deployments + +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](../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](../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](../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)). +{: .note } diff --git a/docs/compatibility.md b/docs/compatibility.md new file mode 100644 index 0000000..6454826 --- /dev/null +++ b/docs/compatibility.md @@ -0,0 +1,30 @@ +--- +title: NBS 6 to 7 compatibility +layout: page +nav_order: 2 +nav_enabled: true +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 + +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. + +- **✓ 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/deploy-nbs7.md b/docs/deploy-nbs7.md index 571783b..a0e44ee 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,9 +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](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 e9835fa..14440e4 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, 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](../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 6a2118a..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 page (coming soon), 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) @@ -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/docs/deploy-nbs7/deploy-on-azure.md b/docs/deploy-nbs7/deploy-on-azure.md index 935aaec..df0cb6f 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](../compatibility.html). ## In this section diff --git a/docs/deploy-nbs7/prerequisites.md b/docs/deploy-nbs7/prerequisites.md index a680c93..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 (coming soon) 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. @@ -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 - +- **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 @@ -98,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). diff --git a/docs/deploy-nbs7/quickstart.md b/docs/deploy-nbs7/quickstart.md index 143bd74..a2156e6 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 } - +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/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/maintain-nbs7.md b/docs/maintain-nbs7.md index 0b76eab..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. --- @@ -18,10 +18,10 @@ Use this section for recurring maintenance work such as upgrades, infrastructure > 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/index.md b/index.md index db4771e..6235033 100644 --- a/index.md +++ b/index.md @@ -21,13 +21,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