From 8003258efa314e419344854f65a4ea96d31c4d95 Mon Sep 17 00:00:00 2001 From: Eric Buckley Date: Tue, 23 Jun 2026 14:10:39 -0700 Subject: [PATCH 01/11] first draft at changes for RTR in the 7.13 release --- .../real-time-reporting/debezium.md | 39 ------ .../real-time-reporting/kafka-connector.md | 8 -- .../real-time-reporting.md | 122 +++--------------- .../real-time-reporting/rtr-java-services.md | 68 ++-------- 4 files changed, 25 insertions(+), 212 deletions(-) diff --git a/docs/deploy-nbs7/real-time-reporting/debezium.md b/docs/deploy-nbs7/real-time-reporting/debezium.md index 2c0cf59..3f2ebfd 100644 --- a/docs/deploy-nbs7/real-time-reporting/debezium.md +++ b/docs/deploy-nbs7/real-time-reporting/debezium.md @@ -46,45 +46,6 @@ Follow these steps to configure and deploy the Debezium Helm chart for RTR. # Kafka bootstrap server endpoint from AWS MSK bootstrap_server: "EXAMPLE_MSK_KAFKA_ENDPOINT" - # Connector for NBS_ODSE transactional data - sqlserverconnector_odse: - config: - database.hostname: "nbs-db.private-EXAMPLE_DOMAIN" - database.port: "1433" - database.user: "EXAMPLE_ODSE_DB_USER" - database.password: "EXAMPLE_ODSE_DB_USER_PASSWORD" - database.dbname: "nbs_odse" - database.names: "nbs_odse" - database.server.name: "odse" - database.history.kafka.bootstrap.servers: "EXAMPLE_MSK_KAFKA_ENDPOINT" - schema.history.internal.kafka.bootstrap.servers: "EXAMPLE_MSK_KAFKA_ENDPOINT" - - # Connector for NBS_ODSE metadata - sqlserverconnector_odse_meta: - config: - database.hostname: "nbs-db.private-EXAMPLE_DOMAIN" - database.port: "1433" - database.user: "EXAMPLE_ODSE_DB_USER" - database.password: "EXAMPLE_ODSE_DB_USER_PASSWORD" - database.dbname: "nbs_odse" - database.names: "nbs_odse" - database.server.name: "odse-meta" - database.history.kafka.bootstrap.servers: "EXAMPLE_MSK_KAFKA_ENDPOINT" - schema.history.internal.kafka.bootstrap.servers: "EXAMPLE_MSK_KAFKA_ENDPOINT" - - # Connector for NBS_SRTE reference and terminology data - sqlserverconnector_srte: - config: - database.hostname: "nbs-db.private-EXAMPLE_DOMAIN" - database.port: "1433" - database.user: "EXAMPLE_SRTE_DB_USER" - database.password: "EXAMPLE_SRTE_DB_USER_PASSWORD" - database.dbname: "nbs_srte" - database.names: "nbs_srte" - database.server.name: "srte" - database.history.kafka.bootstrap.servers: "EXAMPLE_MSK_KAFKA_ENDPOINT" - schema.history.internal.kafka.bootstrap.servers: "EXAMPLE_MSK_KAFKA_ENDPOINT" - env: # Kafka bootstrap server endpoint from AWS MSK - name: BOOTSTRAP_SERVERS diff --git a/docs/deploy-nbs7/real-time-reporting/kafka-connector.md b/docs/deploy-nbs7/real-time-reporting/kafka-connector.md index 2561ff4..39a5b19 100644 --- a/docs/deploy-nbs7/real-time-reporting/kafka-connector.md +++ b/docs/deploy-nbs7/real-time-reporting/kafka-connector.md @@ -42,14 +42,6 @@ Follow these steps to configure and deploy the Kafka connector Helm chart for RT # Replace with the target release version tag, e.g. v1.0.1 tag: - sqlServerConnector: - config: - # [SME REVIEW: confirm databaseName should be rdb_modern, not rdb] - connection.url: "jdbc:sqlserver://nbs-db.EXAMPLE_FIXME.nbspreview.com:1433;databaseName=rdb;encrypt=true;trustServerCertificate=true" - # SQL Server username for reporting database - connection.user: "EXAMPLE_FIXME" - connection.password: "EXAMPLE_FIXME" - kafka: # Kafka bootstrap server endpoint from AWS MSK bootstrapServers: "EXAMPLE_FIXME" diff --git a/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md b/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md index c2b30aa..76f7f36 100644 --- a/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md +++ b/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md @@ -62,30 +62,10 @@ To reduce risk, consider setting up RTR in a testing environment before moving t > Back up the `RDB` database before you proceed. This step cannot be undone. {: .warning } -1. Choose a database path and use it consistently throughout this guide. Both paths support Liquibase or script-based installation. +1. Choose a database path and use it consistently throughout this guide. - **RDB path:** Use `RDB` as the default reporting database. Turn off the classic ETL batch jobs and proceed to the next step. MasterETL remains available for manual recovery runs if needed. - - **rdb_modern path:** Create a separate reporting database. To create the database, see [Set up the rdb_modern database](#set-up-the-rdb_modern-database-rdb_modern-path-only) before moving on to [Create service users and database objects](#create-service-users-and-database-objects). - -1. Set the environment variable for your chosen path. - - - **RDB path:** Insert the following value into `NBS_Configuration`: - - ```sql - IF NOT EXISTS(SELECT 1 FROM NBS_ODSE.DBO.NBS_Configuration WHERE config_key ='ENV' AND config_value ='PROD') - INSERT INTO NBS_ODSE.dbo.NBS_Configuration - (config_key, config_value, short_name, desc_txt, default_value, valid_values, category, add_release, version_ctrl_nbr, add_user_id, add_time, last_chg_user_id, last_chg_time, status_cd, status_time, admin_comment, system_usage, config_value_large) - VALUES(N'ENV', N'PROD', N'RTR reporting database', N'Indicates scripts should be run against RDB database', NULL, N'UAT, PROD', N'RTR', N'7.12.0', 1, 0, getdate(), 0, getdate(), N'A', getdate(), NULL, NULL, NULL); - ``` - - - **rdb_modern path:** This setting overrides the default `RDB` during script execution unless a script explicitly prompts for a database. - - ```sql - IF NOT EXISTS(SELECT 1 FROM NBS_ODSE.DBO.NBS_Configuration WHERE config_key ='ENV' AND config_value ='UAT') - INSERT INTO NBS_ODSE.dbo.NBS_Configuration - (config_key, config_value, short_name, desc_txt, default_value, valid_values, category, add_release, version_ctrl_nbr, add_user_id, add_time, last_chg_user_id, last_chg_time, status_cd, status_time, admin_comment, system_usage, config_value_large) - VALUES(N'ENV', N'UAT', N'RTR reporting database', N'Indicates scripts should be run against UAT rdb_modern database', NULL, N'UAT, PROD', N'RTR', N'7.12.0', 1, 0, getdate(), 0, getdate(), N'A', getdate(), NULL, NULL, NULL); - ``` + - **rdb_modern path:** Create a separate reporting database. There are many paths for duplicating your reporting database, depending on which version of SQL Server you are using and where it is running. Please see [Microsoft's Documentation on Backup and Restore Operations](https://learn.microsoft.com/en-us/sql/relational-databases/backup-restore/back-up-and-restore-of-sql-server-databases?view=sql-server-ver17) for more information, if this process is unfamiliar before moving on to [Create service users and database objects](#create-service-users-and-database-objects). ## Set up the rdb_modern database (rdb_modern path only) @@ -93,102 +73,41 @@ If you are on the **rdb_modern path**, complete this section. If you are on the RTR requires a dedicated reporting database. To create `rdb_modern`, you restore a copy of `RDB` under a new name. This keeps the classic ETL-hydrated `RDB` intact and available while `rdb_modern` hosts the data structures the RTR pipeline requires. -If your `RDB` database is hosted on Amazon RDS, follow the steps in [Back up and restore a SQL Server database on Amazon RDS](../../maintain-nbs7/rds-backup-restore.html). For all other database hosting providers, use your standard backup and restore procedure to create a copy of `RDB` as `rdb_modern`. - -## Create service users and database objects +## Create service users and secrets Complete the following steps to create the database users, Kubernetes secrets, and database objects that the RTR pipeline requires before [Change Data Capture](#enable-change-data-capture) can be enabled. -> Generate passwords for each service user before running the scripts. Password generation scripts can take several minutes to run. Do not use spaces, equal signs (`=`), or colons (`:`). These characters cause script execution failures. -{: .important } - -1. **Create admin user.** Run [000-create_rtr_admin_user-001.sql][nedss-datareporting-onboarding-user-scripts] from the NEDSS-DataReporting onboarding user creation scripts. This user provides Liquibase permissions to maintain required database components for RTR and enable Change Data Capture. Review the script and update the `PASSWORD` value before execution. - -1. **Create RTR microservice user logins.** Run [001-service_users_login_creation-001.sql and 002-service_database_user_creation-001.sql][nedss-datareporting-onboarding-user-scripts] from the same directory. These scripts create dedicated user accounts for each RTR microservice, which are referenced in Helm values for RTR services. Review the scripts and update the `PASSWORD` values before execution. - -1. **Create Kubernetes secrets for each service user.** Include the admin user from step 1. Each secret should include the database username and password. Script location: [NEDSS-DataReporting/create-kubernetes-secrets][nedss-helm-k8-secrets-manifest]. For steps to create secrets, see [Create secrets in your cluster](../../deploy-nbs7/initial-kubernetes-deployment/initial-kubernetes-deployment.html#create-secrets-in-your-cluster). - -1. **Create required database objects.** Run the scripts for your chosen path: +Running the RTR pipeline requires SQL Server login accounts for two distinct purposes: running the bootstrap scripts and schema migrations, and running the application services. Depending on your environment, these can be two separate accounts or collapsed into one. - The database scripts referenced throughout this guide are maintained in the [NEDSS-DataReporting][nedss-datareporting-liquibase-service] repository. You can create the required database objects through Liquibase, which will automatically implement database schema changes, or you can use the provided scripts to install database schema changes. Both options are referenced in the relevant sections. - {: .important } +### Accounts at a Glance - - **Liquibase:** See [Deploy Liquibase](../../deploy-nbs7/real-time-reporting/liquibase.html) to create all necessary objects, then return here to continue. Liquibase also handles future database upgrades automatically, so no manual intervention is needed when you update NBS 7. +| Account | Purpose | Databases | Key Permissions | +| :--- | :--- | :--- | :--- | +| **Admin account** (e.g. `rtr-admin`) | Liquibase migrations | `NBS_ODSE`, `NBS_SRTE`, `RDB / RDB_MODERN` | All NBS DBs: `db_owner` | +| **Service account** (e.g. `rtr-service-user`) | Application services reading source data and writing to the reporting database | `NBS_ODSE`, `NBS_SRTE`, `RDB / RDB_MODERN` | ODSE/SRTE: `db_datareader`
RDB/RDB_MODERN: `db_owner` | - - **Upgrade scripts:** See the script execution sequence and `db_upgrade` script in [NEDSS-DataReporting/db-upgrade][nedss-datareporting-manual-deployment]. Clone or download the repository, then run: +Two accounts cover everything: `rtr-admin` handles migrations, `rtr-service-user` runs the application. A single account with both sets of permissions also works if your environment doesn't require separation. - ```bash - upgrade_db.bat - ``` - - When you update NBS 7 to a new release version, you will need to run the upgrade scripts again. See [After onboarding: database upgrades](#after-onboarding-database-upgrades). +1. **Create Kubernetes secrets for each sql user.** Each secret should include the database username and password. Script location: [NEDSS-DataReporting/create-kubernetes-secrets][nedss-helm-k8-secrets-manifest]. For steps to create secrets, see [Create secrets in your cluster](../../deploy-nbs7/initial-kubernetes-deployment/initial-kubernetes-deployment.html#create-secrets-in-your-cluster). ## Enable Change Data Capture -Change Data Capture (CDC) streams row-level changes from `NBS_ODSE` and `NBS_SRTE` to Kafka, where RTR services load them into the reporting database. Complete the following steps to load the initial data, enable Change Data Capture, and verify the configuration before deploying RTR services. - -1. **Load data and enable Change Data Capture.** This one-time step is required after all database objects are created. - - - **Liquibase:** The `--load-data` flag is not required when using Liquibase. Proceed to step 2. +Change Data Capture (CDC) streams row-level changes from `NBS_ODSE` and `NBS_SRTE` to Kafka, where RTR services load them into the reporting database. Enabling CDC on these databases does require `sysadmin` level permissions, because of this, we have not automated its installation and have instead provided two scripts to manually apply. For more information on SQL Server Change Data Capture, please review [Microsoft's official documentation](https://learn.microsoft.com/en-us/sql/relational-databases/track-changes/enable-and-disable-change-data-capture-sql-server?view=sql-server-ver17). - - **Upgrade scripts:** Navigate to [02_onboarding_script_data_load][nedss-datareporting-onboarding-data-load] and clone or download the repository, then run: +1. Apply bootstrap script [101 to enable CDC on NBS_ODSE](https://github.com/CDCgov/NEDSS-DataReporting/blob/main/bootstrap/101-enable_cdc_on_odse_database-001.sql). - ```bash - upgrade_db.bat --load-data master - ``` - -1. **Verify Change Data Capture.** `is_cdc_enabled=1` indicates successful configuration. - - > In the following statements, `cdc` appears as part of SQL Server column and parameter names and refers to **Change Data Capture**, not the Centers for Disease Control and Prevention. - {: .note } - - ```sql - SELECT name, is_cdc_enabled - FROM sys.databases; - - -- View ODSE tables with Change Data Capture enabled - USE NBS_ODSE; - SELECT - name, - CASE WHEN is_tracked_by_cdc = 1 THEN 'YES' ELSE 'NO' END AS is_tracked_by_cdc - FROM sys.tables - WHERE is_tracked_by_cdc = 1; - - -- View SRTE tables with Change Data Capture enabled - USE NBS_SRTE; - SELECT - name, - CASE WHEN is_tracked_by_cdc = 1 THEN 'YES' ELSE 'NO' END AS is_tracked_by_cdc - FROM sys.tables - WHERE is_tracked_by_cdc = 1; - ``` - - The following images show expected query results for a successful Change Data Capture configuration. - -
-
-
Change Data Capture tables (NBS_ODSE)
- Query results showing 19 Change Data Capture enabled tables in NBS_ODSE, all with is_tracked_by_cdc set to YES -
-
-
Change Data Capture tables (NBS_SRTE)
- Query results showing 44 Change Data Capture enabled tables in NBS_SRTE, all with is_tracked_by_cdc set to YES -
-
- -1. **Back up all databases.** Before going live, take backups of `NBS_ODSE`, `NBS_SRTE`, `RDB`, and `rdb_modern` (if applicable). +1. Apply bootstrap script [102 to enable CDC on NBS_SRTE](https://github.com/CDCgov/NEDSS-DataReporting/blob/main/bootstrap/102-enable_cdc_on_srte_database-001.sql). ## Deploy RTR services -Now that you have completed database setup and onboarding, deploy the RTR services in the following order. Each service depends on the previous one completing successfully before deployment begins. +Now that you have completed database setup and onboarding, deploy the RTR services in the following order. Some services depend on the previous ones completing successfully before deployment begins. -> Confirm that Kubernetes secrets exist for each RTR service user and the admin user before deploying. If you have not yet created them, see [Create service users and database objects](#create-service-users-and-database-objects). +> Confirm that Kubernetes secrets exist for each RTR service user and the admin user before deploying. {: .important } -1. [Liquibase](../../deploy-nbs7/real-time-reporting/liquibase.html): Skip this step if you used the upgrade script path in [Create required database objects](#create-service-users-and-database-objects). 1. [Debezium](../../deploy-nbs7/real-time-reporting/debezium.html) 1. [Kafka connector](../../deploy-nbs7/real-time-reporting/kafka-connector.html) -1. [Java services](../../deploy-nbs7/real-time-reporting/rtr-java-services.html) +1. [Java service](../../deploy-nbs7/real-time-reporting/rtr-java-services.html) [nedss-datareporting-liquibase-service]: [nedss-datareporting-onboarding-user-scripts]: @@ -197,10 +116,3 @@ Now that you have completed database setup and onboarding, deploy the RTR servic [nedss-datareporting-onboarding-data-load]: --- - -## After onboarding: database upgrades - -Database upgrades apply schema changes required by each NBS 7 release. Run database upgrades when you update NBS 7 to a new release version. - -- If you chose the **Liquibase** path during onboarding, no action is needed. The Liquibase container applies schema changes automatically with each release. -- If you chose the **upgrade scripts** path, navigate to [02_onboarding_script_data_load][nedss-datareporting-onboarding-data-load] and run all of the scripts in the order listed in the repository. Onboarding scripts are excluded from upgrade runs. diff --git a/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md b/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md index 131af98..7e8c5cb 100644 --- a/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md +++ b/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md @@ -9,12 +9,9 @@ redirect_from: - /docs/7_feature_preview/4_rtr_java_reporting_services/ --- -# Deploy real-time reporting (RTR) Java services +# Deploy real-time reporting (RTR) Java service -> The Java reporting services are being consolidated in an upcoming release. The service validation URLs reflect the NBS {{ site.version_latest }} configuration. -{: .warning } - -This page covers deploying the RTR Java services that process streamed events from Kafka and load domain-specific reporting data. +This page covers deploying the RTR Java service that process streamed events from Kafka and load domain-specific reporting data. ## On this page {: .no_toc .text-delta } @@ -53,21 +50,13 @@ Follow these steps to configure and deploy the RTR Java services Helm chart. 1. Validate the image repository: ```yaml - global.image.repository: "quay.io/us-cdcgov/cdc-nbs-modernization/data-reporting-service" + global.image.repository: "quay.io/us-cdcgov/cdc-nbs-modernization/" ``` -1. Update feature flags for each service. Verify that `PHCMartETL.bat` is turned off before enabling updates to the PublicHealthCaseFact datamart via RTR: - - ```yaml - featureFlag: - investigation-reporting: - phcDatamartEnable: '''true''' - ``` - -1. Install the Helm chart for all RTR Java services: +1. Install the Helm chart for the RTR Java service: ```bash - helm install rtr . -f values.yaml + helm install reporting-pipeline-service . -f values.yaml ``` 1. Verify the pods are running: @@ -80,56 +69,15 @@ Follow these steps to configure and deploy the RTR Java services Helm chart. ```text NAME READY STATUS RESTARTS AGE - rtr-java-services-investigation-reporting- 1/1 Running 0 2m6s - rtr-java-services-ldfdata-reporting- 1/1 Running 0 2m6s - rtr-java-services-observation-reporting- 1/1 Running 0 2m6s - rtr-java-services-organization-reporting- 1/1 Running 0 2m6s - rtr-java-services-person-reporting- 1/1 Running 0 2m6s - rtr-java-services-post-processing-reporting- 1/1 Running 0 2m6s + rtr-java-services-reporting-pipeline-service- 1/1 Running 0 2m6s ``` 1. Validate the services. Replace `` with your actual domain (see [Deploy Traefik ingress controller](../../deploy-nbs7/initial-kubernetes-deployment/initial-kubernetes-deployment.html#deploy-traefik-ingress-controller)): - **investigation-svc** - - ```text - https://data./reporting/investigation-svc/status - Expected: Investigation Service Status OK - ``` - - **person-svc** - - ```text - https://data./reporting/person-svc/status - Expected: Person Service Status OK - ``` - - **observation-svc** - - ```text - https://data./reporting/observation-svc/status - Expected: Observation Service Status OK - ``` - - **organization-svc** - - ```text - https://data./reporting/organization-svc/status - Expected: Organization Service Status OK - ``` - - **ldfdata-svc** - - ```text - https://data./reporting/ldfdata-svc/status - Expected: LDFData Service Status OK - ``` - - **post-processing-svc** + **reporting-pipeline-service** ```text - https://data./reporting/post-processing-svc/status - Expected: Post Processing Service Status OK + https://data./reporting-pipeline-svc/actuor/health ``` [nedss-helm-rtr-chart]: From 21dabf2434c3c366829b35dd0039da7f57d9e0dd Mon Sep 17 00:00:00 2001 From: Eric Buckley Date: Tue, 23 Jun 2026 14:27:32 -0700 Subject: [PATCH 02/11] docs(rtr): improve documentation and fix typos Improve clarity in the Real-Time Reporting (RTR) documentation. Update section references, improve descriptions, and correct typos in the Java service documentation, including a fix for an incorrect URL path. --- .../real-time-reporting/real-time-reporting.md | 4 ++-- .../real-time-reporting/rtr-java-services.md | 16 ++++++++-------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md b/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md index 76f7f36..bc7ade8 100644 --- a/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md +++ b/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md @@ -65,11 +65,11 @@ To reduce risk, consider setting up RTR in a testing environment before moving t 1. Choose a database path and use it consistently throughout this guide. - **RDB path:** Use `RDB` as the default reporting database. Turn off the classic ETL batch jobs and proceed to the next step. MasterETL remains available for manual recovery runs if needed. - - **rdb_modern path:** Create a separate reporting database. There are many paths for duplicating your reporting database, depending on which version of SQL Server you are using and where it is running. Please see [Microsoft's Documentation on Backup and Restore Operations](https://learn.microsoft.com/en-us/sql/relational-databases/backup-restore/back-up-and-restore-of-sql-server-databases?view=sql-server-ver17) for more information, if this process is unfamiliar before moving on to [Create service users and database objects](#create-service-users-and-database-objects). + - **rdb_modern path:** Create a separate reporting database by duplicating your existing reporting database. The exact steps depend on your SQL Server version and where it is hosted. If this process is unfamiliar, see [Microsoft's documentation on backup and restore operations](https://learn.microsoft.com/en-us/sql/relational-databases/backup-restore/back-up-and-restore-of-sql-server-databases?view=sql-server-ver17) before moving on to [Create service users and secrets](#create-service-users-and-secrets). ## Set up the rdb_modern database (rdb_modern path only) -If you are on the **rdb_modern path**, complete this section. If you are on the **RDB path**, move on to [Create service users and database objects](#create-service-users-and-database-objects). For more information on choosing a path, see Step 3 in the [Prerequisites](#prerequisites) section. +If you are on the **rdb_modern path**, complete this section. If you are on the **RDB path**, move on to [Create service users and secrets](#create-service-users-and-secrets). For more information on choosing a path, see Step 3 in the [Prerequisites](#prerequisites) section. RTR requires a dedicated reporting database. To create `rdb_modern`, you restore a copy of `RDB` under a new name. This keeps the classic ETL-hydrated `RDB` intact and available while `rdb_modern` hosts the data structures the RTR pipeline requires. diff --git a/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md b/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md index 7e8c5cb..aa52212 100644 --- a/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md +++ b/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md @@ -1,9 +1,9 @@ --- -title: Java services +title: Java service layout: page parent: Deploy real-time reporting nav_order: 4 -description: Covers deployment of RTR Java services that transform Kafka events and load reporting datamarts. +description: Covers deployment of the RTR Java service that transforms Kafka events and loads reporting datamarts. redirect_from: - /docs/7_feature_preview/4_rtr_java_reporting_services.html - /docs/7_feature_preview/4_rtr_java_reporting_services/ @@ -11,7 +11,7 @@ redirect_from: # Deploy real-time reporting (RTR) Java service -This page covers deploying the RTR Java service that process streamed events from Kafka and load domain-specific reporting data. +This page covers deploying the RTR Java service that processes streamed events from Kafka and loads domain-specific reporting data. ## On this page {: .no_toc .text-delta } @@ -22,14 +22,14 @@ This page covers deploying the RTR Java service that process streamed events fro > These steps require a Unix-compatible shell. On Windows, use Git Bash, WSL, or an equivalent terminal emulator. {: .note } -## Installing RTR Java services +## Installing the RTR Java service -Follow these steps to configure and deploy the RTR Java services Helm chart. +Follow these steps to configure and deploy the RTR Java service Helm chart. > Verify that you are connected to the correct Kubernetes cluster before proceeding. To confirm, run `kubectl config current-context`. {: .important } -1. Locate the Helm chart for all RTR Java services in the [NEDSS-Helm repository][nedss-helm-rtr-chart]. +1. Locate the Helm chart for the RTR Java service in the [NEDSS-Helm repository][nedss-helm-rtr-chart]. 1. Validate the Kubernetes secret for database credentials: @@ -72,12 +72,12 @@ Follow these steps to configure and deploy the RTR Java services Helm chart. rtr-java-services-reporting-pipeline-service- 1/1 Running 0 2m6s ``` -1. Validate the services. Replace `` with your actual domain (see [Deploy Traefik ingress controller](../../deploy-nbs7/initial-kubernetes-deployment/initial-kubernetes-deployment.html#deploy-traefik-ingress-controller)): +1. Validate the service. Replace `` with your actual domain (see [Deploy Traefik ingress controller](../../deploy-nbs7/initial-kubernetes-deployment/initial-kubernetes-deployment.html#deploy-traefik-ingress-controller)): **reporting-pipeline-service** ```text - https://data./reporting-pipeline-svc/actuor/health + https://data./reporting-pipeline-svc/actuator/health ``` [nedss-helm-rtr-chart]: From 466f8a586bf258becd501e69ad840dd18ab381ed Mon Sep 17 00:00:00 2001 From: Eric Buckley Date: Tue, 23 Jun 2026 16:01:10 -0700 Subject: [PATCH 03/11] docs: remove deprecated liquibase deployment documentation --- .../real-time-reporting/liquibase.md | 241 ------------------ .../real-time-reporting.md | 4 - 2 files changed, 245 deletions(-) delete mode 100644 docs/deploy-nbs7/real-time-reporting/liquibase.md diff --git a/docs/deploy-nbs7/real-time-reporting/liquibase.md b/docs/deploy-nbs7/real-time-reporting/liquibase.md deleted file mode 100644 index b7e60dc..0000000 --- a/docs/deploy-nbs7/real-time-reporting/liquibase.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Liquibase -layout: page -parent: Deploy real-time reporting -nav_order: 1 -description: Explains deployment of the RTR Liquibase job to apply required schema changes across NBS databases. -redirect_from: - - /docs/7_feature_preview/1_liquibase.html - - /docs/7_feature_preview/1_liquibase/ ---- - -# Deploy Liquibase for real-time reporting (RTR) - -In RTR deployments, the Liquibase job runs once and applies required SQL Server database changes for onboarding and upgrades. This page covers steps to deploy the Liquibase Helm chart. - -## On this page -{: .no_toc .text-delta } - -1. TOC -{:toc} - -## Installing Liquibase - -Follow these steps to configure and deploy the Liquibase Helm chart for RTR. - -> Verify that you are connected to the correct Kubernetes cluster before proceeding. To confirm, run `kubectl config current-context`. -{: .important } - -1. Locate the Liquibase Helm chart in the [NEDSS-Helm repository][nedss-helm-liquibase-chart]. -1. Configure `values.yaml`. Replace all placeholder values before installation: - - Replace `app.EXAMPLE_DOMAIN` with the URL of your modern app (see [Deploy Traefik ingress controller](../../deploy-nbs7/initial-kubernetes-deployment/initial-kubernetes-deployment.html#deploy-traefik-ingress-controller)): - - ```yaml - image: - repository: "quay.io/us-cdcgov/cdc-nbs-modernization/liquibase-service" - tag: # Example: v1.0.1 - ``` - - Replace `EXAMPLE_DB_ENDPOINT` with your SQL Server endpoint and set credentials. - For `username`, use `db_deploy_admin`. - - To retrieve your Kafka bootstrap server endpoints, see [Get bootstrap brokers](https://docs.aws.amazon.com/msk/latest/developerguide/msk-get-bootstrap-brokers.html) in the AWS MSK documentation. - - The following fields define the JDBC connection strings for each NBS database. Each URL - identifies the SQL Server endpoint, the database name, and the connection security settings. - - ```yaml - jdbc: - # SQL Server system database - master_db_url: "jdbc:sqlserver://EXAMPLE_DB_ENDPOINT:1433;databaseName=master;integratedSecurity=false;encrypt=true;trustServerCertificate=true" - # NBS transactional database - odse_db_url: "jdbc:sqlserver://EXAMPLE_DB_ENDPOINT:1433;databaseName=nbs_odse;integratedSecurity=false;encrypt=true;trustServerCertificate=true" - # NBS reference and terminology database - srte_db_url: "jdbc:sqlserver://EXAMPLE_DB_ENDPOINT:1433;databaseName=nbs_srte;integratedSecurity=false;encrypt=true;trustServerCertificate=true" - # Legacy reporting database (RDB path) - rdb_db_url: "jdbc:sqlserver://EXAMPLE_DB_ENDPOINT:1433;databaseName=rdb;integratedSecurity=false;encrypt=true;trustServerCertificate=true" - # Separate reporting database (rdb_modern path only) - rdb_modern_db_url: "jdbc:sqlserver://EXAMPLE_DB_ENDPOINT:1433;databaseName=rdb_modern;integratedSecurity=false;encrypt=true;trustServerCertificate=true" - # db_deploy_admin user created in prerequisites - username: "EXAMPLE_DB_USER" - password: "EXAMPLE_DB_USER_PASSWORD" - # Separate credentials for NBS_SRTE if applicable - srte_username: "EXAMPLE_SRTE_DB_USER" - srte_password: "EXAMPLE_SRTE_DB_USER_PASSWORD" - ``` - -1. Install the pod: - - ```bash - helm install -f ./liquibase/values.yaml liquibase ./liquibase/ - ``` - -1. Verify the pod is running: - - ```bash - kubectl get pods - ``` - -1. Validate Liquibase updates from NBS databases using the `DATABASECHANGELOG` table: - - ```sql - --Last script executed should be 999-_database_object_permission_grants-001.sql. - USE NBS_ODSE; - SELECT TOP 1 * - FROM NBS_ODSE.DBO.DATABASECHANGELOG - ORDER BY DATEEXECUTED DESC; - - USE NBS_SRTE; - SELECT TOP 1 * - FROM NBS_SRTE.DBO.DATABASECHANGELOG - ORDER BY DATEEXECUTED DESC; - - USE RDB; - SELECT TOP 1 * - FROM RDB.DBO.DATABASECHANGELOG - ORDER BY DATEEXECUTED DESC; - - USE RDB_MODERN; - SELECT TOP 1 * - FROM RDB_MODERN.DBO.DATABASECHANGELOG - ORDER BY DATEEXECUTED DESC; - ``` - -If validation fails or returns unexpected results, see [Troubleshooting Liquibase installation](#troubleshooting-liquibase-installation). - -> If you arrived here from [Create service users and database objects](../real-time-reporting/#create-service-users-and-database-objects), return there to continue after Liquibase completes successfully. -{: .note } - -## Troubleshooting Liquibase installation - -Troubleshooting can vary by database. If issues persist after initial troubleshooting, contact support at . - -### User permission errors - -If a Liquibase execution fails due to a user permission error, run the following script: - -```sql -USE [NBS_SRTE] -GO -ALTER USER [nbs_ods] WITH DEFAULT_SCHEMA=[dbo] -GO -USE [NBS_SRTE] -GO -ALTER ROLE [db_owner] ADD MEMBER [nbs_ods] -``` - -### Migration errors - -If you see `Migration failed` or `Invalid object name` errors, run the following script: - -```sql -Use rdb_modern; -IF NOT EXISTS (SELECT 1 FROM sysobjects WHERE name = 'nrt_odse_Page_cond_mapping' and xtype = 'U') - BEGIN - CREATE TABLE [dbo].[nrt_odse_Page_cond_mapping] ( - [page_cond_mapping_uid] [bigint] NOT NULL, - [wa_template_uid] [bigint] NOT NULL, - [condition_cd] [varchar](20) NOT NULL, - [add_time] [datetime] NOT NULL, - [add_user_id] [bigint] NOT NULL, - [last_chg_time] [datetime] NOT NULL, - [last_chg_user_id] [bigint] NOT NULL, - CONSTRAINT [PK_nrt_odse_Page_cond_mapping] PRIMARY KEY CLUSTERED ( - [page_cond_mapping_uid] ASC - ) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY] - ) ON [PRIMARY]; - END; - -USE RDB_MODERN; -IF NOT EXISTS (SELECT 1 FROM sysobjects WHERE name = 'nrt_odse_NBS_page' and xtype = 'U') - BEGIN - CREATE TABLE [dbo].[nrt_odse_NBS_page] ( - [nbs_page_uid] [bigint] NOT NULL, - [wa_template_uid] [bigint] NOT NULL, - [form_cd] [varchar](50) NULL, - [desc_txt] [varchar](2000) NULL, - [jsp_payload] [image] NULL, - [datamart_nm] [varchar](21) NULL, - [local_id] [varchar](50) NULL, - [bus_obj_type] [varchar](50) NOT NULL, - [last_chg_user_id] [bigint] NOT NULL, - [last_chg_time] [datetime] NOT NULL, - [record_status_cd] [varchar](20) NOT NULL, - [record_status_time] [datetime] NOT NULL, - CONSTRAINT [PK_nrt_odse_NBS_page] PRIMARY KEY CLUSTERED ( - [nbs_page_uid] ASC - ) - WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY] - ) ON [PRIMARY] TEXTIMAGE_ON [PRIMARY]; - END; - -USE RDB_MODERN; -IF NOT EXISTS (SELECT 1 FROM sysobjects WHERE name = 'nrt_odse_NBS_rdb_metadata' and xtype = 'U') - BEGIN - CREATE TABLE [dbo].[nrt_odse_NBS_rdb_metadata] ( - [nbs_rdb_metadata_uid] [bigint] NOT NULL, - [nbs_page_uid] [bigint] NULL, - [nbs_ui_metadata_uid] [bigint] NOT NULL, - [rdb_table_nm] [varchar](30) NULL, - [user_defined_column_nm] [varchar](30) NULL, - [record_status_cd] [varchar](20) NOT NULL, - [record_status_time] [datetime] NOT NULL, - [last_chg_user_id] [bigint] NOT NULL, - [last_chg_time] [datetime] NOT NULL, - [local_id] [varchar](50) NULL, - [rpt_admin_column_nm] [varchar](50) NULL, - [rdb_column_nm] [varchar](30) NULL, - [block_pivot_nbr] [int] NULL, - CONSTRAINT [PK_nrt_odse_NBS_rdb_metadata] PRIMARY KEY CLUSTERED ( - [nbs_rdb_metadata_uid] ASC - ) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY] - ) ON [PRIMARY]; - - CREATE NONCLUSTERED INDEX [RDB_PERF_RDB_TBL_NM] ON [dbo].[nrt_odse_NBS_rdb_metadata] ( - [rdb_table_nm] ASC - ) - INCLUDE ( - [nbs_ui_metadata_uid], - [rdb_column_nm] - ) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, SORT_IN_TEMPDB = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) - ON [PRIMARY]; - - CREATE NONCLUSTERED INDEX [RDB_PERF_UID_RDB_TBL_NM] ON [dbo].[nrt_odse_NBS_rdb_metadata] ( - [nbs_ui_metadata_uid] ASC, - [rdb_table_nm] ASC - ) - INCLUDE ( - [rdb_column_nm] - ) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, SORT_IN_TEMPDB = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) - ON [PRIMARY]; - - CREATE NONCLUSTERED INDEX [RDB_PERF_UID] ON [dbo].[nrt_odse_NBS_rdb_metadata]( - [nbs_ui_metadata_uid] ASC - ) - INCLUDE ( - [rdb_column_nm] - ) WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, SORT_IN_TEMPDB = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) - ON [PRIMARY]; - END; -``` - -### Incomplete migration - -If the expected values are not returned for the `NBS_ODSE`, `RDB`, `NBS_SRTE` or `rdb_modern` database and the update is incomplete, clear the `DATABASECHANGELOG` table. Then rerun Liquibase: - -```sql -USE NBS_ODSE; -DELETE FROM NBS_ODSE.dbo.DATABASECHANGELOG; - -USE NBS_SRTE; -DELETE FROM NBS_SRTE.dbo.DATABASECHANGELOG; - -USE RDB; -DELETE FROM RDB.dbo.DATABASECHANGELOG; - -USE rdb_modern; -DELETE FROM rdb_modern.dbo.DATABASECHANGELOG; -``` - -[nedss-helm-liquibase-chart]: diff --git a/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md b/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md index bc7ade8..e870b5a 100644 --- a/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md +++ b/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md @@ -109,10 +109,6 @@ Now that you have completed database setup and onboarding, deploy the RTR servic 1. [Kafka connector](../../deploy-nbs7/real-time-reporting/kafka-connector.html) 1. [Java service](../../deploy-nbs7/real-time-reporting/rtr-java-services.html) -[nedss-datareporting-liquibase-service]: -[nedss-datareporting-onboarding-user-scripts]: [nedss-helm-k8-secrets-manifest]: -[nedss-datareporting-manual-deployment]: -[nedss-datareporting-onboarding-data-load]: --- From 1767481e7e4ff04106a9bda12cbda6157333abef Mon Sep 17 00:00:00 2001 From: Eric Buckley Date: Tue, 30 Jun 2026 12:17:07 -0700 Subject: [PATCH 04/11] docs: simplify real-time reporting microservices documentation Replace the itemized list of individual RTR microservices with a consolidated description of the Reporting Pipeline service to reflect current architecture. --- docs/deploy-nbs7/architecture-and-microservices.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/deploy-nbs7/architecture-and-microservices.md b/docs/deploy-nbs7/architecture-and-microservices.md index e86701d..16af55c 100644 --- a/docs/deploy-nbs7/architecture-and-microservices.md +++ b/docs/deploy-nbs7/architecture-and-microservices.md @@ -75,13 +75,7 @@ Real-Time Reporting (RTR) provides rapid transformation and delivery of data fro The following services comprise RTR: -- **Liquibase job**: Database version control management that deploys stored procedures, tables and views required for RTR pipeline -- **Person service**: Processes Patient and Provider change events -- **Observation services**: Processes Observation change events -- **Organization service**: Processes Organization change events -- **LDF service**: Processes LDF or State-defined field data change events -- **Investigation service**: Processes Public_health_case change events and provides information for page builder investigation, notifications, confirmation method, and updates the `PublicHealthCaseFact_Modern` datamart -- **Post-processing service**: Calls the post-processing stored procedures to hydrate dimensions, fact tables, and datamarts +- **Reporting Pipeline service**: ⏺ consumes ODSE/SRTE change events from Kafka, transforms them via stored procedures, and hydrates the reporting database's dimensions, facts, and datamarts in near real time. - **Debezium service**: Monitors and streams the selected list of `NBS_ODSE` and `NBS_SRTE` tables to Kafka topics - **Kafka sink service**: Persists the data from the Kafka topics to the `RDB_Modern` database tables From c66e1afb1716b4865321ccc6c0ef3ffd2a777441 Mon Sep 17 00:00:00 2001 From: Eric Buckley Date: Wed, 1 Jul 2026 16:37:31 -0700 Subject: [PATCH 05/11] docs: clarify reporting database setup options Replaced the "RDB path" and "rdb_modern path" terminology with clearer instructions on whether to use the existing RDB database or a new, duplicated database for real-time reporting (RTR). --- .../real-time-reporting/real-time-reporting.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md b/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md index e870b5a..ee12e70 100644 --- a/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md +++ b/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md @@ -62,16 +62,15 @@ To reduce risk, consider setting up RTR in a testing environment before moving t > Back up the `RDB` database before you proceed. This step cannot be undone. {: .warning } -1. Choose a database path and use it consistently throughout this guide. +1. Choose a reporting database. RTR can write to your existing `RDB` database, or to a new database you create by duplicating `RDB`. Pick one option and use it consistently throughout this guide. - - **RDB path:** Use `RDB` as the default reporting database. Turn off the classic ETL batch jobs and proceed to the next step. MasterETL remains available for manual recovery runs if needed. - - **rdb_modern path:** Create a separate reporting database by duplicating your existing reporting database. The exact steps depend on your SQL Server version and where it is hosted. If this process is unfamiliar, see [Microsoft's documentation on backup and restore operations](https://learn.microsoft.com/en-us/sql/relational-databases/backup-restore/back-up-and-restore-of-sql-server-databases?view=sql-server-ver17) before moving on to [Create service users and secrets](#create-service-users-and-secrets). + - **Use your existing RDB database** — RTR takes over writing to `RDB`. Turn off the classic ETL batch jobs and proceed to the next step. MasterETL remains available for manual recovery runs if needed. -## Set up the rdb_modern database (rdb_modern path only) + - **Create a new reporting database** (recommended for first installs) — Duplicate your existing `RDB` and point RTR at the copy. This lets you run RTR alongside MasterETL to compare results before fully committing, then turn off MasterETL only once you are satisfied. -If you are on the **rdb_modern path**, complete this section. If you are on the **RDB path**, move on to [Create service users and secrets](#create-service-users-and-secrets). For more information on choosing a path, see Step 3 in the [Prerequisites](#prerequisites) section. - -RTR requires a dedicated reporting database. To create `rdb_modern`, you restore a copy of `RDB` under a new name. This keeps the classic ETL-hydrated `RDB` intact and available while `rdb_modern` hosts the data structures the RTR pipeline requires. + If you choose this option, note the following before proceeding: + - The new database cannot be used for legacy SAS reporting. + - Run MasterETL one final time to make sure your `RDB` is fully up to date, then duplicate it under a new name. The exact steps depend on your SQL Server version and hosting environment. If this process is unfamiliar, see [Microsoft's documentation on backup and restore operations](https://learn.microsoft.com/en-us/sql/relational-databases/backup-restore/back-up-and-restore-of-sql-server-databases?view=sql-server-ver17). ## Create service users and secrets From 15c3bc2163a5ce5ca520721ac7fabad24e0e8030 Mon Sep 17 00:00:00 2001 From: Eric Buckley Date: Thu, 2 Jul 2026 17:03:14 -0700 Subject: [PATCH 06/11] docs(rtr-java): update deployment instructions Update the deployment documentation to reflect the required two-phase process for the RTR Java service. The first phase seeds the caching tables without post-processing, and the second phase enables post-processing once seeding is complete. Added new instructions for monitoring seeding progress using the /actuator/lag endpoint. --- .../real-time-reporting/rtr-java-services.md | 106 ++++++++++++------ 1 file changed, 73 insertions(+), 33 deletions(-) diff --git a/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md b/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md index aa52212..bcceb4b 100644 --- a/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md +++ b/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md @@ -13,6 +13,8 @@ redirect_from: This page covers deploying the RTR Java service that processes streamed events from Kafka and loads domain-specific reporting data. +Deploying the Java service is a two-phase process. The first deployment seeds the `nrt_*` caching tables that RTR depends on. Once seeding is complete, you reinstall the chart with post-processing enabled. + ## On this page {: .no_toc .text-delta } @@ -22,63 +24,101 @@ This page covers deploying the RTR Java service that processes streamed events f > These steps require a Unix-compatible shell. On Windows, use Git Bash, WSL, or an equivalent terminal emulator. {: .note } -## Installing the RTR Java service - -Follow these steps to configure and deploy the RTR Java service Helm chart. - > Verify that you are connected to the correct Kubernetes cluster before proceeding. To confirm, run `kubectl config current-context`. {: .important } +## Configure values.yaml + 1. Locate the Helm chart for the RTR Java service in the [NEDSS-Helm repository][nedss-helm-rtr-chart]. -1. Validate the Kubernetes secret for database credentials: +1. Copy the default `values.yaml` from the chart and fill in the required values for your environment — database connection, Kafka cluster, image repository, and any environment-specific overrides. - ```bash - kubectl get secret/database-access -o yaml +1. Set `featureFlag.postProcessingEnable` to `"false"` for the initial deployment. This is required so that the first run seeds the `nrt_*` caching tables without triggering post-processing before the data is ready: + + ```yaml + featureFlag: + postProcessingEnable: "false" ``` - > Verify that the secret contains the correct database username and password, Kafka cluster, and other required configuration values. If the secret does not exist, create it by applying the provided YAML file. Replace all placeholder values before running: - > - > Script location: [NEDSS-Helm/nbs-secrets.yaml][nedss-helm-k8-secrets-manifest] - > - > ```bash - > kubectl apply -f k8-manifests/nbs-secrets.yaml - > ``` - > - {: .note } +## Initial deployment -1. Validate the image repository: +Install the Helm chart with post-processing disabled: - ```yaml - global.image.repository: "quay.io/us-cdcgov/cdc-nbs-modernization/" - ``` +```bash +helm install reporting-pipeline-service . -f values.yaml +``` -1. Install the Helm chart for the RTR Java service: +Verify the pods are running: - ```bash - helm install reporting-pipeline-service . -f values.yaml +```bash +kubectl get pods -l app=reporting-pipeline-service +``` + +Expected output: + +```text +NAME READY STATUS RESTARTS AGE +reporting-pipeline-service- 1/1 Running 0 2m +``` + +Check the service logs to confirm it is processing events: + +```bash +kubectl logs -l app=reporting-pipeline-service --tail=50 -f +``` + +## Monitor seeding progress + +The `/actuator/lag` endpoint reports how far behind the service is in consuming its Kafka topics. Use it to determine when initial seeding is complete. When all lag values reach zero, seeding is done. + +Use `kubectl port-forward` to reach the endpoint from your local machine: + +```bash +kubectl port-forward svc/reporting-pipeline-service 8080:8080 +``` + +Then in a separate terminal: + +```bash +curl -s http://localhost:8080/actuator/lag | jq . +``` + +To poll continuously until lag reaches zero: + +```bash +watch -n 10 "curl -s http://localhost:8080/actuator/lag | jq ." +``` + +When all topic lag values are `0`, seeding is complete. Stop the port-forward (`Ctrl+C`) and proceed to the next step. + +## Final deployment + +Reinstall the chart with post-processing enabled: + +1. Update `values.yaml` to enable post-processing: + + ```yaml + featureFlag: + postProcessingEnable: "true" ``` -1. Verify the pods are running: +1. Upgrade the release: ```bash - kubectl get pods + helm upgrade reporting-pipeline-service . -f values.yaml ``` - Expected output: +1. Verify the pods restarted cleanly: - ```text - NAME READY STATUS RESTARTS AGE - rtr-java-services-reporting-pipeline-service- 1/1 Running 0 2m6s + ```bash + kubectl rollout status deployment/reporting-pipeline-service + kubectl get pods -l app=reporting-pipeline-service ``` -1. Validate the service. Replace `` with your actual domain (see [Deploy Traefik ingress controller](../../deploy-nbs7/initial-kubernetes-deployment/initial-kubernetes-deployment.html#deploy-traefik-ingress-controller)): - - **reporting-pipeline-service** +1. Confirm the service is healthy. Replace `` with your actual domain (see [Deploy Traefik ingress controller](../../deploy-nbs7/initial-kubernetes-deployment/initial-kubernetes-deployment.html#deploy-traefik-ingress-controller)): ```text https://data./reporting-pipeline-svc/actuator/health ``` [nedss-helm-rtr-chart]: -[nedss-helm-k8-secrets-manifest]: From 4622071fd6c80fc19a7ef0b7b4dc6fe2137417bb Mon Sep 17 00:00:00 2001 From: Eric Buckley Date: Tue, 7 Jul 2026 11:19:50 -0700 Subject: [PATCH 07/11] docs: update rtr java services deployment documentation - Update helm command syntax for consistency and clarity. - Update kubectl commands to monitor deployments instead of pods. - Simplify seeding progress monitoring instructions by using the URL endpoint instead of port-forwarding. --- .../real-time-reporting/rtr-java-services.md | 42 ++++++------------- 1 file changed, 12 insertions(+), 30 deletions(-) diff --git a/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md b/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md index bcceb4b..1850eb3 100644 --- a/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md +++ b/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md @@ -45,51 +45,33 @@ Deploying the Java service is a two-phase process. The first deployment seeds th Install the Helm chart with post-processing disabled: ```bash -helm install reporting-pipeline-service . -f values.yaml +helm install -f reporting-pipeline-service/values.yaml reporting-pipeline-service ./reporting-pipeline-service/ ``` Verify the pods are running: ```bash -kubectl get pods -l app=reporting-pipeline-service +kubectl get deployment reporting-pipeline-service ``` Expected output: ```text -NAME READY STATUS RESTARTS AGE -reporting-pipeline-service- 1/1 Running 0 2m -``` - -Check the service logs to confirm it is processing events: - -```bash -kubectl logs -l app=reporting-pipeline-service --tail=50 -f +NAME READY UP-TO-DATE AVAILABLE AGE +reporting-pipeline-service 1/1 1 1 16m ``` ## Monitor seeding progress -The `/actuator/lag` endpoint reports how far behind the service is in consuming its Kafka topics. Use it to determine when initial seeding is complete. When all lag values reach zero, seeding is done. - -Use `kubectl port-forward` to reach the endpoint from your local machine: - -```bash -kubectl port-forward svc/reporting-pipeline-service 8080:8080 -``` - -Then in a separate terminal: - -```bash -curl -s http://localhost:8080/actuator/lag | jq . -``` +The `/actuator/lag` endpoint reports how far behind the service is in consuming its Kafka topics. Use it to determine when initial seeding is complete. -To poll continuously until lag reaches zero: +Retrieve information on reporting-pipeline-service lag in your browser. Replace `` with your actual domain (see [Deploy Traefik ingress controller](../../deploy-nbs7/initial-kubernetes-deployment/initial-kubernetes-deployment.html#deploy-traefik-ingress-controller)): -```bash -watch -n 10 "curl -s http://localhost:8080/actuator/lag | jq ." +```text + https://data./reporting-pipeline-svc/actuator/lag ``` -When all topic lag values are `0`, seeding is complete. Stop the port-forward (`Ctrl+C`) and proceed to the next step. +When all "messagesQueued" values are `0`, seeding is complete. ## Final deployment @@ -105,14 +87,14 @@ Reinstall the chart with post-processing enabled: 1. Upgrade the release: ```bash - helm upgrade reporting-pipeline-service . -f values.yaml - ``` + helm upgrade -f reporting-pipeline-service/values.yaml reporting-pipeline-service ./reporting-pipeline-service/ + 1. Verify the pods restarted cleanly: ```bash kubectl rollout status deployment/reporting-pipeline-service - kubectl get pods -l app=reporting-pipeline-service + kubectl get deployment reporting-pipeline-service ``` 1. Confirm the service is healthy. Replace `` with your actual domain (see [Deploy Traefik ingress controller](../../deploy-nbs7/initial-kubernetes-deployment/initial-kubernetes-deployment.html#deploy-traefik-ingress-controller)): From c6b41815298e6ff40dc08c7f96d89e6857359484 Mon Sep 17 00:00:00 2001 From: Eric Buckley Date: Wed, 8 Jul 2026 13:10:35 -0700 Subject: [PATCH 08/11] docs(rtr): simplify reporting database and service user setup - Streamline the reporting database setup process by clarifying the `RDB_MODERN` duplication step. - Simplify service user configuration by focusing on necessary permissions rather than complex account separation. - Update the CDC enablement instructions to use the consolidated bootstrap script. - Remove outdated Kubernetes secret configuration steps from the guide. - Update the Java service deployment instructions to remove the `postProcessingEnable` flag configuration, which is no longer required. --- .../real-time-reporting.md | 55 +++++++------------ .../real-time-reporting/rtr-java-services.md | 9 +-- 2 files changed, 20 insertions(+), 44 deletions(-) diff --git a/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md b/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md index ee12e70..4014087 100644 --- a/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md +++ b/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md @@ -47,67 +47,50 @@ To reduce risk, consider setting up RTR in a testing environment before moving t FROM NBS_ODSE.dbo.NBS_Release; ``` - Or: - - ```sql - USE [NBS_ODSE]; - SELECT * FROM NBS_Configuration WHERE config_key = 'CODE_BASE'; - ``` - -1. Verify that the following classic ETL batch jobs have completed successfully: - - `MasterETL.bat` +1. Run the ETL jobs one final time and make sure they complete successfully. - `PHCMartETL.bat` + - `MasterETL.bat` - `covid19ETL.bat` +1. Choose a reporting database. RTR can write to your existing `RDB` database, or to a new database you create by duplicating `RDB`. Pick one option and use it consistently throughout this guide. + > Back up the `RDB` database before you proceed. This step cannot be undone. {: .warning } -1. Choose a reporting database. RTR can write to your existing `RDB` database, or to a new database you create by duplicating `RDB`. Pick one option and use it consistently throughout this guide. - - **Use your existing RDB database** — RTR takes over writing to `RDB`. Turn off the classic ETL batch jobs and proceed to the next step. MasterETL remains available for manual recovery runs if needed. - - **Create a new reporting database** (recommended for first installs) — Duplicate your existing `RDB` and point RTR at the copy. This lets you run RTR alongside MasterETL to compare results before fully committing, then turn off MasterETL only once you are satisfied. - - If you choose this option, note the following before proceeding: - - The new database cannot be used for legacy SAS reporting. - - Run MasterETL one final time to make sure your `RDB` is fully up to date, then duplicate it under a new name. The exact steps depend on your SQL Server version and hosting environment. If this process is unfamiliar, see [Microsoft's documentation on backup and restore operations](https://learn.microsoft.com/en-us/sql/relational-databases/backup-restore/back-up-and-restore-of-sql-server-databases?view=sql-server-ver17). - -## Create service users and secrets + - **Create a new reporting database** (recommended) — Duplicate your existing `RDB`, this lets you run RTR alongside MasterETL to compare results before fully committing. You can use any name for this reporting database, but for the remainder of this guide, we'll refer to it as `RDB_MODERN`. The exact steps for database duplication depend on your SQL Server version and hosting environment. If this process is unfamiliar, see [Microsoft's documentation on backup and restore operations](https://learn.microsoft.com/en-us/sql/relational-databases/backup-restore/back-up-and-restore-of-sql-server-databases?view=sql-server-ver17). -Complete the following steps to create the database users, Kubernetes secrets, and database objects that the RTR pipeline requires before [Change Data Capture](#enable-change-data-capture) can be enabled. + > If using a new reporting database, you must use the new reporting execution server to run reports (TODO: add link) + {: .note } -Running the RTR pipeline requires SQL Server login accounts for two distinct purposes: running the bootstrap scripts and schema migrations, and running the application services. Depending on your environment, these can be two separate accounts or collapsed into one. +## Create service user -### Accounts at a Glance +Complete the following steps to create the database user that the RTR requires. -| Account | Purpose | Databases | Key Permissions | -| :--- | :--- | :--- | :--- | -| **Admin account** (e.g. `rtr-admin`) | Liquibase migrations | `NBS_ODSE`, `NBS_SRTE`, `RDB / RDB_MODERN` | All NBS DBs: `db_owner` | -| **Service account** (e.g. `rtr-service-user`) | Application services reading source data and writing to the reporting database | `NBS_ODSE`, `NBS_SRTE`, `RDB / RDB_MODERN` | ODSE/SRTE: `db_datareader`
RDB/RDB_MODERN: `db_owner` | +Running RTR requires a SQL Server login account for two distinct purposes: configuring the database and running the application services. -Two accounts cover everything: `rtr-admin` handles migrations, `rtr-service-user` runs the application. A single account with both sets of permissions also works if your environment doesn't require separation. +### Account Permissions -1. **Create Kubernetes secrets for each sql user.** Each secret should include the database username and password. Script location: [NEDSS-DataReporting/create-kubernetes-secrets][nedss-helm-k8-secrets-manifest]. For steps to create secrets, see [Create secrets in your cluster](../../deploy-nbs7/initial-kubernetes-deployment/initial-kubernetes-deployment.html#create-secrets-in-your-cluster). +1. **Name**: Any name works, but we recommend using a name descriptive to the role, such as `rtr-service-user`. +1. **Purpose**: The application services reading source database and writing to the reporting database. +1. **Databases Permissions**: + - `NBS_ODSE`: `db_datareader` + - `NBS_SRTE`: `db_datareader` + - `RDB` / `RDB_MODERN`: `db_owner` ## Enable Change Data Capture -Change Data Capture (CDC) streams row-level changes from `NBS_ODSE` and `NBS_SRTE` to Kafka, where RTR services load them into the reporting database. Enabling CDC on these databases does require `sysadmin` level permissions, because of this, we have not automated its installation and have instead provided two scripts to manually apply. For more information on SQL Server Change Data Capture, please review [Microsoft's official documentation](https://learn.microsoft.com/en-us/sql/relational-databases/track-changes/enable-and-disable-change-data-capture-sql-server?view=sql-server-ver17). +Change Data Capture (CDC) streams row-level changes from `NBS_ODSE` and `NBS_SRTE` to Kafka, where RTR services load them into the reporting database. Enabling CDC on these databases does require `sysadmin` level permissions, so be sure to run the bootstrap script with a `sysadmin`account. For more information on SQL Server Change Data Capture, please review [Microsoft's official documentation](https://learn.microsoft.com/en-us/sql/relational-databases/track-changes/enable-and-disable-change-data-capture-sql-server?view=sql-server-ver17). -1. Apply bootstrap script [101 to enable CDC on NBS_ODSE](https://github.com/CDCgov/NEDSS-DataReporting/blob/main/bootstrap/101-enable_cdc_on_odse_database-001.sql). - -1. Apply bootstrap script [102 to enable CDC on NBS_SRTE](https://github.com/CDCgov/NEDSS-DataReporting/blob/main/bootstrap/102-enable_cdc_on_srte_database-001.sql). +1. Apply bootstrap script [101 to enable CDC on NBS_ODSE and NBS_SRTE](https://github.com/CDCgov/NEDSS-DataReporting/blob/v7.13/bootstrap/101-enable_cdc_on_odse_srte_databases-001.sql). ## Deploy RTR services Now that you have completed database setup and onboarding, deploy the RTR services in the following order. Some services depend on the previous ones completing successfully before deployment begins. -> Confirm that Kubernetes secrets exist for each RTR service user and the admin user before deploying. -{: .important } - 1. [Debezium](../../deploy-nbs7/real-time-reporting/debezium.html) 1. [Kafka connector](../../deploy-nbs7/real-time-reporting/kafka-connector.html) 1. [Java service](../../deploy-nbs7/real-time-reporting/rtr-java-services.html) -[nedss-helm-k8-secrets-manifest]: - --- diff --git a/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md b/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md index 1850eb3..3877e50 100644 --- a/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md +++ b/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md @@ -31,14 +31,7 @@ Deploying the Java service is a two-phase process. The first deployment seeds th 1. Locate the Helm chart for the RTR Java service in the [NEDSS-Helm repository][nedss-helm-rtr-chart]. -1. Copy the default `values.yaml` from the chart and fill in the required values for your environment — database connection, Kafka cluster, image repository, and any environment-specific overrides. - -1. Set `featureFlag.postProcessingEnable` to `"false"` for the initial deployment. This is required so that the first run seeds the `nrt_*` caching tables without triggering post-processing before the data is ready: - - ```yaml - featureFlag: - postProcessingEnable: "false" - ``` +1. Edit the "EXAMPLE*" placeholder values in `values.yaml` and replace with the correct values for your environment — database connection, Kafka cluster, and any environment-specific overrides. ## Initial deployment From 5c055400241576b7e500328ab69378b3eb3a3b3f Mon Sep 17 00:00:00 2001 From: Eric Buckley Date: Wed, 8 Jul 2026 13:12:41 -0700 Subject: [PATCH 09/11] docs: remove data compare tool documentation Remove the documentation and related configuration references for the Data Compare tool, as it is no longer supported or needed in the deployment guide. --- contributing/release-checklist.md | 1 - .../deploy-on-aws/provision-aws.md | 10 - .../real-time-reporting/data-compare-tool.md | 211 ------------------ 3 files changed, 222 deletions(-) delete mode 100644 docs/deploy-nbs7/real-time-reporting/data-compare-tool.md diff --git a/contributing/release-checklist.md b/contributing/release-checklist.md index e622dd4..b8ab1f3 100644 --- a/contributing/release-checklist.md +++ b/contributing/release-checklist.md @@ -103,7 +103,6 @@ The following pages require manual content review beyond link verification: |------|----------------| | `docs/deploy-nbs7/real-time-reporting.md` | Update the version number in the 2 code blocks to set the environment variables | | `docs/deploy-nbs7/real-time-reporting/rtr-java-services.md` | Review the consolidation warning callout for accuracy. | -| `docs/deploy-nbs7/real-time-reporting/data-compare-tool.md` | The NEDSS-DataCompare link is pinned to `main` — that repo has no version tags. Confirm this is still correct. | | `docs/deploy-nbs7/microservices-deployment/nnd-service/on-prem-data-sync.md` | Confirm the NEDSS-NNDSS release at the new tag includes a `vX.Y.Z.NEDSS.NBS.Modernized.Documentation.zip` asset. If missing, coordinate with the dev team before publishing. | | `docs/deploy-nbs7/microservices-deployment/nnd-service/on-prem-nnd-sync.md` | Same documentation zip caveat as `on-prem-data-sync.md`. | | `docs/maintain-nbs7/eks-upgrade.md` | Update the Kubernetes versions table. Confirm the conditional add-ons step still reflects correct module version behavior. *(Page not yet created as of 7.12.)* | diff --git a/docs/deploy-nbs7/deploy-on-aws/provision-aws.md b/docs/deploy-nbs7/deploy-on-aws/provision-aws.md index 5305b6b..fd37eec 100644 --- a/docs/deploy-nbs7/deploy-on-aws/provision-aws.md +++ b/docs/deploy-nbs7/deploy-on-aws/provision-aws.md @@ -42,16 +42,6 @@ Complete these steps to download the infrastructure package and prepare your env 1. Update the `terraform.tfvars` and `terraform.tf` with your environment-specific values. - If you plan to deploy the Data Compare tool, also add the following variables to your `terraform.tfvars` before running `terraform apply`. If you deployed to a non-default namespace, you should adjust the `datacompare_namespace_and_service` value accordingly. - - ```hcl - create_datacompare_irsa = true - datacompare_s3_bucket_name = "" - datacompare_s3_bucket_keyname_prefix = "" - datacompare_namespace_and_service = ["default:data-compare-api-service", "default:data-compare-processor-service"] - ``` - - This creates the IAM role (`-datacompare-role`) and S3 access policy required by the Data Compare pods. The role ARN is referenced during [Data Compare deployment](../../deploy-nbs7/real-time-reporting/data-compare-tool.html). ## Validate AWS access and network prerequisites diff --git a/docs/deploy-nbs7/real-time-reporting/data-compare-tool.md b/docs/deploy-nbs7/real-time-reporting/data-compare-tool.md deleted file mode 100644 index 436da41..0000000 --- a/docs/deploy-nbs7/real-time-reporting/data-compare-tool.md +++ /dev/null @@ -1,211 +0,0 @@ ---- -title: Data Compare -layout: page -parent: Deploy real-time reporting -nav_order: 6 -description: Explains deployment and use of Data Compare to validate RTR output against classic ETL results. -redirect_from: - - /docs/7_feature_preview/6_data_compare_tool.html - - /docs/7_feature_preview/6_data_compare_tool/ ---- - -# Deploy and use the RTR Data Compare validation tool - -This page covers deploying and using the Data Compare tool to validate RTR output against classic ETL results. - -## On this page -{: .no_toc .text-delta } - -1. TOC -{:toc} - -## Overview - -The Data Compare tool is an optional RTR validation service that allows STLT users to compare data processed by RTR against the classic ETL pipeline and identify differences. - -> This service is optional. STLTs can choose to install it only if they require RTR validation capabilities. -{: .note } - -The tool consists of two containerized services that communicate asynchronously through Kafka: - -- **Data Compare API** - pulls and prepares data from designated tables, then uploads it to a cloud storage bucket -- **Data Compare Processor** - retrieves data from the cloud storage bucket and performs the comparison logic - -Database changes are managed by Liquibase, integrated within the `DataCompareAPI` service. Schema changes are applied automatically during deployment. The database objects in the following directory are for reference only: [NEDSS-DataCompare/DataCompareAPIs/.../db/data_internal](https://github.com/CDCgov/NEDSS-DataCompare/tree/main/DataCompareAPIs/src/main/resources/db/data_internal) - -## Prerequisites - -Before deploying the Data Compare tool, verify the following: - -- Access to a cloud storage bucket for data exchange between the API and Processor services. These steps currently use Amazon S3. If you are not using Amazon S3, consult your cloud administrator for equivalent storage configuration. - - For AWS deployments, an IAM role granting the Data Compare pods access to S3 must be provisioned before deployment. This role is created by Terraform in NEDSS-Infrastructure when `create_datacompare_irsa = true` is set in your `terraform.tfvars`. The role is named `-datacompare-role`. See [Provision the AWS environment](../deploy-on-aws/provision-aws.html) for details. - -- Keycloak configured with the Data Compare API profile: [NEDSS-Helm/charts/keycloak/extra][nedss-helm-keycloak-extra] - -If your Keycloak pod uses a name or namespace other than the default, update the `authUri` in your `values.yaml`: - -```yaml -authUri: "http://keycloak.default.svc.cluster.local/auth/realms/NBS" -``` - -> These steps require a Unix-compatible shell. On Windows, use Git Bash, WSL, or an equivalent terminal emulator. -{: .note } -> Verify that you are connected to the correct Kubernetes cluster before proceeding. To confirm, run `kubectl config current-context`. -{: .important } - -## Deploy the Data Compare API - -Follow these steps to configure and deploy the Data Compare API Helm chart. - -The Helm chart is located in `charts/data-compare-api-service` in the [NEDSS-Helm repository][nedss-helm-data-compare-api-chart]. - -1. Configure `values.yaml`. Replace all placeholder values before installation: - - ```yaml - image: - # Data Compare API image - repository: "quay.io/us-cdcgov/cdc-nbs-modernization/data-compare-api-service" - pullPolicy: IfNotPresent - # Replace with the target release version tag, e.g. v1.0.1 - tag: - - ingressHost: "data.EXAMPLE_DOMAIN" - jdbc: - # SQL Server endpoint - dbserver: "EXAMPLE_DB_ENDPOINT" - username: "EXAMPLE_ODSE_DB_USER" - password: "EXAMPLE_ODSE_DB_USER_PASSWORD" - authUri: "http://keycloak.default.svc.cluster.local/auth/realms/NBS" - s3: - # AWS-specific: replace with your AWS Region and S3 bucket name - region: "AWS REGION" - bucketName: "S3 BucketName" - ``` - -1. For AWS deployments, add the IRSA role ARN to `values.yaml` to grant the pod access to S3: - - ```yaml - serviceAccount: - annotations: - eks.amazonaws.com/role-arn: "arn:aws:iam:::role/-datacompare-role" - ``` - - Replace `` and `` with your values. The role is created during infrastructure provisioning. See [Provision the AWS environment](../deploy-on-aws/provision-aws.html) for details. - -1. Install the Helm chart: - - ```bash - helm install data-compare-api-service -f ./data-compare-api-service/values.yaml data-compare-api-service - ``` - -1. Verify the pod is running: - - ```bash - kubectl get pods - ``` - -1. Validate the service by opening the Swagger UI. Replace `` with your actual domain: - - ```text - https:///comparison/swagger-ui/index.html - ``` - -## Deploy the Data Compare Processor - -Follow these steps to configure and deploy the Data Compare Processor Helm chart. - -The Helm chart is located in `charts/data-compare-processor-service` in the [NEDSS-Helm repository][nedss-helm-data-compare-processor-chart]. - -> The Processor is a Kafka consumer microservice and does not expose any API endpoints. -{: .note } - -1. Configure `values.yaml`. Replace all placeholder values before installation: - - ```yaml - image: - # Data Compare Processor image - repository: "quay.io/us-cdcgov/cdc-nbs-modernization/data-compare-processor-service" - pullPolicy: IfNotPresent - # Replace with the target release version tag, e.g. v1.0.1 - tag: - - ingressHost: "data.EXAMPLE_DOMAIN" - jdbc: - # SQL Server endpoint - dbserver: "EXAMPLE_DB_ENDPOINT" - username: "EXAMPLE_ODSE_DB_USER" - password: "EXAMPLE_ODSE_DB_USER_PASSWORD" - authUri: "http://keycloak.default.svc.cluster.local/auth/realms/NBS" - s3: - # AWS-specific: replace with your AWS Region and S3 bucket name - region: "AWS REGION" - bucketName: "S3 BucketName" - ``` - -1. For AWS deployments, add the IRSA role ARN to `values.yaml` to grant the pod access to S3: - - ```yaml - serviceAccount: - annotations: - eks.amazonaws.com/role-arn: "arn:aws:iam:::role/-datacompare-role" - ``` - - Replace `` and `` with your values. The role is created during infrastructure provisioning. See [Provision the AWS environment](../deploy-on-aws/provision-aws.html) for details. - -1. Install the Helm chart: - - ```bash - helm install data-compare-processor-service -f ./data-compare-processor-service/values.yaml data-compare-processor-service - ``` - -1. Verify the pod is running: - - ```bash - kubectl get pods - ``` - -## Configure ingress - -The Data Compare API uses the same ingress as the data ingestion service. Reuse the ingress configuration as needed: [dataingestion-service/templates/ingress.yaml](https://github.com/CDCgov/NEDSS-Helm/blob/10623c0d9788a6513bd51f4b6ed4eb0f79b30a2f/charts/dataingestion-service/templates/ingress.yaml#L99) - -## Verify the deployment - -Confirm both services are running without errors: - -```bash -kubectl get pods -kubectl logs -``` - -Both services are ready when they are healthy and the Processor begins consuming from Kafka. - -## Use the Data Compare tool - -The comparison process relies on the `Data_Compare_Config` table, which Liquibase creates and populates when the Data Compare API deploys. The table comes preloaded with records containing table names and queries that determine what data to compare. - -To start a comparison, call: - -```text -POST /comparison/api/data-compare -``` - -Pass the `runNowMode` header to control scope: - -- `true` - runs only on records in the config table where `runNow = true`; resets `runNow` to `false` when complete -- `false` - runs on all records in the config table - -This is an asynchronous endpoint. If authentication passes and there are no logical errors, it returns a success response immediately. The comparison runs in the background. - -The following diagram shows the end-to-end data flow: - -```text -API → Pull data from SQL table → Upload to S3 → Kafka → Processor → Pull from S3 → Perform comparison → Upload results to S3 -``` - -> This data flow uses Amazon S3 as the storage provider. If you are not using Amazon S3, the upload and retrieval steps differ based on your cloud provider. -{: .note } - -[nedss-helm-keycloak-extra]: -[nedss-helm-data-compare-api-chart]: -[nedss-helm-data-compare-processor-chart]: From e139391a2e228cd7ed33a977abb6b667ad8642c7 Mon Sep 17 00:00:00 2001 From: Eric Buckley Date: Wed, 8 Jul 2026 16:04:50 -0700 Subject: [PATCH 10/11] docs: simplify rtr deployment documentation Remove redundant information regarding service user creation and update the CDC documentation link for improved clarity and correctness. --- .../deploy-nbs7/real-time-reporting/real-time-reporting.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md b/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md index 4014087..7be2fe7 100644 --- a/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md +++ b/docs/deploy-nbs7/real-time-reporting/real-time-reporting.md @@ -66,14 +66,9 @@ To reduce risk, consider setting up RTR in a testing environment before moving t ## Create service user -Complete the following steps to create the database user that the RTR requires. - -Running RTR requires a SQL Server login account for two distinct purposes: configuring the database and running the application services. - ### Account Permissions 1. **Name**: Any name works, but we recommend using a name descriptive to the role, such as `rtr-service-user`. -1. **Purpose**: The application services reading source database and writing to the reporting database. 1. **Databases Permissions**: - `NBS_ODSE`: `db_datareader` - `NBS_SRTE`: `db_datareader` @@ -81,7 +76,7 @@ Running RTR requires a SQL Server login account for two distinct purposes: confi ## Enable Change Data Capture -Change Data Capture (CDC) streams row-level changes from `NBS_ODSE` and `NBS_SRTE` to Kafka, where RTR services load them into the reporting database. Enabling CDC on these databases does require `sysadmin` level permissions, so be sure to run the bootstrap script with a `sysadmin`account. For more information on SQL Server Change Data Capture, please review [Microsoft's official documentation](https://learn.microsoft.com/en-us/sql/relational-databases/track-changes/enable-and-disable-change-data-capture-sql-server?view=sql-server-ver17). +[Change Data Capture](https://learn.microsoft.com/en-us/sql/relational-databases/track-changes/about-change-data-capture-sql-server?view=sql-server-ver17) (CDC) streams row-level changes from `NBS_ODSE` and `NBS_SRTE` to Kafka, where RTR services load them into the reporting database. Enabling CDC on these databases does require `sysadmin` level permissions, so be sure to run the bootstrap script with a `sysadmin` account. 1. Apply bootstrap script [101 to enable CDC on NBS_ODSE and NBS_SRTE](https://github.com/CDCgov/NEDSS-DataReporting/blob/v7.13/bootstrap/101-enable_cdc_on_odse_srte_databases-001.sql). From e12cd4a8e0c4f31b8f5db1ba1acf7fb8b44265c8 Mon Sep 17 00:00:00 2001 From: Eric Buckley Date: Tue, 14 Jul 2026 21:17:41 -0400 Subject: [PATCH 11/11] docs: improve real-time reporting deployment instructions - Clarify placeholder example values for Kafka endpoints. - Update kubectl commands to target specific deployments. - Fix missing closing code block fence. --- docs/deploy-nbs7/real-time-reporting/debezium.md | 10 +++++----- .../deploy-nbs7/real-time-reporting/kafka-connector.md | 2 +- .../real-time-reporting/rtr-java-services.md | 1 + 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/deploy-nbs7/real-time-reporting/debezium.md b/docs/deploy-nbs7/real-time-reporting/debezium.md index 3f2ebfd..3ed54c0 100644 --- a/docs/deploy-nbs7/real-time-reporting/debezium.md +++ b/docs/deploy-nbs7/real-time-reporting/debezium.md @@ -31,7 +31,7 @@ Follow these steps to configure and deploy the Debezium Helm chart for RTR. 1. Locate the Debezium Helm chart in the [NEDSS-Helm repository][nedss-helm-debezium-chart]. -1. Configure `values.yaml`. Replace all placeholder values before installation. +1. Edit the "EXAMPLE_*" placeholder values in `values.yaml` and replace with the correct values for your environment (eg EXAMPLE_KAFKA_ENDPOINT). To retrieve your Kafka bootstrap server endpoints, see [Get bootstrap brokers](https://docs.aws.amazon.com/msk/latest/developerguide/msk-get-bootstrap-brokers.html) in the AWS MSK documentation. @@ -44,12 +44,12 @@ Follow these steps to configure and deploy the Debezium Helm chart for RTR. properties: # Kafka bootstrap server endpoint from AWS MSK - bootstrap_server: "EXAMPLE_MSK_KAFKA_ENDPOINT" + bootstrap_server: "EXAMPLE_KAFKA_ENDPOINT" env: # Kafka bootstrap server endpoint from AWS MSK - name: BOOTSTRAP_SERVERS - value: "EXAMPLE_MSK_KAFKA_ENDPOINT" + value: "EXAMPLE_KAFKA_ENDPOINT" ``` 1. Install the pod: @@ -61,7 +61,7 @@ Follow these steps to configure and deploy the Debezium Helm chart for RTR. 1. Verify the pod is running: ```bash - kubectl get pods + kubectl get deployment debezium-debezium-rtr-connect ``` 1. Validate the service. @@ -80,7 +80,7 @@ If issues persist after initial troubleshooting, contact support at diff --git a/docs/deploy-nbs7/real-time-reporting/kafka-connector.md b/docs/deploy-nbs7/real-time-reporting/kafka-connector.md index 39a5b19..fb73cb3 100644 --- a/docs/deploy-nbs7/real-time-reporting/kafka-connector.md +++ b/docs/deploy-nbs7/real-time-reporting/kafka-connector.md @@ -56,7 +56,7 @@ Follow these steps to configure and deploy the Kafka connector Helm chart for RT 1. Verify the pod is running: ```bash - kubectl get pods + kubectl get deployment kafka-connect-sink-cp-kafka-connect ``` 1. Validate the service. diff --git a/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md b/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md index 3877e50..363eccd 100644 --- a/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md +++ b/docs/deploy-nbs7/real-time-reporting/rtr-java-services.md @@ -81,6 +81,7 @@ Reinstall the chart with post-processing enabled: ```bash helm upgrade -f reporting-pipeline-service/values.yaml reporting-pipeline-service ./reporting-pipeline-service/ + ``` 1. Verify the pods restarted cleanly: