{"id":13646339,"url":"https://github.com/lotusload/lotus","last_synced_at":"2025-04-21T18:30:53.793Z","repository":{"id":57489922,"uuid":"160291706","full_name":"lotusload/lotus","owner":"lotusload","description":"Kubernetes controller for running load testing","archived":false,"fork":false,"pushed_at":"2023-02-24T19:34:01.000Z","size":485,"stargazers_count":99,"open_issues_count":5,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-03T03:06:18.873Z","etag":null,"topics":["automation","controller","crd","k8s","kubernetes","load","testing"],"latest_commit_sha":null,"homepage":"","language":"Go","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/lotusload.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":"CODEOWNERS","security":null,"support":null,"governance":null}},"created_at":"2018-12-04T03:35:35.000Z","updated_at":"2025-02-20T14:03:09.000Z","dependencies_parsed_at":"2023-07-13T23:51:33.888Z","dependency_job_id":null,"html_url":"https://github.com/lotusload/lotus","commit_stats":null,"previous_names":["nghialv/lotus"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lotusload%2Flotus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lotusload%2Flotus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lotusload%2Flotus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lotusload%2Flotus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lotusload","download_url":"https://codeload.github.com/lotusload/lotus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250110801,"owners_count":21376539,"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":["automation","controller","crd","k8s","kubernetes","load","testing"],"created_at":"2024-08-02T01:02:53.227Z","updated_at":"2025-04-21T18:30:53.368Z","avatar_url":"https://github.com/lotusload.png","language":"Go","funding_links":[],"categories":["Operators vs Controllers","Go","Test"],"sub_categories":["Chaos / Loading Testing"],"readme":"# Lotus [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat)](http://makeapullrequest.com) [![MIT Licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/lotusload/lotus/blob/master/LICENSE)\n\nLotus is a Kubernetes controller for running load testing. Lotus schedules \u0026 monitors the load test workers, collects \u0026 stores the metrics and notifies the test result.\n\nOnce installed, Lotus provides the following features:\n- GRPC and HTTP support\n- Ability to write the scenario by any language you want\n- Automation-friendly\n  - `Checks` (like asserts, fails in normal test) for easy and flexible CI configuration\n  - Test is configured by using declarative Kubernetes CRD for version control friendliness\n- Flexible metrics storage and visualization\n  - Ability to view visualized time series by Grafana\n  - Ability to persist time series data to a long-term storage like GCS or S3\n  - Ability to notify and store the result summary to multiple receivers: GCS, Slack, Logger...\n\n\u003e _I am thinking about adding a feature that helps us determine the maximum number of  users (requests) the target services can handle. This can be done by automatically running the load tests with the number of virtual users increasing gradually until one of the checks fails. Or a feature that helps us determine the needed resources of the target services so that they can handle the given number of users. [more](https://github.com/lotusload/lotus/issues/1)_\n\n### Installation\nFirstly, you need to install Lotus controller on your Kubernetes cluster to start using.\nLotus requires a Kubernetes cluster of version `\u003e=1.9.0`.\n\nThe Lotus controller can be installed either by using the helm [`chart`](https://github.com/lotusload/lotus/tree/master/install/helm) or by using Kubernetes [`manifests`](https://github.com/lotusload/lotus/tree/master/install/manifests) directly.\n(Using the helm chart is recommended.)\n\n``` console\nhelm install --name lotus ./install/helm\n```\n\nSee [`install`](https://github.com/lotusload/lotus/tree/master/install) for more details.\n\n### Running Lotus\nWe have 2 steps to start running a load test:\n- Writing a load test scenario\n- Writing a Lotus CRD configuration\n\n#### 1. Writing a load test scenario\n\nTheoretically, you can write your scenarios by using any language you like. The only thing you need to have is a metrics exporter for Prometheus.\n\nIn the case of Golang, I have already prepared some util packages (e.g. [`metrics`](https://github.com/lotusload/lotus/tree/master/pkg/metrics), [`virtualuser`](https://github.com/lotusload/lotus/tree/master/pkg/virtualuser)) that help you write your scenarios faster and easier.\n\n- Expose a metrics server in your scenario's `main.go`\n``` go\nimport \"github.com/lotusload/lotus/pkg/metrics\"\n\nm, err := metrics.NewServer(8081)\nif err != nil {\n    return err\n}\ndefer m.Stop()\ngo m.Run()\n```\n- In case you want to send gRPC's rpcs to your load server, let's set `grpcmetrics.ClientHandler` as the `StatsHandler` of your gRPC connection.\n``` go\ngrpc.Dial(\n    grpc.WithStatsHandler(\u0026grpcmetrics.ClientHandler{}),\n)\n```\n\n- In case you want to send HTTP requests to your load server, let's use the `Transport` from `httpmetrics` package.\n``` go\nhttp.Client{\n    Transport: \u0026httpmetrics.Transport{},\n}\n```\n- That is all. Now let's build your scenario image and publish to your container registry.\n\n#### 2. Writing a Lotus CRD configuration\n\n``` yaml\napiVersion: lotus.lotusload.com/v1beta1\nkind: Lotus\nmetadata:\n  name: simple-scenario-12345                                  // The unique testID\nspec:\n  worker:\n    runTime: 10m                                               // How long the load test will be run\n    replicas: 15                                               // How many workers should be created\n    metricsPort: 8081                                          // What port number should be used to collect metrics\n    containers:\n      - name: worker\n        image: your-registry/your-worker-image                 // The scenario image you published above\n        ports:\n          - name: metrics\n            containerPort: 8081\n  checks:                                                      // You can add some checks to be checked while running\n    - name: GRPCHighErrorRate\n      expr: lotus_grpc_client_failure_percentage \u003e 10\n      for: 30s\n```\n\nThen apply this file to your Kubernetes cluster. Lotus will handle this test for you.\n\nSee [`crd-configurations.md`](https://github.com/lotusload/lotus/blob/master/docs/lotus-crd-configurations.md) for all configurable fields.\n\nSee [`examples`](https://github.com/lotusload/lotus/tree/master/examples) for more examples.\n\n### Outputs\n\n- Test summary\n\nLotus collects the metrics data and evaluates the `checks` to build a summary result for each test.\nLotus can be configured to upload this summary file to external services (e.g: GCS, Slack...) or to log into `stdout`.\n3 formats of the summary file are supported: `Text`, `Markdown`, `JSON`.\n\n``` yaml\nTestID:        test-scenario-12345\nTestStatus:    Succeeded\nStart:         09:02:59 2018-12-03\nEnd:           09:12:59 2018-12-03\n\nMetricsSummary:\n\n1. Virtual User\n  - Started:             1M\n  - Failed:              0\n\n2. GRPC\n  - RPCTotal:            25M\n  - FailurePercentage:   2.507\n\nGroupByMethod:\n                        RPCs      Failure%  Latency   SentBytes  RecvBytes\n\n  - helloworld.Hello    12.5M     1.015     105       15        8\n  - helloworld.Profile  12.5M     1.415     152       8         256\n  - all                 25M       1.207     135       12        245\n\nGrafana: http://localhost:3000/dashboard/db/grpc?from=1543827779598\u0026to=1543828379598\n```\n\n\n- Grafana dashboards\n\nTo be able to fully explore and understand your test, Lotus is providing some Grafana dashboards to view the visualizations of the metrics.\nYou can also set up Lotus to persist the time series data to a long-term storage (GCS or S3) for accessing after the test is deleted.\n\n- Test Status\n\nAfter applying the Lotus CRD to your Kubernetes cluster you can also use the following command to check the status of your test.\n\n``` console\nkubectl describe Lotus your-lotus-name\n```\n\nYour test can be one of these status: `Pending`, `Preparing`, `Running`, `Cleaning`, `FailureCleaning`, `Failed`, `Succeeded`\n\n### Examples\n\nPlease checkout [`/examples`](https://github.com/lotusload/lotus/tree/master/examples) directory that contains some prepared examples.\n\n### FAQ\n\nRefer to [FAQ.md](https://github.com/lotusload/lotus/blob/master/docs/faq.md)\n\n### Development\n\nRefer to [development.md](https://github.com/lotusload/lotus/blob/master/docs/development.md)\n\n### LICENSE\nLotus is released under the MIT license. See [LICENSE](https://github.com/lotusload/lotus/blob/master/LICENSE) file for the details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flotusload%2Flotus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flotusload%2Flotus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flotusload%2Flotus/lists"}