{"id":19891351,"url":"https://github.com/lightbend/akka-cluster-operator","last_synced_at":"2025-05-02T18:31:21.126Z","repository":{"id":49203102,"uuid":"177645932","full_name":"lightbend/akka-cluster-operator","owner":"lightbend","description":"Run Akka Cluster applications in Kubernetes.","archived":true,"fork":false,"pushed_at":"2024-09-18T13:51:38.000Z","size":58235,"stargazers_count":69,"open_issues_count":0,"forks_count":14,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-03-16T07:13:28.658Z","etag":null,"topics":["akka-applications","akka-cluster","akka-management","cluster-operator","kubernetes","operator"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":false,"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/lightbend.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}},"created_at":"2019-03-25T18:53:11.000Z","updated_at":"2024-12-29T16:57:00.000Z","dependencies_parsed_at":"2022-09-12T10:00:21.333Z","dependency_job_id":null,"html_url":"https://github.com/lightbend/akka-cluster-operator","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightbend%2Fakka-cluster-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightbend%2Fakka-cluster-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightbend%2Fakka-cluster-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightbend%2Fakka-cluster-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lightbend","download_url":"https://codeload.github.com/lightbend/akka-cluster-operator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252088404,"owners_count":21692789,"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":["akka-applications","akka-cluster","akka-management","cluster-operator","kubernetes","operator"],"created_at":"2024-11-12T18:17:57.483Z","updated_at":"2025-05-02T18:31:16.111Z","avatar_url":"https://github.com/lightbend.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# This project is not maintained and will not see further updates\n\n# Akka Cluster Operator\n\nCard](https://goreportcard.com/badge/github.com/lightbend/akka-cluster-operator)](https://goreportcard.com/report/github.com/lightbend/akka-cluster-operator)\n\nThe Akka Cluster Operator runs applications built with [Akka\nCluster](https://doc.akka.io/docs/akka/current/common/cluster.html) on Kubernetes.\n\nAkka Cluster provides a fault-tolerant, decentralized, peer-to-peer based cluster membership\nservice with no single point of failure. Akka Cluster allows for building distributed\napplications, where one application or service spans multiple nodes.\n\nAkka applications can be run in Kubernetes as plain Deployments using [Akka\nManagement](https://doc.akka.io/docs/akka-management/current/), which provides bootstrap\nvia the Kubernetes API and cluster status via HTTP. See, for example, this [guide to deploying\nLagom on\nOpenShift.](https://developer.lightbend.com/guides/openshift-deployment/lagom/index.html)\nOne can carefully configure the application to keep environment settings separate from\napplication settings, to achieve the ability to deploy the same application into different\nenvironments without rebuilding the application itself.\n\nThis operator builds upon those foundations, providing a top level AkkaCluster resource\nfor interacting with application clusters, giving environmental context to each instance,\nhandling requirements like keeping pod selectors unique and consistently specified, and\nproviding a way to view cluster status in a Kubernetes resource.\n\n![Akka Cluster Operator diagram](doc/images/akka-cluster-operator.png)\n\n## Operator Installation\n\nThe Akka Cluster Operator can be installed from [OperatorHub.io](https://operatorhub.io/operator/akka-cluster-operator).\n\nOperatorHub Operators require the Operator Lifecycle Manager (OLM) controller extensions. With the OLM extensions available, the Akka Cluster Operator can be installed directly from the OperatorHub repository.\n\nSee the installation instructions at [OperatorHub.io](https://operatorhub.io/operator/akka-cluster-operator) for the exact commands.\n\n## Demo application\n\nThe Akka Cluster Operator manages user defined applications built using Akka Cluster and deployed as an [AkkaCluster](https://github.com/lightbend/akka-java-cluster-openshift/blob/master/kubernetes/akka-cluster.yml#L2).\n\n[Akka Cluster visualizer](https://github.com/lightbend/akka-java-cluster-openshift) is an example Java application with those requirements. It forms a cluster, reports\nstatus, and has a visualizer endpoint so you can see the application cluster formation over members\njoining and leaving, and shards rebalancing over the cluster.\n\n## Resources\n\nThe operator and applications under it are loosely coupled. This means the application can\nrun itself and does not require the operator after the initial deployment, so long as top\nlevel resources are the same. The operator is only needed to change the number of\nreplicas, or the application image, or other Deployment level kinds of changes. One can\nthink of this operator as Deployment Plus, meaning is just like a Deployment plus a few\nother things specific to Akka clustering.\n\nEach AkkaCluster resource provides a Deployment spec for an application, which includes a\nnumber of replicas for nodes in the Akka Cluster. The Akka Management component calls the\nKubernetes API to list application pods, as part of determining cluster membership, so\nthis Operator creates a pod-listing ServiceAccount, Role, and RoleBinding suitable for\neach application, as well as supervises the Deployment for the application itself.\n\n![Akka Cluster resources](doc/images/akka-cluster-resources.png)\n\nBy default, the operator will create these sub-resources under each AkkaCluster:\n\n* a ServiceAccount to allow the application to list its own pods. Note that this does\n  _not_ change the default ServiceAccount in the namespace, and every AkkaCluster\n  application has its own ServiceAccount.\n\n* a Role to be a pod-reader, with RoleBinding to connect the ServiceAccount to the role\n\n* Deployment per specification, with default ServiceAccount, pod selector, rolling update\n  strategy, and AKKA_CLUSTER_BOOTSTRAP_SERVICE_NAME environment settings.\n\n## Overriding defaults\n\nThe operator provides a number of defaults, including a ServiceAccount and Role, as\nwell as for selectors, upgrade strategy settings, labels, and environment variables.\nThese defaults are meant to align with common case needs and defaults in Akka Management,\nand are meant to be easily reviewed by inspecting the generated Deployment for your\napplication.\n\nFor example, an AkkaCluster might generate this Deployment, with all the defaults\nlaid out for easy review:\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: akka-cluster-demo\nspec:\n  replicas: 4\n  selector:\n    matchLabels:\n      app: akka-cluster-demo\n  strategy:\n    rollingUpdate:\n      maxSurge: 1\n      maxUnavailable: 0\n    type: RollingUpdate\n  template:\n    metadata:\n      labels:\n        app: akka-cluster-demo\n    spec:\n      containers:\n      - env:\n        - name: AKKA_CLUSTER_BOOTSTRAP_SERVICE_NAME\n          value: akka-cluster-demo\n        image: akka-cluster-demo:1.1.0\n        # ...\n      serviceAccountName: akka-cluster-demo\n```\n\nIf you would like to use your own ServiceAccount, for example, you would set the\n`serviceAccountName` field in the AkkaCluster template spec to your preferred value:\n\n```yaml\napiVersion: app.lightbend.com/v1alpha1\nkind: AkkaCluster\nmetadata:\n  name: akka-cluster-demo\nspec:\n  replicas: 4\n  template:\n    spec:\n      serviceAccountName: my-custom-service-account\n      containers:\n      # - ...\n```\n\nThe operator will notice that you have specified a value and will not create the default\nServiceAccount, Role or RoleBinding, leaving the creation and maintenance of those\nresources alone.\n\nNote that in contrast the default ServiceAccount and Role resources are\ncreated and marked \"owned-by\" the AkkaCluster resource, so that Kubernetes cleans them up\nas a group. If you delete the AkkaCluster, the default sub-resources under it are all\ncleaned up automatically. But if you specify your own ServiceAccount, the operator will\nnot bind it to the AkkaCluster. It will be referenced as you specify, but otherwise left\nalone, meaning your custom resources must be created and deleted independent of the\napplication.\n\nSimilarly if you want different selector, strategy, labels, or any override of a default,\nyou can specify your preferred values in the AkkaCluster spec. The operator will only\nprovide defaults for unspecified fields, and will not override your preferences. The\noperator does not look into your `application.conf` either, so you must make sure you are\napplying environmental configuration consistently where you do not use the defaults.\n\n## Status\n\nEach AkkaCluster resource has a top level `status` section that shows members of the\ncluster, reachability issues, and role assignments. This content is from the point of view\nof the cluster leader, and reflects content from its [Akka Management\nendpoint](https://doc.akka.io/docs/akka-management/current/cluster-http-management.html)\nwhich is located via a named `management` port in the application pod. The operator polls\nthe leader for updates after every resource event.\n\nExample, from `kubectl get akkaclusters -o yaml`:\n\n```yaml\n- apiVersion: app.lightbend.com/v1alpha1\n  kind: AkkaCluster\n  # omitting metadata: and spec: sections\n  status:\n    cluster:\n      leader: akka.tcp://akka-cluster-openshift@172.17.0.10:2552\n      members:\n      - node: akka.tcp://akka-cluster-openshift@172.17.0.10:2552\n        roles:\n        - dc-default\n        status: Up\n      - node: akka.tcp://akka-cluster-openshift@172.17.0.11:2552\n        roles:\n        - dc-default\n        status: Up\n      - node: akka.tcp://akka-cluster-openshift@172.17.0.12:2552\n        roles:\n        - dc-default\n        status: Joining\n      oldest: akka.tcp://akka-cluster-openshift@172.17.0.10:2552\n      oldestPerRole:\n        dc-default: akka.tcp://akka-cluster-openshift@172.17.0.10:2552\n      unreachable: []\n    lastUpdate: \"2019-06-05T22:11:39Z\"\n    managementHost: \"172.17.0.10\"\n    managementPort: 8558\n```\n\nThe `managementHost` and port show the source of this cluster status, so in the above\nexample the data come from\n\n```sh\ncurl http://172.17.0.10:8558/cluster/members/\n```\n\nThe `lastUpdate` timestamp shows the last time that status changed. If you want to see\nwhen the operator last polled for status you can find that in its log.\n\n## Scaling example\n\nTo better understand what happens between the Operator and the Cluster, let's look at the\nscenario of scaling an AkkaCluster up by adding a node. Say the existing cluster is\nalready running at `replicas: 4`\n\n```yaml\napiVersion: app.lightbend.com/v1alpha1\nkind: AkkaCluster\nmetadata:\n  name: akka-cluster-demo\nspec:\n  replicas: 4\n  template:\n    spec:\n      containers:\n      - name: main\n        image: registry.lightbend.com/lightbend-akka-cluster-demo:1.1.0\n        ports:\n        - name: http\n          containerPort: 8080\n        - name: remoting\n          containerPort: 2552\n        - name: management\n          containerPort: 8558\n```\n\nFrom that `AkkaCluster` resource, the Operator has made a `Deployment`, a `ServiceAccount`, `Role`\nand `RoleBinding`, and has set workable defaults for Akka Management. These defaults include\n\n* `spec.selector` so the ReplicaSet works correctly and on the same selector basis as Akka\n  Bootstrap\n* `spec.strategy` to get one-at-a-time rolling updates with no reduction in capacity\n* `spec.template.metadata.labels.app` set to the unique name of this cluster\n* container environment variable `AKKA_CLUSTER_BOOTSTRAP_SERVICE_NAME` set to that same\n  value so Akka Bootstrap works on the same basis as the ReplicaSet\n\n### Scale Up\n\nNow set `replicas: 5`. The Operator will propagate that change down to the Deployment. A\nnew pod with the same `template` will start. The Operator will start polling the cluster\nleader for status changes.\n\n![Akka Cluster Scale New Pod](doc/images/akka-cluster-scale-new-pod.png)\n\nOnce the application in the new pod starts, it initiates Akka Bootstrap. By way of the\nServiceAccount that permits reading pods, it gets a list of pods from Kubernetes. These\npods have the unique label `app=${AKKA_CLUSTER_BOOTSTRAP_SERVICE_NAME}` and are in the\nRunning phase, not marked for deletion, to avoid old or soon-to-be-deleted pods. In our\ncase it lists the 4 running pods in the cluster and starts gossip connections with them.\nThe leader will add the node to the members list and mark it as **Joining** the cluster.\n\nThe Operator will update status to show the new node, and keep polling for status changes.\n\n![Akka Cluster Scale Joining](doc/images/akka-cluster-scale-joining.png)\n\nPresuming all is well and the cluster members can reach the new node, the leader will\npromote it to **Up** and it will start taking cluster work.\n\nThe Operator will update status to show the new **Up** node, and from here will likely not\nget further status changes until some future change to pod resources.\n\n![Akka Cluster Scale Up](doc/images/akka-cluster-scale-up.png)\n\n## Application requirements\n\nThe AkkaCluster Operator is for use with applications using [Akka Management](https://doc.akka.io/docs/akka-management/current/) v1.x or newer, with both [Bootstrap](https://doc.akka.io/docs/akka-management/current/bootstrap/index.html) and [HTTP](https://doc.akka.io/docs/akka-management/current/cluster-http-management.html) modules enabled, and a management port defined to use discovery.\n\nThe minimal `application.conf` settings required are to enable kubernetes discovery:\n\n```hcon\nakka.management {\n  cluster.bootstrap {\n    contact-point-discovery {\n      discovery-method = kubernetes-api\n    }\n  }\n}\n```\nThe `ActorSystem` name should be unique for each desired application cluster.\n\nAs noted in [Akka Cluster Bootstrap](https://doc.akka.io/docs/akka-management/current/bootstrap/index.html#using) \"Akka management must be started as well as the bootstrap process.\" Be certain to include:\n\n```\n// Akka Management hosts the HTTP routes used by bootstrap\nAkkaManagement.get(system).start();\n\n// Starting the bootstrap process needs to be done explicitly\nClusterBootstrap.get(system).start();\n```\n## References\n\n* [Akka](https://doc.akka.io/docs/akka/current/guide/introduction.html)\n* [Akka Cluster](https://doc.akka.io/docs/akka/current/common/cluster.html)\n* [Developer guide](hacking.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flightbend%2Fakka-cluster-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flightbend%2Fakka-cluster-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flightbend%2Fakka-cluster-operator/lists"}