From e410463f4fa90ddde8144f40c01a164f574dd921 Mon Sep 17 00:00:00 2001 From: raphael-istari Date: Mon, 17 Nov 2025 15:43:23 -0800 Subject: [PATCH] move multitenancy to admin --- .../docs/admin/admin-tasks/index.md | 3 - .../multitenancy.md | 4 +- .../admin-tasks/secure-alter-operations.md | 11 -- docusaurus-docs/docs/clients/csharp.md | 2 +- docusaurus-docs/docs/clients/go.md | 2 +- docusaurus-docs/docs/clients/java.md | 3 +- .../docs/clients/javascript/http.md | 3 +- docusaurus-docs/docs/clients/python.md | 2 +- .../configuration/change-data-capture.md | 2 +- .../version-v24.1/admin/admin-tasks/index.md | 3 - .../admin/admin-tasks/multitenancy.md | 179 ++++++++++++++++++ .../version-v24.1/clients/csharp.md | 2 +- .../version-v24.1/clients/go.md | 2 +- .../version-v24.1/clients/java.md | 3 +- .../version-v24.1/clients/javascript/http.md | 3 +- .../version-v24.1/clients/python.md | 2 +- .../configuration/change-data-capture.md | 2 +- .../version-v24.1-sidebars.json | 7 +- docusaurus-docs/sidebars.ts | 5 +- 19 files changed, 198 insertions(+), 42 deletions(-) rename docusaurus-docs/docs/admin/{enterprise-features => admin-tasks}/multitenancy.md (96%) delete mode 100644 docusaurus-docs/docs/admin/admin-tasks/secure-alter-operations.md create mode 100644 docusaurus-docs/docs_versioned_docs/version-v24.1/admin/admin-tasks/multitenancy.md diff --git a/docusaurus-docs/docs/admin/admin-tasks/index.md b/docusaurus-docs/docs/admin/admin-tasks/index.md index 44518ac4..2f6a85cb 100644 --- a/docusaurus-docs/docs/admin/admin-tasks/index.md +++ b/docusaurus-docs/docs/admin/admin-tasks/index.md @@ -15,8 +15,6 @@ Dgraph Alpha provides the following administrative endpoints: - **`/admin/config/cache_mb`** - Configure cache size - **`/admin/draining`** - Drain connections from a node - **`/admin/shutdown`** - Shutdown a single Alpha node -- **`/admin/schema`** - Schema management -- **`/admin/schema/validate`** - Validate schema - **`/alter`** - Apply schema updates and drop predicates - **`/login`** - Authenticate ACL users - **`/health`** - health status @@ -33,7 +31,6 @@ The following administrative tasks are available: ### Data Management - **[Restrict Mutation Operations](restrict-mutation-operations)** - Control mutation permissions and enforce strict schema validation -- **[Secure Alter Operations](secure-alter-operations)** - Protect schema updates and predicate drops with authentication - **[Export Database](export-database)** - Export data from Dgraph for backup, migration, or sharing - **[Delete Database](delete-database)** - Drop all data from the database diff --git a/docusaurus-docs/docs/admin/enterprise-features/multitenancy.md b/docusaurus-docs/docs/admin/admin-tasks/multitenancy.md similarity index 96% rename from docusaurus-docs/docs/admin/enterprise-features/multitenancy.md rename to docusaurus-docs/docs/admin/admin-tasks/multitenancy.md index 6d7511fb..3847302e 100644 --- a/docusaurus-docs/docs/admin/enterprise-features/multitenancy.md +++ b/docusaurus-docs/docs/admin/admin-tasks/multitenancy.md @@ -6,7 +6,7 @@ description: Enable multiple tenants to share a Dgraph cluster using logically s Multi-tenancy enables multiple tenants to coexist in the same Dgraph cluster using `uint64` namespaces. Each tenant operates in its own namespace with logical data separation—data is stored in the same `p` directory but is not accessible across namespaces. :::note -**Enterprise Feature**: Multi-tenancy requires [Access Control Lists](access-control-lists) (ACL) to be enabled. See [License](license) for details. +**Enterprise Feature**: Multi-tenancy requires [Access Control Lists](../../installation/configuration/enable-acl) (ACL) to be enabled. ::: Multi-tenancy builds upon ACL and scopes ACL policies to individual tenants. Access controls are applied per tenant to specific predicates or all predicates within that tenant. Tenants are logically separated; each client must authenticate within a tenant and can only access data as allowed by the tenant's ACL rules. @@ -58,7 +58,7 @@ mutation { } ``` -This creates a namespace, automatically creates a guardian group for that namespace, and creates a `groot` user with the specified password (default is `password`) in the guardian group. Use these credentials to login and perform operations like [`addUser`](access-control-lists#create-a-regular-user). +This creates a namespace, automatically creates a guardian group for that namespace, and creates a `groot` user with the specified password (default is `password`) in the guardian group. Use these credentials to login and perform[`user management opertions`](user-management-access-control). ### List Namespaces diff --git a/docusaurus-docs/docs/admin/admin-tasks/secure-alter-operations.md b/docusaurus-docs/docs/admin/admin-tasks/secure-alter-operations.md deleted file mode 100644 index aeef9eef..00000000 --- a/docusaurus-docs/docs/admin/admin-tasks/secure-alter-operations.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Secure Alter Operations ---- - -Alter operations allow clients to apply schema updates and drop predicates from the database. By default, all clients are allowed to perform alter operations. - -You can secure alter operations using token authentication. See [Admin Endpoint Security](../security/admin-endpoint-security#securing-alter-operations) for detailed configuration instructions. - -For enterprise-grade access control, see [Enable ACL](../../installation/configuration/enable-acl) and [User Management and Access Control](user-management-access-control). - - diff --git a/docusaurus-docs/docs/clients/csharp.md b/docusaurus-docs/docs/clients/csharp.md index 867b0b25..a1b0c611 100644 --- a/docusaurus-docs/docs/clients/csharp.md +++ b/docusaurus-docs/docs/clients/csharp.md @@ -28,7 +28,7 @@ var client = new DgraphClient(new Channel("127.0.0.1:9080", ChannelCredentials.I ### Multi-tenancy -In [multi-tenancy](../admin/enterprise-features/multitenancy) environments, Dgraph provides a new method `LoginRequest()`, +In multi-tenants environments, Dgraph provides a method `LoginRequest()`, which will allow the users to login to a specific namespace. In order to create a Dgraph client, and make the client login into namespace `123`: diff --git a/docusaurus-docs/docs/clients/go.md b/docusaurus-docs/docs/clients/go.md index 9503cab0..94567183 100644 --- a/docusaurus-docs/docs/clients/go.md +++ b/docusaurus-docs/docs/clients/go.md @@ -63,7 +63,7 @@ func newClient() *dgo.Dgraph { ### Multi-tenancy -In [multi-tenancy](../admin/enterprise-features/multitenancy) environments, Dgraph provides a new method `LoginIntoNamespace()`, +In multi-tenants environments, Dgraph provides the method `LoginIntoNamespace()`, which will allow the users to login to a specific namespace. In order to create a dgo client, and make the client login into namespace `123`: diff --git a/docusaurus-docs/docs/clients/java.md b/docusaurus-docs/docs/clients/java.md index 9089f776..1c26886e 100644 --- a/docusaurus-docs/docs/clients/java.md +++ b/docusaurus-docs/docs/clients/java.md @@ -67,8 +67,7 @@ dgraphClient.login(USER_ID, USER_PASSWORD); ### Multi-tenancy -If [multi-tenancy](../admin/enterprise-features/multitenancy) is enabled, by default the login method on client will login into the namespace `0`. -In order to login into some other namespace, use the `loginIntoNamespace` method on the client: +In multi-tenants environments, use the `loginIntoNamespace` method on the client: ```java dgraphClient.loginIntoNamespace(USER_ID, USER_PASSWORD, NAMESPACE); diff --git a/docusaurus-docs/docs/clients/javascript/http.md b/docusaurus-docs/docs/clients/javascript/http.md index 87387d97..be2cc44e 100644 --- a/docusaurus-docs/docs/clients/javascript/http.md +++ b/docusaurus-docs/docs/clients/javascript/http.md @@ -78,8 +78,7 @@ await clientStub.login(); Some Dgraph configurations require extra access tokens. - -Alpha servers can be configured with [Secure Alter Operations](../../admin/admin-tasks/secure-alter-operations). +Alpha servers can be configured with [Secure Alter Operations](../../admin/security/admin-endpoint-security). In this case the token needs to be set on the client instance: ```js diff --git a/docusaurus-docs/docs/clients/python.md b/docusaurus-docs/docs/clients/python.md index bc48c2cc..060f4fa8 100644 --- a/docusaurus-docs/docs/clients/python.md +++ b/docusaurus-docs/docs/clients/python.md @@ -39,7 +39,7 @@ client = pydgraph.DgraphClient(client_stub) ### Multi-tenancy -In [multi-tenancy](../admin/enterprise-features/multitenancy) environments, PyDgraph provides a new method `login_into_namespace()`, +In multi-tenants environments, PyDgraph provides the method `login_into_namespace()`, which will allow the users to login to a specific namespace. In order to create a python client, and make the client login into namespace `123`: diff --git a/docusaurus-docs/docs/installation/configuration/change-data-capture.md b/docusaurus-docs/docs/installation/configuration/change-data-capture.md index 4f112f33..033fba26 100644 --- a/docusaurus-docs/docs/installation/configuration/change-data-capture.md +++ b/docusaurus-docs/docs/installation/configuration/change-data-capture.md @@ -89,7 +89,7 @@ The `operation` field specifies the drop operation: `attribute`, `type`, `data`, ## Multi-Tenancy -In a [multi-tenant environment](../../admin/enterprise-features/multitenancy), CDC events streamed to Kafka are distributed across Kafka partitions by the Kafka client based on the multi-tenancy namespace. +In multi-tenants environment, CDC events streamed to Kafka are distributed across Kafka partitions by the Kafka client based on the multi-tenancy namespace. ## Limitations diff --git a/docusaurus-docs/docs_versioned_docs/version-v24.1/admin/admin-tasks/index.md b/docusaurus-docs/docs_versioned_docs/version-v24.1/admin/admin-tasks/index.md index 44518ac4..2f6a85cb 100644 --- a/docusaurus-docs/docs_versioned_docs/version-v24.1/admin/admin-tasks/index.md +++ b/docusaurus-docs/docs_versioned_docs/version-v24.1/admin/admin-tasks/index.md @@ -15,8 +15,6 @@ Dgraph Alpha provides the following administrative endpoints: - **`/admin/config/cache_mb`** - Configure cache size - **`/admin/draining`** - Drain connections from a node - **`/admin/shutdown`** - Shutdown a single Alpha node -- **`/admin/schema`** - Schema management -- **`/admin/schema/validate`** - Validate schema - **`/alter`** - Apply schema updates and drop predicates - **`/login`** - Authenticate ACL users - **`/health`** - health status @@ -33,7 +31,6 @@ The following administrative tasks are available: ### Data Management - **[Restrict Mutation Operations](restrict-mutation-operations)** - Control mutation permissions and enforce strict schema validation -- **[Secure Alter Operations](secure-alter-operations)** - Protect schema updates and predicate drops with authentication - **[Export Database](export-database)** - Export data from Dgraph for backup, migration, or sharing - **[Delete Database](delete-database)** - Drop all data from the database diff --git a/docusaurus-docs/docs_versioned_docs/version-v24.1/admin/admin-tasks/multitenancy.md b/docusaurus-docs/docs_versioned_docs/version-v24.1/admin/admin-tasks/multitenancy.md new file mode 100644 index 00000000..3847302e --- /dev/null +++ b/docusaurus-docs/docs_versioned_docs/version-v24.1/admin/admin-tasks/multitenancy.md @@ -0,0 +1,179 @@ +--- +title: Multi-Tenancy +description: Enable multiple tenants to share a Dgraph cluster using logically separated namespaces +--- + +Multi-tenancy enables multiple tenants to coexist in the same Dgraph cluster using `uint64` namespaces. Each tenant operates in its own namespace with logical data separation—data is stored in the same `p` directory but is not accessible across namespaces. + +:::note +**Enterprise Feature**: Multi-tenancy requires [Access Control Lists](../../installation/configuration/enable-acl) (ACL) to be enabled. +::: + +Multi-tenancy builds upon ACL and scopes ACL policies to individual tenants. Access controls are applied per tenant to specific predicates or all predicates within that tenant. Tenants are logically separated; each client must authenticate within a tenant and can only access data as allowed by the tenant's ACL rules. + +The default namespace (`0x00`) is called a `galaxy`. [Guardians of the Galaxy](#guardians-of-the-galaxy) are super-admins with special privileges to create or delete namespaces and reset passwords across namespaces. Each namespace has a guardian group with root access to that namespace. Users belong to a single namespace; to access multiple namespaces, create separate user accounts for each. + +:::tip +For multi-tenant environments, consider setting a query timeout using `--limit query-limit=500ms` when starting Dgraph Alpha. +::: + +## Access Control Roles + +### Guardians of the Galaxy +Super Admins of namespace `0x00` + +- Create and delete namespaces +- Reset passwords across namespaces +- Query and mutate the default namespace (`0x00`) +- Trigger cluster-wide backups and exports +- Export all namespaces or specific namespaces + +### Guardians of a Namespace +- Create users and groups within the namespace +- Assign users to groups and predicates to groups +- Export the namespace +- Drop data within the namespace +- Query and mutate within the namespace + +**Normal Users**: +- Login into a namespace +- Query and mutate within the namespace as permitted by ACL rules + +:::note +Guardians of the Galaxy cannot read across tenants. They are used only for database administration operations such as exporting data of all tenants. +::: + +## Namespace Operations + +### Create a Namespace + +Only [Guardians of the Galaxy](#guardians-of-the-galaxy) can create namespaces. Send the JWT access token in the `X-Dgraph-AccessToken` header: + +```graphql +mutation { + addNamespace(input: {password: "mypass"}) { + namespaceId + message + } +} +``` + +This creates a namespace, automatically creates a guardian group for that namespace, and creates a `groot` user with the specified password (default is `password`) in the guardian group. Use these credentials to login and perform[`user management opertions`](user-management-access-control). + +### List Namespaces + +Only [Guardians of the Galaxy](#guardians-of-the-galaxy) can list active namespaces using the GraphQL `state` query: + +```graphql +query { + state { + namespaces + } +} +``` + +Response: + +```json +{ + "data": { + "state": { + "namespaces": [2, 1, 0] + } + } +} +``` + +### Delete a Namespace + +Only [Guardians of the Galaxy](#guardians-of-the-galaxy) can delete namespaces. Send the JWT access token in the `X-Dgraph-AccessToken` header: + +```graphql +mutation { + deleteNamespace(input: {namespaceId: 123}) { + namespaceId + message + } +} +``` + +### Reset Passwords + +Only [Guardians of the Galaxy](#guardians-of-the-galaxy) can reset passwords across namespaces: + +```graphql +mutation { + resetPassword(input: {userId: "groot", password: "newpassword", namespace: 100}) { + userId + message + } +} +``` + +## Drop Operations + +The `drop all` operation can only be triggered by a [Guardian of the Galaxy](#guardians-of-the-galaxy) and deletes data and schema across all namespaces. All other drop operations run at namespace level. Guardians of a namespace can trigger `drop data` within their namespace, which deletes all data but retains the schema. + +For example, to drop data within a namespace: + +```bash +curl 'http://localhost:8080/alter' \ + -H 'X-Dgraph-AccessToken: ' \ + --data-raw '{"drop_op":"DATA"}' +``` + +For information about other drop operations, see [Alter the database](../../clients/raw-http#alter-the-dql-schema). + +## Backups and Exports + +Backups are cluster-wide only and can only be triggered by a [Guardian of the Galaxy](#guardians-of-the-galaxy). Exports can be generated cluster-wide or at namespace level. + +[Initial import](../../migration/bulk-loader) and [Live import](../../migration/live-loader) tools support multi-tenancy. + + +### Exports + +Exports generate `.rdf` or `.json` files and schemas that include namespace information. If a Guardian of the Galaxy exports the whole cluster, a single folder contains export data of all namespaces in a single file with a single schema. + +Namespace-specific exports contain the namespace value in the generated `.rdf` file: + +```rdf +<0x01> "name" "ibrahim" <0x12> . -> belongs to namespace 0x12 +<0x01> "name" "ibrahim" <0x0> . -> belongs to namespace 0x00 +``` + +**Export a specific namespace** (Guardian of the Galaxy): + +```graphql +mutation { + export(input: {format: "rdf", namespace: 1234}) { + response { + message + } + } +} +``` + +**Export current namespace** (Guardian of a Namespace - no namespace parameter needed): + +```graphql +mutation { + export(input: {format: "rdf"}) { + response { + message + } + } +} +``` + +**Export all namespaces** (Guardian of the Galaxy only): + +```graphql +mutation { + export(input: {format: "rdf", namespace: -1}) { + response { + message + } + } +} +``` diff --git a/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/csharp.md b/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/csharp.md index 867b0b25..a1b0c611 100644 --- a/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/csharp.md +++ b/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/csharp.md @@ -28,7 +28,7 @@ var client = new DgraphClient(new Channel("127.0.0.1:9080", ChannelCredentials.I ### Multi-tenancy -In [multi-tenancy](../admin/enterprise-features/multitenancy) environments, Dgraph provides a new method `LoginRequest()`, +In multi-tenants environments, Dgraph provides a method `LoginRequest()`, which will allow the users to login to a specific namespace. In order to create a Dgraph client, and make the client login into namespace `123`: diff --git a/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/go.md b/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/go.md index 9503cab0..94567183 100644 --- a/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/go.md +++ b/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/go.md @@ -63,7 +63,7 @@ func newClient() *dgo.Dgraph { ### Multi-tenancy -In [multi-tenancy](../admin/enterprise-features/multitenancy) environments, Dgraph provides a new method `LoginIntoNamespace()`, +In multi-tenants environments, Dgraph provides the method `LoginIntoNamespace()`, which will allow the users to login to a specific namespace. In order to create a dgo client, and make the client login into namespace `123`: diff --git a/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/java.md b/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/java.md index 9089f776..1c26886e 100644 --- a/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/java.md +++ b/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/java.md @@ -67,8 +67,7 @@ dgraphClient.login(USER_ID, USER_PASSWORD); ### Multi-tenancy -If [multi-tenancy](../admin/enterprise-features/multitenancy) is enabled, by default the login method on client will login into the namespace `0`. -In order to login into some other namespace, use the `loginIntoNamespace` method on the client: +In multi-tenants environments, use the `loginIntoNamespace` method on the client: ```java dgraphClient.loginIntoNamespace(USER_ID, USER_PASSWORD, NAMESPACE); diff --git a/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/javascript/http.md b/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/javascript/http.md index 87387d97..be2cc44e 100644 --- a/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/javascript/http.md +++ b/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/javascript/http.md @@ -78,8 +78,7 @@ await clientStub.login(); Some Dgraph configurations require extra access tokens. - -Alpha servers can be configured with [Secure Alter Operations](../../admin/admin-tasks/secure-alter-operations). +Alpha servers can be configured with [Secure Alter Operations](../../admin/security/admin-endpoint-security). In this case the token needs to be set on the client instance: ```js diff --git a/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/python.md b/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/python.md index bc48c2cc..060f4fa8 100644 --- a/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/python.md +++ b/docusaurus-docs/docs_versioned_docs/version-v24.1/clients/python.md @@ -39,7 +39,7 @@ client = pydgraph.DgraphClient(client_stub) ### Multi-tenancy -In [multi-tenancy](../admin/enterprise-features/multitenancy) environments, PyDgraph provides a new method `login_into_namespace()`, +In multi-tenants environments, PyDgraph provides the method `login_into_namespace()`, which will allow the users to login to a specific namespace. In order to create a python client, and make the client login into namespace `123`: diff --git a/docusaurus-docs/docs_versioned_docs/version-v24.1/installation/configuration/change-data-capture.md b/docusaurus-docs/docs_versioned_docs/version-v24.1/installation/configuration/change-data-capture.md index 4f112f33..033fba26 100644 --- a/docusaurus-docs/docs_versioned_docs/version-v24.1/installation/configuration/change-data-capture.md +++ b/docusaurus-docs/docs_versioned_docs/version-v24.1/installation/configuration/change-data-capture.md @@ -89,7 +89,7 @@ The `operation` field specifies the drop operation: `attribute`, `type`, `data`, ## Multi-Tenancy -In a [multi-tenant environment](../../admin/enterprise-features/multitenancy), CDC events streamed to Kafka are distributed across Kafka partitions by the Kafka client based on the multi-tenancy namespace. +In multi-tenants environment, CDC events streamed to Kafka are distributed across Kafka partitions by the Kafka client based on the multi-tenancy namespace. ## Limitations diff --git a/docusaurus-docs/docs_versioned_sidebars/version-v24.1-sidebars.json b/docusaurus-docs/docs_versioned_sidebars/version-v24.1-sidebars.json index d5763ef0..c28b5aff 100644 --- a/docusaurus-docs/docs_versioned_sidebars/version-v24.1-sidebars.json +++ b/docusaurus-docs/docs_versioned_sidebars/version-v24.1-sidebars.json @@ -140,10 +140,10 @@ "items": [ "admin/admin-tasks/check-cluster-health", "admin/admin-tasks/view-cluster-state", - "admin/admin-tasks/user-management-access-control", "admin/admin-tasks/update-dgraph-types", + "admin/admin-tasks/user-management-access-control", + "admin/admin-tasks/multitenancy", "admin/admin-tasks/restrict-mutation-operations", - "admin/admin-tasks/secure-alter-operations", "admin/admin-tasks/export-database", "admin/admin-tasks/shut-down-database", "admin/admin-tasks/delete-database", @@ -191,8 +191,7 @@ "items": [ "admin/enterprise-features/encryption-at-rest", "admin/enterprise-features/license", - "admin/enterprise-features/lsbackup", - "admin/enterprise-features/multitenancy" + "admin/enterprise-features/lsbackup" ] } ] diff --git a/docusaurus-docs/sidebars.ts b/docusaurus-docs/sidebars.ts index 76959443..4ecdb21c 100644 --- a/docusaurus-docs/sidebars.ts +++ b/docusaurus-docs/sidebars.ts @@ -143,10 +143,10 @@ const sidebars: SidebarsConfig = { items: [ 'admin/admin-tasks/check-cluster-health', 'admin/admin-tasks/view-cluster-state', - 'admin/admin-tasks/user-management-access-control', 'admin/admin-tasks/update-dgraph-types', + 'admin/admin-tasks/user-management-access-control', + 'admin/admin-tasks/multitenancy', 'admin/admin-tasks/restrict-mutation-operations', - 'admin/admin-tasks/secure-alter-operations', 'admin/admin-tasks/export-database', 'admin/admin-tasks/shut-down-database', 'admin/admin-tasks/delete-database', @@ -195,7 +195,6 @@ const sidebars: SidebarsConfig = { 'admin/enterprise-features/encryption-at-rest', 'admin/enterprise-features/license', 'admin/enterprise-features/lsbackup', - 'admin/enterprise-features/multitenancy', ], }, ],