diff --git a/menu.md b/menu.md index 1cdcb4da..f81268ab 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 963977b8..7358ca53 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 00000000..d03ca9c2 --- /dev/null +++ b/v2.0.x/deployment/opensearch-fgac-permissions.mdx @@ -0,0 +1,128 @@ +--- +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 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. + +## 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", + "create_index", + "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.