Skip to content

Commit 8a24d67

Browse files
jmacdotorgdormando
jmacdotorg
authored and
dormando
committed
Add a new overview page for the built-in proxy.
1 parent 7400c0b commit 8a24d67

File tree

2 files changed

+92
-4
lines changed

2 files changed

+92
-4
lines changed

‎content/features/proxy/_index.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -101,21 +101,21 @@ Roadmapped features:
101101

102102
---
103103

104-
# Examples and use cases
104+
## Examples and use cases
105105

106106
See [this document on example architectures](/ProxyExamples) for
107107
different methods of deploying and using the proxy.
108108

109109
---
110110

111-
# Architecture and Workflows
111+
## Architecture and Workflows
112112

113113
See [this document on architecture](/ProxyArch) for details on the proxy's
114114
thread components and how various subsystems work.
115115

116116
---
117117

118-
# Configuration API
118+
## Configuration API {#configuration_api}
119119

120120
To load the configuration, a dedicated thread first compiles the Lua code. It then calls the function `mcp_config_pools`, which loads all backends, collects them into pools, and returns a Lua table holding all of the final pool objects. Next, for each worker thread, they each execute `mcp_config_routes`. This function is expected to set up route handling (code that matches requests to a pool), and sets the command hooks that memcached will call (ie; hooks on get, set, and so on).
121121

‎content/features/proxy2/_index.md

Lines changed: 89 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,94 @@
11
+++
22
title = 'Proxy2'
33
date = 2024-09-01T09:31:55-07:00
4+
weight = 1
5+
next = '/features/proxy2/quickstart/'
46
+++
57

6-
[Quickstart](/proxy2/quickstart/)
8+
This page provides a conceptual overview of the Memcached built-in proxy. For a hands-on quick-start guide to install and run the proxy, see [Built-in proxy quickstart]({{<proxy_base_path>}}quickstart).
9+
10+
## Overview {#overview}
11+
12+
Starting with version 1.6.23, Memcached includes a built-in proxy. You can run a Memcached server that acts as a front-end proxy to any number of back-end Memcached servers. These backends can run anywhere that the proxy can connect to using TCP/IP.
13+
14+
With a proxied Memcached setup, clients always connect to the Memcached proxy, instead of connecting directly to the back-end Memcached servers. The proxy forwards cache requests to pools of backends that you define. This setup can provide improved load balancing and fault tolerance to applications with high-demand caching needs.
15+
16+
## Key concepts {#concepts}
17+
18+
<dl>
19+
<dt>Proxy</dt>
20+
<dd>
21+
The Memcached <em>built-in proxy</em> runs as a front-end interface between client applications that need to read or write cached data, and the underlying back-end Memcached servers. The proxy supports <a href="/protocols/basic">the Memcached basic command protocol</a>. This lets clients connect to a Memcached proxy and interact with it using the same techniques that they use with an ordinary Memcached server.
22+
</dd>
23+
24+
<dt>Backend</dt>
25+
<dd>
26+
In the context of a proxied Memcached setup, a <em>backend</em> is a Memcached server that the proxy uses as an underlying cache store.
27+
28+
Setting up a backend doesn't require any special Memcached configuration. A backend is just an ordinary Memcached server that the proxy can connect to using TCP/IP.
29+
</dd>
30+
31+
<dt>Pool</dt>
32+
<dd>
33+
The proxy configuration organizes backends into one or more named groups called <em>pools</em>. Each pool contains one or more backends.
34+
35+
When the proxy receives a request to read or write cache data under a given key, the proxy uses various criteria to select one of its pools. It then forwards the cache request to a backend within that pool. For more information, see [Routing criteria](#routing).
36+
</dd>
37+
38+
<dt>Set</dt>
39+
<dd>
40+
More complex routing topologies might require another layer of grouping. You can further group pools into <em>sets</em>.
41+
42+
Sets can be useful for gathering pools into named <em>zones</em>, in order to set up failover priorities. For more information, see [Prioritize a route using local zones]({{<proxy_base_path>}}configure#zones).
43+
</dd>
44+
45+
<dt>Route</dt>
46+
<dd>
47+
The core elements of the proxy's configuration are pools and <em>routes</em>. Each route defines the following:
48+
49+
* A mapping between some contextual criteria around a received Memcached command and a pool of backends. For example, a route might map all keys whose key has the prefix `cust/` to the pool named `customer_pool`.
50+
51+
* A _route handler_, one of several defined by the route library. Each router handler tells the proxy which backend pools to forward a request to, and in what style or order. For example, given a list of backend pools, different route handlers can forward requests to those pools in parallel, or serially, and optionally randomize the list first.
52+
53+
For more information on defining pools and routes, see [Configure the built-in proxy]({{<proxy_base_path>}}configure)
54+
</dd>
55+
56+
<dt>Route library</dt>
57+
<dd>
58+
The Memcached project includes a <em>route library</em> file that you can download separately. The route library is a Lua source file that defines basic routing functions for defining pools, routes, and route handlers.
59+
60+
The route library exists as a Lua source file on the file system used by your proxy. In typical proxy use, you let the proxy load the route library file as-is, with no changes. In more complex use cases, you can freely modify or replace this library file using your own Lua code.
61+
</dd>
62+
</dl>
63+
64+
## Routing criteria {#routing}
65+
66+
The Memcached proxy uses various criteria to decide which of its known backends that it should forward data storage or retrieval requests to. These criteria can include the following:
67+
68+
* A prefix on the requested key name. For example, you can configure the router to send requests for the key `data/12345` to one pool of back-end servers, and requests for the key `cust/12345` to a different pool. Requests with no prefix or an unrecognized prefix can be handled by a designated default pool.
69+
70+
You can configure the proxy to recognize various shapes of prefixes, with different lead-in or separator characters between the prefix and the main key name. For example, if your application's cache keys look more like `--cust//12345` than `cust/12345`, you can still configure the proxy to recognize the former case as having the prefix `cust`.
71+
72+
* The TCP port that the client has connected to the proxy. For example, you can configure the proxy to listen on TCP ports `11211` and `11212`, and route requests differently depending upon the connected port.
73+
74+
* Specific route handlers invoked by the configuration file. For example, say that you configure the proxy to call the route handler `route_allsync{}`, with a list of three pools, every time it receives a cache request for a key with the prefix `cust`. In that case, a request to store data under `cust/12345-abcd` will be sent in parallel to all three pools that you named in the `route_allsync{}` call in the proxy configuration file, in the definition of the `cust` route.
75+
76+
For more information about configuring proxy pools and routes, see [Configure the built-in proxy]({{<proxy_base_path>}}configure).
77+
78+
## Proxy installation {#installation}
79+
80+
Memcached lets you use its built-in proxy features only if you build the Memcached binary with those features enabled. Proxy features aren't enabled by default. For this reason, using the proxy requires you to compile Memcached from source, rather than installing it from a package manager.
81+
82+
For more information, see [Install the built-in proxy]({{<proxy_base_path>}}install).
83+
84+
## Proxy configuration {#configuration}
85+
86+
If you use the standard route library with the Memcached built-in proxy, then you need to create an additional configuration file that defines the pools available to your proxy, and how it should map requests to pools depending upon various criteria. This configuration file also uses Lua syntax, but in most cases you can treat it as a limited vocabulary specific to Memcached proxy configuration. For more information, see [Configure the built-in proxy]({{<proxy_base_path>}}configure).
87+
88+
In advanced use cases, you can modify the route library file, or even replace it entirely using your own Lua code. This requires a deeper knowledge of the proxy configuration API. For more information, [Configuration API]({{<legacy_proxy_base_path>}}#configuration_api).
89+
90+
## Proxy deployment examples
91+
92+
For a selection of example proxy use cases, see [Usage examples]({{<legacy_proxy_base_path>}}examples).
93+
94+
For a example proxy configuration files, see [Example configuration files]({{<proxy_base_path>}}configure#examples).

0 commit comments

Comments
 (0)