Memcached Settings in the Boxfile

Last Updated October 2014

The Boxfile is a yaml config file that allows you to custom-configure your app's environment. The following configuration options available in the Boxfile allow you to tailor-fit the build of your Memcached service specific to your needs. After reading this, you should understand how to:

  • How to customize your Memcached build
  • Bask in the awesomeness of Memcached and Pagoda Box

Overview of Memcached Boxfile Settings YAML

  cache1:
    type: memcached
    version: 1.4
    stability: production
    topology: single
    memcached_return_error_on_memory_exhausted: false
    memcached_max_connections: 1024
    memcached_chunk_size_growth_factor: 1.25
    memcached_minimum_allocated_space: 48
    memcached_maximum_requests_per_event: 20
    memcached_disable_cas: false
    memcached_max_backlog: 1024
    memcached_binding_protocol: 'auto'
/Boxfile

Memcached Configuration Options

Memcached Type & Version

When configuring a Memcached service in your Boxfile, you must define the type of the service as memcached. You can also specify the version of Memcached to load into your cache service. The following version(s) are available:

  • 1.4

The specific patch level is determined by the "stability" config.

Memcached Version Defined on Create

Due to version compatibility constraints, memcached versions cannot be changed after the service is created. To use a different version, you'll have to create a new Memcached service.

memcached type & version YAML

  # default setting
  cache1:
    type: memcached
    version: 1.4
/Boxfile
Topology

Topology defines the service's architecture and in what ways it can scale. Memcached only supports the "single" topology. More information can be found in the Service Topologies doc.

topology YAML

  #default setting
  cache1:
    type: memcached
    topology: single
/Boxfile
Return Error on Memory Exhausted

This allows you to have memcached return an error when memory is exhausted rather than removing items.

memcached_return_error_on_memory_exhausted YAML

  #default setting
  cache1:
    memcached_return_error_on_memory_exhausted: false
/Boxfile
Max Connections

Sets the limit for simultaneous connections.

memcached_max_connections YAML

  #default setting
  cache1:
    memcached_max_connections: 1024
/Boxfile
Chunk Size Growth Factor

Specifies the chunk size growth factor.

memcached_chunk_size_growth_factor YAML

  #default setting
  cache1:
    memcached_chunk_size_growth_factor: 1.25
/Boxfile
Minimum Allocated Space

Sets the minimum space allocated for key+value+flags.

memcached_minimum_allocated_space YAML

  #default setting
  cache1:
    memcached_minimum_allocated_space: 48
/Boxfile
Maximum Requests Per Event

Sets the maximum number of requests per event and limits the number of requests processed for a given connection to prevent starvation.

memcached_maximum_requests_per_event YAML

  #default setting
  cache1:
    memcached_maximum_requests_per_event: 20
/Boxfile
Disable CAS

Allows you to disable the use of CAS.

memcached_disable_cas YAML

  #default setting
  cache1:
    memcached_disable_cas: false
/Boxfile
Max Backlog

Sets the backlog queue limit.

memcached_max_backlog YAML

  #default setting
  cache1:
    memcached_max_backlog: 1024
/Boxfile
Binding Protocol

Allows you to set the binding protocol. The following are available:

  • auto

  • ascii

  • binary

memcached_binding_protocol YAML

  #default setting
  cache1:
    memcached_binding_protocol: 'auto'
/Boxfile

Boxfile Modifications Only Take Affect After a New Build

Whenever changes are made to a Memcached service's configuration in the Boxfile, those changes will not apply until the service is rebuilt. By default, Memcached services are not rebuilt on deploy. However, there are three options for rebuilding your service:

Enable Rebuild on Deploy

In your app dashboard, under Dev Config > Code Deployment, you can enable the option to have data services rebuild on deploy whenever changes to the service's Boxfile config are detected.

Rebuilding data services on deploy will increase deploy times, but only when changes to the service's config are detected.

Scale

Any time you scale a Memcached service, a new instance is provisioned using the modified Boxfile, requests are routed to the new instance and the old instance is decommissioned.

Repair

In your dashboard, click on your Memcached service to expand it's options. Each data service has a "Repair" option.

"Repairing" your service will provision a new instance based on the settings in your Boxfile, then reroute requests away from the old instance to the new.

Data is Flushed During a Rebuild

Memcached is an in-memory store. Data is only stored in RAM and never persists to disk. Whenever a Memcached service is rebuilt, all memory is flushed and data is cleared.

If you have any questions, suggestions, or corrections, let us know.