Skip to content

Commit c06e4b6

Browse files
ggray-cbggray-cb
authored
MB-68541 Change ejection policy for ephemeral buckets (#3885)
* First pass at fix. Updated current draft docs to say ephemeral buckets can also have their ejection policy changed. * Typo fixes * Updated Memory page * Typo fix * Updates based on feedback and some additional cleanup.
1 parent f17bfea commit c06e4b6

File tree

7 files changed

+144
-44
lines changed

7 files changed

+144
-44
lines changed

‎modules/introduction/partials/new-features-80.adoc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,6 +231,13 @@ For example, you should consider changing a bucket's ejection policy to Full Eje
231231
Using the `noRestart` parameter, you can change the ejection policy at the same time you migrate the bucket to the new storage engine.
232232
See xref:manage:manage-buckets/migrate-bucket.adoc[] for more information.
233233
234+
[#ejection-ephemeral-buckets]
235+
https://jira.issues.couchbase.com/browse/MB-64104[MB-64104] Allow changing the ejection policy of ephemeral buckets::
236+
You can now change the ejection policy of an ephemeral bucket using the Couchbase Server Web Console and the REST API.
237+
Unlike Couchstore buckets, changing the ejection policy of an ephemeral bucket does not require a bucket restart or other additional steps.
238+
For more information, see xref:manage:manage-buckets/change-ejection-policy.adoc[].
239+
240+
234241
[#section-new-feature-800-disk-limits]
235242
https://jira.issues.couchbase.com/browse/MB-59113[MB-59113] Prevent buckets from causing nodes to run out of disk space::
236243
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‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -176,14 +176,13 @@ Ejecting data from a Couchbase bucket does not remove the data from disk, so it'
176176
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.
177177
====
178178

179-
For more information about buckets and bucket types, see xref:buckets-memory-and-storage/buckets.adoc[Buckets].
179+
[#changing-ejection-policy]
180180

181181
### Changing the Ejection Policy of a Couchbase Bucket
182182

183-
You can change the ejection policy of an existing Couchbase bucket.
184-
You cannot change the ejection policy of an Ephemeral bucket after creating it.
185-
186-
After you change the ejection policy of a Couchbase bucket, you must perform one of the following procedures to complete the process:
183+
You can change the ejection policy of an existing bucket.
184+
When you change the ejection policy for an ephemeral bucket, the change takes effect immediately.
185+
When you change the ejection policy for a Couchbase bucket, the change does not take effect until you perform one of the following procedures:
187186

188187
* 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.
189188
* 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‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -183,5 +183,5 @@ It controls whether and how it ejects data from memory when the bucket's memory
183183
The policies you can set depend on the type of the bucket.
184184
See xref:learn:buckets-memory-and-storage/memory.adoc#ejection[Ejection] for more information.
185185

186-
You can set the policy when creating the bucket either by the REST API, command-line interface, or Couchbase Server Web Console.
186+
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.
187187
See xref:manage:manage-buckets/create-bucket.adoc[] for more information.

‎modules/manage/examples/change-ejection-policy.sh‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
1+
# Change ejection policy of Couchbase bucket
22
# tag::change-ejection-no-restart[]
33
curl -v -X POST http://localhost:8091/pools/default/buckets/travel-sample \
44
-u Administrator:password \
@@ -41,3 +41,17 @@ curl -X POST -u Administrator:password \
4141
-d 'knownNodes=ns_1@node1.,ns_1@node2.,ns_1@node3.'
4242
# end::rebalance-cluster[]
4343

44+
# Show setting of ejection policy on ephemeral bucket
45+
# tag::show-ephemeral-policy[]
46+
curl -s GET -u Administrator:password \
47+
http://localhost:8091/pools/default/buckets/sample-ephemeral \
48+
| jq '{ (.name): .evictionPolicy }'
49+
# end::show-ephemeral-policy[]
50+
51+
# Change Ephemeral bucket ejection policy
52+
# tag::change-ephemeral-policy[]
53+
curl -s -X POST http://localhost:8091/pools/default/buckets/sample-ephemeral \
54+
-u Administrator:password \
55+
-d evictionPolicy="nruEviction"
56+
# end::change-ephemeral-policy[]
57+

‎modules/manage/pages/manage-buckets/change-ejection-policy.adoc‎

Lines changed: 108 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
= Change a Bucket's Ejection Policy
2-
:description: You can change the ejection method of a Couchbase bucket.
2+
:description: You can change the ejection method of a bucket using the Couchbase Server Web Console or the REST API.
33
:toclevels: 3
44

55

@@ -8,25 +8,31 @@
88
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.
99
See xref:learn:buckets-memory-and-storage/memory.adoc#ejection[Ejection] for more information about ejection policies.
1010

11-
NOTE: You cannot change the eviction policy of an existing Ephemeral bucket.
12-
If you want an Ephemeral bucket to have a different ejection policy, you must drop and recreate it.
11+
You initially set the ejection policy when you create a Couchbase bucket.
12+
However, you can change the ejection policy of an existing bucket.
1313

14-
You may want to change the ejection policy when migrating a bucket's xref:learn:buckets-memory-and-storage/storage-engines.adoc[storage engine].
14+
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].
1515
For example, when migrating a bucket from Couchstore to Magma, you should consider changing the bucket's ejection policy to Full Ejection.
1616
This policy works well for Magma buckets that have a low memory to storage ratio.
1717
You can change both the storage backend and the ejection policy at the same time.
1818
See xref:manage:manage-buckets/migrate-bucket.adoc[] for steps to perform both operations.
1919

20-
== Changing the Ejection Policy Using the Couchbase Server Web Console
20+
== Change the Ejection Policy Using the Couchbase Server Web Console
2121

22-
You can edit a Couchbase bucket's ejection policy using the Couchbase Server Web Console.
22+
You can edit a bucket's ejection policy using the Couchbase Server Web Console.
2323

24-
IMPORTANT: When you change the ejection policy of a bucket using the Couchbase Server Web Console, Couchbase Server automatically restarts the bucket.
24+
[IMPORTANT]
25+
====
26+
When you change the ejection policy of a Couchbase bucket using the Couchbase Server Web Console, Couchbase Server automatically restarts the bucket.
2527
Restarting the bucket closes all open connections and results in some downtime.
2628
Do not change the ejection policy of a bucket in production unless you're prepared this downtime.
2729
You can also change the ejection policy using REST API which lets you avoid downtime.
2830
See <<rest-api>> for more details.
2931
32+
Changing the ejection policy of an ephemeral bucket does not require a bucket restart or other additional steps.
33+
The new setting takes effect immediately.
34+
====
35+
3036
To change the ejection policy of a bucket, follow these steps:
3137

3238
. In the Web Console, click btn:[Buckets].
@@ -52,39 +58,109 @@ image::manage-buckets/bucket-edit-dialog-initial.png[,400]
5258
+
5359
image::manage-buckets/bucket-edit-dialog-expanded.png[,400]
5460

55-
. Change the [.ui]*Ejection Method* setting the new value you want:
56-
61+
. Change the [.ui]*Ejection Method* setting the new value you want.
62+
The available settings depend on the bucket's type:
5763
+
64+
--
65+
Couchbase buckets::
5866
* *Value-only*: Couchbase Server removes a document's data, but keeps its keys and metadata in memory.
5967
Keeping these values in memory helps lessen the performance overhead of removing the document from memory.
6068
* *Full*: Couchbase Server removes the entire document from memory.
6169

6270
+
63-
When you change the setting, the Couchbase Server Web Console warns you of the consequences of changing the ejection policy.
71+
Ephemeral buckets::
72+
* *No ejection*: If the bucket reaches its memory quota, the Data Service does not eject data.
73+
Instead, it refuses to load any new data until memory becomes available.
74+
* *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.
75+
--
76+
+
77+
If you change the setting of a Couchbase bucket, the Couchbase Server Web Console warns you of the consequences of changing the ejection policy.
6478

6579
. Click btn:[Save] to save the changes.
66-
Couchbase Server restarts the bucket to apply the new ejection policy.
80+
If you changed the ejection policy of a Couchbase bucket, Couchbase Server restarts the bucket to apply the new ejection policy.
81+
If you changed the ejection policy of an ephemeral bucket, the new setting takes effect immediately.
82+
83+
[#ephemeral-rest-api]
84+
== Change Ephemeral Bucket Ejection Policy Using the REST API
85+
86+
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.
87+
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.
88+
The new setting takes effect immediately.
89+
90+
The following steps demonstrate how to change the ejection policy of an ephemeral bucket named `sample-ephemeral` to `nruEviction` using the REST API.
91+
92+
. View the current ejection policy of the bucket by sending a GET request to the `/pools/default/buckets/{BUCKETNAME}` endpoint.
93+
The following command calls the REST API to get the configuration of the `sample-ephemeral` bucket.
94+
It filters the result through the `jq` command to show just the `evictionPolicy` value:
95+
96+
+
97+
[source,console]
98+
----
99+
include::manage:example$change-ejection-policy.sh[tag=show-ephemeral-policy]
100+
----
101+
102+
+
103+
The output of the previous command shows that the `evictionPolicy` of the `sample-ephemeral` bucket is set to `noEviction`:
104+
+
105+
[source,json]
106+
----
107+
{
108+
"sample-ephemeral": "noEviction"
109+
}
110+
----
111+
112+
. Send a POST request to the `/pools/default/buckets/{BUCKETNAME}` endpoint to change the `evictionPolicy` setting to the new ejection policy that you want.
113+
The following command changes the ejection policy of the `sample-ephemeral` bucket to `nruEviction`:
114+
+
115+
[source,console]
116+
----
117+
include::manage:example$change-ejection-policy.sh[tag=change-ephemeral-policy]
118+
----
119+
+
120+
The call to the REST API returns no output if it succeeds.
121+
. Verify that the ejection policy has changed by sending another GET request to `/pools/default/buckets/{BUCKETNAME}` as shown in step 1.
122+
The output shows the new `evictionPolicy` value:
123+
+
124+
[source,json]
125+
----
126+
{
127+
"sample-ephemeral": "nruEviction"
128+
}
129+
----
130+
131+
See xref:rest-api:rest-bucket-create.adoc[] for more information about changing a bucket's settings.
67132

68133
[#rest-api]
69-
== Changing the Ejection Policy Using the REST API
134+
== Change Couchbase Bucket Ejection Policy Using the REST API
135+
136+
You can change the ejection policy for a Couchbase bucket using the REST API.
137+
You change the ejection policy by sending a POST request to the `/pools/default/buckets/{BUCKETNAME}` endpoint to change the `evictionPolicy` setting.
138+
139+
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.
140+
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.
141+
If you do not allow Couchbase Server to restart the Couchbase bucket, you must take additional steps to apply the change.
142+
143+
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.
144+
Couchbase Server only automatically restarts the bucket if you're not changing the ejection policy during a backend storage migration.
145+
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.
146+
See <<#change-during-migration>> for an explanation.
70147

71-
You can change a bucket's ejection policy using the Couchbase Server REST API.
72-
Unlike the Couchbase Server Web Console, using the REST API lets you avoid the downtime caused by restarting the bucket.
73-
You change the ejection policy by sending a POST request to the `/pools/default/buckets/<bucketname>` endpoint and changing the `evictionPolicy` setting.
74-
Setting the `noRestart` parameter to `true` prevents Couchbase Server from restarting the bucket immediately after you make the change.
75-
If you do not allow Couchbase Server to restart the bucket, you must take additional steps to apply the change.
148+
NOTE: The `noRestart` parameter has no effect when changing the ejection policy of an ephemeral bucket.
149+
Changing the ejection policy of an ephemeral bucket takes effect without a bucket restart or other additional steps.
150+
See <<#ephemeral-rest-api>> for more details.
76151

77-
How you apply the change depends on whether you're changing the ejection policy during a backend storage migration or not.
152+
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.
78153

79154
[#change-during-migration]
80155
=== Change Ejection Policy During a Backend Storage Migration
81156

82-
You can change the ejection policy while you're migrating the storage engine a bucket uses.
157+
You can change the ejection policy of a Couchbase bucket while you're migrating the storage engine it uses.
83158
You often want to change the ejection policy during migration because the Couchstore and Magma storage engines work best with different ejection policies.
84159
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.
85160

86-
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.
87-
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.
161+
If you choose to change the ejection policy while migrating the storage backend, you must set `noRestart` to `true`.
162+
This setting prevents Couchbase Server from restarting the bucket after changing the policy.
163+
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.
88164

89165
After you change the ejection policy while migrating the storage backend, the policy does not take effect until you complete the migration.
90166
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
96172

97173
=== Standalone Ejection Policy Change
98174

99-
You can change a bucket's ejection policy when you're not migrating its storage backend using the REST API.
175+
You can change a Couchbase bucket's ejection policy when you're not migrating its storage backend using the REST API.
100176
In this case, you can choose whether to have Couchbase Server restart the bucket after you change the ejection policy or not.
101-
You control this behavior using the `noRestart` parameter in the REST API POST method to `/pools/default/buckets/<bucketname>`:
177+
You control this behavior using the `noRestart` parameter in the REST API POST method to `/pools/default/buckets/{BUCKETNAME}`:
102178

103179
* To trigger the automatic bucket restart, set the `noRestart` parameter to `false` or not supply it in the REST API call.
104180
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
108184
* To prevent the automatic bucket restart, set the `noRestart` parameter to `true`.
109185
The new ejection setting does not take effect until you perform one of the following procedures:
110186

111-
** a xref:install:upgrade-procedure-selection.adoc#swap-rebalance[swap rebalance] on all nodes in the cluster running the data service.
187+
** a xref:install:upgrade-procedure-selection.adoc#swap-rebalance[swap rebalance] on all nodes in the cluster running the data service.
112188
** the following steps for all nodes running the data service in the cluster:
113189
+
114190
--
115-
. A xref:learn:clusters-and-availability/graceful-failover.adoc[graceful failover]
116-
. 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]
191+
. A xref:learn:clusters-and-availability/graceful-failover.adoc[graceful failover]
192+
. 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]
117193
. A xref:learn:clusters-and-availability/rebalance.adoc[rebalance]
118194
--
119195

120196
The following procedure shows you how to change the ejection policy of a bucket using the REST API.
121197
It then demonstrates performing a graceful failover followed by a delta recovery and rebalance to apply the change.
122198

123-
. 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.
124-
Also set the `noRestart` parameter to `true` to prevent Couchbase Server from restarting the bucket immediately.
199+
. 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.
200+
Also set the `noRestart` parameter to `true` to prevent Couchbase Server from restarting the bucket.
125201

126202
+
127203
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
137213
However, each node has an override setting that has them use the old ejection policy.
138214

139215
+
140-
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.
216+
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.
141217
The following command calls the REST API to get the configuration of the `travel-sample` bucket.
142218
It filters the result through the `jq` command to show just the `evictionPolicy` values from the bucket level and the individual nodes:
143219

@@ -181,11 +257,11 @@ include::manage:example$change-ejection-policy.sh[tag=failover-node]
181257
----
182258

183259
. Wait until the failover completes.
184-
Then send a POST request to the `/controller/setRecoveryType` REST API endpoint to set the type of recovery for the node to delta.
260+
Then send a POST request to the `/controller/setRecoveryType` REST API endpoint to set the type of recovery for the node to `delta`.
185261
See xref:rest-api:rest-node-recovery-incremental.adoc[] for more information about setting the recovery type.
186262

187263
+
188-
The following calls the REST API to set the recovery type for `node3` to delta:
264+
The following calls the REST API to set the recovery type for `node3` to `delta`:
189265
+
190266
[source,console]
191267
----
@@ -207,7 +283,7 @@ include::manage:example$change-ejection-policy.sh[tag=rebalance-cluster]
207283
. After the rebalance completes, repeat steps 3 through 5 for the rest of the data nodes in the cluster.
208284

209285
+
210-
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.
286+
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.
211287
For example, suppose you have performed a graceful failover, full recovery, and rebalance steps on nodes `node3` and `node2`.
212288
Then the output of the command from step 2 shows that the `evictionPolicy` for `node1` is still set to `valueOnly`:
213289

0 commit comments

Comments
 (0)