{"id":13564759,"url":"https://github.com/strangelove-ventures/cosmos-operator","last_synced_at":"2025-12-29T23:48:16.258Z","repository":{"id":62973713,"uuid":"517759312","full_name":"strangelove-ventures/cosmos-operator","owner":"strangelove-ventures","description":"Cosmos Operator is a kubernetes operator for managing cosmos nodes","archived":false,"fork":false,"pushed_at":"2024-04-05T18:32:17.000Z","size":947,"stargazers_count":65,"open_issues_count":38,"forks_count":11,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-04-13T02:15:37.394Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/strangelove-ventures.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-07-25T17:26:52.000Z","updated_at":"2024-04-15T07:12:26.793Z","dependencies_parsed_at":"2024-01-29T23:22:45.282Z","dependency_job_id":"c84345fa-ec98-4d99-95bd-af55606dbc38","html_url":"https://github.com/strangelove-ventures/cosmos-operator","commit_stats":{"total_commits":150,"total_committers":6,"mean_commits":25.0,"dds":"0.20666666666666667","last_synced_commit":"9f278c69b6a9f55c47d25b3a1a0d13b96a285df7"},"previous_names":[],"tags_count":67,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strangelove-ventures%2Fcosmos-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strangelove-ventures%2Fcosmos-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strangelove-ventures%2Fcosmos-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strangelove-ventures%2Fcosmos-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/strangelove-ventures","download_url":"https://codeload.github.com/strangelove-ventures/cosmos-operator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247083476,"owners_count":20880850,"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":[],"created_at":"2024-08-01T13:01:35.492Z","updated_at":"2025-12-29T23:48:16.224Z","avatar_url":"https://github.com/strangelove-ventures.png","language":"Go","funding_links":[],"categories":["Node Operations","Go"],"sub_categories":["Utilities"],"readme":"[![Conforms to README.lint](https://img.shields.io/badge/README.lint-conforming-brightgreen)](https://github.com/strangelove-ventures/readme-dot-lint)\n[![Project Status: Initial Release](https://img.shields.io/badge/repo%20status-active-green.svg?style=flat-square)](https://www.repostatus.org/#active)\n[![GoDoc](https://img.shields.io/badge/godoc-reference-blue?style=flat-square\u0026logo=go)](https://pkg.go.dev/github.com/strangelove-ventures/cosmos-operator)\n[![Go Report Card](https://goreportcard.com/badge/github.com/strangelove-ventures/cosmos-operator)](https://goreportcard.com/report/github.com/strangelove-ventures/cosmos-operator)\n[![License: Apache-2.0](https://img.shields.io/github/license/strangelove-ventures/cosmos-operator.svg?style=flat-square)](https://github.com/strangelove-ventures/cosmos-operator/blob/main/LICENSE)\n[![Version](https://img.shields.io/github/tag/strangelove-ventures/cosmos-operator.svg?style=flat-square)](https://github.com/cosmos/strangelove-ventures/cosmos-operator)\n\nCosmos Operator is a [Kubernetes Operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) primarily for blockchains built with the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk). It also supports [Penumbra](https://github.com/penumbra-zone/penumbra) and other chains which use [CometBFT](https://github.com/cometbft/cometbft) for consensus. \n\n🌌 Why use Cosmos Operator?\n=============================\n\nKubernetes (\"K8\") makes DevOps easier. Cosmos Operator makes Kubernetes easier for use in the Cosmos Ecosystem.\n\nK8 provides a foundation for creating highly-available, scalable, fault-tolerant applications. It provides well-known DevOps patterns and abstractions (as opposed to traditional DevOps which often requires \"re-inventing the wheel\").\n\nFurthermore, the [Operator Pattern][] allows us to mix infrastructure with business logic,\nthus minimizing human intervention and human error.\n\n\n🌌🌌 Who benefits from Cosmos Operator?\n=============================\n\nPeople who'd like to use the [Operator Pattern][] to \"configure it and forget it\".\n\n\u003e The [operator pattern][] aims to capture the key aim of a human operator who is managing a service or set of services. Human operators who look after specific applications and services have deep knowledge of how the system ought to behave, how to deploy it, and how to react if there are problems.\n\n\u003e People who run workloads on Kubernetes often like to use automation to take care of repeatable tasks. The [operator pattern][] captures how you can write code to automate a task beyond what Kubernetes itself provides.\n\n\n🌌🌌🌌 What does Cosmos Operator do?\n=============================\n\nCosmos Operator is a [Kubernetes Operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) for blockchains built with the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk). Write your own Custom Resource Definition (\"CRD\") as a `yaml` file and deploy with ease!\n\n\n🌌🌌🌌🌌 How do I use Cosmos Operator?\n=============================\n\n## Quick Start\n\nSee the [quick start guide](./docs/quick_start.md).\n\n## CosmosFullNode CRD\n\nCosmosFullNode is the flagship CRD. Its purpose is to deploy highly-available, fault-tolerant blockchain nodes.\n\nThe CosmosFullNode controller is like a StatefulSet for running Cosmos SDK blockchains.\n\nA CosmosFullNode can be configured to run as an RPC node, a validator sentry, or a seed node. All configurations can be used as persistent peers.\n\nAs of this writing, Strangelove has been running CosmosFullNode in production for over a year.\n\n## Samples\n\n- [Minimal example yaml](./config/samples/cosmos_v1_cosmosfullnode.yaml)\n- [Full example yaml](./config/samples/cosmos_v1_cosmosfullnode_full.yaml)\n- [Penumbra example yaml](./config/samples/cosmos_v1_cosmosfullnode_penumbra.yaml)\n\n## Support CRDs\n\nThese CRDs are part of the operator and serve to support CosmosFullNodes.\n\n- [ScheduledVolumeSnapshot](./docs/scheduled_volume_snapshot.md)\n- [StatefulJob](./docs/stateful_job.md)\n\n### Why not a StatefulSet?\n\nEach pod requires different config, such as peer settings in config.toml and mounted node keys. Therefore, a blanket\ntemplate as found in StatefulSet did not suffice.\n\nAdditionally, CosmosFullNode gives you more control over individual pod and pvc pairs vs. a StatefulSet to help the human operator debug and recover from situations such as a corrupted PVCs.\n\n\n🌌🌌🌌🌌🌌 Extras\n=============================\n\n# Disclaimers\n\n- Tested on Google's GKE and Bare-metal with `Kubeadm`. Although kubernetes is portable, we cannot guarantee or provide support for AWS, Azure, or other kubernetes providers.\n- Requires a recent version of kubernetes: v1.23+.\n- CosmosFullNode: The chain must be built from the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk).\n- CosmosFullNode: Validator sentries require a remote signer such as [horcrux](https://github.com/strangelove-ventures/horcrux).\n- CosmosFullNode: The controller requires [heighliner](https://github.com/strangelove-ventures/heighliner) images. If you build your own image, you will need a shell `sh` and set the uid:gid to 1025:1025. If running as a validator sentry, you need `sleep` as well.\n- CosmosFullNode: May not work for all Cosmos chains. (Some chains diverge from common conventions.) Strangelove has yet to encounter a Cosmos chain that does not work with this operator.\n\n# Contributing\n\nSee the [contributing guide](./CONTRIBUTING.md).\n\n# Best Practices\n\nSee the [best practices guide for CosmosFullNode](./docs/fullnode_best_practices.md).\n\n# Roadmap\n\nDisclaimer: Strangelove has not committed to these enhancements and cannot estimate when they will be completed.\n\n- [x] Scheduled upgrades. Set the upgrade height and image version, optionally setting halt height. The controller performs a rolling update with the new image version after the committed height.\n- [x] Support configuration suitable for validator sentries.\n- [x] Reliable, persistent peer support.\n- [x] Quicker p2p discovery using private peers.\n- [ ] Advanced readiness probe behavior. (The CometBFT rpc status endpoint is not always reliable.)\n- [x] Automatic rollout for PVC resizing. (Currently human intervention required to restart pods after PVC resized.) Requires ExpandInUsePersistentVolumes feature gate.\n- [x] Automatic PVC resizing. The controller increases PVC size once storage reaches a configured threshold; e.g. 80% full.\n- [ ] Bootstrap config using the chain registry. Query the chain registry and set config based on the registry.\n- [ ] Validate p2p such as peers, seeds, etc. and filter out non-responsive peers.\n- [ ] HPA support.\n- [ ] Automatic upgrades. Controller monitors governance and performs upgrade without any human intervention.\n- [ ] Corrupt data recovery. Detect when a PVC may have corrupted data. Restore data from a recent VolumeSnapshot.\n- [x] Safe, automatic backups. Create periodic VolumeSnapshots of PVCs while minimizing chance of data corruption during snapshot creation.\n\n# License\n\nCopyright 2023 Strangelove Ventures LLC.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n---\n\n[Operator Pattern]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/#operators-in-kubernetes","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrangelove-ventures%2Fcosmos-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstrangelove-ventures%2Fcosmos-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrangelove-ventures%2Fcosmos-operator/lists"}