Skip to content

Commit b2f6760

Browse files
raphael-istariraphael-istari
authored
Merge pull request #709 from dgraph-io/rapahel/admin-endpoints
clarify admin-endpoints
2 parents 8b1c717 + 4a2a74d commit b2f6760

File tree

22 files changed

+886
-456
lines changed

22 files changed

+886
-456
lines changed

‎docusaurus-docs/docs/admin/admin-endpoints.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: Admin Endpoints
3+
---
4+
5+
The [Admin Tasks](./admin-tasks/index.md) section provides detailed guides for common administrative operations, but this page provides an exhaustive list of all administrative endpoints available in Dgraph.
6+
7+
Dgraph provides administrative endpoints on both Alpha and Zero nodes.
8+
9+
## Alpha HTTP Endpoints (port 8080)
10+
11+
Dgraph Alpha exposes the following HTTP endpoints on port `8080` (plus optional port offset):
12+
13+
- **`/admin/config/cache_mb`** - Configure cache size
14+
- **`/admin/draining`** - Drain connections from a node
15+
- **`/admin/shutdown`** - Shutdown a single Alpha node
16+
- **`/alter`** - Apply schema updates and drop predicates
17+
- **`/login`** - Authenticate ACL users
18+
- **`/health`** - Health status
19+
- **`/health?all`** - Health status of all servers in the cluster
20+
- **`/state`** - Returns information about the nodes that are part of the cluster. This includes information about the size of predicates and which groups they belong to.
21+
22+
## Zero HTTP Endpoints (port 6080)
23+
24+
Dgraph Zero exposes the following HTTP endpoints on port `6080` (plus optional port offset):
25+
26+
### GET Endpoints
27+
28+
- **`/assign?what=uids&num=100`** - Allocates a range of UIDs specified by the `num` argument, and returns a JSON map containing the `startId` and `endId` that defines the range of UIDs (inclusive). This UID range can be safely assigned externally to new nodes during data ingestion.
29+
- **`/assign?what=timestamps&num=100`** - Requests timestamps from Zero. This is useful to "fast forward" the state of the Zero node when starting from a postings directory that already has commits higher than Zero's leased timestamp.
30+
- **`/removeNode?id=3&group=2`** - Removes a dead Zero or Alpha node. When a replica node goes offline and can't be recovered, you can remove it and add a new node to the quorum. To remove dead Zero nodes, pass `group=0` and the id of the Zero node to this endpoint.
31+
32+
:::note
33+
Before using the `/removeNode` endpoint, ensure that the node is down and ensure that it doesn't come back up ever again. Do not use the same `idx` of a node that was removed earlier.
34+
:::
35+
36+
- **`/moveTablet?tablet=name&group=2`** - Moves a tablet to a group. Zero already rebalances shards every 8 mins, but this endpoint can be used to force move a tablet.
37+
38+
### POST Endpoints
39+
40+
- **`/enterpriseLicense`** - Applies an enterprise license to the cluster by supplying it as part of the body.
41+
42+
## Alpha GraphQL Admin Endpoints (port 8080)
43+
44+
**`/admin`** - GraphQL endpoint for cluster management operations
45+
46+
The GraphQL Admin API provides an alternative way to perform the same administrative tasks available through HTTP endpoints. Many operations that can be done via HTTP endpoints (such as export, backup, shutdown, draining, etc.) can also be performed using GraphQL queries and mutations. The GraphQL interface offers a more structured and type-safe approach to administrative operations.
47+
48+
#### Queries
49+
50+
- **`getGQLSchema`** - Get the current GraphQL schema
51+
- **`health`** - Get health status
52+
- **`state`** - Get cluster state
53+
- **`config`** - Get node configuration
54+
- **`task`** - Get task information
55+
- **`getUser`** - Get a user by name
56+
- **`getGroup`** - Get a group by name
57+
- **`getCurrentUser`** - Get the currently logged in user
58+
- **`queryUser`** - Query users with filters
59+
- **`queryGroup`** - Query groups with filters
60+
- **`listBackups`** - Get information about backups at a given location
61+
62+
#### Mutations
63+
64+
- **`updateGQLSchema`** - Update the Dgraph cluster to serve the input schema. This may change the GraphQL schema, the types and predicates in the Dgraph schema, and cause indexes to be recomputed.
65+
- **`export`** - Start an export of all data in the cluster. Export format should be 'rdf' (the default if no format is given), or 'json'.
66+
- **`draining`** - Set (or unset) the cluster draining mode. In draining mode no further requests are served.
67+
- **`shutdown`** - Shutdown this node.
68+
- **`config`** - Alter the node's config.
69+
- **`removeNode`** - Remove a node from the cluster.
70+
- **`moveTablet`** - Move a predicate from one group to another.
71+
- **`assign`** - Lease UIDs, Timestamps or Namespace IDs in advance.
72+
- **`backup`** - Start a binary backup.
73+
- **`restore`** - Start restoring a binary backup.
74+
- **`restoreTenant`** - Restore given tenant into namespace 0 of the cluster.
75+
- **`login`** - Login to Dgraph. Successful login results in a JWT that can be used in future requests. If login is not successful an error is returned.
76+
- **`addUser`** - Add a user. When linking to groups: if the group doesn't exist it is created; if the group exists, the new user is linked to the existing group. It's possible to both create new groups and link to existing groups in the one mutation. Dgraph ensures that usernames are unique, hence attempting to add an existing user results in an error.
77+
- **`addGroup`** - Add a new group and (optionally) set the rules for the group.
78+
- **`updateUser`** - Update users, their passwords and groups. As with AddUser, when linking to groups: if the group doesn't exist it is created; if the group exists, the new user is linked to the existing group. If the filter doesn't match any users, the mutation has no effect.
79+
- **`updateGroup`** - Add or remove rules for groups. If the filter doesn't match any groups, the mutation has no effect.
80+
- **`deleteGroup`** - Delete a group.
81+
- **`deleteUser`** - Delete a user.
82+
- **`addNamespace`** - Add a new namespace.
83+
- **`deleteNamespace`** - Delete a namespace.
84+
- **`resetPassword`** - Reset password can only be used by the Guardians of the galaxy to reset password of any user in any namespace.
85+
86+
87+
For security configuration including authentication, IP whitelisting, and token-based access control, see [Admin Endpoint Security](./security/admin-endpoint-security).

‎docusaurus-docs/docs/admin/admin-tasks/index.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,17 +10,20 @@ For security configuration including authentication, IP whitelisting, and token-
1010

1111
Dgraph Alpha provides the following administrative endpoints:
1212

13-
### HTTP Endpoints
13+
### HTTP Admin Endpoints
1414

15-
- **`/admin`** - GraphQL endpoint for cluster management operations
1615
- **`/admin/config/cache_mb`** - Configure cache size
1716
- **`/admin/draining`** - Drain connections from a node
1817
- **`/admin/shutdown`** - Shutdown a single Alpha node
1918
- **`/admin/schema`** - Schema management
2019
- **`/admin/schema/validate`** - Validate schema
2120
- **`/alter`** - Apply schema updates and drop predicates
2221
- **`/login`** - Authenticate ACL users
22+
- **`/health`** - health status
23+
- **`/health?all`** - health status of all servers in the cluster
2324

25+
### GraphQL ADmin Endpoints
26+
- **`/admin`** - GraphQL endpoint for cluster management operations
2427
By default, the `/admin` endpoint is only accessible from the same machine as the Alpha server. For detailed information about endpoint security and authentication, see [Admin Endpoint Security](../security/admin-endpoint-security).
2528

2629
## Admin Tasks

‎docusaurus-docs/docs/admin/admin-tasks/view-cluster-state.md‎

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
---
2+
title: View Cluster State
3+
---
4+
5+
The cluster state provides detailed information about your cluster's current state, including group membership, predicate distribution (sharding), and cluster metadata. You can query cluster state using either the HTTP endpoint or the GraphQL Admin API on Alpha.
6+
7+
## Query Cluster State
8+
9+
### Using HTTP Endpoint
10+
11+
Query the `/state` endpoint:
12+
13+
```sh
14+
curl http://localhost:8080/state | jq
15+
```
16+
17+
### Using GraphQL Admin API
18+
19+
You can also query cluster state using the GraphQL `state` query on the `/admin` endpoint (port 8080):
20+
21+
```graphql
22+
query {
23+
state {
24+
groups {
25+
id
26+
members {
27+
id
28+
groupId
29+
addr
30+
leader
31+
amDead
32+
}
33+
tablets {
34+
predicate
35+
groupId
36+
space
37+
readOnly
38+
}
39+
}
40+
zeros {
41+
id
42+
groupId
43+
addr
44+
leader
45+
}
46+
maxUID
47+
maxTxnTs
48+
maxRaftId
49+
cid
50+
license {
51+
enabled
52+
maxNodes
53+
expiryTs
54+
}
55+
}
56+
}
57+
```
58+
59+
## Response Information
60+
61+
The `/state` endpoint returns a JSON document containing:
62+
63+
- **Cluster membership**: Instances that are part of the cluster
64+
- **Group information**: Number of instances in Zero group and each Alpha group
65+
- **Leadership**: Current leader of each group
66+
- **Predicate distribution**: Which predicates (tablets) belong to which groups
67+
- **Predicate sizes**: Estimated size in bytes of each predicate
68+
- **Enterprise license**: License information and status
69+
- **Transaction metadata**: Max leased transaction ID
70+
- **UID metadata**: Max leased UID
71+
- **Cluster ID**: Unique cluster identifier (CID)
72+
73+
## Example Response
74+
75+
Here's an example JSON response for a cluster with three Alpha nodes and three Zero nodes:
76+
77+
```json
78+
{
79+
"counter": "22",
80+
"groups": {
81+
"1": {
82+
"members": {
83+
"1": {
84+
"id": "1",
85+
"groupId": 1,
86+
"addr": "alpha2:7082",
87+
"leader": true,
88+
"amDead": false,
89+
"lastUpdate": "1603350485",
90+
"clusterInfoOnly": false,
91+
"forceGroupId": false
92+
},
93+
"2": {
94+
"id": "2",
95+
"groupId": 1,
96+
"addr": "alpha1:7080",
97+
"leader": false,
98+
"amDead": false,
99+
"lastUpdate": "0",
100+
"clusterInfoOnly": false,
101+
"forceGroupId": false
102+
},
103+
"3": {
104+
"id": "3",
105+
"groupId": 1,
106+
"addr": "alpha3:7083",
107+
"leader": false,
108+
"amDead": false,
109+
"lastUpdate": "0",
110+
"clusterInfoOnly": false,
111+
"forceGroupId": false
112+
}
113+
},
114+
"tablets": {
115+
"dgraph.cors": {
116+
"groupId": 1,
117+
"predicate": "dgraph.cors",
118+
"force": false,
119+
"space": "0",
120+
"remove": false,
121+
"readOnly": false,
122+
"moveTs": "0"
123+
},
124+
"dgraph.graphql.schema": {
125+
"groupId": 1,
126+
"predicate": "dgraph.graphql.schema",
127+
"force": false,
128+
"space": "0",
129+
"remove": false,
130+
"readOnly": false,
131+
"moveTs": "0"
132+
},
133+
"dgraph.type": {
134+
"groupId": 1,
135+
"predicate": "dgraph.type",
136+
"force": false,
137+
"space": "0",
138+
"remove": false,
139+
"readOnly": false,
140+
"moveTs": "0"
141+
}
142+
},
143+
"snapshotTs": "22",
144+
"checksum": "18099480229465877561"
145+
}
146+
},
147+
"zeros": {
148+
"1": {
149+
"id": "1",
150+
"groupId": 0,
151+
"addr": "zero1:5080",
152+
"leader": true,
153+
"amDead": false,
154+
"lastUpdate": "0",
155+
"clusterInfoOnly": false,
156+
"forceGroupId": false
157+
},
158+
"2": {
159+
"id": "2",
160+
"groupId": 0,
161+
"addr": "zero2:5082",
162+
"leader": false,
163+
"amDead": false,
164+
"lastUpdate": "0",
165+
"clusterInfoOnly": false,
166+
"forceGroupId": false
167+
},
168+
"3": {
169+
"id": "3",
170+
"groupId": 0,
171+
"addr": "zero3:5083",
172+
"leader": false,
173+
"amDead": false,
174+
"lastUpdate": "0",
175+
"clusterInfoOnly": false,
176+
"forceGroupId": false
177+
}
178+
},
179+
"maxUID": "10000",
180+
"maxTxnTs": "10000",
181+
"maxRaftId": "3",
182+
"removed": [],
183+
"cid": "2571d268-b574-41fa-ae5e-a6f8da175d6d",
184+
"license": {
185+
"user": "",
186+
"maxNodes": "18446744073709551615",
187+
"expiryTs": "1605942487",
188+
"enabled": true
189+
}
190+
}
191+
```
192+
193+
## Understanding the Response
194+
195+
### Group Members
196+
197+
The response shows node members with their addresses and HTTP port numbers:
198+
199+
- **Group 1 members** (Alpha nodes):
200+
- alpha2:7082, id: 1, leader
201+
- alpha1:7080, id: 2
202+
- alpha3:7083, id: 3
203+
- **Group 0 members** (Dgraph Zero nodes):
204+
- zero1:5080, id: 1, leader
205+
- zero2:5082, id: 2
206+
- zero3:5083, id: 3
207+
208+
### maxUID
209+
210+
The current maximum lease of UIDs used for blank node UID assignment. This increments in batches of 10,000 IDs. Once the maximum lease is reached, another 10,000 IDs are leased. In the event that the Zero leader is lost, the new leader starts a new lease from `maxUID`+1. Any UIDs lost between these leases will never be used for blank-node UID assignment.
211+
212+
An admin can use the Zero endpoint HTTP GET `/assign?what=uids&num=1000` to reserve a range of UIDs (in this case, 1000) to use externally. Zero will **never** use these UIDs for blank node UID assignment, so the user can use the range to assign UIDs manually to their own data sets.
213+
214+
### maxTxnTs
215+
216+
The current maximum lease of transaction timestamps used to hand out start timestamps and commit timestamps. This increments in batches of 10,000 IDs. After the max lease is reached, another 10,000 IDs are leased. If the Zero leader is lost, then the new leader starts a new lease from `maxTxnTs`+1. Any lost transaction IDs between these leases will never be used.
217+
218+
An admin can use the Zero endpoint HTTP GET `/assign?what=timestamps&num=1000` to increase the current transaction timestamp (in this case, by 1000). This is mainly useful in special-case scenarios; for example, using an existing `-p directory` to create a fresh cluster to be able to query the latest data in the DB.
219+
220+
### maxRaftId
221+
222+
The number of Zeros available to serve as a leader node. Used by the [RAFT](../../design-concepts/raft) consensus algorithm.
223+
224+
### CID
225+
226+
This is a unique UUID representing the *cluster-ID* for this cluster. It is generated during the initial DB startup and is retained across restarts.
227+
228+
### Enterprise License
229+
230+
License information including:
231+
- Enabled status
232+
- `maxNodes`: Maximum number of nodes allowed (unlimited if not restricted)
233+
- License expiration, shown in seconds since the Unix epoch
234+
235+
### Tablets (Predicates)
236+
237+
The `tablets` section shows which predicates are assigned to which groups. Each tablet entry includes:
238+
- `groupId`: The group that owns this predicate
239+
- `predicate`: The predicate name
240+
- `space`: Estimated size
241+
- `readOnly`: Whether the predicate is read-only
242+
- `moveTs`: Timestamp of last move operation
243+
244+
:::note
245+
The terms "tablet", "predicate", and "edge" are currently synonymous. In future, Dgraph might improve data scalability to shard a predicate into separate tablets that can be assigned to different groups.
246+
:::
247+

0 commit comments

Comments
 (0)