{"id":30754268,"url":"https://github.com/reddit/achilles-sdk","last_synced_at":"2025-09-04T09:09:01.119Z","repository":{"id":262326961,"uuid":"880334552","full_name":"reddit/achilles-sdk","owner":"reddit","description":"SDK for building Kubernetes controllers.","archived":false,"fork":false,"pushed_at":"2025-08-25T18:23:32.000Z","size":613,"stargazers_count":199,"open_issues_count":7,"forks_count":15,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-08-25T19:34:58.219Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reddit.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-10-29T14:39:40.000Z","updated_at":"2025-08-25T16:21:52.000Z","dependencies_parsed_at":"2025-01-23T15:28:19.955Z","dependency_job_id":"be425b99-4125-4e95-9cf4-c92412c266bf","html_url":"https://github.com/reddit/achilles-sdk","commit_stats":null,"previous_names":["reddit/achilles-sdk"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/reddit/achilles-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reddit%2Fachilles-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reddit%2Fachilles-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reddit%2Fachilles-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reddit%2Fachilles-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reddit","download_url":"https://codeload.github.com/reddit/achilles-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reddit%2Fachilles-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273581245,"owners_count":25131393,"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","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"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":[],"created_at":"2025-09-04T09:07:49.859Z","updated_at":"2025-09-04T09:09:01.097Z","avatar_url":"https://github.com/reddit.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Achilles SDK\n\nThe Achilles SDK offers efficient\n[operator/controller](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)\ncreation by allowing engineers to focus on defining their automation business logic, modeled as transitions between resources states (i.e. an FSM). This\nsignificantly lessens the knowledge of controller and Kubernetes plumbing\ntypically required to build controllers. It also forces standardization to\nensure consistency amongst controllers at Reddit, providing common functionality\nsuch as metrics, logging, reusable API structs, etc..\n\nSee the [achilles-token-controller](https://github.com/reddit/achilles-token-controller) repo for \na complete, runnable example of an Achilles SDK backed controller.\n\n## High Level Walkthrough\n\nAs an example, assume you wanted to create a declarative API that allows\ndevelopers to request object storage for their application. The API you wish to\nexpose may look something like:\n\n```yaml\napiVersion: infra.snooguts.net/v1alpha1\nkind: ObjectStorage\nmetadata:\n  name: persistent-storage\n  namespace: web-apps\nspec:\n  encrypted: true\n  region: us-east\n  versioning: true\n```\n\nTo define this API, you'll use a common-convention with Go structs to\nautomatically generate the\n[CustomResourceDefinition](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#:~:text=The%20CustomResourceDefinition%20API%20resource%20allows,storage%20of%20your%20custom%20resource.)\n(API). Then you'll define the states and transition logic, such as:\n\n![FSM Flow](docs/imgs/fsm-flow.png)\n\nAlong with doing the underlying plumbing to support this controller,\nachilles-sdk is providing you logging, metrics, rate-limiting, and\nmore.\n\nLastly, in modeling your controller logic this way, you end up with a clean\ndirected graph that models a\n[finite-state-machine](https://en.wikipedia.org/wiki/Finite-state_machine)\n(FSM). This can significantly reduce the cognitive overhead of reasoning about\nwhat a controller is doing or the state an object is in. More on FSM in the\ndocumentation.\n\n## Documentation\n\n* [Reconciler (FSM) Framework](docs/sdk-fsm-reconciler.md#fsm-reconciler)\n    * Overview of how achilles-sdk works by offering a finite-state machine\n      orchestrated with a Kubernetes reconciler.\n\n## How to Contribute\n1. Fork the repo.\n2. Make changes and test.\n3. Submit a Pull Request with an appropriate description.\n4. Tests will automatically run for you.\n5. Merge PR once it is approved.\n\n## Releasing\nRegular releases will be done by maintainers.\n\nAfter incorporating your changes into the achilles-sdk repository, you can publish a new release to make the updated functionality available for repos that consume achilles-sdk.\n\n#### Publish a new release:\n1. Navigate to the [GHE releases page for achilles-sdk](https://github.com/reddit/achilles-sdk/releases) and click the “Draft a new release” button in the top right\n2. Choose the appropriate next semantic version (`major.minor.patch`):\n   - If there are breaking code changes (e.g., new function signatures for public functions), increment the minor version if the release is pre-1.0, otherwise increment the major version\n   - If there are no breaking changes, increment the patch version if pre-1.0, otherwise increment the minor version if adding functionality or the patch version if fixing bugs\n   - To create a tag with the new version, click the “Choose a tag” button. Enter the new version number and click “Create new tag: `$your-tagname-here` on publish.”\n3. Click the “Generate release notes” button and verify that the changes align with expectations. If everything looks good, publish the release\n\n#### Make updated functionality available for repos consuming the achilles-sdk:\n1. Create a branch in the consuming repository\n2. Run the following command to upgrade the achilles-sdk version (replace v0.7.1 with the new version number):  \n   `go get github.com/reddit/achilles-sdk@v0.7.1`\n3. Run a `git diff` and validate that the changes made to `go.mod` and `go.sum` are as expected.\n4. Create a PR in the consuming repo with the newly upgraded achilles-sdk version\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freddit%2Fachilles-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freddit%2Fachilles-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freddit%2Fachilles-sdk/lists"}