From d77c56bd4440f122a636e478f391f3d6ad3b6d3d Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Mon, 10 Jun 2024 14:29:02 -0400 Subject: [PATCH 1/5] * Added admonitions about the enableCrossClusterVersioning * Updated example in Getting Bucket Information to catch changes since the last time it was updated. --- .../rest-api/pages/rest-bucket-create.adoc | 10 + .../rest-api/pages/rest-buckets-summary.adoc | 168 +-------- .../partials/get_bucket_travel_sample.json | 335 ++++++++++++++++++ 3 files changed, 353 insertions(+), 160 deletions(-) create mode 100644 modules/rest-api/partials/get_bucket_travel_sample.json diff --git a/modules/rest-api/pages/rest-bucket-create.adoc b/modules/rest-api/pages/rest-bucket-create.adoc index fe52138b80..5c3ef70cec 100644 --- a/modules/rest-api/pages/rest-bucket-create.adoc +++ b/modules/rest-api/pages/rest-bucket-create.adoc @@ -830,6 +830,7 @@ curl -v -X POST http://localhost:8091/pools/default/buckets/testBucket \ Success returns `200 OK`. + [#auto-compaction-parameters] == Auto-Compaction Parameters @@ -1099,6 +1100,15 @@ If the bucket cannot created due to a missing or incorrect parameter, a `400` re If the URL is incorrectly specified a `404 (Object Not Found)` error is returned. Failure to authenticate gives `401 Unauthorized`. +[#notes] +== Notes + +Couchbase Server 7.6.2 added a property named `enableCrossClusterVersioning` to support a future feature. +Do not change the value of this property. + +CAUTION: Once enabled, you cannot turn off the `enableCrossClusterVersioning` property. +The only way for you to undo setting this value to `true` is to backup your data, create a new database, and reload the data. + == See Also A conceptual description of buckets is provided in xref:learn:buckets-memory-and-storage/buckets.adoc[Buckets]. diff --git a/modules/rest-api/pages/rest-buckets-summary.adoc b/modules/rest-api/pages/rest-buckets-summary.adoc index 3187311242..2cfec45f35 100644 --- a/modules/rest-api/pages/rest-buckets-summary.adoc +++ b/modules/rest-api/pages/rest-buckets-summary.adoc @@ -54,169 +54,17 @@ If successful, the call returns `200 OK`, and an object such as the following. The fields `historyRetentionCollectionDefault`, `historyRetentionCollectionBytes`, and `historyRetentionCollectionSeconds` are specific to _Magma_ storage: if `magma` is not the value of `storageBackend`, these parameters are not displayed. +[source, json] ---- -{ - "name": "testBucket", - "nodeLocator": "vbucket", - "bucketType": "membase", - "storageBackend": "magma", - "uuid": "d76bc79b761458f95d7dcf48bbe2fe92", - "uri": "/pools/default/buckets/testBucket?bucket_uuid=d76bc79b761458f95d7dcf48bbe2fe92", - "streamingUri": "/pools/default/bucketsStreaming/testBucket?bucket_uuid=d76bc79b761458f95d7dcf48bbe2fe92", - "bucketCapabilitiesVer": "", - "bucketCapabilities": [ - "collections", - "durableWrite", - "tombstonedUserXAttrs", - "subdoc.ReplaceBodyWithXattr", - "subdoc.DocumentMacroSupport", - "subdoc.ReviveDocument", - "nonDedupedHistory", - "dcp", - "cbhello", - "touch", - "cccp", - "xdcrCheckpointing", - "nodesExt", - "xattr" - ], - "collectionsManifestUid": "2", - "vBucketServerMap": { - "hashAlgorithm": "CRC", - "numReplicas": 1, - "serverList": [ - "127.0.0.1:11210" - ], - "vBucketMap": [ - [ - 0, - -1 - ], - . - . - . - }, - "localRandomKeyUri": "/pools/default/buckets/testBucket/localRandomKey", - "controllers": { - "compactAll": "/pools/default/buckets/testBucket/controller/compactBucket", - "compactDB": "/pools/default/buckets/testBucket/controller/compactDatabases", - "purgeDeletes": "/pools/default/buckets/testBucket/controller/unsafePurgeBucket", - "startRecovery": "/pools/default/buckets/testBucket/controller/startRecovery" - }, - "nodes": [ - { - "couchApiBaseHTTPS": "https://127.0.0.1:18092/testBucket%2Bd76bc79b761458f95d7dcf48bbe2fe92", - "couchApiBase": "http://127.0.0.1:8092/testBucket%2Bd76bc79b761458f95d7dcf48bbe2fe92", - "clusterMembership": "active", - "recoveryType": "none", - "status": "healthy", - "otpNode": "ns_1@127.0.0.1", - "thisNode": true, - "hostname": "127.0.0.1:8091", - "nodeUUID": "fa173ccb5d6d48648ae79cbbd278dbb5", - "clusterCompatibility": 458754, - "version": "7.2.0-5127-enterprise", - "os": "x86_64-pc-linux-gnu", - "cpuCount": 1, - "ports": { - "direct": 11210, - "httpsCAPI": 18092, - "httpsMgmt": 18091, - "distTCP": 21100, - "distTLS": 21150 - }, - "services": [ - "backup", - "index", - "kv", - "n1ql" - ], - "nodeEncryption": false, - "addressFamilyOnly": false, - "configuredHostname": "127.0.0.1:8091", - "addressFamily": "inet", - "externalListeners": [ - { - "afamily": "inet", - "nodeEncryption": false - } - ], - "serverGroup": "Group 1", - "replication": 0, - "nodeHash": 47731734, - "systemStats": { - "cpu_utilization_rate": 11.40536280284413, - "cpu_stolen_rate": 0, - "swap_total": 2047864832, - "swap_used": 1323008, - "mem_total": 2039574528, - "mem_free": 1229828096, - "mem_limit": 2039574528, - "cpu_cores_available": 1, - "allocstall": 2 - }, - "interestingStats": { - "cmd_get": 0, - "couch_docs_actual_disk_size": 34, - "couch_docs_data_size": 0, - "couch_spatial_data_size": 0, - "couch_spatial_disk_size": 0, - "couch_views_actual_disk_size": 0, - "couch_views_data_size": 0, - "curr_items": 0, - "curr_items_tot": 0, - "ep_bg_fetched": 0, - "get_hits": 0, - "mem_used": 60589912, - "ops": 0, - "vb_active_num_non_resident": 0, - "vb_replica_curr_items": 0 - }, - "uptime": "1170", - "memoryTotal": 2039574528, - "memoryFree": 1229828096, - "mcdMemoryReserved": 1556, - "mcdMemoryAllocated": 1556 - } - ], - "stats": { - "uri": "/pools/default/buckets/testBucket/stats", - "directoryURI": "/pools/default/buckets/testBucket/stats/Directory", - "nodeStatsListURI": "/pools/default/buckets/testBucket/nodes" - }, - "authType": "sasl", - "autoCompactionSettings": false, - "replicaNumber": 1, - "threadsNumber": 3, - "quota": { - "ram": 1258291200, - "rawRAM": 1258291200 - }, - "basicStats": { - "quotaPercentUsed": 4.815253575642903, - "opsPerSec": 0, - "diskFetches": 0, - "itemCount": 0, - "diskUsed": 34, - "dataUsed": 0, - "memUsed": 60589912, - "vbActiveNumNonResident": 0 - }, - "evictionPolicy": "fullEviction", - "durabilityMinLevel": "none", - "pitrEnabled": false, - "pitrGranularity": 600, - "pitrMaxHistoryAge": 86400, - "storageQuotaPercentage": 50, - "historyRetentionSeconds": 0, - "historyRetentionBytes": 0, - "historyRetentionCollectionDefault": true, - "conflictResolutionType": "seqno", - "maxTTL": 0, - "compressionMode": "passive" -} +include::partial$get_bucket_travel_sample.json ---- +NOTE: Couchbase Server version 7.6.2 added a property named `enableCrossClusterVersioning` to support a future feature. +Do not change the value of this field. +Once enabled, you cannot turn it off. +See the xref:rest-bucket-create.adoc#notes[Notes] section of xref:rest-bucket-create.adoc[] for more information. + + [#see-also] == See Also diff --git a/modules/rest-api/partials/get_bucket_travel_sample.json b/modules/rest-api/partials/get_bucket_travel_sample.json new file mode 100644 index 0000000000..bbe2812419 --- /dev/null +++ b/modules/rest-api/partials/get_bucket_travel_sample.json @@ -0,0 +1,335 @@ +{ + "name": "travel-sample", + "nodeLocator": "vbucket", + "bucketType": "membase", + "storageBackend": "couchstore", + "uuid": "85ff541d1f4cfbc9e67cda3db698cac6", + "uri": "/pools/default/buckets/travel-sample?bucket_uuid=85ff541d1f4cfbc9e67cda3db698cac6", + "streamingUri": "/pools/default/bucketsStreaming/travel-sample?bucket_uuid=85ff541d1f4cfbc9e67cda3db698cac6", + "numVBuckets": 1024, + "bucketCapabilitiesVer": "", + "bucketCapabilities": [ + "collections", + "durableWrite", + "tombstonedUserXAttrs", + "couchapi", + "subdoc.ReplaceBodyWithXattr", + "subdoc.DocumentMacroSupport", + "subdoc.ReviveDocument", + "dcp.IgnorePurgedTombstones", + "preserveExpiry", + "querySystemCollection", + "mobileSystemCollection", + "subdoc.ReplicaRead", + "rangeScan", + "dcp", + "cbhello", + "touch", + "cccp", + "xdcrCheckpointing", + "nodesExt", + "xattr" + ], + "collectionsManifestUid": "2", + "ddocs": { + "uri": "/pools/default/buckets/travel-sample/ddocs" + }, + "vBucketServerMap": { + "hashAlgorithm": "CRC", + "numReplicas": 1, + "serverList": [ + "node1.:11210", + "node2.:11210", + "node3.:11210" + ], + "vBucketMap": [ + [ + 0, + 1 + ], + [ + 0, + 1 + ], + . + . + . + [ + 2, + 1 + ] + ] + }, + "localRandomKeyUri": "/pools/default/buckets/travel-sample/localRandomKey", + "controllers": { + "compactAll": "/pools/default/buckets/travel-sample/controller/compactBucket", + "compactDB": "/pools/default/buckets/travel-sample/controller/compactDatabases", + "purgeDeletes": "/pools/default/buckets/travel-sample/controller/unsafePurgeBucket", + "startRecovery": "/pools/default/buckets/travel-sample/controller/startRecovery" + }, + "nodes": [ + { + "couchApiBaseHTTPS": "https://node3.:18092/travel-sample%2B85ff541d1f4cfbc9e67cda3db698cac6", + "couchApiBase": "http://node3.:8092/travel-sample%2B85ff541d1f4cfbc9e67cda3db698cac6", + "clusterMembership": "active", + "recoveryType": "none", + "status": "healthy", + "otpNode": "ns_1@node3.", + "hostname": "node3.:8091", + "nodeUUID": "d6bfd3cccf28f3e648bca46cb30ac271", + "clusterCompatibility": 524288, + "version": "8.0.0-1649-enterprise", + "os": "aarch64-unknown-linux-gnu", + "cpuCount": 4, + "ports": { + "direct": 11210, + "httpsMgmt": 18091, + "httpsCAPI": 18092, + "distTCP": 21100, + "distTLS": 21150 + }, + "services": [ + "backup", + "index", + "kv", + "n1ql" + ], + "nodeEncryption": false, + "nodeEncryptionClientCertVerification": false, + "addressFamilyOnly": false, + "configuredHostname": "node3.:8091", + "addressFamily": "inet", + "externalListeners": [ + { + "afamily": "inet", + "nodeEncryption": false + } + ], + "serverGroup": "Group 1", + "replication": 1, + "nodeHash": 48264202, + "systemStats": { + "cpu_utilization_rate": 10.20000000018626, + "cpu_stolen_rate": 0, + "swap_total": 2147479552, + "swap_used": 396525568, + "mem_total": 8327258112, + "mem_free": 1855406080, + "mem_limit": 8327258112, + "cpu_cores_available": 4, + "allocstall": 37181 + }, + "interestingStats": { + "cmd_get": 0, + "couch_docs_actual_disk_size": 48142369, + "couch_docs_data_size": 32943627, + "couch_spatial_data_size": 0, + "couch_spatial_disk_size": 0, + "couch_views_actual_disk_size": 0, + "couch_views_data_size": 0, + "curr_items": 21189, + "curr_items_tot": 42289, + "ep_bg_fetched": 0, + "get_hits": 0, + "index_data_size": 37010997, + "index_disk_size": 16332886, + "mem_used": 63213008, + "ops": 0, + "vb_active_num_non_resident": 0, + "vb_replica_curr_items": 21100 + }, + "uptime": "788913", + "memoryTotal": 8327258112, + "memoryFree": 1855406080, + "mcdMemoryReserved": 6353, + "mcdMemoryAllocated": 6353 + }, + { + "couchApiBaseHTTPS": "https://node2.:18092/travel-sample%2B85ff541d1f4cfbc9e67cda3db698cac6", + "couchApiBase": "http://node2.:8092/travel-sample%2B85ff541d1f4cfbc9e67cda3db698cac6", + "clusterMembership": "active", + "recoveryType": "none", + "status": "healthy", + "otpNode": "ns_1@node2.", + "hostname": "node2.:8091", + "nodeUUID": "b737df3d566f6c6ccb2bcafec61e85a2", + "clusterCompatibility": 524288, + "version": "8.0.0-1649-enterprise", + "os": "aarch64-unknown-linux-gnu", + "cpuCount": 4, + "ports": { + "direct": 11210, + "httpsMgmt": 18091, + "httpsCAPI": 18092, + "distTCP": 21100, + "distTLS": 21150 + }, + "services": [ + "eventing", + "fts", + "kv", + "n1ql" + ], + "nodeEncryption": false, + "nodeEncryptionClientCertVerification": false, + "addressFamilyOnly": false, + "configuredHostname": "node2.:8091", + "addressFamily": "inet", + "externalListeners": [ + { + "afamily": "inet", + "nodeEncryption": false + } + ], + "serverGroup": "Group 1", + "replication": 1, + "nodeHash": 34469021, + "systemStats": { + "cpu_utilization_rate": 10.23397660196727, + "cpu_stolen_rate": 0, + "swap_total": 2147479552, + "swap_used": 396525568, + "mem_total": 8327258112, + "mem_free": 1855901696, + "mem_limit": 8327258112, + "cpu_cores_available": 4, + "allocstall": 37181 + }, + "interestingStats": { + "cmd_get": 0, + "couch_docs_actual_disk_size": 56100897, + "couch_docs_data_size": 32866921, + "couch_spatial_data_size": 0, + "couch_spatial_disk_size": 0, + "couch_views_actual_disk_size": 0, + "couch_views_data_size": 0, + "curr_items": 21118, + "curr_items_tot": 42167, + "ep_bg_fetched": 0, + "get_hits": 0, + "mem_used": 63213888, + "ops": 0, + "vb_active_num_non_resident": 0, + "vb_replica_curr_items": 21049 + }, + "uptime": "788913", + "memoryTotal": 8327258112, + "memoryFree": 1855901696, + "mcdMemoryReserved": 6353, + "mcdMemoryAllocated": 6353 + }, + { + "couchApiBaseHTTPS": "https://node1.:18092/travel-sample%2B85ff541d1f4cfbc9e67cda3db698cac6", + "couchApiBase": "http://node1.:8092/travel-sample%2B85ff541d1f4cfbc9e67cda3db698cac6", + "clusterMembership": "active", + "recoveryType": "none", + "status": "healthy", + "otpNode": "ns_1@node1.", + "thisNode": true, + "hostname": "node1.:8091", + "nodeUUID": "87a797d06f374f8006cc4a3a683db4e1", + "clusterCompatibility": 524288, + "version": "8.0.0-1649-enterprise", + "os": "aarch64-unknown-linux-gnu", + "cpuCount": 4, + "ports": { + "direct": 11210, + "httpsMgmt": 18091, + "httpsCAPI": 18092, + "distTCP": 21100, + "distTLS": 21150 + }, + "services": [ + "cbas", + "index", + "kv", + "n1ql" + ], + "nodeEncryption": false, + "nodeEncryptionClientCertVerification": false, + "addressFamilyOnly": false, + "configuredHostname": "node1.:8091", + "addressFamily": "inet", + "externalListeners": [ + { + "afamily": "inet", + "nodeEncryption": false + } + ], + "serverGroup": "Group 1", + "replication": 1, + "nodeHash": 72627629, + "systemStats": { + "cpu_utilization_rate": 10.24295140934561, + "cpu_stolen_rate": 0, + "swap_total": 2147479552, + "swap_used": 396525568, + "mem_total": 8327258112, + "mem_free": 1854889984, + "mem_limit": 8327258112, + "cpu_cores_available": 4, + "allocstall": 37181 + }, + "interestingStats": { + "cmd_get": 0, + "couch_docs_actual_disk_size": 44320702, + "couch_docs_data_size": 32823159, + "couch_spatial_data_size": 0, + "couch_spatial_disk_size": 0, + "couch_views_actual_disk_size": 0, + "couch_views_data_size": 0, + "curr_items": 21036, + "curr_items_tot": 42230, + "ep_bg_fetched": 0, + "get_hits": 0, + "index_data_size": 38186104, + "index_disk_size": 23976600, + "mem_used": 62882016, + "ops": 0, + "vb_active_num_non_resident": 0, + "vb_replica_curr_items": 21194 + }, + "uptime": "788913", + "memoryTotal": 8327258112, + "memoryFree": 1854889984, + "mcdMemoryReserved": 6353, + "mcdMemoryAllocated": 6353 + } + ], + "stats": { + "uri": "/pools/default/buckets/travel-sample/stats", + "directoryURI": "/pools/default/buckets/travel-sample/stats/Directory", + "nodeStatsListURI": "/pools/default/buckets/travel-sample/nodes" + }, + "authType": "sasl", + "autoCompactionSettings": false, + "replicaIndex": false, + "rank": 0, + "enableCrossClusterVersioning": false, + "versionPruningWindowHrs": 720, + "replicaNumber": 1, + "threadsNumber": 3, + "quota": { + "ram": 629145600, + "rawRAM": 209715200 + }, + "basicStats": { + "quotaPercentUsed": 30.08984120686849, + "opsPerSec": 0, + "diskFetches": 0, + "itemCount": 63343, + "diskUsed": 148563968, + "dataUsed": 98633707, + "memUsed": 189308912, + "vbActiveNumNonResident": 0 + }, + "evictionPolicy": "fullEviction", + "durabilityMinLevel": "none", + "pitrEnabled": false, + "pitrGranularity": 600, + "pitrMaxHistoryAge": 86400, + "conflictResolutionType": "seqno", + "maxTTL": 0, + "compressionMode": "passive", + "accessScannerEnabled": false +} \ No newline at end of file From 6bb9dff92bb26390774b878846bce05f7a512253 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Mon, 10 Jun 2024 15:00:29 -0400 Subject: [PATCH 2/5] Deleted stay blank line --- modules/rest-api/pages/rest-bucket-create.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/rest-api/pages/rest-bucket-create.adoc b/modules/rest-api/pages/rest-bucket-create.adoc index 5c3ef70cec..b4da5a3184 100644 --- a/modules/rest-api/pages/rest-bucket-create.adoc +++ b/modules/rest-api/pages/rest-bucket-create.adoc @@ -830,7 +830,6 @@ curl -v -X POST http://localhost:8091/pools/default/buckets/testBucket \ Success returns `200 OK`. - [#auto-compaction-parameters] == Auto-Compaction Parameters From beec01ae3e37e26400a5256aa386f1088ec0aca7 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Mon, 10 Jun 2024 15:09:50 -0400 Subject: [PATCH 3/5] Fixed include link --- modules/rest-api/pages/rest-buckets-summary.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/rest-api/pages/rest-buckets-summary.adoc b/modules/rest-api/pages/rest-buckets-summary.adoc index 2cfec45f35..705e3bf3b6 100644 --- a/modules/rest-api/pages/rest-buckets-summary.adoc +++ b/modules/rest-api/pages/rest-buckets-summary.adoc @@ -56,7 +56,7 @@ The fields `historyRetentionCollectionDefault`, `historyRetentionCollectionBytes [source, json] ---- -include::partial$get_bucket_travel_sample.json +include::partial$get_bucket_travel_sample.json[] ---- NOTE: Couchbase Server version 7.6.2 added a property named `enableCrossClusterVersioning` to support a future feature. From 587786f947521b563b9fb8036661d6f4b7c08c25 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Mon, 10 Jun 2024 15:38:21 -0400 Subject: [PATCH 4/5] Updated example description to fix several issues. --- modules/rest-api/pages/rest-buckets-summary.adoc | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/modules/rest-api/pages/rest-buckets-summary.adoc b/modules/rest-api/pages/rest-buckets-summary.adoc index 705e3bf3b6..ffc8c71160 100644 --- a/modules/rest-api/pages/rest-buckets-summary.adoc +++ b/modules/rest-api/pages/rest-buckets-summary.adoc @@ -41,18 +41,20 @@ If an internal error prevents successful execution, `500 Internal Server Error` [#example] == Example -The following example returns information on a single bucket, which is `testBucket`. -The output of the call is piped to https://stedolan.github.io/jq/[jq^], to facilitate readability. +The following example returns information on a single bucket named `travel-sample`. +The output of the call is piped to https://stedolan.github.io/jq/[jq^] to improve readability. ---- curl -X GET -u Administrator:password \ -http://localhost:8091/pools/default/buckets/testBucket | jq '.' +http://localhost:8091/pools/default/buckets/travel-sample | jq '.' ---- -If successful, the call returns `200 OK`, and an object such as the following. -(Note that actual console-output contains an extensive array of vBucket-information: this has been omitted from this example.) +If successful, the call returns `200 OK`, and an object similar to the one shown in the following example. -The fields `historyRetentionCollectionDefault`, `historyRetentionCollectionBytes`, and `historyRetentionCollectionSeconds` are specific to _Magma_ storage: if `magma` is not the value of `storageBackend`, these parameters are not displayed. +NOTE: The output contains an extensive array of vBucket data that is omitted from this example. + +The fields `historyRetentionCollectionDefault`, `historyRetentionCollectionBytes`, and `historyRetentionCollectionSeconds` are specific to Magma storage. +When the bucket does not use Magma as its storage backend, these properties do not appear in the output. [source, json] ---- From 89f9ba0dc5aba85eb31e47c991dd432aff38a3d4 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Tue, 11 Jun 2024 10:51:50 -0400 Subject: [PATCH 5/5] Update based on Hyun-Ju's feedback. --- modules/rest-api/pages/rest-bucket-create.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/rest-api/pages/rest-bucket-create.adoc b/modules/rest-api/pages/rest-bucket-create.adoc index b4da5a3184..76320237cc 100644 --- a/modules/rest-api/pages/rest-bucket-create.adoc +++ b/modules/rest-api/pages/rest-bucket-create.adoc @@ -1106,7 +1106,7 @@ Couchbase Server 7.6.2 added a property named `enableCrossClusterVersioning` to Do not change the value of this property. CAUTION: Once enabled, you cannot turn off the `enableCrossClusterVersioning` property. -The only way for you to undo setting this value to `true` is to backup your data, create a new database, and reload the data. +The only way for you to undo setting this value to `true` is to backup your data, create a new bucket, and reload the data into it. == See Also