diff --git a/wiki/content/enterprise-features/binary-backups.md b/wiki/content/enterprise-features/binary-backups.md index 11259c70d1d..3bf3b281f3f 100644 --- a/wiki/content/enterprise-features/binary-backups.md +++ b/wiki/content/enterprise-features/binary-backups.md @@ -53,6 +53,42 @@ To create a backup, make an HTTP POST request to `/admin` to a Dgraph Alpha HTTP address and port (default, "localhost:8080"). Like with all `/admin` endpoints, this is only accessible on the same machine as the Alpha unless [whitelisted for admin operations]({{< relref "deploy/dgraph-administration.md#whitelisting-admin-operations" >}}). +You can look at `BackupInput` given below for all the possible options. +```graphql +input BackupInput { + + """ + Destination for the backup: e.g. Minio or S3 bucket. + """ + destination: String! + + """ + Access key credential for the destination. + """ + accessKey: String + + """ + Secret key credential for the destination. + """ + secretKey: String + + """ + AWS session token, if required. + """ + sessionToken: String + + """ + Set to true to allow backing up to S3 or Minio bucket that requires no credentials. + """ + anonymous: Boolean + + """ + Force a full backup instead of an incremental backup. + """ + forceFull: Boolean + } +``` + Execute the following mutation on /admin endpoint using any GraphQL compatible client like Insomnia, GraphQL Playground or GraphiQL. ### Backup to Amazon S3 @@ -255,6 +291,100 @@ Backup is an online tool, meaning it is available when alpha is running. For enc {{% /notice %}} ## Restore from Backup +To restore from a backup, execute the following mutation on `/admin` endpoint. + +```graphql +mutation{ + restore(input:{ + location: "/path/to/backup/directory", + }){ + message + code + restoreId + } +} +``` +Restore can be performed from Amazon S3 / Minio or from Local Directory. Below is the `RestoreInput` to be passed into the mutation. +```graphql +input RestoreInput { + + """ + Destination for the backup: e.g. Minio or S3 bucket. + """ + location: String! + + """ + Backup ID of the backup series to restore. This ID is included in the manifest.json file. + If missing, it defaults to the latest series. + """ + backupId: String + + """ + Path to the key file needed to decrypt the backup. This file should be accessible + by all alphas in the group. The backup will be written using the encryption key + with which the cluster was started, which might be different than this key. + """ + encryptionKeyFile: String + + """ + Vault server address where the key is stored. This server must be accessible + by all alphas in the group. Default "http://localhost:8200". + """ + vaultAddr: String + + """ + Path to the Vault RoleID file. + """ + vaultRoleIDFile: String + + """ + Path to the Vault SecretID file. + """ + vaultSecretIDFile: String + + """ + Vault kv store path where the key lives. Default "secret/data/dgraph". + """ + vaultPath: String + + """ + Vault kv store field whose value is the key. Default "enc_key". + """ + vaultField: String + + """ + Vault kv store field's format. Must be "base64" or "raw". Default "base64". + """ + vaultFormat: String + + """ + Access key credential for the destination. + """ + accessKey: String + + """ + Secret key credential for the destination. + """ + secretKey: String + + """ + AWS session token, if required. + """ + sessionToken: String + + """ + Set to true to allow backing up to S3 or Minio bucket that requires no credentials. + """ + anonymous: Boolean +} +``` + +## Restore using `dgraph restore` + +{{% notice "note" %}} +`dgraph restore` is being deprecated, please use GraphQL api for Restoring from Backup. +{{% /notice %}} + The restore utility is a standalone tool today. A new flag `--encryption_key_file` is added to the restore utility so it can decrypt the backup. This file must contain the same key that was used for encryption during backup. Alternatively, starting with v20.07.0, the `vault_*` options can be used to restore a backup. diff --git a/wiki/content/graphql/admin/index.md b/wiki/content/graphql/admin/index.md index 6bdeb6ffa63..94cd93ff351 100644 --- a/wiki/content/graphql/admin/index.md +++ b/wiki/content/graphql/admin/index.md @@ -45,40 +45,290 @@ At `/admin` you'll find an admin API for administering your GraphQL instance. T Here are the important types, queries, and mutations from the admin schema. ```graphql -type GQLSchema { - id: ID! - schema: String! - generatedSchema: String! -} - -type UpdateGQLSchemaPayload { - gqlSchema: GQLSchema -} - -input UpdateGQLSchemaInput { - set: GQLSchemaPatch! -} - -input GQLSchemaPatch { - schema: String! -} - -type Query { - getGQLSchema: GQLSchema - health: Health -} - -type Mutation { - updateGQLSchema(input: UpdateGQLSchemaInput!) : UpdateGQLSchemaPayload -} + scalar DateTime + + """ + Data about the GraphQL schema being served by Dgraph. + """ + type GQLSchema @dgraph(type: "dgraph.graphql") { + id: ID! + + """ + Input schema (GraphQL types) that was used in the latest schema update. + """ + schema: String! @dgraph(pred: "dgraph.graphql.schema") + + """ + The GraphQL schema that was generated from the 'schema' field. + This is the schema that is being served by Dgraph at /graphql. + """ + generatedSchema: String! + } + + type Cors @dgraph(type: "dgraph.cors"){ + acceptedOrigins: [String] + } + + """ + SchemaHistory contains the schema and the time when the schema has been created. + """ + type SchemaHistory @dgraph(type: "dgraph.graphql.history") { + schema: String! @id @dgraph(pred: "dgraph.graphql.schema_history") + created_at: DateTime! @dgraph(pred: "dgraph.graphql.schema_created_at") + } + + """ + A NodeState is the state of an individual Alpha or Zero node in the Dgraph cluster. + """ + type NodeState { + + """ + Node type : either 'alpha' or 'zero'. + """ + instance: String + + """ + Address of the node. + """ + address: String + + """ + Node health status : either 'healthy' or 'unhealthy'. + """ + status: String + + """ + The group this node belongs to in the Dgraph cluster. + See : https://dgraph.io/docs/deploy/#cluster-setup. + """ + group: String + + """ + Version of the Dgraph binary. + """ + version: String + + """ + Time in nanoseconds since the node started. + """ + uptime: Int + + """ + Time in Unix epoch time that the node was last contacted by another Zero or Alpha node. + """ + lastEcho: Int + + """ + List of ongoing operations in the background. + """ + ongoing: [String] + + """ + List of predicates for which indexes are built in the background. + """ + indexing: [String] + + """ + List of Enterprise Features that are enabled. + """ + ee_features: [String] + } + + type MembershipState { + counter: Int + groups: [ClusterGroup] + zeros: [Member] + maxLeaseId: Int + maxTxnTs: Int + maxRaftId: Int + removed: [Member] + cid: String + license: License + } + + type ClusterGroup { + id: Int + members: [Member] + tablets: [Tablet] + snapshotTs: Int + checksum: Int + } + + type Member { + id: Int + groupId: Int + addr: String + leader: Boolean + amDead: Boolean + lastUpdate: Int + clusterInfoOnly: Boolean + forceGroupId: Boolean + } + + type Tablet { + groupId: Int + predicate: String + force: Boolean + space: Int + remove: Boolean + readOnly: Boolean + moveTs: Int + } + + type License { + user: String + maxNodes: Int + expiryTs: Int + enabled: Boolean + } + + directive @dgraph(type: String, pred: String) on OBJECT | INTERFACE | FIELD_DEFINITION + directive @secret(field: String!, pred: String) on OBJECT | INTERFACE + + + type UpdateGQLSchemaPayload { + gqlSchema: GQLSchema + } + + input UpdateGQLSchemaInput { + set: GQLSchemaPatch! + } + + input GQLSchemaPatch { + schema: String! + } + + input ExportInput { + format: String + + """ + Destination for the backup: e.g. Minio or S3 bucket or /absolute/path + """ + destination: String + + """ + Access key credential for the destination. + """ + accessKey: String + + """ + Secret key credential for the destination. + """ + secretKey: String + + """ + AWS session token, if required. + """ + sessionToken: String + + """ + Set to true to allow backing up to S3 or Minio bucket that requires no credentials. + """ + anonymous: Boolean + } + + type Response { + code: String + message: String + } + + type ExportPayload { + response: Response + exportedFiles: [String] + } + + type DrainingPayload { + response: Response + } + + type ShutdownPayload { + response: Response + } + + input ConfigInput { + + """ + Estimated memory the LRU cache can take. Actual usage by the process would be + more than specified here. (default -1 means no set limit) + """ + lruMb: Float + + """ + True value of logRequest enables logging of all the requests coming to alphas. + False value of logRequest disables above. + """ + logRequest: Boolean + } + + type ConfigPayload { + response: Response + } + + type Config { + lruMb: Float + } + + type Query { + getGQLSchema: GQLSchema + health: [NodeState] + state: MembershipState + config: Config + getAllowedCORSOrigins: Cors + querySchemaHistory(first: Int, offset: Int): [SchemaHistory] + } + + type Mutation { + + """ + 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. + """ + updateGQLSchema(input: UpdateGQLSchemaInput!) : UpdateGQLSchemaPayload + + """ + Starts an export of all data in the cluster. Export format should be 'rdf' (the default + if no format is given), or 'json'. + See : https://dgraph.io/docs/deploy/#export-database + """ + export(input: ExportInput!): ExportPayload + + """ + Set (or unset) the cluster draining mode. In draining mode no further requests are served. + """ + draining(enable: Boolean): DrainingPayload + + """ + Shutdown this node. + """ + shutdown: ShutdownPayload + + """ + Alter the node's config. + """ + config(input: ConfigInput!): ConfigPayload + + replaceAllowedCORSOrigins(origins: [String]): Cors + + } ``` You'll notice that the /admin schema is very much the same as the schemas generated by Dgraph GraphQL. * The `health` query lets you know if everything is connected and if there's a schema currently being served at `/graphql`. +* The `state` query returns the current state of the cluster and group membership information. For more information about `state` see [here](https://dgraph.io/docs/deploy/dgraph-zero/#more-about-state-endpoint). +* The `config` query returns the configuration options of the cluster set at the time of starting it. * The `getGQLSchema` query gets the current GraphQL schema served at `/graphql`, or returns null if there's no such schema. +* The `getAllowedCORSOrigins` query returns your CORS policy. * The `updateGQLSchema` mutation allows you to change the schema currently served at `/graphql`. +## Enterprise Features + +Enterprise Features like ACL, Backups and Restore are also available using the GraphQL API at `/admin` endpoint. + +* [ACL](https://dgraph.io/docs/enterprise-features/access-control-lists/#using-graphql-admin-api). +* [Backups](https://dgraph.io/docs/enterprise-features/binary-backups/#create-a-backup). +* [Restore](https://dgraph.io/docs/enterprise-features/binary-backups/#restore-from-backup). + ## First Start On first starting with a blank database: