{"id":24659120,"url":"https://github.com/ibm/kar","last_synced_at":"2025-03-16T07:07:10.576Z","repository":{"id":37211924,"uuid":"329448357","full_name":"IBM/kar","owner":"IBM","description":"KAR: A Runtime for the Hybrid Cloud","archived":false,"fork":false,"pushed_at":"2024-09-16T11:04:57.000Z","size":8866,"stargazers_count":28,"open_issues_count":13,"forks_count":12,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-12-20T23:34:01.558Z","etag":null,"topics":["cloud","cloud-native","distributed-computing","fault-tolerance","hybrid-cloud","java","javascript","kubernetes"],"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/IBM.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-13T22:37:03.000Z","updated_at":"2024-07-29T17:39:48.000Z","dependencies_parsed_at":"2022-07-12T03:46:42.165Z","dependency_job_id":"8eb44a83-e561-413d-98ae-31c08b65991a","html_url":"https://github.com/IBM/kar","commit_stats":{"total_commits":1348,"total_committers":17,"mean_commits":79.29411764705883,"dds":0.5801186943620178,"last_synced_commit":"9e5081b719fe7d9cf0fb4a42dd129af209f5da78"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fkar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fkar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fkar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fkar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IBM","download_url":"https://codeload.github.com/IBM/kar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243835983,"owners_count":20355613,"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":["cloud","cloud-native","distributed-computing","fault-tolerance","hybrid-cloud","java","javascript","kubernetes"],"created_at":"2025-01-26T02:31:58.882Z","updated_at":"2025-03-16T07:07:10.554Z","avatar_url":"https://github.com/IBM.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\n# Copyright IBM Corporation 2020,2023\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n#     http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n--\u003e\n\n# KAR: A Runtime for the Hybrid Cloud\n\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0)\n[![Continuous Integration](https://github.com/IBM/kar/actions/workflows/ci.yaml/badge.svg)](https://github.com/IBM/kar/actions/workflows/ci.yaml)\n\nThe KAR runtime makes it easy to _develop_ and _run_ stateful, scalable,\nresilient applications for the _hybrid cloud_ that combine microservices and\nmanaged services.\n\nKAR is:\n- open source and vendor neutral.\n- cloud-native: KAR is built for Kubernetes and OpenShift.\n- polyglot: KAR supports any programming language and developer framework by\n  means of REST APIs. Idiomatic SDKs for specific languages may be developed\n  with minor effort.\n- simple yet expressive: KAR interfaces stateless and stateful microservices\n  using requests and events.\n- scalable: KAR is designed from the ground up to handle dynamic scaling of\n  replicated stateless and stateful microservices.\n- resilient: KAR combines persistent message queues with persistent data stores\n  to offer strong fault-tolerance guarantees.\n- extensible: KAR applications can produce or consume events and data streams\n  using hundreds of [Apache Camel](https://camel.apache.org) sources and sinks.\n\n# Scalable and Fault-Tolerant State\n\nKAR puts a great deal of emphasis on helping developers manage application\nstate. Stateless microservices are easy to scale and easy to restart or replace\non failure. Stateful microservices are not. Moreover the state of an application\nnot only includes the state of its microservice components, but also the state\nof in-flight requests or events, external state in databases or on disk, etc.\nKeeping track of this state, avoiding performance bottlenecks, and protecting it\nfrom failures is typically very hard.\n\n## Actors\n\nKAR make it easy to structure the state of microservices as a collection of\n_actor_ instances. The [actor model](https://en.wikipedia.org/wiki/Actor_model)\nis a popular and well-understood approach to programming concurrent and\ndistributed systems. Each actor instance is responsible for its own state. The\nstate of an actor instance can be saved or restored safely (because actor\ninstances are single-threaded) and independently from other actor instances\n(since there is no shared state).\n\nKAR offers simple APIs for actors to incrementally save their state to Redis.\nThese APIs can be triggered periodically, or when idle with little effort. KAR\ncan automatically restore the state of a failed actor instance. Timers or event\nsubscriptions associated with an actor instance are also restored.\n\nActor instances can migrate from one microservice replica to another due to\nfailures or for load balancing purposes. KAR understands that actors are\nrelocatable. KAR's API for invoking actors transparently routes, and if necessary\nreroutes, requests to the proper destination.\n\nFor instance, in the simulation engine example  described below, the simulation state is\npartitioned across multiple replicas of the simulator microservice using actors.\nA developer can reason about and program these actors and their interactions\nwithout having to worry about exhausting the resources of a single process or\nmapping actor instances to processes. In that sense, KAR supports a \"serverless\"\nexperience.\n\n## Retry Orchestration\n\nKAR automatically retries failed (i.e., interrupted) actor method invocations.\nRetries are necessary but dangerous. Many other systems\nproactively retry a task when its success is in\ndoubt, for\ninstance if it has not completed by a deadline. As a result, multiple executions\nof a task may happen concurrently. Worse, two tasks in a sequence may end up\nrunning concurrently as a spurious retry of the first one overlaps with the\nsecond. The tasks therefore have to be carefully engineered to be resilient not\nonly to sequential retries, but also concurrent retries, and possible\nreordering. By contrast, KAR is designed to better orchestrate retries---retries\nare more constrained---so as to unburden developers from complex non-local\nreasoning.\n\nTo start with, KAR guarantees that:\n- a failed invocation is retried until success\n- a successfully completed invocation is never retried\n- a strict happens before relationship is preserved across failures within each distributed chain of invocations and retries.\n\nIn other words, KAR will try as many times as necessary, making one attempt\nafter the other, but not once more than necessary.\nKAR goes beyond individual invocations to offer guarantees about nested\ninvocations and chains of invocations.\n- KAR guarantees that a retry of a failed caller will not begin until all of the\nnon-failed callees of the previous execution have completed.\n- KAR introduces a tail call\nmechanism that makes it possible to transactionally transfer control from one\nactor method to another (of the same or a different actor) so that in a chain of\ninvocations, only the last invocation in the chain will be retried even if both\nthe caller and callee actors have failed. Developers still have to worry about\nretries, typically by making individual actor methods idempotent, but, using tail\ncalls, complex code can be broken into smaller pieces that are easier to make\nidempotent.\n\nKAR strives to achieve such guarantees in a dynamic, distributed system with\nminimal overheads.\n\nFor a detailed technical description, see [Reliable Actors with Retry Orchestration](https://arxiv.org/abs/2111.11562).\n\n# KAR Application Mesh\n\nKAR is deployed as a lightweight process, a container, or a Kubernetes sidecar\nthat runs alongside each microservice:\n- The KAR process exposes a REST API to the microservice. Using this API, the\n  microservice can make synchronous and asynchronous requests to other\n  microservices, produce or consume events, or manage its persistent state.\n- This REST API is served over HTTP/1.1 for maximal compatibility as well as\n  HTTP/2 for high performance and scalability.\n\nTogether the KAR processes form a mesh:\n- This mesh can run entirely on a developer's laptop, or entirely within a single Kubernetes cluster,\n  or spanning multiple clusters, servers, VMs, edge devices, etc.\n- This mesh leverages Kafka to decouple the microservices from one another and\n  guarantee reliable request/response and publish/subscribe interactions.\n- This mesh has no leader, no single point of failure, and no external dependency other than\n  a Kafka and Redis instances.\n\n![KAR](docs/images/mesh.png)\n\nUsing the KAR mesh, a typical application interfaces a collection of\nmicroservices, event sources, event sinks, and interactive client/CLI processes.\nConsider for instance the architecture of the simulation engine described in\n[actor-ykt](examples/actors-ykt/README.md). This application combines:\n- a replicated simulator microservice that can be scaled to accommodate many\n  simulated agents.\n- a singleton reporter microservice that produces reports on a schedule or on\n  demand.\n- a controller that runs only when a human operator is controlling the\n  simulator.\n- a notifier that sends reports to a Slack channel.\n\nThe simulator, reporter, and controller are Node.js components implemented in\nJavaScript. The notifier component leverages the Camel runtime and is configured\nby means of a few lines of YAML.\n\nA developer may choose to deploy the simulator to Kubernetes/OpenShift but run\nthe controller on his laptop. The KAR CLI or operator automatically injects and\nconfigures the KAR runtime that runs alongside each component.\n\n# Quick Links\n\n+ See [Getting Started](docs/getting-started.md) for hands-on instructions for\n  trying KAR.\n+ See [KAR Deployment Options](docs/kar-deployments.md) for detailed instructions\n  for deploying KAR-based applications on a wide range of platforms.\n+ Check out our [examples](examples/README.md).\n+ Read about the KAR [Programming Model](docs/KAR.md).\n+ Read a technical description about KAR's approach to fault tolerance: [Reliable Actors with Retry Orchestration](https://arxiv.org/abs/2111.11562).\n+ Check out some larger [applications](https://github.com/IBM/kar-apps) that use KAR.\n+ Browse the Swagger specification of the [KAR API](https://ibm.github.io/kar/api/redoc/).\n+ See [Notes for KAR Developers](docs/kar-dev-hints.md) for detailed\n  instructions on how to build KAR for source.\n\n# License\n\nKAR is an open-source project with an [Apache 2.0 license](LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm%2Fkar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibm%2Fkar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm%2Fkar/lists"}