{"id":40656933,"url":"https://github.com/kai-niemi/pestcontrol","last_synced_at":"2026-01-21T08:54:23.102Z","repository":{"id":332914787,"uuid":"1103004656","full_name":"kai-niemi/pestcontrol","owner":"kai-niemi","description":"A cluster manager and chaos testing tool for CockroachDB","archived":false,"fork":false,"pushed_at":"2026-01-16T07:35:31.000Z","size":711,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-16T22:40:48.052Z","etag":null,"topics":["chaos-engineering","cockroachdb","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Java","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/kai-niemi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-24T10:03:53.000Z","updated_at":"2025-11-24T10:05:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kai-niemi/pestcontrol","commit_stats":null,"previous_names":["kai-niemi/pestcontrol"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kai-niemi/pestcontrol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kai-niemi%2Fpestcontrol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kai-niemi%2Fpestcontrol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kai-niemi%2Fpestcontrol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kai-niemi%2Fpestcontrol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kai-niemi","download_url":"https://codeload.github.com/kai-niemi/pestcontrol/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kai-niemi%2Fpestcontrol/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28630935,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["chaos-engineering","cockroachdb","spring-boot"],"created_at":"2026-01-21T08:54:22.298Z","updated_at":"2026-01-21T08:54:23.095Z","avatar_url":"https://github.com/kai-niemi.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp\u003e\t\n\t\u003ca href=\"https://github.com/kai-niemi/pestcontrol/actions/workflows/maven.yml\"\u003e\u003cimg src=\"https://github.com/kai-niemi/pestcontrol/actions/workflows/maven.yml/badge.svg?branch=main\" alt=\"\"\u003e\n\u003c/p\u003e\n\n\u003c!-- TOC --\u003e\n* [About](#about)\n  * [Main features](#main-features)\n  * [Compatibility](#compatibility)\n  * [How it works](#how-it-works)\n* [Terms of Use](#terms-of-use)\n* [Prerequisites](#prerequisites)\n  * [Install the JDK](#install-the-jdk)\n  * [Install Toxiproxy (optional)](#install-toxiproxy-optional)\n  * [Install Haproxy (optional)](#install-haproxy-optional)\n* [Building](#building)\n  * [Clone the project](#clone-the-project)\n  * [Build the artifacts](#build-the-artifacts)\n* [Running](#running)\n* [Configuration](#configuration)\n* [Usage Tutorials](#usage-tutorials)\n  * [Local 3-node self-hosted cluster (insecure)](#local-3-node-self-hosted-cluster-insecure)\n  * [Local 3-node self-hosted cluster (secure)](#local-3-node-self-hosted-cluster-secure)\n  * [Remote 3-node self-hosted cluster (insecure)](#remote-3-node-self-hosted-cluster-insecure)\n  * [Remarks](#remarks)\n\u003c!-- TOC --\u003e\n\n# About\n\n\u003cimg  align=\"left\" src=\"docs/logo.png\" alt=\"\" width=\"64\"/\u003e \n\n[Pest Control](https://github.com/kai-niemi/pestcontrol) is a tool for managing \nand chaos testing CockroachDB clusters. It provides a command-line shell for \ncontrolling and disrupting cluster deployments and a web interface for visualizing \nnode failure and recovery, including the impact on synthetic application workloads. \n\n## Main features\n\n- Simple local and remote self-hosted cluster management.\n- Network chaos testing via [Toxiproxy](https://github.com/Shopify/toxiproxy) for self-hosted clusters.\n- Disruption API controls for Cockroach Cloud clusters.\n- A web UI for self-hosted clusters to:\n  - View cluster topology and status.\n  - Run synthetic workloads to visualize application impact during adverse events.\n  - Manage toxiproxy proxies and toxics.\n\n## Compatibility\n\nSupported platforms and versions:\n\n- CockroachDB Self-Hosted v22.2+\n  - Secure or insecure mode\n  - Local or remote deployments \n- CockroachDB Cloud v22.2+\n  - Disruption API requires a feature flag enabled for the organization\n- MacOS (main platform)\n- Linux\n\n## How it works\n\nPest Control is a single spring boot application with a shell offering commands to \ninstalling and control CockroachDB nodes via bash scripts. In a network environment, \nit uses itself as an agent to invoke local commands on behalf of a control-plane instance.\nFor Cockroach Cloud clusters, it only provides disruption API controls and no web UI \nsupport for visualization.\n\n# Terms of Use\n\nThis tool is not supported by Cockroach Labs. Use of this tool is entirely at your\nown risk and Cockroach Labs makes no guarantees or warranties about its operation.\n\nSee [MIT](LICENSE.txt) for terms and conditions.\n\n# Prerequisites\n\n- Java 21+ JDK\n  - https://openjdk.org/projects/jdk/21/\n  - https://www.oracle.com/java/technologies/downloads/#java21\n- Toxiproxy (optional)\n  - https://github.com/Shopify/toxiproxy\n- Haproxy (optional)\n  - https://www.haproxy.org/\n- You can use the following cluster types:\n  - Local - one machine/instance for all nodes (laptop typically).\n  - Remote- A network environment with one machine/instance per node. For this type, Pest Control \n  must be running on each node acting as an agent for a control plane instance.\n  - Cloud - An existing CockroachDB Cloud cluster. For this type, you can only use the disruption \n  API through shell commands.\n    \nNotice that Pest Control does not interact with any public cloud APIs for cluster provisioning \nand deployment. It's either local, your own pre-configured network or CockroachDB Cloud.\n\n## Install the JDK\n\nMacOS (using sdkman):\n\n    curl -s \"https://get.sdkman.io\" | bash\n    sdk list java\n    sdk install java 21.0 (pick version)  \n\nUbuntu:\n\n    sudo apt-get install openjdk-21-jdk\n\n## Install Toxiproxy (optional)\n\nToxiproxy is a TCP/IP interceptor chaos testing tool that can be used with pest control \nto intercepting CockroachDB inter-node gRPC traffic. It can apply different \"toxics\" like \nslowing down responses, limiting bandwidth etc.\n\nSee [Installing Toxiproxy](https://github.com/Shopify/toxiproxy?tab=readme-ov-file#1-installing-toxiproxy)\n\n## Install Haproxy (optional)\n                             \nUsually bundled in most distributions.\n\n# Building\n\nInstructions for building the project locally, as an alternative to using the \npackaged `TAR.GZ` assembly artifact.\n\n## Clone the project\n\n    git clone git@github.com:kai-niemi/pestcontrol.git \u0026\u0026 cd pestcontrol\n\n## Build the artifacts\n\n    chmod +x mvnw\n    ./mvnw clean install\n\nAt this point you can run it from the base directory or explode the `TAR.gz` bundle (in `target/`)\nto another location.\n\n# Running\n\nTo start the app in the foreground with an interactive shell:\n\n    ./pest\n\nTo start the app with the web UI enabled:\n\n    ./pest --web\n\nTo start the app in the foreground with a non-interactive shell to run a command \n(like `status 1`) and then quit:\n\n    ./pest node status -n 1\n\nTo start the app in the background without shell:\n\n    ./pest-op start-service\n\nNow you can access the application via http://localhost:9090.\n\nTo stop the app in the background:\n\n    ./pest-op stop-service\n\n# Configuration\n\nPest Control adopts convention over configuration, as far as it goes. After that, there's baseline\nconfiguration and after that there's per-node configuration. Everything is configured through a single\nYAML file like [config/application-default.yml](config/application-default.yml).\n\nYou can either edit the default profile file above directly, or create a new one with a custom name\nsuffix and then pass that name in the `--profiles` argument.\n\nThe active profile(s) will be listed in the startup banner and the selected cluster in shell prompt.\n\nExample of creating a new profile:\n\n    cp config/application-default.yml config/application-craig.yml\n    java -jar pestcontrol.jar --profiles craig\n\nFor a configuration reference, see the comments added to each item below:\n\n```yaml\napplication:\n  # Defines which cluster to pre-select\n  default-cluster-id: \"local-insecure\" \n  # List of all available clusters\n  clusters: \n      # Unique cluster ID, the UUID in case of cockroachdb cloud\n    - cluster-id: \"remote-insecure\"\n      # Cluster title\n      cluster-name: \"Remote Cluster (insecure)\" \n      # Defines the range of commands available to this cluster.\n      # cloud_serverless\n      # cloud_standard\n      # cloud_dedicated\n      # hosted_insecure\n      # hosted_secure\n      cluster-type: hosted_insecure\n      # URL pointing either at the first node console or haproxy HTTP listener\n      admin-url: \"http://localhost:8080\"\n      # Database connection properties   \n      data-source-properties:\n        url: \"jdbc:postgresql://localhost:26257/defaultdb?sslmode=disable\"\n        username: \"craig\"\n        password: \"\"\n      # Port numbers when generating haproxy config\n      load-balancer:\n        rpc-addr: :26250\n        http-addr: :8070\n        stats-addr: :7070\n      # Baseline DB version and address and port tuples. The + sign denotes incremental port assignments.\n      # If internal-ips is defined, each node will the prefixed with the address, thus\n      # the internal-ips and nodes must be equal in size.\n      baseline:\n        # The CockroachDB version to download and install\n        # See https://www.cockroachlabs.com/docs/releases/#downloads\n        version: \"v25.3.4.darwin-11.0-arm64\"\n        # version: \"v25.3.4.darwin-11.0-amd64\"\n        # version: \"v25.3.4.linux-amd64\"\n        # version: \"v25.3.4.linux-arm64\"\n        # Pest Control base URL\n        service-addr: localhost:9091\n        # CockroachDB listen addr\n        listen-addr: :+25257\n        # CockroachDB advertise addr\n        advertise-addr: localhost\n        # CockroachDB advertise proxy addr\n        advertise-proxy-addr: localhost:+35257\n        # CockroachDB SQL addr\n        sql-addr: :+26257\n        # CockroachDB HTTP addr\n        http-addr: :+8080\n        # Used for remote cluster types only to replace the canonical host names\n        internal-ips:\n          - 10.1.2.3\n          - 10.1.2.4\n          - 10.1.2.5\n      # List of nodes in the cluster\n      nodes:\n        # Required property denoting the locality flag. All the CockroachDB address:port properties\n        # in the baseline section above can be overridden here.\n        - locality: \"region=eu-central-1,zone=eu-central-1a\"\n        - locality: \"region=eu-central-1,zone=eu-central-1b\"\n        - locality: \"region=eu-central-1,zone=eu-central-1c\"\n```\n\n# Tutorials\n\n## Local 3-node self-hosted cluster (insecure)\n\nStart the interactive shell with:\n\n    ./pest\n\nThe commands will download and install the CockroachDB binaries, start a local insecure \n3-node cluster, initialize the cluster and also start haproxy.\n    \n````shell\nnode install\nnode start -n 1-3\nnode init \nhaproxy gen\nhaproxy start\nexit\n````\n\nYou can also copy all of the above to a text file and use:\n\n    ./pest @cmd.txt\n\n## Local 3-node self-hosted cluster (secure)\n\nThese commands will download and install the CockroachDB binaries, start a local secure \n3-node cluster with haproxy and initialize the cluster.\n\n```shell\ncluster use --clusterId local-secure\nnode install\nnode certs\nnode start -n 1-3\nnode init \nhaproxy gen\nhaproxy start\nexit\n```\n\nYou can also copy all of the above to a text file and use:\n\n    ./pest @cmd.txt\n\nThe secure mode uses self-signed CA certificates and keys stored in the `.certs` directory, \nincluding a PKCS12 truststore used by the web app. To login to a secure cluster, you may \nneed to restart the shell in order to pick up the self-signed certificate.\n\n## Remote 3-node self-hosted cluster (insecure)\n\nTo deploy and manage a cluster on dedicated machines, you first need to deploy and run \npestcontrol agents on each host. These agents will act as gateways to run local bash scripts \nto start, stop, kill nodes and so on. Your local instance will act as the control plane and \nsend HTTP requests to the other instances when running shell commands like `start`.\n\nA quick method is to scp the tar.gz assembly to each host. \nAssuming you have 3 pest control machines, host1, host2 and host3:\n\n```shell\nscp target/pestcontrol-2.0.0-bin.tar.gz user@host1:/~\nscp target/pestcontrol-2.0.0-bin.tar.gz user@host2:/~\nscp target/pestcontrol-2.0.0-bin.tar.gz user@host3:/~\nssh -t user@host1 'tar xvf pestcontrol-2.0.0-bin.tar.gz \u0026\u0026 cd pestcontrol-2.0.0 \u0026\u0026 ./pest-op start-service'\nssh -t user@host2 'tar xvf pestcontrol-2.0.0-bin.tar.gz \u0026\u0026 cd pestcontrol-2.0.0 \u0026\u0026 ./pest-op start-service'\nssh -t user@host3 'tar xvf pestcontrol-2.0.0-bin.tar.gz \u0026\u0026 cd pestcontrol-2.0.0 \u0026\u0026 ./pest-op start-service'\n```\n\nOn the control host, your local laptop/desktop for example, a cluster configuration named `remote-insecure` \nwith the IP/host names setup accordingly (no need to sync it across machines):\n\n```yaml\n    - cluster-id: \"remote-insecure\"\n      cluster-name: \"Remote Cluster (insecure)\"\n      cluster-type: hosted_insecure\n      admin-url: \"http://localhost:8080\"\n      data-source-properties:\n        url: \"jdbc:postgresql://localhost:26257/defaultdb?sslmode=disable\"\n        username: \"craig\"\n        password: \"\"\n      load-balancer:\n        rpc-addr: :26257\n        http-addr: :8070\n        stats-addr: :7070\n      baseline:\n        version: \"v25.3.4.darwin-11.0-arm64\"\n        service-addr: :9091\n        listen-addr: :+25257\n        advertise-addr: :+25257\n        advertise-proxy-addr: :+35257\n        sql-addr: :+26257\n        http-addr: :+8080\n        internal-ips:\n          - 10.1.2.3\n          - 10.1.2.4\n          - 10.1.2.5\n      nodes:\n        - locality: \"region=eu-central-1,zone=eu-central-1a\"\n        - locality: \"region=eu-central-1,zone=eu-central-1b\"\n        - locality: \"region=eu-central-1,zone=eu-central-1c\"\n```\n\nOn the control host, start the interactive shell with:\n\n    ./pest --cluster remote-insecure\n    \nThen execute:\n\n```shell\nnode install -n 1-3\nnode start -n 1-3\nnode init\n```\n\n## Remarks\n\n- If you switch between the `secure` and `insecure` modes, re-run the `init` command to\n  set proper SQL user roles and secrets.\n\n---\n\nThat is all, carry on!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkai-niemi%2Fpestcontrol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkai-niemi%2Fpestcontrol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkai-niemi%2Fpestcontrol/lists"}