> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open-metadata.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Breaking Changes - Platform, Config & Security | Official Documentation
> llmConfiguration, database-backed sessions and concurrent-session limits, openmetadata.yaml changes and the 2.0.0 database migration.
# Platform, Configuration & Security
Two changes here will stop a 2.0 server from behaving as expected with a 1.13 configuration: the LLM
and embedding configuration move, and the new session limits.
## LLM and embedding configuration moved
**Breaking.** Affects every deployment using semantic search, natural-language query, or any LLM
feature.
Provider configuration is no longer nested inside `elasticsearch.naturalLanguageSearch`. It moves to a
new **top-level `llmConfiguration`** block, with embeddings as a sub-section that reuses the same
provider credentials.
### Removed from `naturalLanguageSearch`
```
embeddingProvider
maxConcurrentRequests
bedrock.* (awsConfig, modelId, embeddingModelId, embeddingDimension, maxTokens, temperature, timeoutSeconds)
openai.* (apiKey, endpoint, deploymentName, apiVersion, modelId, embeddingModelId, embeddingDimension, …)
google.* (apiKey, endpoint, modelId, embeddingModelId, embeddingDimension)
djl.* (embeddingModel)
```
What remains under `naturalLanguageSearch` is only its own knobs — `semanticSearchEnabled`,
`knnNumCandidatesMultiplier` (new, default `2`) and a new `filterExtractor` block. Every LLM
provider, credential, chat model and embedding setting now lives under `llmConfiguration`.
### The 2.0 shape
```yaml conf/openmetadata.yaml theme={null}
elasticsearch:
naturalLanguageSearch:
semanticSearchEnabled: ${SEMANTIC_SEARCH_ENABLED:-false}
# Embedding provider/model/credentials now live under llmConfiguration.embeddings
llmConfiguration:
enabled: ${LLM_ENABLED:-false}
provider: ${LLM_PROVIDER:-noop} # noop | openai | azureOpenAI | bedrock | google | anthropic
maxConcurrentRequests: ${LLM_MAX_CONCURRENT_REQUESTS:-5}
openai:
apiKey: ${LLM_OPENAI_API_KEY:-""}
modelId: ${LLM_OPENAI_MODEL_ID:-"gpt-4o-mini"}
endpoint: ${LLM_OPENAI_ENDPOINT:-""} # with deploymentName for Azure OpenAI
deploymentName: ${LLM_OPENAI_DEPLOYMENT:-""}
apiVersion: ${LLM_OPENAI_API_VERSION:-"2024-02-01"}
maxTokens: ${LLM_OPENAI_MAX_TOKENS:-4096}
bedrock:
awsConfig:
enabled: ${BEDROCK_AWS_IAM_AUTH_ENABLED:-true}
region: ${AWS_DEFAULT_REGION:-""}
accessKeyId: ${AWS_ACCESS_KEY_ID:-""}
secretAccessKey: ${AWS_SECRET_ACCESS_KEY:-""}
sessionToken: ${AWS_SESSION_TOKEN:-""}
modelId: ${LLM_BEDROCK_MODEL_ID:-"eu.anthropic.claude-haiku-4-5-20251001-v1:0"}
google:
apiKey: ${LLM_GOOGLE_API_KEY:-""}
modelId: ${LLM_GOOGLE_MODEL_ID:-"gemini-2.5-flash"}
anthropic:
apiKey: ${LLM_ANTHROPIC_API_KEY:-""}
modelId: ${LLM_ANTHROPIC_MODEL_ID:-"claude-3-5-sonnet-20240620"}
baseUrl: ${LLM_ANTHROPIC_BASE_URL:-"https://api.anthropic.com"}
embeddings:
provider: ${EMBEDDING_PROVIDER:-bedrock} # bedrock | openai | google | djl
maxConcurrentRequests: ${MAX_CONCURRENT_EMBEDDING_REQUESTS:-10}
bedrock:
embeddingModelId: ${AWS_BEDROCK_EMBED_MODEL_ID:-"amazon.titan-embed-text-v2:0"}
embeddingDimension: ${AWS_BEDROCK_EMBEDDING_DIMENSION:-512}
openai:
embeddingModelId: ${OPENAI_EMBEDDING_MODEL_ID:-"text-embedding-3-small"}
embeddingDimension: ${OPENAI_EMBEDDING_DIMENSION:-1536}
google:
embeddingModelId: ${GOOGLE_EMBEDDING_MODEL_ID:-"gemini-embedding-001"}
embeddingDimension: ${GOOGLE_EMBEDDING_DIMENSION:-768}
djl:
embeddingModel: ${DJL_EMBEDDING_MODEL:-"ai.djl.huggingface.pytorch/sentence-transformers/all-MiniLM-L6-v2"}
```
The embedding provider may differ from the chat provider; embeddings reuse the credentials from the
provider blocks above.
### Environment variable renames
| 1.13 | 2.0 |
| --------------------------- | ------------------------ |
| `AWS_BEDROCK_REGION` | `AWS_DEFAULT_REGION` |
| `AWS_BEDROCK_ACCESS_KEY` | `AWS_ACCESS_KEY_ID` |
| `AWS_BEDROCK_SECRET_KEY` | `AWS_SECRET_ACCESS_KEY` |
| `AWS_BEDROCK_SESSION_TOKEN` | `AWS_SESSION_TOKEN` |
| `AWS_BEDROCK_MODEL_ID` | `LLM_BEDROCK_MODEL_ID` |
| `OPENAI_API_KEY` | `LLM_OPENAI_API_KEY` |
| `OPENAI_API_ENDPOINT` | `LLM_OPENAI_ENDPOINT` |
| `OPENAI_DEPLOYMENT_NAME` | `LLM_OPENAI_DEPLOYMENT` |
| `OPENAI_API_VERSION` | `LLM_OPENAI_API_VERSION` |
| `GOOGLE_API_KEY` | `LLM_GOOGLE_API_KEY` |
| `GOOGLE_API_ENDPOINT` | *(removed)* |
The embedding-specific variables keep their names but move under `llmConfiguration.embeddings`.
**Unchanged:** `SEMANTIC_SEARCH_ENABLED`, `EMBEDDING_PROVIDER`, `MAX_CONCURRENT_EMBEDDING_REQUESTS`,
`BEDROCK_AWS_IAM_AUTH_ENABLED`, and every `*_EMBEDDING_MODEL_ID` / `*_EMBEDDING_DIMENSION` variable.
**`LLM_ENABLED` and `LLM_PROVIDER` gate the entire block.** Both must be set before embeddings — or
any other LLM feature — will run. Porting the provider credentials across without also enabling the
block leaves semantic search switched off.
`BEDROCK_AWS_IAM_AUTH_ENABLED` flips from `false` to **`true`**. Deployments that relied on the
default being off, and supplied static keys, should confirm which credential chain is used.
Port your configuration into `llmConfiguration` **before** upgrading. Semantic search silently
degrades — the provider resolves to `noop` — rather than failing loudly if the block is missing.
## Session management
### Sessions are database-backed
**Behavioural.** Affects multi-pod deployments.
2.0 adds a `user_session` table so sessions survive pod restarts and are shared across pods.
Previously each pod held its own in-memory session state, which caused spurious logouts behind a load
balancer without sticky sessions.
### Concurrent sessions are capped per user
**Behavioural — users will be logged out.**
```yaml theme={null}
authenticationConfiguration:
sessionExpiry: ${AUTHENTICATION_SESSION_EXPIRY:-"604800"} # 7 days, all auth providers
maxActiveSessionsPerUser: ${AUTHENTICATION_MAX_ACTIVE_SESSIONS_PER_USER:-5}
```
When the limit is exceeded, the **least recently used active sessions are revoked**. `sessionExpiry`
now applies to **all** auth providers with a minimum of 3600 s; `oidcConfiguration.sessionExpiry`
becomes a deprecated fallback.
Users who work across several browsers or devices, and **service accounts driving many concurrent
sessions**, will start being silently signed out of the oldest sessions. Raise
`AUTHENTICATION_MAX_ACTIVE_SESSIONS_PER_USER` if that is your pattern — but prefer bot tokens for
automation.
### Additional trusted redirect URIs
**Additive.** `additionalTrustedRedirectUris` allows redirect URIs beyond the callback URL and the
server's own callbacks. Each entry must match the requested URI **exactly**. Intended for
browser-extension logins.
Related SSO hardening: the server callback is trusted in the SAML redirect allowlist, SAML
pending-session ids are carried in `RelayState`, and the OIDC login loop is hardened with an
interactive fallback that preserves pending logins.
### Admin test-login
**Additive.** `POST /v1/system/security/test-login/validate-token` validates a browser-obtained OIDC
`id_token` against a **candidate (unsaved)** security configuration, so an admin can confirm a real
login resolves the expected identity before saving.
### LDAP
**Additive.** `recursiveGroupMembership` (default `false`) enables transitive group resolution for
Active Directory nested groups.
## Database connection timeouts changed
**Behavioural — long-running queries will now be cut off.**
| Setting | 1.13 | 2.0 |
| --------------------------------------- | ------------------- | -------------------- |
| `database.queryTimeoutSeconds` | — | **`300`** (new) |
| Postgres `loginTimeout` (s) | `300` | `30` |
| Postgres `postgresqlConnectTimeout` (s) | `60` | `30` |
| Postgres `postgresqlSocketTimeout` (s) | `30000` (≈8.3 h) | **`300`** (5 min) |
| MySQL `mysqlSocketTimeout` (ms) | `30000000` (≈8.3 h) | **`300000`** (5 min) |
Any statement that previously ran for more than five minutes — a large reindex batch, a heavy Data
Insights aggregation, an oversized CSV import — now aborts. Raise `DB_QUERY_TIMEOUT_SECONDS`,
`DB_POSTGRESQL_SOCKET_TIMEOUT` or `DB_MYSQL_SOCKET_TIMEOUT` if you have legitimately long statements,
and check upgrade logs for statement-timeout errors.
## Server & logging configuration
### HTTP/2 is available (opt-in)
**Additive.**
```yaml theme={null}
server:
applicationConnectors:
- type: ${SERVER_PROTOCOL:-http} # http (default) | h2c (cleartext HTTP/2) | h2 (TLS)
```
Both HTTP/2 modes are backwards compatible — HTTP/1.1 clients keep working on the same port. Worth
enabling when browsers hit the server directly; not worth it behind an HTTP/2-terminating load
balancer.
### Response compression enabled
**Behavioural.** `server.gzip.enabled` is now `true`. Responses above roughly 256 bytes are gzipped.
Clients that mishandle `Content-Encoding: gzip` need `Accept-Encoding: identity`.
### Logging hardening
**Behavioural and security-relevant.**
```yaml theme={null}
logging:
loggers:
org.eclipse.jetty:
level: ${JETTY_LOG_LEVEL:-INFO}
org.openmetadata.service.audit.AuditLogRepository:
level: INFO
appenders:
- type: console
filterFactories:
- type: audit-exclude-filter-factory
```
`LOG_LEVEL` sets the **root** logger, and at `DEBUG` the HTTP parser prints every request header
verbatim — including `Authorization: Bearer ` and session cookies. Since `DEBUG` is exactly what
support asks customers to enable, and those logs get attached to tickets, the Jetty logger is now
pinned independently via `JETTY_LOG_LEVEL`.
Audit entries are logged at `INFO` with an audit marker and routed to `logs/audit.log`, and a filter
keeps them out of the console appender.
If you parsed audit entries out of stdout, read `logs/audit.log` instead. If you need Jetty debug
output, set `JETTY_LOG_LEVEL=DEBUG` explicitly — and be aware of what it prints.
### Object storage configuration expanded
**Behavioural.** Affects deployments using file attachments.
The `objectStorage` block gains full `s3` and `azure` sub-sections (endpoint, bucket, region,
credentials, IAM role, prefix path, SSE algorithm and KMS key for S3; container, connection string,
managed identity and blob endpoint for Azure). The default `provider` changes from `NOOP` to `s3`, but
`enabled` still defaults to `false`, so nothing activates until you turn it on.
This backs the new `/v1/attachments` API for uploaded assets. For MinIO, use provider `s3` and point
`s3.endpoint` at the MinIO server.
## The 2.0.0 database migration
**Plan a maintenance window.**
### New tables
| Table | Purpose |
| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
| `task_entity`, `new_task_sequence`, `task_migration_mapping` | Task redesign |
| `task_form_schema_entity` | Task form schemas |
| `announcement_entity` | Standalone announcements |
| `activity_stream` (partitioned), `activity_stream_config` | Activity stream |
| `background_job_logs` | Background job logs |
| `search_index_job`, `search_index_retry_queue` | Distributed reindexing |
| `user_session` | Database-backed sessions |
| `user_preferences` | Application-managed per-user preferences |
| `knowledge_center`, `drive_folder`, `context_file`, `context_file_content`, `context_memory`, `asset_entity` | Knowledge and Context Center, plus attachments |
| `ai_governance_framework_entity`, `ai_framework_control_entity`, `audit_report_entity` | AI Governance Studio |
### Altered tables
* `background_jobs` gains `progress`, `total`, `result`, `error`, `message`, `cancelRequested`, `completedAt`
* `tag_usage` gains `metadata JSON`
* `audit_log_event` gains `search_text`
* `thread_entity` is **renamed** to `thread_entity_legacy`
### Data migrations
| Step | Effect |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Suggestions migration | `suggestions` → `task_entity` |
| Thread task migration | thread tasks → `task_entity` (plus `task_migration_mapping`) |
| Legacy activity migration | generated feed threads → `activity_stream` |
| Announcement migration | `thread_entity` → `announcement_entity` |
| Search ranking backfill | Staged ranking configuration into search settings |
| RDF schedule migration | Weekly cadence and full rebuild |
| Four policy steps | Task permissions on roles and policies |
| SQL rewrites | Databricks Pipeline `authType`, Snowflake/Databricks/Unity Catalog `policyAgentConfig`, Postgres `policyAgentConfig` removal, application runtime-field stripping, Data Insights `dataQuality` removal, MCP application configuration removal, `AutoClassificationBotPolicy` Topic rule, CVV recognizer anchor, stale `pipelineStatuses` cleanup |
### Index additions
Many, including `(deleted, name)` and `(deleted, serviceType)` composites on all thirteen service
tables (for `/v1/services/overview`), `name` indexes on the new entity tables so the distributed
reindex cursor runs index-only, and an execution-id index on the workflow instance state time series.
On clusters with tens of millions of rows, composite index creation on service and entity tables is
the long pole of the migration. Size your maintenance window accordingly.
## Dependency and CVE updates
**Additive** — not breaking, but relevant to hardened deployments.
Backend: Jetty 12.1.10 (with the Jetty BOM imported so transitive modules follow), Netty
4.1.137.Final, BouncyCastle 1.85, jackson-databind 2.18.8, log4j 2.25.5, thrift 0.24.0,
reactor-netty-http 1.2.18, tomcat-jdbc/juli 11.0.11, httpcore5 5.4.3, Redshift JDBC 2.2.2, Kubernetes
client-java 25.0.1 and Apache Airflow 3.2.1.
Frontend: `ws` 8.21.0, `handlebars` 4.5.2, `js-yaml` 5.2.2, `fast-uri` 3.1.5, `nanoid` 3.3.17 and
`brace-expansion` 1.1.18 / 5.0.9.
Other operationally relevant security fixes: test-connection workflow triggers are authorized, CSRF
failures fail secure and retry on the next request, `testDestination` redacts destination
configuration, and SCIM `displayName` synchronisation is fixed.