From 3e722c6706ff0d38b2a152208a392b020d67b2f6 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Fri, 19 Sep 2025 13:57:17 -0400 Subject: [PATCH 1/5] First pass at fix. Updated current draft docs to say ephemeral buckets can also have their ejection policy changed. --- .../partials/new-features-80.adoc | 7 ++ .../buckets-memory-and-storage/memory.adoc | 5 +- .../storage-settings.adoc | 2 +- .../manage/examples/change-ejection-policy.sh | 16 +++- .../change-ejection-policy.adoc | 96 ++++++++++++++++--- .../rest-api/pages/rest-bucket-create.adoc | 6 +- ..._Change_eviction_on_Ephemeral_buckets.yml} | 8 +- 7 files changed, 117 insertions(+), 23 deletions(-) rename preview/{DOC-12483_remove_memcached_buckets.yml => MB-68541_Change_eviction_on_Ephemeral_buckets.yml} (82%) diff --git a/modules/introduction/partials/new-features-80.adoc b/modules/introduction/partials/new-features-80.adoc index f0a782aa1a..e18c017f5a 100644 --- a/modules/introduction/partials/new-features-80.adoc +++ b/modules/introduction/partials/new-features-80.adoc @@ -231,6 +231,13 @@ For example, you should consider changing a bucket's ejection policy to Full Eje Using the `noRestart` parameter, you can change the ejection policy at the same time you migrate the bucket to the new storage engine. See xref:manage:manage-buckets/migrate-bucket.adoc[] for more information. +[#ejection-ephemeral-buckets] +https://jira.issues.couchbase.com/browse/MB-64104[MB-64104] Allow changing the ejection policy of ephemeral buckets:: +You can now change the ejection policy of an ephemeral bucket using the Couchbase Server Web Console and the REST API. +Unlike Couchstore buckets, changing the ejection policy of an ephemeral bucket does not require a bucket restart or other additional steps. +For more information, see xref:manage:manage-buckets/change-ejection-policy.adoc[]. + + [#section-new-feature-800-disk-limits] https://jira.issues.couchbase.com/browse/MB-59113[MB-59113] Prevent buckets from causing nodes to run out of disk space:: You can configure Couchbase Server to prevent the Data Service from writing to the data service path once the filesystem has filled to a configurable threshold. diff --git a/modules/learn/pages/buckets-memory-and-storage/memory.adoc b/modules/learn/pages/buckets-memory-and-storage/memory.adoc index 655efdd71d..d663ffadf0 100644 --- a/modules/learn/pages/buckets-memory-and-storage/memory.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/memory.adoc @@ -176,7 +176,10 @@ Ejecting data from a Couchbase bucket does not remove the data from disk, so it' The only effect is that the next access to the data is slower because the Data Service has to read it from disk instead of from memory. ==== -For more information about buckets and bucket types, see xref:buckets-memory-and-storage/buckets.adoc[Buckets]. +For more information about buckets and bucket types, see xref:buckets-memory-and-storage/buckets.adoc[]. +To learn how to change a bucket's ejection policy, see xref:manage:manage-buckets/change-ejection-policy.adoc[]. + +[#changing-ejection-policy] ### Changing the Ejection Policy of a Couchbase Bucket diff --git a/modules/learn/pages/buckets-memory-and-storage/storage-settings.adoc b/modules/learn/pages/buckets-memory-and-storage/storage-settings.adoc index 9571898d77..64c9027ba3 100644 --- a/modules/learn/pages/buckets-memory-and-storage/storage-settings.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/storage-settings.adoc @@ -183,5 +183,5 @@ It controls whether and how it ejects data from memory when the bucket's memory The policies you can set depend on the type of the bucket. See xref:learn:buckets-memory-and-storage/memory.adoc#ejection[Ejection] for more information. -You can set the policy when creating the bucket either by the REST API, command-line interface, or Couchbase Server Web Console. +You set the policy when creating the bucket and can change it later using the REST API, command-line interface, or Couchbase Server Web Console. See xref:manage:manage-buckets/create-bucket.adoc[] for more information. diff --git a/modules/manage/examples/change-ejection-policy.sh b/modules/manage/examples/change-ejection-policy.sh index 7eff45aa92..aab197f979 100644 --- a/modules/manage/examples/change-ejection-policy.sh +++ b/modules/manage/examples/change-ejection-policy.sh @@ -1,4 +1,4 @@ - +# Change ejection policy of Couchbase bucket # tag::change-ejection-no-restart[] curl -v -X POST http://localhost:8091/pools/default/buckets/travel-sample \ -u Administrator:password \ @@ -41,3 +41,17 @@ curl -X POST -u Administrator:password \ -d 'knownNodes=ns_1@node1.,ns_1@node2.,ns_1@node3.' # end::rebalance-cluster[] +# Show setting of ejection policy on empehermal bucket +# tag::show-ephemeral-policy[] +curl -s GET -u Administrator:password \ + http://localhost:8091/pools/default/buckets/sample-ephemeral \ + | jq '{ (.name): .evictionPolicy }' +# end::show-ephemeral-policy[] + +# Change Ephemeral bucet ejection policy +# tag::change-ephemeral-policy[] +curl -s -X POST http://localhost:8091/pools/default/buckets/sample-ephemeral \ + -u Administrator:password \ + -d evictionPolicy="nruEviction" +# end::change-ephemeral-policy[] + diff --git a/modules/manage/pages/manage-buckets/change-ejection-policy.adoc b/modules/manage/pages/manage-buckets/change-ejection-policy.adoc index 78b1d8d9ce..70021e0f33 100644 --- a/modules/manage/pages/manage-buckets/change-ejection-policy.adoc +++ b/modules/manage/pages/manage-buckets/change-ejection-policy.adoc @@ -1,5 +1,5 @@ = Change a Bucket's Ejection Policy -:description: You can change the ejection method of a Couchbase bucket. +:description: You can change the ejection method of a bucket using theCouchbase Server Web Console or the REST API. :toclevels: 3 @@ -8,25 +8,31 @@ The bucket's ejection policy (also known as its eviction method) controls how Couchbase Server removes documents from memory as the bucket approaches its memory quota. See xref:learn:buckets-memory-and-storage/memory.adoc#ejection[Ejection] for more information about ejection policies. -NOTE: You cannot change the eviction policy of an existing Ephemeral bucket. -If you want an Ephemeral bucket to have a different ejection policy, you must drop and recreate it. +You initially set the ejection policy when you create a Couchbase bucket. +However, you can change the ejection policy of an existing bucket using either the Couchbase Server Web Console or the Couchbase Server REST API. -You may want to change the ejection policy when migrating a bucket's xref:learn:buckets-memory-and-storage/storage-engines.adoc[storage engine]. +You may want to change the ejection policy of a Couchbase bucket when migrating its xref:learn:buckets-memory-and-storage/storage-engines.adoc[storage engine]. For example, when migrating a bucket from Couchstore to Magma, you should consider changing the bucket's ejection policy to Full Ejection. This policy works well for Magma buckets that have a low memory to storage ratio. You can change both the storage backend and the ejection policy at the same time. See xref:manage:manage-buckets/migrate-bucket.adoc[] for steps to perform both operations. -== Changing the Ejection Policy Using the Couchbase Server Web Console +== Change the Ejection Policy Using the Couchbase Server Web Console -You can edit a Couchbase bucket's ejection policy using the Couchbase Server Web Console. +You can edit a bucket's ejection policy using the Couchbase Server Web Console. -IMPORTANT: When you change the ejection policy of a bucket using the Couchbase Server Web Console, Couchbase Server automatically restarts the bucket. +[IMPORTANT] +==== +When you change the ejection policy of a Couchbase bucket using the Couchbase Server Web Console, Couchbase Server automatically restarts the bucket. Restarting the bucket closes all open connections and results in some downtime. Do not change the ejection policy of a bucket in production unless you're prepared this downtime. You can also change the ejection policy using REST API which lets you avoid downtime. See <> for more details. +Changing the ejection policy of an ephemeral bucket does not require a bucket restart or other additional steps. +The new setting takes effect immediately. +==== + To change the ejection policy of a bucket, follow these steps: . In the Web Console, click btn:[Buckets]. @@ -52,28 +58,88 @@ image::manage-buckets/bucket-edit-dialog-initial.png[,400] + image::manage-buckets/bucket-edit-dialog-expanded.png[,400] -. Change the [.ui]*Ejection Method* setting the new value you want: - +. Change the [.ui]*Ejection Method* setting the new value you want. +The available settings depend on the bucket's type: + +-- +Couchbase buckets:: * *Value-only*: Couchbase Server removes a document's data, but keeps its keys and metadata in memory. Keeping these values in memory helps lessen the performance overhead of removing the document from memory. * *Full*: Couchbase Server removes the entire document from memory. + -When you change the setting, the Couchbase Server Web Console warns you of the consequences of changing the ejection policy. +Ephemeral buckets:: +* *No ejection*: If the bucket reaches its memory quota, the Data Service does not eject data. +Instead, it refuses to load any new data until memory becomes available. +* *Eject data when RAM is full*: If the bucket approaches its memory quota, the Data Service ejects the least-recently used documents to make space for new data. +-- ++ +If you change the setting of a Couchbase bucket, the Couchbase Server Web Console warns you of the consequences of changing the ejection policy. . Click btn:[Save] to save the changes. -Couchbase Server restarts the bucket to apply the new ejection policy. +If you changed the ejection policy of a Couchbase bucket, Couchbase Server restarts the bucket to apply the new ejection policy. +If you changed the ejection policy of an ephemeral bucket, the new setting takes effect immediately. + +[#ephemeral-rest-api] +== Change Ephemeral Bucket Ejection Policy Using the REST API + +You can change the ejection policy for an ephemeral bucket by sending a POST request to the `/pools/default/buckets/` endpoint to change the `evictionPolicy` setting. +Unlike changing a Couchbase bucket's ejection policy, changing the ejection policy of an ephemeral bucket does not require a bucket restart or other additional steps. +The new setting takes effect immediately. + +The following steps demonstrate how to change the ejection policy of an ephemeral bucket named `sample-ephemeral` to `nruEviction` using the REST API. + +. View the current ejection policy of the bucket by sending a GET request to the `/pools/default/buckets/` endpoint. +The following command calls the REST API to get the configuration of the `sample-ephemeral` bucket. +It filters the result through the `jq` command to show just the `evictionPolicy` value: + ++ +[source,console] +---- +include::manage:example$change-ejection-policy.sh[tag=show-ephemeral-policy] +---- + ++ +The output of the previous command shows that the `evictionPolicy` of the `sample-ephemeral` bucket is set to `noEviction`: ++ +[source,json] +---- +{ + "sample-ephemeral": "noEviction" +} +---- + +. Send a POST request to the `/pools/default/buckets/` endpoint to change the `evictionPolicy` setting to the new ejection policy that you want. +The following command changes the ejection policy of the `sample-ephemeral` bucket to `nruEviction`: ++ +[source,console] +---- +include::manage:example$change-ejection-policy.sh[tag=change-ephemeral-policy] +---- ++ +The call to the REST API returns no output if it succeeds. +. Verify that the ejection policy has changed by sending another GET request to `/pools/default/buckets/` as shown in step 1. +The the output shows the new `evictionPolicy` value: ++ +[source,json] +---- +{ + "sample-ephemeral": "nruEviction" +} +---- + +See xref:rest-api:rest-bucket-create.adoc[] for more information about changing a bucket's settings. [#rest-api] -== Changing the Ejection Policy Using the REST API +== Change Couchbase Bucket Ejection Policy Using the REST API -You can change a bucket's ejection policy using the Couchbase Server REST API. -Unlike the Couchbase Server Web Console, using the REST API lets you avoid the downtime caused by restarting the bucket. -You change the ejection policy by sending a POST request to the `/pools/default/buckets/` endpoint and changing the `evictionPolicy` setting. +Unlike the Couchbase Server Web Console, using the REST API to change a Couchbase buclet's ejection policy lets you avoid the downtime caused by restarting the bucket. +You change the ejection policy by sending a POST request to the `/pools/default/buckets/` endpoint to change the `evictionPolicy` setting. Setting the `noRestart` parameter to `true` prevents Couchbase Server from restarting the bucket immediately after you make the change. If you do not allow Couchbase Server to restart the bucket, you must take additional steps to apply the change. +If you do not set the `noRestart` parameter or set it to `false`, Couchbase Server automatically restarts the bucket after you change the ejection policy. + How you apply the change depends on whether you're changing the ejection policy during a backend storage migration or not. [#change-during-migration] diff --git a/modules/rest-api/pages/rest-bucket-create.adoc b/modules/rest-api/pages/rest-bucket-create.adoc index d020a70c9f..a1845c94cd 100644 --- a/modules/rest-api/pages/rest-bucket-create.adoc +++ b/modules/rest-api/pages/rest-bucket-create.adoc @@ -392,13 +392,17 @@ Each type of bucket has its own set of ejection policies: * Couchbase bucket: `valueOnly` (the default for buckets using the xref:learn:buckets-memory-and-storage/storage-engines.adoc#couchstore[Couchstore] storage engine) or `fullEviction` (the default for buckets using xref:learn:buckets-memory-and-storage/storage-engines.adoc#storage-engine-magma[Magma]). * Ephemeral bucket: `noEviction` (which is the default) or `nruEviction`. -Before the change takes effect, you must perform one of the following actions: +Changes to the ejection policy of an ephemeral bucket take effect without requiring any further steps. +Before the change takes effect on a Couchbase bucket, you must perform 1 of the following actions: * Allow Couchbase Server to restart the bucket automatically. It does so automatically unless you set <> to `true`. When Couchbase Server restarts the bucket, it closes connections and makes the bucket unavailable temporarily. * Perform a xref:install:upgrade-procedure-selection.adoc#swap-rebalance[swap rebalance] on all nodes in the cluster running the data service. * Perform a xref:learn:clusters-and-availability/graceful-failover.adoc[graceful failover] followed by a xref:learn:clusters-and-availability/recovery.adoc#delta-recovery[delta recovery] and xref:learn:clusters-and-availability/rebalance.adoc[rebalance] for all nodes running the data service in the cluster. ++ +NOTE: If you're performing a storage backend migration (see xref:manage:manage-buckets/migrate-bucket.adoc[]) while you're changing the ejection policy, you must set `noRestart` to `true`. +You must also perform a full recovery instead of a delta recovery after the graceful failover because the migration process requires it. For more information about changing the ejection policy of a bucket, including the steps to take to change the policy without downtime, see xref:manage:manage-buckets/change-ejection-policy.adoc[]. diff --git a/preview/DOC-12483_remove_memcached_buckets.yml b/preview/MB-68541_Change_eviction_on_Ephemeral_buckets.yml similarity index 82% rename from preview/DOC-12483_remove_memcached_buckets.yml rename to preview/MB-68541_Change_eviction_on_Ephemeral_buckets.yml index 58eddfd02b..c5a7dff6be 100644 --- a/preview/DOC-12483_remove_memcached_buckets.yml +++ b/preview/MB-68541_Change_eviction_on_Ephemeral_buckets.yml @@ -18,8 +18,8 @@ sources: #analytics: # url: ../../docs-includes/docs-analytics # branches: HEAD - cb-swagger: - rl: https://github.com/couchbaselabs/cb-swagger - branches: release/8.0 - start_path: docs + #cb-swagger: + # rl: https://github.com/couchbaselabs/cb-swagger + # branches: release/8.0 + # start_path: docs From f4962bdfd21c3667e2fbe5833144a14f5fac27a8 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Fri, 19 Sep 2025 14:30:55 -0400 Subject: [PATCH 2/5] Typo fixes --- .../manage/pages/manage-buckets/change-ejection-policy.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/manage/pages/manage-buckets/change-ejection-policy.adoc b/modules/manage/pages/manage-buckets/change-ejection-policy.adoc index 70021e0f33..5a078e7c35 100644 --- a/modules/manage/pages/manage-buckets/change-ejection-policy.adoc +++ b/modules/manage/pages/manage-buckets/change-ejection-policy.adoc @@ -119,7 +119,7 @@ include::manage:example$change-ejection-policy.sh[tag=change-ephemeral-policy] + The call to the REST API returns no output if it succeeds. . Verify that the ejection policy has changed by sending another GET request to `/pools/default/buckets/` as shown in step 1. -The the output shows the new `evictionPolicy` value: +The output shows the new `evictionPolicy` value: + [source,json] ---- @@ -133,7 +133,7 @@ See xref:rest-api:rest-bucket-create.adoc[] for more information about changing [#rest-api] == Change Couchbase Bucket Ejection Policy Using the REST API -Unlike the Couchbase Server Web Console, using the REST API to change a Couchbase buclet's ejection policy lets you avoid the downtime caused by restarting the bucket. +Unlike the Couchbase Server Web Console, using the REST API to change a Couchbase bucket's ejection policy lets you avoid the downtime caused by restarting the bucket. You change the ejection policy by sending a POST request to the `/pools/default/buckets/` endpoint to change the `evictionPolicy` setting. Setting the `noRestart` parameter to `true` prevents Couchbase Server from restarting the bucket immediately after you make the change. If you do not allow Couchbase Server to restart the bucket, you must take additional steps to apply the change. @@ -174,7 +174,7 @@ Do not change the ejection policy of a bucket in production unless you're prepar * To prevent the automatic bucket restart, set the `noRestart` parameter to `true`. The new ejection setting does not take effect until you perform one of the following procedures: -** a xref:install:upgrade-procedure-selection.adoc#swap-rebalance[swap rebalance] on all nodes in the cluster running the data service. +** a xref:install:upgrade-procedure-selection.adoc#swap-rebalance[swap rebalance] on all nodes in the cluster running the data service. ** the following steps for all nodes running the data service in the cluster: + -- From 2575e19c29d17707e9174ff8575120d7aec043b8 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Fri, 19 Sep 2025 14:52:54 -0400 Subject: [PATCH 3/5] Updated Memory page --- .../learn/pages/buckets-memory-and-storage/memory.adoc | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/modules/learn/pages/buckets-memory-and-storage/memory.adoc b/modules/learn/pages/buckets-memory-and-storage/memory.adoc index d663ffadf0..cc9fb3a63a 100644 --- a/modules/learn/pages/buckets-memory-and-storage/memory.adoc +++ b/modules/learn/pages/buckets-memory-and-storage/memory.adoc @@ -176,17 +176,13 @@ Ejecting data from a Couchbase bucket does not remove the data from disk, so it' The only effect is that the next access to the data is slower because the Data Service has to read it from disk instead of from memory. ==== -For more information about buckets and bucket types, see xref:buckets-memory-and-storage/buckets.adoc[]. -To learn how to change a bucket's ejection policy, see xref:manage:manage-buckets/change-ejection-policy.adoc[]. - [#changing-ejection-policy] ### Changing the Ejection Policy of a Couchbase Bucket -You can change the ejection policy of an existing Couchbase bucket. -You cannot change the ejection policy of an Ephemeral bucket after creating it. - -After you change the ejection policy of a Couchbase bucket, you must perform one of the following procedures to complete the process: +You can change the ejection policy of an existing bucket. +When you change the ejection policy for an ephemeral bucket, the change takes effect immediately. +When you change the ejection policy for a Couchbase bucket, the change does not take effect until you perform one of the following procedures: * Restart the bucket, which is the default behavior unless you set the `noRestart` parameter to `true` in the REST API call to change the ejection policy. * If you set the `noRestart` parameter to `true`, you must perform one of the following processes: From 5953bd411fa535bd5c11da6d14d1c548d28fff87 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Fri, 19 Sep 2025 15:11:29 -0400 Subject: [PATCH 4/5] Typo fix --- modules/manage/examples/change-ejection-policy.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/examples/change-ejection-policy.sh b/modules/manage/examples/change-ejection-policy.sh index aab197f979..bd81b49e28 100644 --- a/modules/manage/examples/change-ejection-policy.sh +++ b/modules/manage/examples/change-ejection-policy.sh @@ -48,7 +48,7 @@ curl -s GET -u Administrator:password \ | jq '{ (.name): .evictionPolicy }' # end::show-ephemeral-policy[] -# Change Ephemeral bucet ejection policy +# Change Ephemeral bucket ejection policy # tag::change-ephemeral-policy[] curl -s -X POST http://localhost:8091/pools/default/buckets/sample-ephemeral \ -u Administrator:password \ From 9fbb281e04e13c8fb4c6fb1f64604ba17d8d50b4 Mon Sep 17 00:00:00 2001 From: Gary Gray <137797428+ggray-cb@users.noreply.github.com> Date: Tue, 30 Sep 2025 13:47:23 -0400 Subject: [PATCH 5/5] Updates based on feedback and some additional cleanup. --- .../manage/examples/change-ejection-policy.sh | 2 +- .../change-ejection-policy.adoc | 60 +++++++++++-------- 2 files changed, 36 insertions(+), 26 deletions(-) diff --git a/modules/manage/examples/change-ejection-policy.sh b/modules/manage/examples/change-ejection-policy.sh index bd81b49e28..75e0c0471e 100644 --- a/modules/manage/examples/change-ejection-policy.sh +++ b/modules/manage/examples/change-ejection-policy.sh @@ -41,7 +41,7 @@ curl -X POST -u Administrator:password \ -d 'knownNodes=ns_1@node1.,ns_1@node2.,ns_1@node3.' # end::rebalance-cluster[] -# Show setting of ejection policy on empehermal bucket +# Show setting of ejection policy on ephemeral bucket # tag::show-ephemeral-policy[] curl -s GET -u Administrator:password \ http://localhost:8091/pools/default/buckets/sample-ephemeral \ diff --git a/modules/manage/pages/manage-buckets/change-ejection-policy.adoc b/modules/manage/pages/manage-buckets/change-ejection-policy.adoc index 5a078e7c35..d18a7e15ce 100644 --- a/modules/manage/pages/manage-buckets/change-ejection-policy.adoc +++ b/modules/manage/pages/manage-buckets/change-ejection-policy.adoc @@ -1,5 +1,5 @@ = Change a Bucket's Ejection Policy -:description: You can change the ejection method of a bucket using theCouchbase Server Web Console or the REST API. +:description: You can change the ejection method of a bucket using the Couchbase Server Web Console or the REST API. :toclevels: 3 @@ -9,7 +9,7 @@ The bucket's ejection policy (also known as its eviction method) controls how Co See xref:learn:buckets-memory-and-storage/memory.adoc#ejection[Ejection] for more information about ejection policies. You initially set the ejection policy when you create a Couchbase bucket. -However, you can change the ejection policy of an existing bucket using either the Couchbase Server Web Console or the Couchbase Server REST API. +However, you can change the ejection policy of an existing bucket. You may want to change the ejection policy of a Couchbase bucket when migrating its xref:learn:buckets-memory-and-storage/storage-engines.adoc[storage engine]. For example, when migrating a bucket from Couchstore to Magma, you should consider changing the bucket's ejection policy to Full Ejection. @@ -83,13 +83,13 @@ If you changed the ejection policy of an ephemeral bucket, the new setting takes [#ephemeral-rest-api] == Change Ephemeral Bucket Ejection Policy Using the REST API -You can change the ejection policy for an ephemeral bucket by sending a POST request to the `/pools/default/buckets/` endpoint to change the `evictionPolicy` setting. +You can change the ejection policy for an ephemeral bucket by sending a POST request to the `/pools/default/buckets/{BUCKETNAME}` endpoint to change the `evictionPolicy` setting. Unlike changing a Couchbase bucket's ejection policy, changing the ejection policy of an ephemeral bucket does not require a bucket restart or other additional steps. The new setting takes effect immediately. The following steps demonstrate how to change the ejection policy of an ephemeral bucket named `sample-ephemeral` to `nruEviction` using the REST API. -. View the current ejection policy of the bucket by sending a GET request to the `/pools/default/buckets/` endpoint. +. View the current ejection policy of the bucket by sending a GET request to the `/pools/default/buckets/{BUCKETNAME}` endpoint. The following command calls the REST API to get the configuration of the `sample-ephemeral` bucket. It filters the result through the `jq` command to show just the `evictionPolicy` value: @@ -109,7 +109,7 @@ The output of the previous command shows that the `evictionPolicy` of the `sampl } ---- -. Send a POST request to the `/pools/default/buckets/` endpoint to change the `evictionPolicy` setting to the new ejection policy that you want. +. Send a POST request to the `/pools/default/buckets/{BUCKETNAME}` endpoint to change the `evictionPolicy` setting to the new ejection policy that you want. The following command changes the ejection policy of the `sample-ephemeral` bucket to `nruEviction`: + [source,console] @@ -118,7 +118,7 @@ include::manage:example$change-ejection-policy.sh[tag=change-ephemeral-policy] ---- + The call to the REST API returns no output if it succeeds. -. Verify that the ejection policy has changed by sending another GET request to `/pools/default/buckets/` as shown in step 1. +. Verify that the ejection policy has changed by sending another GET request to `/pools/default/buckets/{BUCKETNAME}` as shown in step 1. The output shows the new `evictionPolicy` value: + [source,json] @@ -133,24 +133,34 @@ See xref:rest-api:rest-bucket-create.adoc[] for more information about changing [#rest-api] == Change Couchbase Bucket Ejection Policy Using the REST API -Unlike the Couchbase Server Web Console, using the REST API to change a Couchbase bucket's ejection policy lets you avoid the downtime caused by restarting the bucket. -You change the ejection policy by sending a POST request to the `/pools/default/buckets/` endpoint to change the `evictionPolicy` setting. -Setting the `noRestart` parameter to `true` prevents Couchbase Server from restarting the bucket immediately after you make the change. -If you do not allow Couchbase Server to restart the bucket, you must take additional steps to apply the change. +You can change the ejection policy for a Couchbase bucket using the REST API. +You change the ejection policy by sending a POST request to the `/pools/default/buckets/{BUCKETNAME}` endpoint to change the `evictionPolicy` setting. -If you do not set the `noRestart` parameter or set it to `false`, Couchbase Server automatically restarts the bucket after you change the ejection policy. +Unlike the Couchbase Server Web Console, using the REST API to change a Couchbase bucket's ejection policy lets you prevent the downtime caused by restarting a Couchbase bucket. +When you call the REST API to change the ejection policy, can set the `noRestart` parameter to `true` to prevent Couchbase Server from restarting the bucket after you make the change. +If you do not allow Couchbase Server to restart the Couchbase bucket, you must take additional steps to apply the change. -How you apply the change depends on whether you're changing the ejection policy during a backend storage migration or not. +If you do not set the `noRestart` parameter or set it to `false` for a Couchbase bucket, Couchbase Server may automatically restart the bucket after you change the ejection policy. +Couchbase Server only automatically restarts the bucket if you're not changing the ejection policy during a backend storage migration. +If you're changing the ejection policy during a backend storage migration, you must set `noRestart` to `true` to prevent Couchbase Server from restarting the bucket. +See <<#change-during-migration>> for an explanation. + +NOTE: The `noRestart` parameter has no effect when changing the ejection policy of an ephemeral bucket. +Changing the ejection policy of an ephemeral bucket takes effect without a bucket restart or other additional steps. +See <<#ephemeral-rest-api>> for more details. + +How you apply the ejection policy change for a Couchbase bucket depends on whether you're changing the ejection policy during a backend storage migration or not. [#change-during-migration] === Change Ejection Policy During a Backend Storage Migration -You can change the ejection policy while you're migrating the storage engine a bucket uses. +You can change the ejection policy of a Couchbase bucket while you're migrating the storage engine it uses. You often want to change the ejection policy during migration because the Couchstore and Magma storage engines work best with different ejection policies. See xref:learn:buckets-memory-and-storage/storage-engines.adoc[] for information about storage engines and xref:manage:manage-buckets/migrate-bucket.adoc[] for information about migrating a bucket's storage backend. -If you choose to change the ejection policy while migrating the storage backend, you must set `noRestart` to `true` to prevent Couchbase Server from restarting the bucket. -If you set this option to `false` or do not include it from your REST API call to change the ejection policy, Couchbase Server does not change the ejection policy. +If you choose to change the ejection policy while migrating the storage backend, you must set `noRestart` to `true`. +This setting prevents Couchbase Server from restarting the bucket after changing the policy. +If you set this option to `false` or do not include it from your REST API call, Couchbase Server does not change the ejection policy. After you change the ejection policy while migrating the storage backend, the policy does not take effect until you complete the migration. You complete the migration by performing 1 of the following procedures: @@ -162,9 +172,9 @@ See xref:manage:manage-buckets/migrate-bucket.adoc[] for information about migra === Standalone Ejection Policy Change -You can change a bucket's ejection policy when you're not migrating its storage backend using the REST API. +You can change a Couchbase bucket's ejection policy when you're not migrating its storage backend using the REST API. In this case, you can choose whether to have Couchbase Server restart the bucket after you change the ejection policy or not. -You control this behavior using the `noRestart` parameter in the REST API POST method to `/pools/default/buckets/`: +You control this behavior using the `noRestart` parameter in the REST API POST method to `/pools/default/buckets/{BUCKETNAME}`: * To trigger the automatic bucket restart, set the `noRestart` parameter to `false` or not supply it in the REST API call. Couchbase Server automatically restart the bucket once the REST API call completes. @@ -178,16 +188,16 @@ The new ejection setting does not take effect until you perform one of the follo ** the following steps for all nodes running the data service in the cluster: + -- -. A xref:learn:clusters-and-availability/graceful-failover.adoc[graceful failover] -. A xref:learn:clusters-and-availability/recovery.adoc#delta-recovery[delta recovery] or a xref:learn:clusters-and-availability/recovery.adoc#full-recovery[full recovery] +. A xref:learn:clusters-and-availability/graceful-failover.adoc[graceful failover] +. A xref:learn:clusters-and-availability/recovery.adoc#delta-recovery[delta recovery] or a xref:learn:clusters-and-availability/recovery.adoc#full-recovery[full recovery] . A xref:learn:clusters-and-availability/rebalance.adoc[rebalance] -- The following procedure shows you how to change the ejection policy of a bucket using the REST API. It then demonstrates performing a graceful failover followed by a delta recovery and rebalance to apply the change. -. Send a POST request to the `/pools/default/buckets/` REST API endpoint to edit the bucket, and change the `evictionPolicy` parameter to the new ejection policy that you want. -Also set the `noRestart` parameter to `true` to prevent Couchbase Server from restarting the bucket immediately. +. Send a POST request to the `/pools/default/buckets/{BUCKETNAME}` REST API endpoint to edit the bucket, and change the `evictionPolicy` parameter to the new ejection policy that you want. +Also set the `noRestart` parameter to `true` to prevent Couchbase Server from restarting the bucket. + The following command changes the ejection policy of the `travel-sample` bucket to Full Ejection without restarting the bucket: @@ -203,7 +213,7 @@ include::manage:example$change-ejection-policy.sh[tag=change-ejection-no-restart However, each node has an override setting that has them use the old ejection policy. + -You can compare the bucket and node settings to see which nodes have an override by sending a GET request to the `/pools/default/buckets/` REST API endpoint. +You can compare the bucket and node settings to see which nodes have an override by sending a GET request to the `/pools/default/buckets/{BUCKETNAME}` REST API endpoint. The following command calls the REST API to get the configuration of the `travel-sample` bucket. It filters the result through the `jq` command to show just the `evictionPolicy` values from the bucket level and the individual nodes: @@ -247,11 +257,11 @@ include::manage:example$change-ejection-policy.sh[tag=failover-node] ---- . Wait until the failover completes. -Then send a POST request to the `/controller/setRecoveryType` REST API endpoint to set the type of recovery for the node to delta. +Then send a POST request to the `/controller/setRecoveryType` REST API endpoint to set the type of recovery for the node to `delta`. See xref:rest-api:rest-node-recovery-incremental.adoc[] for more information about setting the recovery type. + -The following calls the REST API to set the recovery type for `node3` to delta: +The following calls the REST API to set the recovery type for `node3` to `delta`: + [source,console] ---- @@ -273,7 +283,7 @@ include::manage:example$change-ejection-policy.sh[tag=rebalance-cluster] . After the rebalance completes, repeat steps 3 through 5 for the rest of the data nodes in the cluster. + -You can verify which nodes still need to have the change applied to them by sending another GET request to `/pools/default/buckets/` as shown in step 2. +You can verify which nodes still need to have the change applied to them by sending another GET request to `/pools/default/buckets/{BUCKETNAME}` as shown in step 2. For example, suppose you have performed a graceful failover, full recovery, and rebalance steps on nodes `node3` and `node2`. Then the output of the command from step 2 shows that the `evictionPolicy` for `node1` is still set to `valueOnly`: