Skip to content

Getting Started

Writing an application

Atomix provides language-specific SDKs for building applications.

The Go SDK requires at least Go 1.19 for generics support. To add the SDK to your Go module:

go get

Distributed primitives are created using a builder pattern:

m, err := atomix.Map[string, string]("my-map").
if err != nil {

Each distributed primitive must be assigned a string name, and state is shared across pods that reference primitives of the same name. For example, if pod-1 creates a primitive named foo, and pod-2 creates a primitive named foo, both primitives will point to the same logical state.


The SDK is designed to run inside a Kubernetes pod where it connects to the Atomix runtime proxy sidecar container on a fixed port and therefore does not need to be configured by the application. For advanced configuration and testing, see the Go SDK documentation.

Once you’ve created your desired primitive, use the interface to store and share state with other pods:

entry, err := m.Put(context.Background(), "foo", "bar")
if err != nil {

entry, err = m.Get(context.Background(), "foo")
if err != nil {

For detailed documentation on the primitives and APIs available in the Go SDK, see the user guide.

The Java SDK is distributed through Maven Central. To add the SDK to your Maven dependencies:


A builder pattern is used to construct distributed primitives:

AtomicMap<String, String> map = AtomicMap.builder("my-map")

Each primitive interface exposes empty

Installing the runtime

Atomix extends the Kubernetes API with numerous custom resources and controllers to orchestrate stores and applications. Collectively, these components are referred to as the Atomix runtime.

To install the runtime, it’s recommended you use the atomix-runtime Helm chart, which can be found in the Atomix Helm charts repo at

> helm repo add atomix

Update the Helm repository cache to ensure you have the latest copy of the atomix-runtime chart:

> helm repo update

The runtime should be installed in the kube-system namespace, where other Kubernetes controllers are deployed, to prevent controllers from being deleted:

> helm install -n kube-system atomix-runtime atomix/atomix-runtime --wait

The atomix-runtime chart deploys numerous controllers to the target namespace, each providing orchestration for a different type of data store.

> kubectl get pods -n kube-system
NAME                                                       READY   STATUS    RESTARTS   AGE
atomix-runtime-consensus-controller-5f6cd7c8b5-qzzl8       1/1     Running   0          104s
atomix-runtime-controller-5fd8c86f99-h7tp4                 1/1     Running   0          104s
atomix-runtime-pod-memory-controller-857b8dc557-js7lf      1/1     Running   0          104s
atomix-runtime-shared-memory-controller-8565cd5f94-m7s9v   1/1     Running   0          104s

Deploying a data store

To deploy an application, you must first deploy a data store to be used by the application. The runtime provides a variety of data stores to choose from, but the simplest is the SharedMemoryStore:

kind: SharedMemoryStore
  name: my-data-store
spec: {}

Once you’ve defined the store, deploy it using kubectl:

> kubectl create -f data-store.yaml

The SharedMemoryStore will deploy a single pod to hold primitive state in memory. To enable persistence and/or replication, explore the data stores.

Configuring the application

kind: StorageProfile
  name: my-application
    - store:
        name: my-data-store
> kubectl create -f storage-profile.yaml
apiVersion: apps/v1
kind: Deployment
  name: my-application
      name: my-application
        name: my-application
      annotations: "true" "my-application"
> kubectl create -f application.yaml