MACROECO NWU Onboarding Guide

Part 1 — Central Deployment (HO Workspace)
Part 2 — Self-Managed Fork (Own Workspace)
Troubleshooting

Deployment Model	Target Workspace	Who Deploys	Who Manages Secrets	How Upgrades Work
Central	HO workspace	Central team	Central repo	Central team redeploys all NWUs
Self-managed fork	NWU’s own workspace	NWU team	Fork repo	NWU team syncs fork and redeploys

Currently deployed NWUs:

NWU	Model	Workspace
`ho`, `tbsk`, `rbua`, `rbro`, `rbspk`, `validation`	Central	HO (`rbi-apex-at04-ws08`)

Part 1 — Central Deployment (HO Workspace)

NWU teams do not perform any of these steps. The entire onboarding and deployment process is handled by the central MACROECO team. NWU teams only provide their infrastructure details.

What the NWU team provides

The NWU team sends the following to the central team (e.g. via email or JIRA):

Field	Example
NWU identifier	`rbhu`
Service Principal UUID	`a1b2c3d4-5678-9abc-def0-1234567890ab`
SP Client Secret	(via secure channel)
Cluster Policy ID	`001F3A2B7C8D9E00`
Instance Profile ARN	`arn:aws:iam::982081076718:instance-profile/apex-uc-rbi-apex-at04-ws08-uc09`
IAM Role ARN	`arn:aws:iam::890742592045:role/finca-copy-s3apex-data-p02-rbhu`
Notification emails	`jan.novak@example.com`, `petra.kralova@example.com`

How the NWU team obtains these values: Create a JIRA ticket referencing APEX-15817 requesting an SP and Use Case Role ARN. Include:

Field Value

Source S3 Bucket s3://finca-890742592045-mopla-p02-data/<nwu>

ARN Role arn:aws:iam::890742592045:role/finca-copy-s3apex-data-p02-<nwu>

KMS ARN arn:aws:kms:eu-central-1:890742592045:key/6d321a0b-148a-4a9a-898b-75e60b4bfcd8

Field	Value
Source S3 Bucket	`s3://finca-890742592045-mopla-p02-data/<nwu>`
ARN Role	`arn:aws:iam::890742592045:role/finca-copy-s3apex-data-p02-<nwu>`
KMS ARN	`arn:aws:kms:eu-central-1:890742592045:key/6d321a0b-148a-4a9a-898b-75e60b4bfcd8`

What the central team does

1. Create the config file

cp config/TEMPLATE.yml config/rram-ifrs9-<nwu>.yml

Fill in only the required fields — everything else inherits from defaults:

variables:
  nwu:
    default: "<nwu>"
  cluster_user:
    default: "<service-principal-uuid>"
  policy_id:
    default: "<cluster-policy-id>"
  instance_profile_arn:
    default: "arn:aws:iam::982081076718:instance-profile/<instance-profile-name>"
  role_arn:
    default: "arn:aws:iam::890742592045:role/finca-copy-s3apex-data-p02-${var.nwu}"
  notification_emails:
    default:
      - "<email-1>"
      - "<email-2>"

2. Add GitHub secrets

In Repository Settings → Secrets and variables → Actions, add:

Secret	Value
`DATABRICKS_CLIENT_ID_<NWU>`	Service Principal Client ID
`DATABRICKS_CLIENT_SECRET_<NWU>`	Service Principal Client Secret

3. Commit, push, and deploy

git checkout -b onboard/<nwu>
git add config/rram-ifrs9-<nwu>.yml
git commit -m "Onboard <nwu> NWU configuration"
git push origin onboard/<nwu>
# Merge PR after validate-configs CI passes

Then: Actions → Deploy → Run workflow

Input	Value
Branch	e.g. `release/1.1.0`
NWU identifier	e.g. `rbhu`
Target	`prod`
Databricks Workspace URL	(leave empty)

4. Notify the NWU team

Your MACROECO app is deployed at: https://rbi-apex-at04-ws08.cloud.databricks.com/compute/apps

Look for macroeco-ui-<nwu>-prod. Start via the three-dot menu (1-2 min startup). Job failure alerts go to the notification emails in your config.

Upgrades

On each new release, the central team redeploys all NWUs:

Actions → Deploy → Run workflow → NWU: ho  → prod
Actions → Deploy → Run workflow → NWU: tbsk → prod
Actions → Deploy → Run workflow → NWU: rbua → prod
...

All NWUs can be deployed in parallel — each has its own concurrency group.

Part 2 — Self-Managed Fork (Own Workspace)

NWUs that operate their own Databricks workspace deploy independently by forking this repository at a release tag. No central team involvement is needed after the initial fork.

All values shown with <angle-bracket> placeholders must be replaced with your actual infrastructure details.

Workflow at a glance

 ┌─────────────────────────────────────────────┐
 │  PREREQUISITES                              │
 │  Provision SP, Cluster Policy, Instance      │
 │  Profile, Role ARN in your own workspace     │
 └──────────────────────┬──────────────────────┘
                        │
                        ▼
 ┌─────────────────────────────────────────────┐
 │  STEP 1 — Fork & Clone                      │
 │  Fork repo on GitHub UI                      │
 │  git checkout tags/v1.x.0                    │
 └──────────────────────┬──────────────────────┘
                        │
                        ▼
 ┌─────────────────────────────────────────────┐
 │  STEP 2 — Create Config File                 │
 │  cp TEMPLATE.yml to rram-ifrs9-<nwu>.yml     │
 │  Fill required fields + own-workspace        │
 │  overrides: use_case, workspace_host,        │
 │  s3_bucket                                   │
 └──────────────────────┬──────────────────────┘
                        │
                        ▼
 ┌─────────────────────────────────────────────┐
 │  STEP 3 — Add GitHub Secrets                 │
 │  DATABRICKS_CLIENT_ID_<NWU>                  │
 │  DATABRICKS_CLIENT_SECRET_<NWU>              │
 │  in fork's repo settings                     │
 └──────────────────────┬──────────────────────┘
                        │
                        ▼
 ┌─────────────────────────────────────────────┐
 │  STEP 4 — Deploy                             │
 │                                              │
 │  Option A (recommended):                     │
 │    Actions > Deploy > Run workflow            │
 │    NWU: <nwu>  Target: prod                  │
 │    Workspace URL: leave empty                │
 │                                              │
 │  Option B (CLI):                             │
 │    export DATABRICKS_HOST=...                │
 │    databricks bundle deploy -t prod          │
 └──────────────────────┬──────────────────────┘
                        │
                        ▼
 ┌─────────────────────────────────────────────┐
 │  STEP 5 — Access the App                     │
 │  <workspace-url>/compute/apps                │
 │  Find macroeco-ui-<nwu>-prod                 │
 │  Start via three-dot menu                    │
 └──────────────────────┬──────────────────────┘
                        │
                        ▼
 ┌─────────────────────────────────────────────┐
 │  UPGRADES                                    │
 │  git fetch upstream --tags                   │
 │  git checkout tags/v<new>                    │
 │  Re-run Deploy workflow                      │
 └─────────────────────────────────────────────┘

Prerequisites

Before starting, ensure the following are provisioned in your own workspace:

A Service Principal (SP) with workspace access
A Use Case Role ARN (Instance Profile ARN) for S3 access
A Cluster Policy assigned to the SP
Your Databricks workspace URL
Your S3 bucket name
Your APEX use case / group name in the workspace

Step 1: Fork the repository

Fork this repository on GitHub (one-time, via the GitHub UI):

https://code.rbi.tech/raiffeisen/rram-primes-macromodeling-pypk-dab → Fork

Then clone your fork and check out the desired release tag:

git clone https://code.rbi.tech/<your-github-org>/<your-fork-repo>.git
cd <your-fork-repo>

git fetch --all --tags
git checkout tags/v1.1.0

Verify the version:

cat VERSION
# Expected output: 1.1.0

Step 2: Create your config file

cp config/TEMPLATE.yml config/rram-ifrs9-<nwu>.yml

Fill in all required fields plus the three own-workspace overrides at the bottom:

variables:

  nwu:
    default: "<nwu>"

  cluster_user:
    default: "<service-principal-uuid>"

  node_type:
    default: "r7a.4xlarge"

  policy_id:
    default: "<cluster-policy-id>"

  instance_profile_arn:
    default: "<instance-profile-arn>"

  role_arn:
    default: "arn:aws:iam::890742592045:role/finca-copy-s3apex-data-p02-<nwu>"

  notification_emails:
    default:
      - "<team-email-1>"
      - "<team-email-2>"

  # ─── Own-workspace overrides (required for self-managed forks) ─────────
  use_case:
    default: "<your-use-case>"

  workspace_host:
    default: "<your-workspace-url>"

  s3_bucket:
    default: "<your-s3-bucket>"

You may delete other NWU config files from config/ — they belong to other NWUs.

Config file naming rule

The filename must end with -<nwu>.yml where <nwu> matches the nwu variable:

Filename	`nwu` variable	Valid?
`rram-ifrs9-<nwu>.yml`	`<nwu>`	Yes
`<nwu>-macroeco.yml`	`<nwu>`	Yes (pattern: `rram-*-<nwu>.yml` — but `rram-ifrs9-` prefix is recommended)
`config-<nwu>.yml`	`<nwu>`	No — doesn’t match `rram-*-<nwu>.yml`

Where to find each value

Variable	Where to find it
`nwu`	Your NWU short name (lowercase, e.g. `rbhu`, `rbsk`)
`cluster_user`	Service Principal UUID from APEX provisioning
`policy_id`	Workspace → Compute → Policies → your use case → Policy ID at the top
`instance_profile_arn`	Instance Profile ARN from the JIRA ticket
`role_arn`	IAM Role ARN from the JIRA ticket
`notification_emails`	Team emails — these receive Databricks job failure alerts
`use_case`	Your APEX use case / group name in the workspace
`workspace_host`	Your full Databricks workspace URL (e.g. `https://rbi-apex-xx00-ws00.cloud.databricks.com`)
`s3_bucket`	Your S3 bucket name (e.g. `finca-<aws-account-id>-<nwu>-prod-data`)

Step 3: Add GitHub secrets

In your fork’s GitHub settings → Secrets and variables → Actions, add:

Secret	Value
`DATABRICKS_CLIENT_ID_<NWU>`	Service Principal Client ID
`DATABRICKS_CLIENT_SECRET_<NWU>`	Service Principal Client Secret

The secret names must follow the pattern DATABRICKS_CLIENT_ID_<NWU> / DATABRICKS_CLIENT_SECRET_<NWU> where <NWU> is the uppercase NWU identifier.

Step 4: Deploy

Option A: GitHub Actions (recommended)

In your fork: Actions → Deploy → Run workflow

Input	Value
Branch	`v1.1.0` (the tag you checked out)
NWU identifier	`<nwu>`
Target	`prod`
Databricks Workspace URL	(leave empty — auto-resolves from config)

The workflow will: 1. Find config/rram-*-<nwu>.yml 2. Read workspace_host from config 3. Read use_case from config 4. Derive app path → /Workspace/<use_case>/macroeco_prod/files/resources/apps/macroeco_ui 5. Validate secrets DATABRICKS_CLIENT_ID_<NWU> / DATABRICKS_CLIENT_SECRET_<NWU> 6. Deploy the DAB bundle and start the app

Option B: CLI (alternative)

export DATABRICKS_HOST="<your-workspace-url>"
export DATABRICKS_CLIENT_ID="<service-principal-client-id>"
export DATABRICKS_CLIENT_SECRET="<service-principal-client-secret>"

cp config/rram-ifrs9-<nwu>.yml config.yml
export BUNDLE_VAR_bundle_version=$(cat VERSION)

databricks bundle validate -t prod
databricks bundle deploy -t prod

Step 5: Access the application

After deployment, the app is available at:

<your-workspace-url>/compute/apps

Look for macroeco-ui-<nwu>-prod. Start via the three-dot menu on the right (1-2 min startup).

Refer to the User Manual for usage instructions.

Upgrades

When a new version is released by the central team:

# Add upstream remote (one-time)
git remote add upstream https://code.rbi.tech/raiffeisen/rram-primes-macromodeling-pypk-dab.git

# Sync to new release
git fetch upstream --tags
git checkout tags/v1.2.0

Or use GitHub’s “Sync fork” button, then re-run the Deploy workflow with the same NWU identifier.

Your config file and secrets remain unchanged across upgrades unless the release notes specify new required variables.

Troubleshooting

Issue	Cause	Fix
`No config file found for NWU 'xxx'`	Config file missing or wrong naming	Ensure `config/rram-*-xxx.yml` exists with matching `nwu` value
`Missing GitHub secrets`	Secrets not added or wrong naming	Add `DATABRICKS_CLIENT_ID_XXX` / `DATABRICKS_CLIENT_SECRET_XXX` in repo settings
Deployment targets wrong workspace	`workspace_host` not set in config	Add `workspace_host` override (required for own-workspace NWUs)
App path incorrect	`use_case` doesn’t match workspace structure	Set `use_case` explicitly in config
Fork is behind upstream	New MACROECO release available	`git fetch upstream --tags && git checkout tags/v<new>`
CI validation fails on PR	Missing required field or empty value	Check all REQUIRED fields in TEMPLATE.yml are filled

MACROECO NWU Onboarding Guide

Table of Contents

Part 1 — Central Deployment (HO Workspace)

What the NWU team provides

What the central team does

1. Create the config file

2. Add GitHub secrets

3. Commit, push, and deploy

4. Notify the NWU team

Upgrades

Part 2 — Self-Managed Fork (Own Workspace)

Workflow at a glance

Prerequisites

Step 1: Fork the repository

Step 2: Create your config file

Config file naming rule

Where to find each value

Step 3: Add GitHub secrets

Step 4: Deploy

Option A: GitHub Actions (recommended)

Option B: CLI (alternative)

Step 5: Access the application

Upgrades

Troubleshooting