fix: use run-mode-aware admin client for init_index instead of the end-user JWT client

[edwinjosechittilappilly]

In SaaS with IBM auth, _ensure_index_exists built the OpenSearch client from the end-user's JWT. That identity can search/write documents but lacks index-admin privileges on managed OpenSearch, so the first admin call in init_index (HEAD / via indices.exists) failed with TransportError(500, '') and connector sync returned 500.

Add Clients.create_index_admin_opensearch_client, mirroring the onboarding client selection: saas -> platform service token (user-JWT fallback for legacy deployments without OPENRAG_SERVICE_TOKEN), on_prem/oss -> OpenSearch basic auth. Use it in _ensure_index_exists (fixes connector sync, traditional uploads, and router ingest in one place) and fold the onboarding block in settings/endpoints.py onto the shared helper.

Summary by CodeRabbit

• Chores

  • Improved OpenSearch client initialization and authentication handling across deployment modes to streamline index setup operations and enhance credential management consistency.

• Tests

  • Added comprehensive unit tests for client selection logic across different deployment configurations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ede1a61f-7968-4f6d-9e32-0555163a73e7

📥 Commits

Reviewing files that changed from the base of the PR and between 499a2c5 and 01eea90.

📒 Files selected for processing (4)

• src/api/documents.py
• src/api/settings/endpoints.py
• src/config/settings.py
• tests/unit/config/test_index_admin_client_selection.py

---

Walkthrough

This PR centralizes OpenSearch admin client selection logic into a single create_index_admin_opensearch_client helper method in AppClients. The helper implements run-mode-aware credential selection: SaaS prefers a service token, falls back to user JWT, or returns None; on-prem and OSS modes use basic-auth credentials. Two existing callers (_ensure_index_exists and the onboarding endpoint) are refactored to use the centralized helper, and comprehensive unit tests verify behavior across all deployment modes.

Changes

OpenSearch Admin Client Centralization

Layer / File(s)	Summary
Admin client selection helper implementation src/config/settings.py	Introduces AppClients.create_index_admin_opensearch_client(user_jwt_token: str = None) method that selects credentials for OpenSearch index administration by run mode: SaaS prefers OPENRAG_SERVICE_TOKEN with fallback to user JWT (returns None if neither available); on-prem/OSS return a newly constructed basic-auth client using current OPENSEARCH_USERNAME and OPENSEARCH_PASSWORD for runtime credential updates.
Unit tests for admin client selection tests/unit/config/test_index_admin_client_selection.py	Five test functions verify create_index_admin_opensearch_client behavior across deployment modes: SaaS prefers service token over user JWT, falls back to user JWT when service token absent, returns None when no token available; on-prem and OSS modes use basic-auth credentials; tests use monkeypatching to stub run-mode detection, token/credential getters, and client factories.
Document API index initialization update src/api/documents.py	_ensure_index_exists refactored to import app_clients and call create_index_admin_opensearch_client(jwt_token) for index initialization, replacing prior conditional initialization based on IBM_AUTH_ENABLED and jwt_token.
Onboarding endpoint index setup refactoring src/api/settings/endpoints.py	Onboarding OpenSearch index setup consolidated to call shared create_index_admin_opensearch_client helper; imports updated to remove get_opensearch_password dependency; SaaS-mode admin_username derived from service token JWT identity when available, otherwise falls back to onboarding user's user_id; updated inline documentation reflects the run-mode-aware approach.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• langflow-ai/openrag#1713: Both PRs modify the onboarding OpenSearch index/security initialization to change how the OpenSearch client and admin_username are selected (JWT-based for SaaS vs basic-auth for on-prem/OSS).
• langflow-ai/openrag#1772: Both PRs implement/use an admin-capable OpenSearch client for index operations (main PR by centralizing admin client selection, retrieved PR by wiring index refresh to use the admin client).
• langflow-ai/openrag#1626: Both PRs add service/platform-token-derived helpers on AppClients for OpenSearch admin operations.

Suggested reviewers

• ricofurtado
• rodageve
• phact

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 38.46% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: replacing end-user JWT clients with a run-mode-aware admin client for index initialization operations across the codebase.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-admin-user-jwt-os

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ricofurtado]

Liked the centralized OpenSearch admin client selection logic