{"id":15213002,"url":"https://github.com/blacksmith-community/redis-forge-boshrelease","last_synced_at":"2025-10-30T23:25:36.094Z","repository":{"id":42704010,"uuid":"59781068","full_name":"blacksmith-community/redis-forge-boshrelease","owner":"blacksmith-community","description":"A Blacksmith Forge for deploying dedicated standalone and clustered Redis instances","archived":false,"fork":false,"pushed_at":"2025-02-06T20:34:55.000Z","size":332,"stargazers_count":2,"open_issues_count":1,"forks_count":11,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-06-11T02:05:28.927Z","etag":null,"topics":["bosh","forge","redis"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blacksmith-community.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-05-26T20:25:37.000Z","updated_at":"2025-02-06T20:34:34.000Z","dependencies_parsed_at":"2024-06-20T13:01:02.321Z","dependency_job_id":"2a0dd059-4d83-48fd-8e78-b6b33e14b2ad","html_url":"https://github.com/blacksmith-community/redis-forge-boshrelease","commit_stats":null,"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"purl":"pkg:github/blacksmith-community/redis-forge-boshrelease","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacksmith-community%2Fredis-forge-boshrelease","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacksmith-community%2Fredis-forge-boshrelease/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacksmith-community%2Fredis-forge-boshrelease/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacksmith-community%2Fredis-forge-boshrelease/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blacksmith-community","download_url":"https://codeload.github.com/blacksmith-community/redis-forge-boshrelease/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blacksmith-community%2Fredis-forge-boshrelease/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260689039,"owners_count":23046996,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bosh","forge","redis"],"created_at":"2024-09-28T09:08:34.652Z","updated_at":"2025-10-30T23:25:36.011Z","avatar_url":"https://github.com/blacksmith-community.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blacksmith Redis Forge\n\nThis Blacksmith Forge teaches a [Blacksmith Broker][broker] how to\ndeploy standalone and clustered [Redis][redis] service\ndeployments, which are useful for caching, persistent key-value\nstore, and distributed lock management.\n\n## Deploying\n\nTo deploy this forge, you will need to add it to your existing\nBlacksmith Broker manifest deployment, co-locating the\n`redis-blacksmith-plans` job on the Blacksmith instance group.\n\nHere's an example to get you started (clipped for brevity):\n\n```yaml\nreleases:\n  - name:    redis-forge\n    version: latest\n\ninstance_groups:\n  - name: blacksmith\n    jobs:\n      - name:    redis-blacksmith-plans\n        release: redis-forge\n        properties:\n          plans:\n            # your plans here\n            # (see below)\n```\n\nThe Redis Forge deploys redis by using jobs that are found\n_inside_ the `redis-forge` BOSH release, which means that your\nBlacksmith BOSH director also needs that release.  Blacksmith is\nable to upload that release for you, if you want.\n\nFor the Spruce users out there:\n\n```\n---\ninstance_groups:\n  - name: blacksmith\n    jobs:\n      - name: blacksmith\n        properties:\n          releases:\n            - (( append ))\n            - (( grab releases.redis-forge ))\n```\n\nFinally, you'll need to define plans for Blacksmith to deploy.\nThe following sections discuss those ad nauseum.\n\n## Standalone Topology\n\nThe `standalone` topology is as straightforward as they come: a\nsinge dedicated VM that runs redis bound on all interfaces, to\nport 6379. If TLS is enabled it will bind to port 16379.\n\nHere's a diagram to clear things up:\n\n![Standalone Topology Diagram](docs/diag/topology-standalone.png)\n\n### Configuration Options\n\n- *vm_type* - The name of a BOSH `vm_type` from your cloud-config.\n  You can use this to size your Redis appropriate to your workload\n  requirements, in terms of RAM and CPU.  Increasing the disk size\n  via the VM type is not going to net you much of a gain (see\n  the `disk_size`, `disk_type`, and `persist` options instead.\n\n- *azs* - An array of BOSH availability zone names (per cloud-config),\n  for your standalone node placement. Deployed VMs will be\n  randomly distributed across these AZs. By default, all nodes will\n  be put in `z1`.\n\n- *network* - The name of the network to deply these instances to.\n  This network should be defined in your cloud-config, and should\n  be large enough to handle your anticipated service footprint.\n  It does not need any static IP addresses.\n\n  By default, VMs will be deployed into a network named\n  `redis-service`.\n\n- *persist* - Whether or not the data stored in this Redis\n  instance should be written to disk or not.  If you are just\n  implementing a cache service using Redis, you don't need to\n  specify this (or `disk_size`) -- by default this topology is\n  diskless.\n\n  Persistent Redis instances use the append-only format (AOF),\n  storing the file in `/var/vcap/store/standalone/redis.aof`.  The\n  AOF file is fsync'd once every second to balance safety with\n  performance.\n\n- *disk_size* - If you specify `persist` to get a durable key-value\n  store, you can also specify this configuration value to change\n  the size of the persistent disk.  By default, you get a 1G disk.\n\n- *disk_type* - If you specify `persist` to get a durable key-value\n  store, you can also specify this configuration value to change\n  the persistent disk type. If both _disk_ and _disk_type_ are\n  defined, the _disk_ configuration value will be ignored.\n\n### Example Configuration\n\nA single standalone plan, persistent, with 4G of disk:\n\n```\ninstance_groups:\n  - name: blacksmith\n    jobs:\n      - name:    redis-blacksmith-plans\n        release: redis-forge\n        properties:\n          plans:\n            single-4g:\n              type:      standalone\n              persist:   true\n              disk_size: 4_096\n```\n\nHere's a configuration that provides two different sizes of\npersistent standalone, as well as a large (per cloud-config)\nnon-persistent cache service:\n\n```\ninstance_groups:\n  - name: blacksmith\n    jobs:\n      - name:    redis-blacksmith-plans\n        release: redis-forge\n        properties:\n          plans:\n            small:\n              type:     standalone\n              persist:  true\n              disk_size: 4_096\n\n            large:\n              type:      standalone\n              persist:   true\n              disk_size: 16_384\n\n            cache:\n              type:    standalone\n```\n\n## Clustered Topology\n\nThe `cluster` topology shards the Redis key hash space across _M_\nmasters, each with _R_ replicas.  It provides fault tolerance,\nwith optional (but highly encouraged) striping across BOSH\navailability zones.\n\nHere's a diagram, showing a _M=2, R=2_ configuration:\n\n![Cluster Topology Diagram](docs/diag/topology-cluster.png)\n\nWe can refer to this as a _2x2_ setup, 2 masters, with 2 replicas\neach, for a total of 6 VMs.  The first master (in purple) will\nhandle hash slots 0-8191, and the second master (in blue) takes\nslots 8192-16382.  Each pair of replicas contain a complete copy\nof the hash slots its master is responsible for.\n\nIn the event of failure of a master, one of its replicas will\npromote to a master, ensuring consistent cluster operations.\n\nClustered nodes do not persist their data to disk; instead they\nrely on replication to ensure durability of the data.\n\n### Configuration Options\n\n- *vm_type* - The name of a BOSH `vm_type` from your cloud-config.\n  You can use this to size your Redis appropriate to your workload\n  requirements, in terms of RAM and CPU.\n\n- *azs* - A list of BOSH availability zone names (per\n  cloud-config), across which to stripe the nodes.  By default,\n  nodes will be put in `z1` and `z2`.\n\n- *network* - The name of the network to deply these instances to.\n  This network should be defined in your cloud-config, and should\n  be large enough to handle your anticipated service footprint.\n  It does not need any static IP addresses.\n\n  By default, VMs will be deployed into a network named\n  `redis-service`.\n\n- *masters* - How many Redis Master instances to spin.  Must be at\n  least 1.  There is no default.\n\n- *replicas* - How many Redis Replica instances to provision for\n  each Redis Master.  Must be at least 1, which is the default.\n  Normally, you only need 1-3 replicas, depending on your\n  tolerance for data loss.\n\n## Example Configuration\n\nHere's the configuration for the 6-VM 2x2 cluster pictured in the\ntopology digram above:\n\n```\ninstance_groups:\n  - name: blacksmith\n    jobs:\n      - name:    redis-blacksmith-plans\n        release: redis-forge\n        properties:\n          plans:\n            clustered:\n              type:     cluster\n              masters:  2\n              replicas: 2\n```\n\nHere, we provide two different clustered configurations, one with\nwide sharding but shallow replication (4x1), and another 3-node\nminimal cluster on very large (per cloud-config) VMs.\n\n```\ninstance_groups:\n  - name: blacksmith\n    jobs:\n      - name:    redis-blacksmith-plans\n        release: redis-forge\n        properties:\n          plans:\n            clustered-4x1:\n              type:     cluster\n              masters:  4\n              replicas: 1\n\n            minimal:\n              type:     cluster\n              vm_type:  very-large\n              masters:  1\n              replicas: 2\n```\n## Redis Hard Coded Redis Configuration Parameters\n\nFor security reasons the following Redis commands have been disabled in all plan types. \n1. DEBUG\n1. CONFIG\n1. SHUTDOWN\n1. SYNC\n1. SLAVEOF\n\n## Redis Configuration Plan Parameters\n\nThese Redis configuration parameters can be used when plans are created during forge deployment. \nSome of these parameters may dependent on other parameters or plan model properties.\n\n| Parameter | Description | Default | Notes |\n| --------- | ----------- | ------- | ----- |\n| auth.password | The password required of clients wishing to use this Redis instance. | | |\n| persistent | Whether or not the Redis dataset should persist to disk (via AOF semantics) | true | |\n| lua_scripting_enabled | Whether or not to allow lua scripting. | true | |\n| client_connections | Set the max number of connected clients at the same time | 10000 | |\n| client_timeout | Close the connection after a client is idle for N seconds | 0 | 0 = disable |\n| client_tcpkeepalive | If non-zero, use SO_KEEPALIVE to send TCP ACKs to clients in absence of communication | 300 | |\n| redis_maxmemory | Set a memory usage limit to the specified amount of bytes. | 0 | 0 = VM limit |\n|  redis_maxmemory-policy | Sets the behavior Redis follows when maxmemory is reached. | allkeys-lru, |allkeys-lru, noeviction,\u003cbr/\u003e volatile-lru, allkeys-random,\u003cbr/\u003e volatile-ttl, volatile-lfu,\u003cbr/\u003e allkeys-lfu |\n| redis_notify-keyspace-events | Sets the keyspace notifications for events that affect the Redis data set | \"\" | |\n| redis_slowlog-log-slower-than | Sets the threshhold execution time (seconds).  Commands that exceed this execution time are added to the slowlog.| 10000 | |\n| redis_slowlog-max-len | Sets the length (count) of the slowlog queue. | 128 | |\n|  redis_no-appendfsync-on-rewrite | If you have latency problems turn this to true. Otherwise leave it as false | false | This parameter has significance only if the *persistent* parameter is set true. |\n|  redis_auto-aof-rewrite-percentage | Modify the percentage for auto append on rewrite. | 100 | This parameter has significance only if the *persistent* parameter is set true. |\n|  redis_auto-aof-rewrite-min-size: | Modify the minimum file size  for auto append on rewrite. | 64mb | This parameter has significance only if the *persistent* parameter is set true. |\n| exporter | If set to true, a Prometheus redis_exporter will be colocated on the Redis nodes | false |\n\n   Memory units may be specified when specifying bytes.  \n   1k =\u003e 1000 bytes  \n   1kb =\u003e 1024 bytes  \n   1m =\u003e 1000000 bytes  \n   1mb =\u003e 1024\\*1024 bytes  \n   1g =\u003e 1000000000 bytes  \n   1gb =\u003e 1024\\*1024\\*1024 bytes  \n   units are case insensitive so 1GB 1Gb 1gB are all the same.\n\n## CF Create Service Configuration Parameters\nApp developers can customize the following parameters. See the [Redis documentation](https://redis.io/topics/config) for more detail. In particular, look at the self documented redis.conf file for your deployed Redis version.\n\n|                Property                 | Default | Options | Description |\n|-----------------------------|---------|---------| ----------- |\n| **maxmemory-policy** | *allkeys-lru*\t| allkeys-lru, noeviction,\u003cbr/\u003e volatile-lru,\u003cbr/\u003e allkeys-random,\u003cbr/\u003e volatile-ttl,\u003cbr/\u003e volatile-lfu,\u003cbr/\u003e allkeys-lfu | Sets the behavior Redis follows when *maxmemory* is reached. Please see the [redis.conf][2] for their brief definitions.|\n| **notify-keyspace-events** | “” | Set a combination of the following characters\u003cbr/\u003e (e.g., *“Elg”*):\u003cbr/\u003e K, E, g, $, l, s, h, z, x, e, A | Sets the keyspace notifications for events that affect the Redis data set. Please see the [redis.conf][2] file for their succinct definitions. |\n| **slowlog-log-slower-than** | 10000 | 0-20000 | Sets the threshhold execution time (seconds). Commands that exceed this execution time are added to the slowlog. |\n| **slowlog-max-len** | 128 | 1-2024 | Sets the length (count) of the slowlog queue.|\n\n## Forge Maintainer Notes\n### Upgrading Redis Releases\n1. Remember to use the s3 folder 'redis' when adding a new Redis tarbal.  \n   example: `bosh add-blob ~/Downloads/redis-5.0.12.tar.gz redis/redis-5.0.12.tar.gz`\n1. Remember to remove the previous redis blob before creating a final release through the pipeline  \n   example: `bosh remove-blob redis/redis-5.0.10.tar.gz`\n1. Create a release tarball for testing purposes.  You will need the --version the first time you create a\ndevelopment release  \n   example `bosh create-release --name=redis-forge --version=0.4.7+dev.1 --tarball=/tmp/redis-forge.tar.gz --force`\n1. Get the private.yml for the S3 bucket from someone in the know.  The file goes into the 'config' directory.\n   Now you can use bosh to upload the blob to S3.\n1. Add the 'release_notes.md' to the ci directory.\n\n## Contributing\n\nIf you find a bug, please raise a [Github Issue][1] first,\nbefore submitting a PR.\n\n\n[1]: https://github.com/blacksmith-community/redis-forge-boshrelease/issues\n[2]: https://raw.githubusercontent.com/redis/redis/5.0/redis.conf\n[broker]: https://github.com/cloudfoundry-community/blacksmith\n[redis]:  https://redis.io\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblacksmith-community%2Fredis-forge-boshrelease","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblacksmith-community%2Fredis-forge-boshrelease","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblacksmith-community%2Fredis-forge-boshrelease/lists"}