{"id":18425581,"url":"https://github.com/atomix/atomix-controller","last_synced_at":"2025-04-07T16:31:50.014Z","repository":{"id":42679126,"uuid":"189267520","full_name":"atomix/atomix-controller","owner":"atomix","description":"Kubernetes controller for Atomix 4","archived":false,"fork":false,"pushed_at":"2023-02-06T23:48:26.000Z","size":15160,"stargazers_count":11,"open_issues_count":5,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-03T05:05:11.554Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atomix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSES/Apache-2.0.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":"2019-05-29T17:11:20.000Z","updated_at":"2024-03-12T03:10:56.000Z","dependencies_parsed_at":"2024-06-18T21:35:18.343Z","dependency_job_id":"bd31ce50-3aab-4f31-83d7-4818077174f5","html_url":"https://github.com/atomix/atomix-controller","commit_stats":null,"previous_names":["atomix/controller","atomix/kubernetes-controller"],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomix%2Fatomix-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomix%2Fatomix-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomix%2Fatomix-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomix%2Fatomix-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atomix","download_url":"https://codeload.github.com/atomix/atomix-controller/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247687978,"owners_count":20979574,"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-11-06T05:04:27.890Z","updated_at":"2025-04-07T16:31:49.460Z","avatar_url":"https://github.com/atomix.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: 2019-present Open Networking Foundation \u003cinfo@opennetworking.org\u003e\nSPDX-License-Identifier: Apache-2.0\n--\u003e\n\n# Atomix Kubernetes atomix-controller\n\n[![Build Status](https://travis-ci.org/atomix/atomix-controller.svg?branch=master)](https://travis-ci.org/atomix/atomix-controller)\n[![Integration Test Status](https://img.shields.io/travis/atomix/atomix-controller?label=Atomix%20Tests\u0026logo=Atomix)](https://travis-ci.org/onosproject/onos-test)\n[![Go Report Card](https://goreportcard.com/badge/github.com/atomix/atomix-controller)](https://goreportcard.com/report/github.com/atomix/atomix-controller)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/gojp/goreportcard/blob/master/LICENSE)\n[![GoDoc](https://godoc.org/github.com/atomix/atomix-controller?status.svg)](https://godoc.org/github.com/atomix/atomix-controller)\n\nThis project provides an [Atomix] controller for [Kubernetes]. The controller\nimplements the Atomix controller API and uses [custom Kubernetes resources][custom-resources]\nto provide seamless integration, allowing standard k8s tools to be used to deploy and scale\npartition groups and partitions. For more information see [how it works](#how-it-works).\n\n## Deployment\n\nTo deploy the controller, use the `atomix-controller.yaml` manifest:\n\n```bash\n\u003e kubectl create -f https://raw.githubusercontent.com/atomix/atomix-controller/master/deploy/atomix-controller.yaml\ncustomresourcedefinition.apiextensions.k8s.io/databases.cloud.atomix.io created\ncustomresourcedefinition.apiextensions.k8s.io/partitions.cloud.atomix.io created\ncustomresourcedefinition.apiextensions.k8s.io/members.cloud.atomix.io created\ncustomresourcedefinition.apiextensions.k8s.io/primitives.cloud.atomix.io created\nserviceaccount/atomix-atomix-atomix-controller created\nclusterrole.rbac.authorization.k8s.io/atomix-atomix-atomix-controller created\nclusterrolebinding.rbac.authorization.k8s.io/atomix-atomix-atomix-controller created\nservice/atomix-atomix-atomix-controller created\ndeployment.apps/atomix-atomix-atomix-controller created\n```\n\n## Usage\n\nThe `controller` is the primary controller for deploying Atomix `Database`s in [Kubernetes]. The controller\nadds a number of custom resources to the k8s cluster:\n* `Database` is used to deploy new databases\n* `Partition` is used by clients to partition databases\n* `Member` is used by clients for peer-to-peer protocols\n* `Primitive` is used to store metadata about distributed primitives\n\nIn order to deploy a `Database`, you must first deploy a storage controller to manage a specific type of database:\n* [`atomix/raft-storage-controller`](https://github.com/atomix/raft-storage-controller) adds support for Raft primitive databases\n* [`atomix/cache-storage-controller`](https://github.com/atomix/cache-storage-controller) adds support for in-memory cache primitive databases\n* [`atomix/redis-storage-controller`](https://github.com/atomix/redis-storage-controller) adds support for Redis primitive databases\n\nOnce a storage controller has been deployed, you can create a storage configuration and `Database`:\n\n```yaml\napiVersion: storage.cloud.atomix.io/v1beta1\nkind: RaftStorageClass\nmetadata:\n    name: raft\n    labels:\n      app: raft\nspec:\n  image: atomix/raft-replica:latest\n  imagePullPolicy: IfNotPresent\n  replicas: 3\n---\napiVersion: cloud.atomix.io/v1beta2\nkind: Database\nmetadata:\n  name: raft\nspec:\n  clusters: 3\n  template:\n    spec:\n      partitions: 1\n      storage:\n        group: storage.cloud.atomix.io\n        version: v1beta1\n        kind: RaftStorageClass\n        name: raft\n        namespace: kube-system\n```\n\nUse `kubectl` to create the database:\n\n```bash\n\u003e kubectl create -f raft.yaml\nraftstorageclass.storage.cloud.atomix.io/raft created\ndatabase.cloud.atomix.io/raft created\n```\n\nOnce the database has been created, you should be able to see it with `kubectl`:\n\n```bash\n\u003e kubectl get databases\nNAME   AGE\nraft   12s\n```\n\nThe database will create a number of partitions equal to the `partitions` defined\nin the database spec:\n\n```bash\n\u003e kubectl get partitions\nNAME     AGE\nraft-1   57s\nraft-2   57s\nraft-3   57s\n```\n\nEach cluster will create a `StatefulSet`:\n\n```bash\n\u003e kubectl get statefulsets\nNAME     READY   AGE\nraft-1   1/1     2m11s\nraft-2   1/1     2m11s\nraft-3   1/1     2m11s\n```\n\nAnd each `StatefulSet` contains a number of pods equal to the storage class's `replicas`:\n\n```bash\n\u003e kubectl get pods\nNAME       READY   STATUS    RESTARTS   AGE\nraft-1-0   1/1     Running   0          74s\nraft-1-1   1/1     Running   0          74s\nraft-1-2   1/1     Running   0          74s\nraft-2-0   1/1     Running   0          74s\nraft-2-1   1/1     Running   0          74s\nraft-2-2   1/1     Running   0          74s\nraft-3-0   1/1     Running   0          74s\nraft-3-1   1/1     Running   0          74s\nraft-3-2   1/1     Running   0          74s\n...\n```\n\nA `Service` will be created for each partition in the group as well:\n\n```bash\n\u003e kubectl get services\nNAME         TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE\nraft-1       ClusterIP   10.98.166.215   \u003cnone\u003e        5678/TCP   95s\nraft-2       ClusterIP   10.109.34.146   \u003cnone\u003e        5678/TCP   95s\nraft-3       ClusterIP   10.99.37.182    \u003cnone\u003e        5678/TCP   95s\n...\n```\n\nOnce the database is deployed and ready, it can used to create and operate on \ndistributed primitives programmatically using any [Atomix client][atomix-go-client]:\n\n```go\nimport (\n\tatomixclient \"github.com/atomix/go-client/pkg/client\"\n)\n\nclient, err := atomixclient.New(\"atomix-controller.kube-system.svc.cluster.local:5679\")\nif err != nil {\n\t...\n}\n\ngroup, err := client.GetGroup(context.TODO(), \"raft\")\nif err != nil {\n\t...\n}\n\nlock, err := group.GetLock(context.TODO(), \"my-lock\")\nif err != nil {\n\t...\n}\n\nid, err := lock.Lock(context.TODO())\nif err != nil {\n\t...\n}\n```\n\n## How it works\n\nAtomix 4 provides a framework for building, running and scaling replicated state machines\nusing a variety of protocols (e.g. Raft consensus, primary-backup, distributed log, etc) and\nexports a gRPC API for operating on replicated state machines. Atomix primitives are designed\nto scale through partitioning, but the Atomix core framework does not handle partitioning itself.\nInstead, it exports a gRPC API for implementing Atomix controllers and leaves partition\nmanagement to environment-specific controller implementations like this one.\n\nThe Atomix k8s controller implements the Atomix 4 controller API and runs inside Kubernetes to\nmanage deployment of partition groups and partitions using\n[custom resource controllers][custom-resources].\n\n![Kubernetes Controller Architecture](https://i.imgur.com/9YkdF3D.png)\n\nDatabases and partitions can be managed either through the\n[Atomix client API][atomix-go-client] or using standard Kubernetes tools like `kubectl`.\n\nThe Atomix controller manages databases, and add-on storage controllers deploy specific types \nof databases. When a `Database` is created, the database's storage controller is triggered to\ncreate the appropriate `StatefulSet`s, `Service`s, and other resources for the database and\nits partitions.\n\n![Storage Controller](https://i.imgur.com/rrabEYY.png)\n\n[Atomix]: https://atomix.io\n[Kubernetes]: https://kubernetes.io\n[custom-resources]: https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/\n[atomix-go-client]:https://github.com/atomix/go-client\n[Raft]: https://raft.github.io/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatomix%2Fatomix-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatomix%2Fatomix-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatomix%2Fatomix-controller/lists"}