Skip to content

Add battle-tested improvements to app-python, app-apx, and model-serving skills#209

Open
CheeYuTan wants to merge 1 commit intodatabricks-solutions:mainfrom
CheeYuTan:fix/app-skills-battle-tested-improvements
Open

Add battle-tested improvements to app-python, app-apx, and model-serving skills#209
CheeYuTan wants to merge 1 commit intodatabricks-solutions:mainfrom
CheeYuTan:fix/app-skills-battle-tested-improvements

Conversation

@CheeYuTan
Copy link
Contributor

Summary

Adds real-world fixes and troubleshooting guidance to 3 skills, based on hands-on experience deploying Databricks Apps in production.

databricks-app-python (6 files, +8.4KB)

Critical Rules (SKILL.md):

  • /metrics endpoint requirement — gateway health-checks this endpoint
  • CDN blocking — app runtime blocks outbound CDN requests (React, Recharts, Google Fonts, Babel)
  • Don't delete-recreate apps — just redeploy; deleting disrupts OAuth integration
  • Don't upload dev files (node_modules/, __pycache__/, frontend/src/)
  • React hooks ordering — hooks before early returns to avoid Error #310

Resource Management (2-app-resources.md):

  • Fix valueFrom YAML syntax (valueFrom.resource: instead of flat valueFrom:)
  • Add CLI API PATCH workflow for attaching resources programmatically
  • Add valueFrom vs value fallback troubleshooting

Framework Guidance (3-frameworks.md):

  • Add DATABRICKS_APP_PORT details per framework command
  • Add general tips: /metrics endpoint, CDN blocking, never delete apps

Deployment (4-deployment.md):

  • Add port binding guidance
  • Add "never delete-recreate" warning with clean stale files workflow
  • Add resource attachment via API PATCH (critical — without it, gateway shows "App Not Available")
  • Add permissions configuration via CLI

Lakebase (5-lakebase.md):

  • Add OAuth security label error fix (SECURITY LABEL FOR databricks_auth)
  • Add PGPASSWORD empty workaround using SDK token generation
  • Add Lakebase Sync (reverse ETL) quick-start instructions

Troubleshooting (SKILL.md):

  • "App Not Available" after deploy
  • Frontend loads blank/black (CDN blocking)
  • React page crashes to blank (Error #310)
  • Gateway health check fails

databricks-app-apx (1 file, +385B)

  • Add React Error #310 (hooks ordering) troubleshooting entry

databricks-model-serving (1 file, +61B)

  • Add system.ai.similarity_search to built-in UC functions table

Test plan

  • Verify SKILL.md renders correctly in GitHub
  • Verify valueFrom YAML syntax matches current Databricks Apps runtime
  • Verify API PATCH endpoints are current (/api/2.0/apps/<app-name>)
  • Confirm system.ai.similarity_search is a valid built-in function

…ing skills

Real-world fixes from deploying Databricks Apps in production:

databricks-app-python:
- Add 5 critical MUST/MUST NOT rules: /metrics endpoint, CDN blocking, don't
  delete-recreate apps, don't upload dev files, React hooks ordering
- Fix valueFrom YAML syntax (valueFrom.resource instead of flat valueFrom)
- Add CLI API PATCH workflow for attaching resources programmatically
- Add valueFrom vs value fallback troubleshooting
- Add port binding guidance and DATABRICKS_APP_PORT details per framework
- Add "never delete-recreate" warning and clean stale files workflow
- Add Lakebase OAuth security label error fix and PGPASSWORD workaround
- Add Lakebase Sync (reverse ETL) quick-start instructions
- Add 4 new troubleshooting entries: App Not Available, blank frontend,
  React Error #310, gateway health check

databricks-app-apx:
- Add React Error #310 (hooks ordering) troubleshooting entry

databricks-model-serving:
- Add system.ai.similarity_search to built-in UC functions table
@CheeYuTan CheeYuTan force-pushed the fix/app-skills-battle-tested-improvements branch from 30840d6 to e37b320 Compare March 5, 2026 12:15
@CheeYuTan
Copy link
Contributor Author

Test Results

Test Status Details
CI Validation (validate_skills.py) PASS All 26 skills validated
SKILL.md Frontmatter PASS All 3 modified skills (databricks-app-python, databricks-app-apx, databricks-model-serving) have valid frontmatter
No /metrics endpoint PASS Zero matches across all files — incorrect requirement properly excluded
OAuth patterns PASS Uses correct from databricks.sdk import WorkspaceClient pattern
install_skills.sh PASS No changes needed

Changes Summary (7 files, +173/-23 lines)

File What Changed
databricks-app-apx/SKILL.md Added React Error #310 troubleshooting (hooks after early returns)
databricks-app-python/SKILL.md 4 new critical rules (no CDN, no delete-recreate, no dev files, hooks ordering). 3 new troubleshooting entries
databricks-app-python/2-app-resources.md Fixed valueFrom syntax to use nested resource: key. Added CLI API PATCH for resource attachment
databricks-app-python/3-frameworks.md Port-binding notes for Streamlit/Flask/FastAPI. CDN blocking warning
databricks-app-python/4-deployment.md Fixed valueFrom syntax. Rewrote redeployment (clean stale files, not delete-all). Added permissions config via CLI
databricks-app-python/5-lakebase.md OAuth/SP troubleshooting. generate_database_credential SDK pattern. Lakebase Sync (reverse ETL) section
databricks-model-serving/4-tools-integration.md Added system.ai.similarity_search to built-in UC functions

All changes are battle-tested fixes from real deployments.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant