MB-68541 Change ejection policy for ephemeral buckets

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.

modules/learn/pages/buckets-memory-and-storage/memory.adoc

@@ -176,14 +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[Buckets].
+[#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:

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.

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 ephemeral 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 bucket 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[]
+

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 the Couchbase 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.
 
-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 <<rest-api>> 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,39 +58,109 @@ 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/{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/{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:
+
++
+[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/{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]
+----
+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/{BUCKETNAME}` as shown in step 1.
+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 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.
+
+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.
+
+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.
 
-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/<bucketname>` endpoint and changing 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.
+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 change depends on whether you're changing the ejection policy during a backend storage migration or not.
+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:
@@ -96,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/<bucketname>`:
+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.
@@ -108,20 +184,20 @@ 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:
 +
 --
-. 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/<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 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:
@@ -137,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/<bucketname>` 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:
 
@@ -181,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]
 ----
@@ -207,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/<bucketname>` 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`: