Consistent Hash

Learn how to use the Consistent Hash module.

Deploy

Follow the steps below to deploy the Consistent Hash module to your environment:

1. Go to the Git config of the environment you want to deploy the Consistent Hash module in.

2. In the top of the page, copy the URL next to Clone with HTTPS.

3. Open a terminal and change the current working directory to the location where you want the cloned environment repository.

4. Clone the environment repository to your local computer. Type git clone followed by the copied URL and then press Enter:

   git clone <copied_url>

5. In the root directory of the environment repository, create a new directory for the module to reside in, such as consistenthash.

6. In the new directory, create a new file named server.conf with the following:

   consistenthash/server.conf

   # Use HTTP 1.1 to allow for keepalive connections
   proxy_http_version 1.1;
   
   # Pass the request host header through to the upstream
   proxy_set_header Host $host;
   
   # Allow http connections to be kept open
   proxy_set_header Connection '';
   
   # Pass the origin server response header through rather than allowing nginx to set it to "nginx"
   proxy_pass_header Server;
   
   location / {
       proxy_pass "http://consistenthash_uri_next_hop_upstream";
   }

   note

   This default config implements the consistent hash based on the URI path of the HTTP request in the proxy_pass directive, but you can use different values for other forms of consistent hashing:

   • consistenthash_uri_next_hop_upstream will implement a consistent hash based on the full original request URI (with arguments).
   • consistenthash_uri_path_next_hop_upstream will implement a consistent hash based on the request URI path with the query string removed.
   • consistenthash_client_ip_next_hop_upstream will implement a consistent hash based on the originating client IP address.
   • next_hop_upstream will not implement a consistent hash.

7. In the environment's section.config.json file, add the following module object to the proxychain array, replacing <module_directory_name> with the value used in step five and <module_image> with the module image you want to deploy:

   section.config.json

   ...
   "proxychain": [
       ...
       {
           "name": "<module_directory_name>",
           "image": "<module_image>"
       },
       ...
   ],
   ...

   section.config.json

   ...
   "proxychain": [
       ...
       {
           "name": "consistenthash",
           "image": "consistenthash:1.1.1"
       },
       ...
   ],
   ...

   note

   The proxychain array order determines how the modules are layered in the environment's proxy stack. The first array item is closest to the client and the last is closest to the origin. You will typically add this in front, or above, the module you want to load balance traffic to based on the consistent hash.

   section.config.json

   ...
   "proxychain": [
       ...
       {
           "name": "consistenthash",
           "image": "consistenthash:1.1.1"
       },
       {
           "name": "varnish",
           "image": "varnish:7.0.2"
       },
       ...
   ],
   ...

8. Stage, commit, and push the changes to the environment's remote repository:

   git add .
   git commit -m "Add the Consistent Hash module"
   git push

Manage

Manage the Consistent Hash module through the Git config.

tip

Check out the related Consistent Hash reference to get started with customizing your Consistent Hash module.

note

Submit a support request by clicking the Support link in the left sidebar if you need help managing this module.

Delete

Follow the steps below to delete the Consistent Hash module from your environment:

1. Go to the Git config of the environment you want to delete the Consistent Hash module from.

2. In the top of the page, copy the URL next to Clone with HTTPS.

3. Open a terminal and change the current working directory to the location where you want the cloned environment repository.

4. Clone the environment repository to your local computer. Type git clone followed by the copied URL and then press Enter:

   git clone <copied_url>

5. In the root directory of the environment repository, delete the Consistent Hash module directory (typically named consistenthash).

   note

   Skip this step to disable the module instead of deleting it.

6. In the environment's section.config.json file, delete the module object from the proxychain array, which will look like the following:

   section.config.json

   ...
   "proxychain": [
       ...
       {
           "name": "<module_directory_name>",
           "image": "<module_image>"
       },
       ...
   ],
   ...

   section.config.json

   ...
   "proxychain": [
       ...
       {
           "name": "consistenthash",
           "image": "consistenthash:1.1.1"
       },
       ...
   ],
   ...

7. Stage, commit, and push the changes to the environment's remote repository:

   git add .
   git commit -m "Delete the Consistent Hash module"
   git push