This is an automated email from the ASF dual-hosted git repository. donalevans pushed a commit to branch support/1.15 in repository https://gitbox.apache.org/repos/asf/geode.git
commit 254af1d67e93daf257840a62babbdb5d3fd4a676 Author: John Martin <[email protected]> AuthorDate: Wed Feb 2 16:02:31 2022 -0500 GEODE-9999: Update the Geode for Redis documentation (#7326) (cherry picked from commit 064fe005297e82094a1ef68d754efa2579b3277a) --- geode-docs/images_svg/geode_for_redis.svg | 189 --------------------- .../tools_modules/geode_for_redis.html.md.erb | 136 +++++++-------- 2 files changed, 63 insertions(+), 262 deletions(-) diff --git a/geode-docs/images_svg/geode_for_redis.svg b/geode-docs/images_svg/geode_for_redis.svg deleted file mode 100644 index 26efc38..0000000 --- a/geode-docs/images_svg/geode_for_redis.svg +++ /dev/null @@ -1,189 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<svg - width="1127" - height="319" - viewBox="0 0 1127 319" - fill="none" - version="1.1" - id="svg713" - sodipodi:docname="geode_for_redis.svg" - inkscape:version="1.1.1 (c3084ef, 2021-09-22)" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"; - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"; - xmlns:xlink="http://www.w3.org/1999/xlink"; - xmlns="http://www.w3.org/2000/svg"; - xmlns:svg="http://www.w3.org/2000/svg";> - <sodipodi:namedview - id="namedview715" - pagecolor="#ffffff" - bordercolor="#999999" - borderopacity="1" - inkscape:pageshadow="0" - inkscape:pageopacity="0" - inkscape:pagecheckerboard="0" - showgrid="false" - fit-margin-top="0" - fit-margin-left="0" - fit-margin-right="0" - fit-margin-bottom="0" - borderlayer="false" - showguides="true" - inkscape:guide-bbox="true" - inkscape:zoom="0.97515528" - inkscape:cx="209.71019" - inkscape:cy="303.02866" - inkscape:window-width="1312" - inkscape:window-height="1027" - inkscape:window-x="4480" - inkscape:window-y="218" - inkscape:window-maximized="0" - inkscape:current-layer="svg713" /> - <rect - x="122.96814" - width="183" - height="92" - rx="4" - fill="#a41f10" - id="rect691" - y="0.038216591" /> - <path - d="m 436.97414,51.038217 h 2.484 l -5.166,-12.366 h -2.502 l -5.166,12.366 h 2.502 l 0.936,-2.232 h 5.976 z m -6.102,-4.176 2.178,-5.202 2.178,5.202 z m 15.642,-5.346 c -1.386,0 -2.502,0.63 -3.24,1.692 v -1.476 h -2.196 v 12.402 h 2.196 v -4.572 c 0.738,1.062 1.854,1.692 3.24,1.692 2.466,0 4.266,-2.016 4.266,-4.878 0,-2.844 -1.8,-4.86 -4.266,-4.86 z m -0.594,7.866 c -1.548,0 -2.628,-1.26 -2.628,-3.006 0,-1.746 1.08,-2.988 2.628,-2.988 1.566,0 2.682,1.242 2.682,2.988 0,1.746 -1.116,3 [...] - fill="#000000" - id="path695" /> - <path - d="m 437.07914,164.03822 h 2.484 l -5.166,-12.366 h -2.502 l -5.166,12.366 h 2.502 l 0.936,-2.232 h 5.976 z m -6.102,-4.176 2.178,-5.202 2.178,5.202 z m 15.641,-5.346 c -1.386,0 -2.502,0.63 -3.24,1.692 v -1.476 h -2.196 v 12.402 h 2.196 v -4.572 c 0.738,1.062 1.854,1.692 3.24,1.692 2.466,0 4.266,-2.016 4.266,-4.878 0,-2.844 -1.8,-4.86 -4.266,-4.86 z m -0.594,7.866 c -1.548,0 -2.628,-1.26 -2.628,-3.006 0,-1.746 1.08,-2.988 2.628,-2.988 1.566,0 2.682,1.242 2.682,2.988 0,1.746 -1.116,3 [...] - fill="#000000" - id="path697" /> - <line - x1="305.96814" - y1="45.538216" - x2="391.96814" - y2="45.538216" - stroke="#000000" - id="line699" /> - <line - x1="305.96814" - y1="158.53822" - x2="391.96814" - y2="158.53822" - stroke="#000000" - id="line701" /> - <circle - cx="391.46814" - cy="45.538216" - r="1.5" - fill="#000000" - id="circle703" /> - <circle - cx="391.46814" - cy="158.53822" - r="1.5" - fill="#000000" - id="circle705" /> - <defs - id="defs711"> - <pattern - id="pattern0" - patternContentUnits="objectBoundingBox" - width="1" - height="1"> - <use - xlink:href="#image0" - transform="translate(0 -0.00215054) scale(0.00129032 0.00409919)" - id="use707" /> - </pattern> - <image - id="image0" - width="775" - height="245" - xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAwcAAAD1CAYAAAAF6onAAAAACXBIWXMAAC4jAAAuIwF4pT92AAAgAElEQVR4nO2dvW8jWZfeiy/GwTpRT7YbSQM7NEAO4NCwOCiAAKPmRHYmtrB5cwJq4ajZgOE1qKDZkR2xqXDhYChsIIBAoSXAwWaj+gtGzJy9YuTEAI2jeWq6ms0i7711b9WtqucHCPO+MxI/isWq85yP57S2221A6s24Px8EQXB/fXf5zI+aEEIIIYRk8RcemXoz7s+HQRD8KuJg3J+/avrxIIQQQggh2VAc1BgIg094h20KBEIIIYQQcgiKg5qyIwwSKBAIIYQQQkgmFAc1JEMYJFAgEEIIIYSQvVAcFEQvDM96Yeg8ID8iDBIKFQhFvG9CCCGEEJIfioPiWAZB8NgLw6GrZ1QUBgnOBUIvDLu9MHzCeyeEEEI [...] - </defs> - <text - xml:space="preserve" - style="font-style:normal;font-weight:normal;font-size:20.0182px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.938356" - x="134.30402" - y="51.743076" - id="text4527"><tspan - sodipodi:role="line" - id="tspan4525" - x="134.30402" - y="51.743076" - style="font-size:20.0182px;fill:#ffffff;stroke-width:0.938356">Geode for Redis</tspan></text> - <rect - width="1127" - height="319" - fill="#ffffff" - id="rect685-1" - x="0" - y="0" /> - <rect - x="0.5" - y="0.5" - width="749" - height="318" - rx="3.5" - fill="#ffffff" - stroke="#000000" - id="rect687-3" /> - <rect - x="567.00006" - width="183" - height="92" - rx="4" - fill="#a41f10" - id="rect691-8" - y="0" /> - <path - d="m 881.00604,51 h 2.484 l -5.166,-12.366 h -2.502 L 870.65604,51 h 2.502 l 0.936,-2.232 h 5.976 z m -6.102,-4.176 2.178,-5.202 2.178,5.202 z m 15.642,-5.346 c -1.386,0 -2.502,0.63 -3.24,1.692 v -1.476 h -2.196 v 12.402 h 2.196 v -4.572 c 0.738,1.062 1.854,1.692 3.24,1.692 2.466,0 4.266,-2.016 4.266,-4.878 0,-2.844 -1.8,-4.86 -4.266,-4.86 z m -0.594,7.866 c -1.548,0 -2.628,-1.26 -2.628,-3.006 0,-1.746 1.08,-2.988 2.628,-2.988 1.566,0 2.682,1.242 2.682,2.988 0,1.746 -1.116,3.006 -2. [...] - fill="#000000" - id="path695-4" /> - <path - d="m 881.11104,164 h 2.484 l -5.166,-12.366 h -2.502 l -5.166,12.366 h 2.502 l 0.936,-2.232 h 5.976 z m -6.102,-4.176 2.178,-5.202 2.178,5.202 z m 15.641,-5.346 c -1.386,0 -2.502,0.63 -3.24,1.692 v -1.476 h -2.196 v 12.402 h 2.196 v -4.572 c 0.738,1.062 1.854,1.692 3.24,1.692 2.466,0 4.266,-2.016 4.266,-4.878 0,-2.844 -1.8,-4.86 -4.266,-4.86 z m -0.5941,7.866 c -1.548,0 -2.6279,-1.26 -2.6279,-3.006 0,-1.746 1.0799,-2.988 2.6279,-2.988 1.5661,0 2.6821,1.242 2.6821,2.988 0,1.746 -1.11 [...] - fill="#000000" - id="path697-8" /> - <line - x1="750" - y1="45.5" - x2="836" - y2="45.5" - stroke="#000000" - id="line699-0" /> - <line - x1="750" - y1="158.5" - x2="836" - y2="158.5" - stroke="#000000" - id="line701-4" /> - <circle - cx="835.5" - cy="45.5" - r="1.5" - fill="#000000" - id="circle703-6" /> - <circle - cx="835.5" - cy="158.5" - r="1.5" - fill="#000000" - id="circle705-0" /> - <image - width="428.75452" - height="141.707" - preserveAspectRatio="none" - xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAsQAAADqCAYAAAClbFPsAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJ bWFnZVJlYWR5ccllPAAAA/RpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdp bj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6 eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuNi1jMDE0IDc5LjE1 Njc5NywgMjAxNC8wOC8yMC0wOTo1MzowMiAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJo dHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpE [...] - id="image1071-3" - x="78.576782" - y="110.10629" /> - <text - xml:space="preserve" - style="font-style:normal;font-weight:normal;font-size:20.0182px;line-height:1.25;font-family:sans-serif;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.938356" - x="578.33582" - y="51.704861" - id="text4527-2"><tspan - sodipodi:role="line" - id="tspan4525-6" - x="578.33582" - y="51.704861" - style="font-size:20.0182px;fill:#ffffff;stroke-width:0.938356">Geode for Redis</tspan></text> -</svg> diff --git a/geode-docs/tools_modules/geode_for_redis.html.md.erb b/geode-docs/tools_modules/geode_for_redis.html.md.erb index 482d817..dc6c2b9 100644 --- a/geode-docs/tools_modules/geode_for_redis.html.md.erb +++ b/geode-docs/tools_modules/geode_for_redis.html.md.erb @@ -17,25 +17,23 @@ limitations under the License. <% set_title(product_name, "for Redis") %> -<%=vars.product_name%> for Redis allows <%=vars.product_name%> to function as a drop-in replacement for a +<%=vars.product_name%> for Redis allows <%=vars.product_name%> to function as a highly-available Redis data store, letting Redis applications take advantage of -<%=vars.product_name%>’s scaling capabilities without changing their client code. Redis clients connect to a <%=vars.product_name%> -server in the same way they connect to a Redis server, using a hostname and a port number, with -optional password authentication. +<%=vars.product_name%>’s scaling capabilities with minimal changes to their client code. -<img src="../images_svg/geode_for_redis.svg" class="image" /> ## <a id="using-geode-for-redis"></a>Using <%=vars.product_name%> for Redis +To use the <%=vars.product_name%> for Redis feature, the cluster must have at least one server that has enabled the feature to handle incoming Redis commands. -The <%=vars.product_name%> cluster must have at least one server that is set up to handle the incoming Redis commands. - -Prerequisites for running the examples: +Prerequisites: 1. **Install <%=vars.product_name%>** <br/> Using the instructions in the `README.md` file in the root of the <%=vars.product_name%> checkout directory, build and install <%=vars.product_name%>. -2. **Install the Redis CLI** <br/> -Follow installation instructions at https://redis.io/download +2. **A Redis Client to Connect to the Cluster** <br/> +Users will need a Redis client, that supports **Redis cluster commands** to connect to the cluster. This example uses the Redis CLI which can be +installed following the instructions at https://redis.io/download +### <a id="starting-a-geode-for-redis-cluster"></a>Starting a <%=vars.product_name%> for Redis cluster Use `gfsh` to start a locator for managing a <%=vars.product_name%> cluster: ```commandLine @@ -70,8 +68,7 @@ However, there are two ports that must be unique for each server in the cluster, The first server used `6379` for the redis port; we'll use `6380` for the second server. -The first server was started without -a server port specified, so it used the default `40404`. To start up an additional server, you need to specify +The first server was started without a server port specified, so it used the default `40404`. To start up an additional server, you need to specify a different server port, or use `--server-port=0` which tells <%=vars.product_name%> to use an arbitrary available port for the server port. @@ -81,43 +78,29 @@ For example: gfsh> start server --J=-Dgemfire.geode-for-redis-enabled=true --J=-Dgemfire.geode-for-redis-port=6380 --server-port=0 ``` -### <a id="shutting-down"></a>Shutting Down -To shut down the <%=vars.product_name%> cluster you started, in the terminal with gfsh running type the following command - -```commandLine -gfsh> shutdown --include-locators=true -``` - -This command shuts down the entire <%=vars.product_name%> cluster. - -To confirm that everything shut down correctly, if you execute a Redis command in the `redis-cli` you should see the following message: - -```commandline -Could not connect to Redis at 127.0.0.1:6379: Connection refused -``` ## <a id="redis-start-server-options"></a>Start Server Options -The options that are specific to starting a server for <%=vars.product_name%> for Redis are listed below. -For other options see [start server](gfsh/command-pages/start.html#topic_3764EE2DB18B4AE4A625E0354471738A). +The server options specific to the <%=vars.product_name%> for Redis feature are listed below. +For other server options see [start server](gfsh/command-pages/start.html#topic_3764EE2DB18B4AE4A625E0354471738A). -`--J=-Dgemfire.geode-for-redis-enabled` (Default: `false`) <br/> -If set to `true`, a <%=vars.product_name%> server with <%=vars.product_name%> for Redis will be started. +- `--J=-Dgemfire.geode-for-redis-enabled` - **Default: `false`**<br> +When set to `true`, a <%=vars.product_name%> server with <%=vars.product_name%> for Redis will be started. -`--J=-Dgemfire.geode-for-redis-port` (Default: `6379`) <br/> +- `--J=-Dgemfire.geode-for-redis-port` - **Default: `6379`**<br> Specifies the port on which the <%=vars.product_name%> server listens for Redis commands. Note that the default port `6379` is the same port that native Redis uses by default. -`--J=-Dgemfire.geode-for-redis-bind-address` (Default: `""`) <br/> +- `--J=-Dgemfire.geode-for-redis-bind-address` - **Default: `""`**<br> Specifies the host address on which <%=vars.product_name%> for Redis is listening. If set to the empty string or if not specified, the server listens on all local addresses. -`--J=-Dgemfire.geode-for-redis-username` (Default: `"default"`) <br/> +- `--J=-Dgemfire.geode-for-redis-username` - **Default: `"default"`**<br> Specifies the default username that the server uses when a client attempts to authenticate using only a password. See section on [Security](#security) for more information. -`--J=-Dgemfire.geode-for-redis-redundant-copies` (Default: `1`) <br/> +- `--J=-Dgemfire.geode-for-redis-redundant-copies` - **Default: `1`** <br> Specifies the number of redundant copies <%=vars.product_name%> for Redis will attempt to keep in the cluster. A value of 0 means no extra copies of data will be stored in the cluster. Note that extra servers need to be running for redundant copies to be made. For @@ -129,43 +112,65 @@ to implement redundant copies and this property corresponds to the partitioned r ## <a id="security"></a>Security -Security is implemented slightly differently to OSS Redis. Redis stores password information in plain text in the redis.conf file. +Security is implemented slightly differently to Open Source Redis. Redis stores password information in plain text in the redis.conf file. -When using <%=vars.product_name%>, to enable security, a Security Manager needs to be configured on the server(s). -This Security Manager will authenticate `AUTH <password>` commands and `AUTH <username> <password>` commands. -Users can set a custom `default` username using the `geode-for-redis-username` parameter. -If users don't set this parameter, the default username will be "default". -This username will be used when `AUTH <password>` commands are sent without a `<username>`. +When using <%=vars.product_name%>, to enable security, a Security Manager needs to be configured on the server(s) or _all_ `AUTH` requests will fail. + +This Security Manager will authenticate the `AUTH <password>` command and the `AUTH <username> <password>` command. +Similar to Open Source Redis, when users send the `AUTH <password>` command without a username, the system will use the default username `default`. + +Users can change this to a custom default username using the `geode-for-redis-username` parameter. +The custom username will then be used when the `AUTH <password>` command is sent without a `<username>`. -Note that the `geode-for-redis-username` property is only needed if `AUTH` commands are issued without a username. -In this case, the Security Manager will need to respond to authentication requests using this username. -Note also that _any_ `AUTH` requests will fail if no Security Manager has been configured. For more information about configuring a Security Manager for authentication, see [Implementing Authentication](../managing/security/implementing_authentication.html). In addition to authentication, each command is authorized according to <%=vars.product_name%>'s [security model](../managing/security/implementing_authorization.html). Commands are divided into Read operations and Write operations for which the resource permissions -DATA:READ:GEODE_FOR_REDIS and DATA:WRITE:GEODE_FOR_REDIS are respectively required. +DATA:READ and DATA:WRITE are respectively required. + +To restrict users to _only_ be able to interact with the <%=vars.product_name%> for Redis region, +they must set the resource permissions to DATA:READ:GEODE_FOR_REDIS and DATA:WRITE:GEODE_FOR_REDIS. +This specificity will restrict users to only be able to READ and/or WRITE data to the `GEODE_FOR_REDIS` region. For information on configuring the cluster for SSL, see [Configuring SSL](../managing/security/implementing_ssl.html). ## <a id="application-development"></a>Application Development ### <a id="thingstoknowbeforyoubegin"></a>Things to know before you begin -- <%=vars.product_name%> for Redis currently implements a subset of the full Redis set of commands -- Applications must be using a redis client that supports Redis Cluster mode. -- If your application is using Spring Session Data Redis you will need to add the following code to disable Spring Session from calling CONFIG (CONFIG is not supported). - -```java -@Bean -public static ConfigureRedisAction configureRedisAction() { - return ConfigureRedisAction.NO_OP; -} +- Applications must be using a Redis client that **supports Redis Cluster mode**. +- <%=vars.product_name%> for Redis currently implements a [subset of the full set of Redis commands](#redis-commands) +- If your application is using **Spring Session Data Redis** you will need to add the following code to disable Spring Session from calling CONFIG (CONFIG is not supported). + + ```java + @Bean + public static ConfigureRedisAction configureRedisAction() { + return ConfigureRedisAction.NO_OP; + } + ``` + This is a known solution for many Managed Redis products (ElastiCache, Azure Cache for Redis, etc.) that disable the CONFIG command for security reasons. + You can read more about why this is done in the [Spring Session issue report](https://github.com/spring-projects/spring-session/issues/124). + +- If your application is using **redis-py-cluster** you will need to specificy the option **"skip_full_coverage_check=True"** when creating the connection to the cluster. + This is a known solution for many Managed Redis products (ElastiCache, Azure Cache for Redis, etc) that disable the CONFIG command for security reasons. + You can read more about why this is done [here](https://github.com/Grokzen/redis-py-cluster/issues/189). + +### <a id="shutting-down"></a>Shutting Down +To shut down the <%=vars.product_name%> cluster you started, in the terminal with gfsh running type the following command + +> **This command shuts down the entire <%=vars.product_name%> cluster.** + +```commandLine +gfsh> shutdown --include-locators=true +``` + +To confirm that everything shut down correctly, if you execute a Redis command in the `redis-cli` you should see the following message: + +```commandline +Could not connect to Redis at 127.0.0.1:6379: Connection refused ``` -This is a known solution for many Managed Redis products (ElastiCache, Azure Cache for Redis, etc.) that disable the CONFIG command for security reasons. -You can read more about why this is done in the [Spring Session issue report](https://github.com/spring-projects/spring-session/issues/124). ## <a id="redis-commands"></a>Redis Commands @@ -211,7 +216,7 @@ These commands are supported for Redis 5. **[2]** COMMAND is implemented only with no subcommands. -**[3]** Native Redis supports a range of values of +/- the capacity of unsigned 64-bit integers +**[3]** HSCAN, SSCAN, ZSCAN. Native Redis supports a range of values of +/- the capacity of unsigned 64-bit integers (+/- 1.8446744e+19) for the CURSOR, but 64-bit signed integers for COUNT. <%=vars.product_name%> for Redis matches native Redis's behavior for COUNT, but only supports values of +/- the capacity of a signed 64-bit integer (+/- 9223372036854775807) for CURSOR. @@ -229,27 +234,12 @@ integer (+/- 9223372036854775807) for CURSOR. | server | redis_version<br/>redis_mode (always returns "cluster" because <%=vars.product_name%> for Redis always runs in cluster mode.)<br/>tcp_port<br/>uptime_in_seconds<br/>uptime_in_days | | stats | total_commands_processed<br/>instantaneous_ops_per_sec<br/>total_net_input_bytes<br/>instantaneous_input_kbps<br/>total_connections_received<br/>keyspace_hits<br/>keyspace_misses<br/>evicted_keys (always returns 0)<br/>rejected_connections (always returns 0)<br/>pubsub_channels<br/>pubsub_patterns| -## <a id="advantages-over-redis"></a>Advantages of <%=vars.product_name%> over Redis - -<%=vars.product_name%>’s primary advantage is its **scalability**. While the Redis server is single threaded, <%=vars.product_name%> supports high concurrency. Many Redis clients can execute commands on the <%=vars.product_name%> cluster simultaneously. - -<%=vars.product_name%>'s architecture and management features help detect and resolve **network partitioning** problems without explicit management on the part of the Redis client. - -<%=vars.product_name%> for Redis partitions data across multiple servers and keeps replicated data up to date _synchronously_, whereas Redis uses asynchronous replication. -This provides a higher level of data consistency within the cluster. - ## <a id="expiration-accuracy"></a>Expiration Accuracy Keys are expired in two ways, actively and passively: -- With active expiration, expiration is evaluated whenever a key is accessed. If the key is due to expire, it is deleted. Active expiration is accurate to the millisecond. -- With passive expiration, keys are evaluated every three minutes. If they are due to expire, they are deleted. Passive expiration is accurate to the second. - -## <a id="high-availability-model"></a>High Availability Model - -Data is stored in a single partitioned region that by default has one redundant copy. -In practice this means that the cluster can tolerate the loss of a single server without the loss of -data. +- With active expiration, expiration is evaluated **whenever a key is accessed**. If the key is due to expire, it is deleted. +- With passive expiration, keys are evaluated **every three minutes**. If they are due to expire, they are deleted. ## <a id="loss-of-connections"></a>Loss of Connections
