diff --git a/jetty-documentation/src/main/asciidoc/administration/sessions/session-clustering-gcloud-datastore.adoc b/jetty-documentation/src/main/asciidoc/administration/sessions/session-clustering-gcloud-datastore.adoc
index 357db9a5d7f..9d9ccd40ab1 100644
--- a/jetty-documentation/src/main/asciidoc/administration/sessions/session-clustering-gcloud-datastore.adoc
+++ b/jetty-documentation/src/main/asciidoc/administration/sessions/session-clustering-gcloud-datastore.adoc
@@ -29,8 +29,8 @@ For those load balancers that examine the session ID, the Jetty persistent sessi
There are two components to session management in Jetty: a session ID manager and a session manager.
-* The session ID manager ensures that session IDs are unique across all webapps hosted on a Jetty instance, and thus there can only be one session ID manager per Jetty instance.
-* The session manager handles the session lifecycle (create/update/invalidate/expire) on behalf of a web application, so there is one session manager per web application instance.
+- The session ID manager ensures that session IDs are unique across all webapps hosted on a Jetty instance, and thus there can only be one session ID manager per Jetty instance.
+- The session manager handles the session lifecycle (create/update/invalidate/expire) on behalf of a web application, so there is one session manager per web application instance.
These managers also cooperate and collaborate with the `org.eclipse.jetty.server.session.SessionHandler` to enable cross-context dispatch.
@@ -63,43 +63,40 @@ jetty.gcloudSession.workerName::
This value will also be used by the sticky load balancer to identify the node.
Don't forget to change the value of this property on *each* node on which you enable gcloud datastore session clustering.
-Which other properties you need to set depends on the execution environment:
-====== Running Within Google Infrastructure
+===== Configuring GCloud Datastore
-When you upload your webapp to run in Compute Engine, you do not need to set any other properties for Jetty.
-If you follow the instructions in the https://cloud.google.com/datastore/docs/activate[Cloud Datastore documentation], all authorizations...etc. will be provided by the runtime environment.
+Things that you will need:
-====== Running Externally to Google Infrastructure
+- a local installation of the https://cloud.google.com/sdk/[Google Cloud SDK]
+- a project id referred to below as [YOUR PROJECT ID]
+- to have https://cloud.google.com/datastore/docs/activate[enabled your project id] to use GCloud Datastore
-When your app is executing outside of Google, you can either contact a remote Cloud Datastore instance, or a https://cloud.google.com/datastore/docs/tools/devserver[local test dev server] provided by the sdk.
-The choice determines which properties you need to set:
+====== Using GCloud Datastore from Compute/AppEngine
-Contacting an sdk dev server for testing:::
- In this case, you need to set up either some _System_ properties or _environment variables_ - *NOT* Jetty properties!
-
- DATASTORE_DATASET;;
- This must be the name of your (test) project.
- DATASTORE_HOST;;
- This is the url of the dev server as described https://cloud.google.com/datastore/docs/tools/devserver#setting_environment_variables[in Google's documentation].
- An example may be "http://localhost:9999".
-
-Contacting a remote Cloud Datastore:::
- In this case, you need to provide all of the authentication and authorization information explicitly via jetty properties in the ini file:
-
- jetty.gcloudSession.projectId;;
- This is the name of your project.
- jetty.gcloudSession.p12File;;
- This is the location of the p12 key file that is associated with your project.
- jetty.gcloudSession.serviceAccount;;
- This is the email address that defines your service account for the Cloud Datastore.
- jetty.gcloudSession.password;;
- This is the password associated with the p12 key file.
+If you are running your webapp from within ComputeEngine or AppEngine, you do not need to do anything else in order to configure your GCloud setup. All necessary information will be inferred from the environment by the infrastrcture.
+
+====== Using GCloud Datastore from an external server
+
+If you are running your webapp externally to Google infrastructure, you can still interact with the remote GCloud Datastore service.
+
+Execute the following commands:
+
+- gcloud config set project [YOUR PROJECT ID].
+- gcloud auth login
+
+This will populate your environment with the necessary authentication information to allow you to contact the remote GCloud Datastore instance.
+
+====== Using GCloud Datastore local development server
+
+If you would like to locally test your application, you can use the Google Cloud SDK's https://cloud.google.com/datastore/docs/tools/datastore-emulator[GCloud Datastore emulator].
+
+Follow the instructions on the https://cloud.google.com/datastore/docs/tools/datastore-emulator[GCloud Datastore emulator page] to set up your environment.
===== Configuring the GCloudSessionManager
-As mentioned elsewhere, there should be one `GCloudSessionManager` per context (e.g. webapp).
-It will need to reference the single `GCloudSessionIdManager` from which it derives the Cloud Datastore configuration information.
+As mentioned elsewhere, there must be one `SessionManager` per context (e.g. webapp).
+Each SessionManager needs to reference the single `GCloudSessionIdManager`.
The way you configure a `GCloudSessionManager` depends on whether you're configuring from a context xml file, a `jetty-web.xml` file or code.
The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.server.Server` instance.
@@ -166,3 +163,112 @@ maxQueryResults::
For efficiency it is important to limit the size of the result.
The default is 100.
If 0 or negative numbers are set, the default is used instead.
+
+===== The gcloud-memcached-sessions module
+
+As an optimization, you can have Jetty store your session data into GCloud Datastore but also cache it into memcached. This serves two purposes: faster read-accesses and also better support for non-sticky load balancers (although using a non-sticky load balancer is highly undesirable and not recommended).
+
+You will need to enable the `gcloud-memcached-sessions` link:#startup-modules[module] for your link:#creating-jetty-base[base] using the `--add-to-start` or `--add-to-startd` argument to the link:#startup-overview[start.jar].
+
+If you already enabled the gcloud-sessions module, that's fine as the gcloud-memcached-sessions module depends on it anyway.
+
+Jetty uses the https://github.com/killme2008/xmemcached[Xmemcached] java client.
+It depends on http://www.slf4j.org/[slf4j], so you will need to choose an http://www.slf4j.org/[slf4j logging implementation]. You can copy the chosen implementation jars into your $jetty.base/lib/ext directory.
+
+====== Configuring the GCloudSessionIdManager
+
+The instructions here are exactly the same as for the gcloud-sessions module.
+
+====== Configuring GCloud Datastore
+
+The instructions here are exactly the same as for the gcloud-sessions module.
+
+====== Configuring Memcached
+
+If you have installed memcached on a host and port other than the defaults of `localhost` and `11211`, then you will need to take note of these values and supply them to the configuration of the `GCloudMemcachedSessionManager`.
+
+====== Configuring the GCloudMemcachedSessionManager
+
+*Note that* you will be configuring a `GCloudMemcachedSessionManager` 'instead of' a `GCloudSessionManager`.
+
+As usual, there must be only one per context (e.g. webapp).
+Each GCloudMemcachedSessionManager needs to reference the single `GCloudSessionIdManager`.
+
+
+The way you configure a `GCloudMemcachedSessionManager` depends on whether you're configuring from a context xml file, a `jetty-web.xml` file or code.
+The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.server.Server` instance.
+
+From a context xml file, you reference the Server instance as a Ref:
+
+[source, xml, subs="{sub-order}"]
+----
+
+ [
+
+ ]
+
+
+
+
+
+
+
+