How to Deploy TSID for Distributed ID Generation: From Local Setup to Multi‑Cluster Kubernetes

Quick Start

Start by adding the Maven dependency com.github.f4b6a3:tsid-creator:5.2.6 to pom.xml, compile the project, and write a minimal main method that calls TsidCreator.getTsid(). The returned Tsid can be converted to a long with toLong() for storage in a BIGINT column, or to a 13‑character Crockford Base32 String with toString() for API responses. The example prints the numeric value, the string representation, the embedded timestamp, and verifies that converting back yields the original ID.

Each call to TsidCreator.getTsid() generates a new ID; toLong() and toString() merely change the representation and do not create additional IDs.

Spring Boot Integration

Create a configuration class that registers a singleton TsidFactory bean:

@Configuration
public class TsidConfiguration {
    @Bean
    public TsidFactory tsidFactory() {
        // Spring creates this bean once.
        // The factory reads TSIDCREATOR_NODE and TSIDCREATOR_NODE_COUNT.
        return new TsidFactory();
    }
}

Wrap the factory in a component that business code can inject:

@Component
public class TsidGenerator {
    private final TsidFactory factory;
    public TsidGenerator(TsidFactory factory) {
        this.factory = factory;
    }
    public Tsid next() {
        return factory.create();
    }
}

Application code now calls tsidGenerator.next() without directly referencing the static creator. The factory holds the node configuration and is shared across all threads.

Node and NodeCount Configuration

The factory reads two values:

node – the identifier of the current instance (similar to workerId in Snowflake).

nodeCount – the total size of the node space reserved for the whole system.

If neither is set, the factory defaults to a space of 1,024 nodes and picks a random node number at startup. If only nodeCount is set, the node is still chosen randomly within that space. If only node is set, the default node space is used.

The values can be supplied via JVM system properties ( -Dtsidcreator.node=… -Dtsidcreator.node.count=…) or environment variables ( TSIDCREATOR_NODE, TSIDCREATOR_NODE_COUNT). System properties take precedence over environment variables.

Deployment Scenarios

1. Fixed Machines (Physical/VM/Container)

Manually assign a unique node to each instance and set nodeCount to the maximum number of instances (e.g., 64).

Supply the values via export TSIDCREATOR_NODE=3 and export TSIDCREATOR_NODE_COUNT=64 before starting the Java process, or use the corresponding -D JVM flags.

2. Single Kubernetes Cluster

Prefer a StatefulSet so each pod receives a stable ordinal.

Expose the pod ordinal to the container with an environment variable that reads the label apps.kubernetes.io/pod-index:

env:
  - name: TSIDCREATOR_NODE
    valueFrom:
      fieldRef:
        fieldPath: metadata.labels['apps.kubernetes.io/pod-index']
  - name: TSIDCREATOR_NODE_COUNT
    value: "64"

The factory reads these variables at startup; a rolling restart is required after any change.

3. Multiple Kubernetes Clusters

Reserve a distinct node range for each cluster (e.g., cluster A uses 0‑31, cluster B uses 32‑63).

Define a constant CLUSTER_BASE per cluster and combine it with the pod ordinal inside the container entrypoint:

env:
  - name: POD_ORDINAL
    valueFrom:
      fieldRef:
        fieldPath: metadata.labels['apps.kubernetes.io/pod-index']
  - name: CLUSTER_BASE
    value: "32"
  - name: TSIDCREATOR_NODE_COUNT
    value: "64"
command: ["/bin/sh", "-c"]
args:
  - |
    export TSIDCREATOR_NODE=$((CLUSTER_BASE + POD_ORDINAL))
    exec java -jar /app/app.jar

All clusters share the same TSIDCREATOR_NODE_COUNT (the total reserved nodes). When a new cluster is added, adjust the base values and, if necessary, increase the overall count.

Key Takeaways

The TSID creator is a lightweight, single‑call API for generating globally unique IDs.

Node assignment is the only coordination required; the library itself handles time‑ordering and per‑node counters.

Configuration is read once at factory initialization, so environment changes require a pod restart.

Using StatefulSet pod ordinals or a calculated base+ordinal scheme enables safe node allocation across single or multiple Kubernetes clusters without external coordination services.