{"id":48975261,"url":"https://github.com/runityru/cephctl","last_synced_at":"2026-04-18T09:00:45.218Z","repository":{"id":245149642,"uuid":"789700582","full_name":"runityru/cephctl","owner":"runityru","description":"Small utility to control Ceph cluster configuration just like any other declarative configuration","archived":false,"fork":false,"pushed_at":"2026-04-18T06:56:35.000Z","size":369,"stargazers_count":14,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-18T09:00:13.643Z","etag":null,"topics":["ceph","configuration-management","declarative-config"],"latest_commit_sha":null,"homepage":"","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/runityru.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":"SECURITY.md","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":"2024-04-21T10:07:43.000Z","updated_at":"2026-04-18T06:54:42.000Z","dependencies_parsed_at":"2025-03-29T17:26:07.878Z","dependency_job_id":"364a0554-8200-426a-8113-509239224588","html_url":"https://github.com/runityru/cephctl","commit_stats":null,"previous_names":["runityru/cephctl"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/runityru/cephctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runityru%2Fcephctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runityru%2Fcephctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runityru%2Fcephctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runityru%2Fcephctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/runityru","download_url":"https://codeload.github.com/runityru/cephctl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runityru%2Fcephctl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31962889,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ceph","configuration-management","declarative-config"],"created_at":"2026-04-18T09:00:24.634Z","updated_at":"2026-04-18T09:00:45.198Z","avatar_url":"https://github.com/runityru.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cephctl\n\n[![Verify](https://github.com/runityru/cephctl/actions/workflows/verify.yml/badge.svg?branch=master)](https://github.com/runityru/cephctl/actions/workflows/verify.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/runityru/cephctl)](https://goreportcard.com/report/github.com/runityru/cephctl)\n[![Go Reference](https://pkg.go.dev/badge/github.com/runityru/cephctl.svg)](https://pkg.go.dev/github.com/runityru/cephctl)\n\nSmall utility to control Ceph cluster configuration just like any other declarative\n    configuration\n\n## Main features\n\n* Easy-to-use healthcheck which may contain checks against status \u0026 configuration\n    and indicate some some not trivial issues\n* Declarative configuration support which is apply only if needed\n* Diff configuration: check what the difference between currently running configuration\n    and desired or migrated from other cluster\n\n## Usage\n\n\u003c!-- markdownlint-disable MD013 --\u003e\n```shell\n$ ./cephctl\nusage: cephctl [\u003cflags\u003e] \u003ccommand\u003e [\u003cargs\u003e ...]\n\nSmall utility to control Ceph cluster configuration just like any other declarative configuration\n\n\nFlags:\n      --[no-]help   Show context-sensitive help (also try --help-long and --help-man).\n  -b, --ceph-binary=\"/usr/bin/ceph\"\n                    Specify path to ceph binary ($CEPHCTL_CEPH_BINARY)\n  -d, --[no-]debug  Enable debug mode ($CEPHCTL_DEBUG)\n  -t, --[no-]trace  Enable trace mode (debug mode on steroids) ($CEPHCTL_TRACE)\n  -c, --[no-]color  Colorize diff output ($CEPHCTL_COLOR)\n\nCommands:\nhelp [\u003ccommand\u003e...]\n    Show help.\n\napply \u003cfilename\u003e\n    Apply ceph configuration\n\ndiff \u003cfilename\u003e\n    Show difference between running and desired configurations\n\ndump cephconfig\n    dump Ceph runtime configuration\n\ndump cephosdconfig\n    dump Ceph OSD configuration\n\nhealthcheck\n    Perform a cluster healthcheck and print report\n\nversion\n    Print version and exit\n\n```\n\u003c!-- markdownlint-enable MD013 --\u003e\n\n## How it works\n\nCephctl uses native Ceph CLIs to work with cluster configuration so it's require\nto have Ceph binaries w/ configured `ceph.conf`. Alternatively it's possible\nto adjust `ceph` binary path to access ceph in container and/or remote machine.\n\n## Roadmap\n\n* [X] v0.0.0\n  * [X] Apply declarative configuration for `ceph config`\n  * [X] Dump cluster configuration to CephConfig specification\n  * [X] Diff configuration against running configuration for `ceph config`\n  * [X] Perform healthcheck based on current cluster status\n  * [X] Add healthchecks based on current cluster configuration\n* [X] v0.1.0\n  * [X] Additional healthchecks based on hardware status\n  * [X] FreeBSD support in builds\n  * [X] Remote Ceph cluster access via SSH\n* [X] v0.2.0\n  * [X] Apply/Dump declarative configuration for `ceph osd set-*` stuff\n* [ ] v0.3.0\n  * [ ] Apply/Dump declarative configuration for Ceph Object Gateway (rgw)\n* [ ] v0.4.0\n  * [ ] Apply/Dump declarative configuration for Pools\n* [ ] v0.5.0\n  * [ ] Live balancing PGs across OSDs\n\n## Ceph compatibility\n\nAll of the changes are tested against Ceph 18.2 (Reef) and 19.2 (Squid), previous\nversions are not tested and not guaranteed to work.\n\n## Interface compatibility disclaimer\n\nIf you gonna use cephctl as a library for your purposes please feel free to\nbut please note a few things:\n\n1. Cephctl doesn't use internal packages to allow you to do whatever you like.\n    Cephctl project doesn't aim to limit your usage.\n2. Internal program interfaces are not guaranteed to be stable between releases\n    since they're written and serve for internal purposes.\n3. CLI interface (until 1.0.x at least) is also not guaranteed to be stable:\n    subcommands and options are subjects to change between versions.\n\n## Installation\n\ncephctl is released in following ways to achieve compatibility and provide\nan easy way for end users.\n\n### Pre-compiled binary\n\nPre-compiled binaries are available on per-release basis and provided on\n[GitHub Releases page](https://github.com/runityru/cephctl/releases). Automatically\ngenerated changelog is available for each release. And binaries are available for:\n\n* FreeBSD (amd64v1, amd64v2, amd64v3, arm64)\n* Linux (amd64v1, amd64v2, amd64v3, arm64)\n* macOS (amd64v1, amd64v2, amd64v3, arm64)\n* Windows (amd64v1, amd64v2, amd64v3, arm64)\n\nAny of them could be used on end-user machine to interact with Ceph\nvia SSH just like the following way:\n\n```shell\ncephctl --ceph-binary='ssh mon01 ceph' healthcheck\n```\n\nor by using environment variables to specify ceph binary:\n\n```shell\nexport CEPHCTL_CEPH_BINARY='ssh mon01 ceph'\ncephctl healthcheck\n```\n\n### Container image\n\nSince cephctl uses ceph binary to achieve cluster data, container image based\non ceph official release image is also available. This image is designed as\ndrop-in replacement for official ceph image to use for `cephadm shell` command.\n\nContainer image is available at [GitHub Packages](https://github.com/runityru/cephctl/pkgs/container/cephctl%2Fceph)\n\nTo replace official Ceph image with the one containing cephctl in cephadm\nclusters just do:\n\n```shell\n# Set container image as a global parameter to all components\nceph config set mgr mgr/cephadm/container_image_base ghcr.io/runityru/cephctl/ceph\n\n# Run upgrade procedure\nceph orch upgrade start --ceph_version=18.2.2\n```\n\nPlease note Ceph orch will automatically replace `container_image` parameter\nfor each component with specific sha256 image ID instead of tag we defined\nmanually. It's OK and it's a guarantee the image won't be changed in your\ncluster.\n\n### Build from source\n\nIt's possible to build cephctl from source by simply running the following\ncommand:\n\n```shell\ngoreleaser build --snapshot --clean\n```\n\nor manually via Go compiler\n\n\u003c!-- markdownlint-disable MD013 --\u003e\n```shell\ngo build -v -ldflags=\"-X 'main.appVersion=$(git rev-parse --short HEAD) (trunk build)' -X 'main.buildTimestamp=$(date -u +%Y-%m-%dT%H:%m:%SZ)'\" -o dist/cephctl ./cmd/cephctl/...\n```\n\u003c!-- markdownlint-enable MD013 --\u003e\n\n## Contribution\n\ncephctl is an open source project so you have the following ways to contribute:\n\n* Documentation\n* Fill issues\n* Fix bugs\n* Suggest/implement new features\n* Or any other way, if you have any doubts please fill free to [open discussion](https://github.com/runityru/cephctl/discussions)\n\n### Something about guidelines for the code\n\nThere's no actually a particular guidelines for the code but there are some\ncommon rules about it based on TDD, DDD and SOLID, the list could be extended:\n\n#### Split layers of abstraction\n\nEach abstraction layer should be isolated: transport layer from data layer,\nDTO models from business logic models and so on.\n\n#### Write unit tests\n\nSince we gonna have amount of packages we can easily write tests, please don't\nignore such ability.\n\n#### Isolate tests\n\nIn many projects I've seen how test are using system-wide configuration files,\nsystem-wide binaries and so on - I think this is a bad, insecure, unsafe and\nirreproducible practice not allowing to be sure the tests are passed in new\nenvironment (on a new developer machine for instance).\n\nSo all the tests in cephctl are isolated:\n\n* code running any commands runs scripts in tests emulating the expected behavior\n* command output payload is gathered from real installations\n* the only thing you need to run tests is go compiler\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunityru%2Fcephctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frunityru%2Fcephctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunityru%2Fcephctl/lists"}