Self-Managed Cluster

We’re overhauling Dgraph’s docs to make them clearer and more approachable. If you notice any issues during this transition or have suggestions, please let us know.

You can deploy and manage Dgraph database in a variety of self-managed deployment scenarios, including:

• Running Dgraph on your on-premises infrastructure (virtual or bare-metal physical servers)
• Running Dgraph on your cloud infrastructure (AWS, Google Cloud and Azure)

This section focuses exclusively on deployment and management for these self-managed scenarios. To learn about fully managed options that let you focus on building apps and websites, rather than managing infrastructure, or Try Dgraph on Hypermode.

Overview

A Dgraph cluster consists of the following:

• Dgraph Alpha database server nodes: The Dgraph Alpha server nodes in your deployment host and serve data. These nodes also host an /admin HTTP and gRPC endpoint that can be used for data and node administration tasks such as backup, export, draining, and shutdown.
• Dgraph Zero management server nodes: The Dgraph Zero nodes in your deployment control the nodes in your Dgraph cluster. Dgraph Zero automatically moves data between different Dgraph Alpha instances based on the volume of data served by each Alpha instance.

You need at least one node of each type to run Dgraph. You need three nodes of each type to run Dgraph in a high-availability (HA) cluster configuration. To learn more about 2-node and 6-node deployment options, see the Production Checklist.

Each Dgraph Alpha exposes various administrative (admin) endpoints both over HTTP and GraphQL, for example endpoints to export data and to perform a clean shutdown. All such admin endpoints are protected by three layers of authentication:

1. IP White-listing (use the --security superflag’s whitelist option on Dgraph Alpha to whitelist IP addresses other than localhost).
2. Poor-man’s auth, if Dgraph Alpha is started with the --security superflag’s token option, then you should pass the token as an X-Dgraph-AuthToken header while making the HTTP request.
3. Guardian-only access, if Access Control Lists (ACL) is enabled. In this case you should pass the ACL-JWT of a Guardian user using the X-Dgraph-AccessToken header while making the HTTP request.

An administration endpoint is any HTTP endpoint which provides admin capabilities. Administration endpoints usually start with the /admin path. The current list of admin endpoints includes the following:

• /admin
• /admin/config/cache_mb
• /admin/draining
• /admin/shutdown
• /admin/schema
• /admin/schema/validate
• /alter
• /login

There are a few exceptions to this general rule:

• /login: This endpoint logs-in an ACL user, and provides them with a JWT. Only IP Whitelisting and Poor-man’s auth checks are performed for this endpoint.
• /admin: This endpoint provides GraphQL queries/mutations corresponding to the HTTP admin endpoints. All of the queries/mutations on /admin have all three layers of authentication, except for login (mutation), which has the same behavior as the HTTP /login endpoint.

Whitelisting admin operations

By default, admin operations can only be initiated from the machine on which the Dgraph Alpha runs.

You can use the --security superflag’s whitelist option to specify a comma-separated whitelist of IP addresses, IP ranges, CIDR ranges, or hostnames for hosts from which admin operations can be initiated.

IP Address

dgraph alpha --security whitelist=127.0.0.1 ...

This would allow admin operations from hosts with IP 127.0.0.1 (that’s localhost only).

IP Range

dgraph alpha --security whitelist=172.17.0.0:172.20.0.0,192.168.1.1 ...

This would allow admin operations from hosts with IP between 172.17.0.0 and 172.20.0.0 along with the server which has IP address as 192.168.1.1.

CIDR Range

dgraph alpha --security whitelist=172.17.0.0/16,172.18.0.0/15,172.20.0.0/32,192.168.1.1/32 ...

This would allow admin operations from hosts that matches the CIDR range 172.17.0.0/16, 172.18.0.0/15, 172.20.0.0/32, or 192.168.1.1/32 (the same range as the IP Range example).

You can set whitelist IP to 0.0.0.0/0 to whitelist all IP addresses.

Hostname

dgraph alpha --security whitelist=admin-bastion,host.docker.internal ...

This would allow admin operations from hosts with hostnames admin-bastion and host.docker.internal.

Restrict mutation operations

By default, you can perform mutation operations for any predicate. If the predicate in mutation doesn’t exist in the schema, the predicate gets added to the schema with an appropriate Dgraph Type.

You can use --limit "mutations=disallow" to disable all mutations, which is set to allow by default.

dgraph alpha --limit "mutations=disallow;"

Enforce a strict schema by setting --limit "mutations=strict. This mode allows mutations only on predicates already in the schema. Before performing a mutation on a predicate that doesn’t exist in the schema, you need to perform an alter operation with that predicate and its schema type.

dgraph alpha --limit "mutations=strict; mutations-nquad=1000000"

Secure alter operations

Clients can use alter operations to apply schema updates and drop particular or all predicates from the database. By default, all clients are allowed to perform alter operations. You can configure Dgraph to only allow alter operations when the client provides a specific token. You can use this “Simple ACL” token to prevent clients from making unintended or accidental schema updates or predicate drops.

You can specify the auth token with the --security superflag’s token option for each Dgraph Alpha in the cluster. Clients must include the same auth token to make alter requests.

dgraph alpha --security token=<authtokenstring>

curl -s localhost:8080/alter -d '{ "drop_all": true }'
# Permission denied. No token provided.

curl -s -H 'X-Dgraph-AuthToken: <wrongsecret>' localhost:8080/alter -d '{ "drop_all": true }'
# Permission denied. Incorrect token.

curl -H 'X-Dgraph-AuthToken: <authtokenstring>' localhost:8080/alter -d '{ "drop_all": true }'
# Success. Token matches.

To fully secure alter operations in the cluster, the authentication token must be set for every Alpha node.

Export database

As an Administrator you might want to export data from Dgraph to:

• backup your data
• migrate your data from one instance to another
• share your data

For more information about exporting your database, see Export data

Shut down database

A clean exit of a single Dgraph node is initiated by running the following GraphQL mutation on /admin endpoint.

This won’t work if called from outside the server where Dgraph is running. You can specify a list or range of whitelisted IP addresses from which shutdown or other admin operations can be initiated using the --security superflag’s whitelist option on dgraph alpha.

mutation {
  shutdown {
    response {
      message
      code
    }
  }
}

This stops the Alpha on which the command is executed and not the entire cluster.

Delete database

To drop all data, you could send a DropAll request via /alter endpoint.

Alternatively, you could:

• Shutdown Dgraph and wait for all writes to complete,
• Delete (maybe do an export first) the p and w directories, then
• Restart Dgraph.

Upgrade database

Doing periodic exports is always a good idea. This is particularly useful if you wish to upgrade Dgraph or reconfigure the sharding of a cluster. The following are the right steps to safely export and restart.

1. Start an export
2. Ensure it’s successful
3. Shutdown Dgraph and wait for all writes to complete
4. Start a new Dgraph cluster using new data directories (this can be done by passing empty directories to the options -p and -w for Alphas and -w for Zeros)
5. Reload the data via Bulk Loader
6. Verify the correctness of the new Dgraph cluster. If all looks good, you can delete the old directories (export serves as an insurance)

These steps are necessary because Dgraph’s underlying data format could have changed, and reloading the export avoids encoding incompatibilities.

Blue-green deployment is a common approach to minimize downtime during the upgrade process. This approach involves switching your app to read-only mode. To make sure that no mutations are executed during the maintenance window you can do a rolling restart of all your Alpha using the option --mutations disallow when you restart the Alpha nodes. This ensures the cluster is in read-only mode.

At this point your app can still read from the old cluster and you can perform steps 4 and 5. When the new cluster (that uses the upgraded version of Dgraph) is up and running, you can point your app to it, and shutdown the old cluster.

Post Installation

Now that Dgraph is up and running, to understand how to add and query data to Dgraph, follow Query Language Spec.

Assistant

Responses are generated using AI and may contain mistakes.