{"id":13451588,"url":"https://github.com/vmware-tanzu/sonobuoy","last_synced_at":"2025-05-14T07:07:31.379Z","repository":{"id":23257434,"uuid":"98453563","full_name":"vmware-tanzu/sonobuoy","owner":"vmware-tanzu","description":"Sonobuoy is a diagnostic tool that makes it easier to understand the state of a Kubernetes cluster by running a set of Kubernetes conformance tests and other plugins in an accessible and non-destructive manner.","archived":false,"fork":false,"pushed_at":"2025-04-22T18:27:46.000Z","size":31306,"stargazers_count":2957,"open_issues_count":21,"forks_count":350,"subscribers_count":55,"default_branch":"main","last_synced_at":"2025-05-07T06:38:32.233Z","etag":null,"topics":["bugreport","cncf","conformance","conformance-tests","discovery","heptio","kubernetes","kubernetes-cluster","kubernetes-deployment","kubernetes-setup","sonobuoy","tanzu"],"latest_commit_sha":null,"homepage":"https://sonobuoy.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vmware-tanzu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-07-26T18:27:09.000Z","updated_at":"2025-04-30T07:29:29.000Z","dependencies_parsed_at":"2025-05-06T17:50:50.417Z","dependency_job_id":null,"html_url":"https://github.com/vmware-tanzu/sonobuoy","commit_stats":{"total_commits":967,"total_committers":104,"mean_commits":9.298076923076923,"dds":0.5873836608066184,"last_synced_commit":"6f9e27f1795f10475c9f6f5decdff692e1e228da"},"previous_names":["heptio/sonobuoy"],"tags_count":101,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-tanzu%2Fsonobuoy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-tanzu%2Fsonobuoy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-tanzu%2Fsonobuoy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-tanzu%2Fsonobuoy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vmware-tanzu","download_url":"https://codeload.github.com/vmware-tanzu/sonobuoy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254092648,"owners_count":22013290,"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":["bugreport","cncf","conformance","conformance-tests","discovery","heptio","kubernetes","kubernetes-cluster","kubernetes-deployment","kubernetes-setup","sonobuoy","tanzu"],"created_at":"2024-07-31T07:00:56.412Z","updated_at":"2025-05-14T07:07:31.357Z","avatar_url":"https://github.com/vmware-tanzu.png","language":"Go","funding_links":[],"categories":["Go","Cli/Management/Tooling:","kubernetes","Testing \u0026 Conformance","Testing","OPS"],"sub_categories":["[Jenkins](#jenkins)"],"readme":"# ![Sonobuoy Logo](site/themes/sonobuoy/static/img/sonobuoy-logo.png)\n\n[![Test](https://github.com/vmware-tanzu/sonobuoy/actions/workflows/ci-test.yaml/badge.svg)](https://github.com/vmware-tanzu/sonobuoy/actions/workflows/ci-test.yaml/badge.svg)\n[![Lint](https://github.com/vmware-tanzu/sonobuoy/actions/workflows/ci-lint.yaml/badge.svg)](https://github.com/vmware-tanzu/sonobuoy/actions/workflows/ci-lint.yaml/badge.svg)\n\n## [Overview][oview]\n\nSonobuoy is a diagnostic tool that makes it easier to understand the state of a Kubernetes cluster by running a set of\nplugins (including [Kubernetes][k8s] conformance tests) in an accessible and non-destructive manner. It is a\ncustomizable, extendable, and cluster-agnostic way to generate clear, informative reports about your cluster.\n\nIts selective data dumps of Kubernetes resource objects and cluster nodes allow for the following use cases:\n\n* Integrated end-to-end (e2e) [conformance-testing][e2ePlugin]\n* Workload debugging\n* Custom data collection via extensible plugins\n\nStarting v0.20, Sonobuoy supports Kubernetes v1.17 or later. Sonobuoy releases will be independent of Kubernetes\nrelease, while ensuring that new releases continue to work functionally across different versions of Kubernetes. Read\nmore about the new release cycles in [our blog][decoupling-sonobuoy-k8s].\n\n\u003e Note: You can skip this version enforcement by running Sonobuoy with the `--skip-preflight` flag.\n\n## Prerequisites\n\n* Access to an up-and-running Kubernetes cluster. If you do not have a cluster, we recommend either:\n  * following the [AWS Quickstart for Kubernetes][quickstart] instructions.\n  * setting up a local cluster using [KinD][kind]\n\n* An admin `kubeconfig` file, and the KUBECONFIG environment variable set.\n\n* For some advanced workflows it may be required to have `kubectl` installed.\n  See [installing via Homebrew (MacOS)][brew] or [building the binary (Linux)][linux].\n\n* The `sonobuoy images` subcommand requires [Docker](https://www.docker.com) to be installed.\n  See [installing Docker][docker].\n\n## Installation\n\nThe following methods exist for installing Sonobuoy:\n\n### Install binary\n\n1. Download the [latest release][releases] for your client platform.\n2. Extract the tarball:\n\n   ```\n   tar -xvf \u003cRELEASE_TARBALL_NAME\u003e.tar.gz\n   ```\n\n   Move the extracted `sonobuoy` executable to somewhere on your `PATH`.\n\n### Install with Hombrew (MacOS)\n\n1. Run the command:\n\n   ```\n   brew install sonobuoy\n   ```\n\n## Getting Started\n\nTo launch conformance tests (ensuring [CNCF][cncf] conformance) and wait until they are finished run:\n\n```bash\nsonobuoy run --wait\n```\n\n\u003e Note: Using `--mode quick` will significantly shorten the runtime of Sonobuoy. It runs just a single test, helping to quickly validate your Sonobuoy and Kubernetes configuration.\n\nGet the results from the plugins (e.g. e2e test results):\n\n```bash\nresults=$(sonobuoy retrieve)\n```\n\nInspect results for test failures. This will list the number of tests failed and their names:\n\n```bash\nsonobuoy results $results\n```\n\n\u003e Note: The `results` command has lots of useful options for various situations. See the [results page][results] for more details.\n\nYou can also extract the entire contents of the file to get much more [detailed data][snapshot] about your cluster.\n\nSonobuoy creates a few resources in order to run and expects to run within its own namespace.\n\nDeleting Sonobuoy entails removing its namespace as well as a few cluster scoped resources.\n\n```bash\nsonobuoy delete --wait\n```\n\n\u003e Note: The --wait option ensures the Kubernetes namespace is deleted, avoiding conflicts if another Sonobuoy run is started quickly.\n\nIf you have an issue with permissions in your cluster but you still want to run Sonobuoy, you can use `--aggregator-permissions` flag. Read more details about it [here][aggregator-permissions].\n\n### Other Tests\n\nBy default, `sonobuoy run` runs the Kubernetes conformance tests but this can easily be configured. The same plugin that\nhas the conformance tests has all the Kubernetes end-to-end tests which include other tests such as:\n\n* tests for specific storage features\n* performance tests\n* scaling tests\n* provider specific tests\n* and many more\n\nTo modify which tests you want to run, checkout our page on the [e2e plugin][e2ePlugin].\n\nIf you want to run other tests or tools which are not a part of the Kubernetes end-to-end suite, refer to our\ndocumentation on [custom plugins][customPlugins].\n\n### Monitoring Sonobuoy during a run\n\nYou can check on the status of each of the plugins running with:\n\n```bash\nsonobuoy status\n```\n\nYou can also inspect the logs of all Sonobuoy containers:\n\n```bash\nsonobuoy logs\n```\n\n## Troubleshooting\n\nIf you encounter any problems that the documentation does not address, [file an issue][issue].\n\n## Docker Hub rate limit\n\nThis year, Docker has started rate limiting image pulls from Docker Hub. We're planning a future release with a better\nuser interface to work around this. Until then, this is the recommended approach.\n\n### Sonobuoy Pod\n\nSonobuoy by default pulls from Docker Hub for [`sonobuoy/sonobuoy` image](https://hub.docker.com/r/sonobuoy/sonobuoy).\n\n### Conformance\n\nKubernetes end-to-end conformance test pulls several images from Docker Hub as part of testing. To override this, you\nwill need to create a registry manifest file locally (e.g. `conformance-image-config.yaml`) containing the following:\n\n```yaml\ndockerLibraryRegistry: mirror.gcr.io/library\n```\n\nThen on running conformance:\n\n```bash\nsonobuoy run --sonobuoy-image sonobuoy/sonobuoy:\u003cVERSION\u003e --e2e-repo-config conformance-image-config.yaml\n```\n\nTechnically `dockerGluster` is also a registry pulling from Docker Hub, but it's not part of Conformance test suite at\nthe moment, so overriding `dockerLibraryRegistry` should be enough.\n\n## Known Issues\n\n### Leaked End-to-end namespaces\n\nThere are some Kubernetes e2e tests that may leak resources. Sonobuoy can help clean those up as well by deleting all\nnamespaces prefixed with `e2e`:\n\n```bash\nsonobuoy delete --all\n```\n\n### Run on Google Cloud Platform (GCP)\n\nSonobuoy requires admin permissions which won't be automatic if you are running via Google Kubernetes Engine (GKE)\ncluster. You must first create an admin role for the user under which you run Sonobuoy:\n\n```bash\nkubectl create clusterrolebinding \u003cyour-user-cluster-admin-binding\u003e --clusterrole=cluster-admin --user=\u003cyour.google.cloud.email@example.org\u003e\n```\n\n### Run on Kubernetes for Docker Desktop\n\nWe don't recommend running via a cluster set up via Docker Desktop. Known issues include:\n\n- `kubectl logs` will not function\n- `sonobuoy logs` will not function\n- `sonobuoy retrieve` will not function\n- `systemd-logs` plugin will hang\n\nMost of these issues revolve around issues with kube-proxy on Docker Desktop so if you know of how to resolve these\nissues, let us know.\n\n### Certified-Conformance bug (versions v0.53.0 and v0.53.1)\n\nThese versions of Sonobuoy have a bug that runs the wrong set of tests without additional actions. See more\ndetails [here][issue1388]. The simplest way to avoid this is to update your version of Sonobuoy to \u003e= v0.53.2.\n\n## Strategy Document\n\nSee our current [strategy document][strategy] and [roadmap][roadmap] for context on what our highest priority use cases and work items\nwill be. Feel free to make comments on Github or start conversations in Slack.\n\n## Contributing\n\nThanks for taking the time to join our community and start contributing! We welcome pull requests. Feel free to dig\nthrough the [issues][issue] and jump in.\n\nThe most common build/test functions are called via the Makefile:\n\n```\n// Build the binary\n$ make build\n\n// Run local unit tests\n$ make test\n```\n\nIf you make changes which change output, you may fail tests which utilize the golden file testing pattern (e.g. correct data is stored in external files), update them by running:\n```\n$ make golden\n```\n\nIn most cases, running integration tests is more simply done in CI when you open a pull request.\nYou can dig into scripts/build_funcs.sh and our .github/workflows/ci-test.yaml for exact details of existing test flows.\n\n### Before you start\n\n* Please familiarize yourself with the [Code of Conduct][coc] before contributing.\n* See [CONTRIBUTING.md][contrib] for instructions on the developer certificate of origin that we require.\n* There is a [Slack channel][slack] if you want to interact with other members of the community\n\n## Changelog\n\nSee [the list of releases][releases] to find out about feature changes.\n\n[decoupling-sonobuoy-k8s]: https://sonobuoy.io/decoupling-sonobuoy-and-kubernetes\n\n[airgap]: https://sonobuoy.io/docs/airgap\n\n[brew]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-with-homebrew-on-macos\n\n[cncf]: https://github.com/cncf/k8s-conformance#certified-kubernetes\n\n[coc]: https://github.com/vmware-tanzu/sonobuoy/blob/main/CODE_OF_CONDUCT.md\n\n[contrib]: https://github.com/vmware-tanzu/sonobuoy/blob/main/CONTRIBUTING.md\n\n[docker]: https://docs.docker.com/get-docker/\n\n[docs]: https://sonobuoy.io/docs\n\n[e2ePlugin]: https://sonobuoy.io/docs/e2eplugin\n\n[customPlugins]: https://sonobuoy.io/docs/plugins\n\n[gen]: https://sonobuoy.io/docs/gen\n\n[issue]: https://github.com/vmware-tanzu/sonobuoy/issues\n\n[issue1388]: https://sonobuoy.io/docs/issue1388\n\n[k8s]: https://github.com/kubernetes/kubernetes\n\n[kind]: https://github.com/kubernetes-sigs/kind\n\n[linux]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#tabset-1\n\n[oview]: https://youtu.be/8QK-Hg2yUd4\n\n[plugins]: https://sonobuoy.io/docs/plugins\n\n[quickstart]: https://aws.amazon.com/quickstart/architecture/vmware-kubernetes/\n\n[releases]: https://github.com/vmware-tanzu/sonobuoy/releases\n\n[results]: https://sonobuoy.io/docs/results\n\n[slack]: https://kubernetes.slack.com/messages/sonobuoy\n\n[snapshot]:https://sonobuoy.io/docs/snapshot\n\n[sonobuoyconfig]: https://sonobuoy.io/docs/sonobuoy-config\n\n[strategy]: https://sonobuoy.io/docs/strategy\n\n[aggregator-permissions]: https://sonobuoy.io/docs/aggregator-permissions\n\n[roadmap]: https://github.com/vmware-tanzu/sonobuoy/wiki\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmware-tanzu%2Fsonobuoy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvmware-tanzu%2Fsonobuoy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmware-tanzu%2Fsonobuoy/lists"}