From 83f574bd427a4b87ba785a0fe9bc03c8b6cdecfe Mon Sep 17 00:00:00 2001 From: Shahzeb Ali <126076773+Shahzeb-DataEngineer@users.noreply.github.com> Date: Wed, 14 Oct 2026 14:05:37 +0500 Subject: [PATCH 1/2] Docs: Add OpenSearch FGAC permissions guide (closes #29856) Documents the minimal OpenSearch security permissions the OpenMetadata server backend needs when running against a security-enabled cluster (FGAC / security plugin), scoped to 2.0.x and verified against the 2.0.5 search-client source. Includes index patterns, cluster permissions with 'when needed' guidance, a ready-to-use role example, and the permission changes across releases (1.6.6, 1.13.x, 2.x). --- menu.md | 2 + v2.0.x/deployment/kubernetes/eks.mdx | 4 + .../opensearch-fgac-permissions.mdx | 127 ++++++++++++++++++ 3 files changed, 133 insertions(+) create mode 100644 v2.0.x/deployment/opensearch-fgac-permissions.mdx diff --git a/menu.md b/menu.md index 1cdcb4da6..f81268ab7 100644 --- a/menu.md +++ b/menu.md @@ -214,6 +214,8 @@ site_menu: - category: Deployment / OSS Security url: /deployment/oss-security + - category: Deployment / OpenSearch FGAC Permissions + url: /deployment/opensearch-fgac-permissions - category: Connectors url: /connectors diff --git a/v2.0.x/deployment/kubernetes/eks.mdx b/v2.0.x/deployment/kubernetes/eks.mdx index 963977b8c..7358ca53f 100644 --- a/v2.0.x/deployment/kubernetes/eks.mdx +++ b/v2.0.x/deployment/kubernetes/eks.mdx @@ -33,6 +33,10 @@ We support When using AWS Services the SearchType Configuration for elastic search should be `opensearch`, for both cases ElasticSearch and OpenSearch, as you can see in the ElasticSearch configuration example below. + +If your Amazon OpenSearch Service domain has fine-grained access control (FGAC) enabled, the OpenMetadata server role only needs a minimal set of index and cluster permissions — not admin access. See the [OpenSearch FGAC Permissions](/deployment/opensearch-fgac-permissions) guide for the full list and a ready-to-use role example. + + We recommend - Amazon RDS to be in Multiple Availability Zones. - Amazon OpenSearch (or ElasticSearch) Service with Multiple Availability Zones with minimum 2 Nodes. diff --git a/v2.0.x/deployment/opensearch-fgac-permissions.mdx b/v2.0.x/deployment/opensearch-fgac-permissions.mdx new file mode 100644 index 000000000..a6f95ce53 --- /dev/null +++ b/v2.0.x/deployment/opensearch-fgac-permissions.mdx @@ -0,0 +1,127 @@ +--- +title: "OpenSearch Fine-Grained Access Control Permissions" +description: "Minimal OpenSearch security permissions required by the OpenMetadata server backend when running against a security-enabled cluster." +sidebarTitle: "OpenSearch FGAC Permissions" +collate: false +--- + +# OpenSearch Fine-Grained Access Control Permissions + +When OpenMetadata runs against a security-enabled OpenSearch cluster — for example, +Amazon OpenSearch Service with fine-grained access control (FGAC), or a self-managed +cluster with the security plugin — the OpenMetadata server role does **not** need +admin-level access. This page lists the minimal set of index patterns and cluster +permissions the server backend requires. + + +**Scope:** OpenMetadata **2.0.x**, OpenSearch backend only. The Elasticsearch backend +is not covered here. This list was compiled by auditing the search-client source +code of the 2.0.5 release. Permission requirements can change between releases — +validate in a non-production environment before applying least-privilege roles in +production. + + +## How OpenMetadata uses OpenSearch + +The server backend writes to two kinds of targets, both namespaced by the +`clusterAlias` setting (default: `openmetadata`): + +- **Entity indexes and aliases** — one index per entity type, named + `_` (for example `openmetadata_table_search_index`). +- **Data Insights data streams** — `-di-data-assets-` + (for example `openmetadata-di-data-assets-table`). + +## Index patterns + +Grant index-level permissions on these patterns (replace `` with your +`clusterAlias`): + +| Pattern | Used for | +|---|---| +| `_*` | Entity indexes and aliases | +| `-di-*` | Data Insights data streams | + + +On 2.x the Data Insights lifecycle (rollover) runs application-side, so the +`.ds--di-*` backing-index pattern required by 1.x ISM policies is no +longer needed for fresh 2.x deployments. If you are migrating from 1.x, keep it +until the migration cleanup has removed the old ISM policies. + + +## Cluster permissions + +| Permission | When needed | +|---|---| +| `cluster:monitor/*` | Always — cluster health, stats, settings and nodes info | +| `cluster_composite_ops` | Always — bulk indexing and multi-search | +| `indices:admin/index_template/*` | Always — create and delete index templates | +| `cluster:admin/index_template/*` | Always — create and delete index templates | +| `indices:admin/component_template/*` | Always — create and delete component templates | +| `cluster:admin/component_template/*` | Always — create and delete component templates | +| `cluster:admin/opendistro/ism/policy/*` | Only when migrating 1.x → 2.x — deletes the legacy DI lifecycle policies; not needed for fresh 2.x deployments | +| `cluster:admin/search/pipeline/*` | Optional — only for deployments still serving hybrid search through the legacy named pipeline; 2.x inlines pipelines in the search request, which needs no cluster privilege | + +## Index-level operations + +All data operations run against the index patterns above and need no extra +cluster privilege: search, multi-get, document get/index/update/delete, bulk, +delete-by-query, update-by-query, reindex, force merge, index settings and +mapping updates, alias management, and data-stream create/delete/get/rollover. + +## Example security role + +Below is a ready-to-use OpenSearch security-plugin role for a 2.0.x deployment +with `clusterAlias: openmetadata`. Adjust the prefix to match your configuration. + +```json +{ + "cluster_permissions": [ + "cluster:monitor/*", + "cluster_composite_ops", + "indices:admin/index_template/*", + "cluster:admin/index_template/*", + "indices:admin/component_template/*", + "cluster:admin/component_template/*" + ], + "index_permissions": [ + { + "index_patterns": ["openmetadata_*", "openmetadata-di-*"], + "allowed_actions": [ + "crud", + "indices:data/write/bulk*", + "indices:data/write/delete_by_query", + "indices:data/write/update_by_query", + "indices:data/write/reindex", + "indices:admin/forcemerge", + "indices:admin/settings/update", + "indices:admin/mapping/put", + "indices:admin/aliases*", + "indices:admin/data_stream/*", + "indices:admin/rollover", + "indices:admin/refresh" + ] + } + ], + "tenant_permissions": [] +} +``` + + +On Amazon OpenSearch Service with FGAC, map this role to the IAM role or user +OpenMetadata authenticates with (for example via IRSA) in **Security → Roles → +Mapped users**. The server connects with SigV4 signing when IRSA is configured. + + +## Permission changes across releases + +Releases sometimes add OpenSearch calls that require new permissions. Notable +changes: + +- **1.6.6** — Data Insights data streams, templates and the ISM policy started + using the `clusterAlias` prefix (`-di-data-assets-*`). Roles scoped to + an unprefixed pattern break in either upgrade direction. +- **1.13.x** — Added reindex, force merge, index settings updates and search + pipelines for hybrid search, expanding the required surface versus 1.6.x. +- **2.0.x** — ISM policy management removed (lifecycle is now application-side + rollover); the named hybrid-search pipeline became best-effort, so + `cluster:admin/search/pipeline/*` is optional. From b53fb53975292fe2adc94a16eb9068ec3538f1d1 Mon Sep 17 00:00:00 2001 From: Shahzeb Ali <126076773+Shahzeb-DataEngineer@users.noreply.github.com> Date: Fri, 16 Oct 2026 09:43:53 +0500 Subject: [PATCH 2/2] docs: add create_index to OpenSearch FGAC example role The crud action group does not grant indices:admin/create, but the 2.0.5 OpenSearchIndexManager calls client.indices().create(...) when initializing missing entity search indexes, so a role copied from this example could not create them. Add the create_index action group to the example role and mention index creation in the operations list. Signed-off-by: Shahzeb Ali <126076773+Shahzeb-DataEngineer@users.noreply.github.com> --- v2.0.x/deployment/opensearch-fgac-permissions.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/v2.0.x/deployment/opensearch-fgac-permissions.mdx b/v2.0.x/deployment/opensearch-fgac-permissions.mdx index a6f95ce53..d03ca9c2a 100644 --- a/v2.0.x/deployment/opensearch-fgac-permissions.mdx +++ b/v2.0.x/deployment/opensearch-fgac-permissions.mdx @@ -63,8 +63,8 @@ until the migration cleanup has removed the old ISM policies. ## Index-level operations -All data operations run against the index patterns above and need no extra -cluster privilege: search, multi-get, document get/index/update/delete, bulk, +All operations run against the index patterns above and need no extra +cluster privilege: index creation, search, multi-get, document get/index/update/delete, bulk, delete-by-query, update-by-query, reindex, force merge, index settings and mapping updates, alias management, and data-stream create/delete/get/rollover. @@ -88,6 +88,7 @@ with `clusterAlias: openmetadata`. Adjust the prefix to match your configuration "index_patterns": ["openmetadata_*", "openmetadata-di-*"], "allowed_actions": [ "crud", + "create_index", "indices:data/write/bulk*", "indices:data/write/delete_by_query", "indices:data/write/update_by_query",