Quick Start

This guide walks you through installing the operator, deploying a three-node GridGain 9 cluster, and verifying that everything is working.

Prerequisites

A valid GridGain 9 license.
A Kubernetes cluster running version 1.22 or later. The operator uses apiextensions.k8s.io/v1 CRDs and server-side apply, both of which require Kubernetes 1.22+.
kubectl configured with administrative access to the target cluster.
Container registry access: The default controller image is gridgain/gridgain9-k8s-operator:0.1.0 on Docker Hub. If you use a private registry or custom image, adjust the Deployment in resources/controller-resources.yaml before applying it.

Install the Operator

Installation is a two-step process: you apply the Custom Resource Definition first, then deploy the controller and its supporting resources.

Install the CRD

Download the Custom Resource Definition file and apply it to register the GridGain9Cluster resource type with the Kubernetes API server:

kubectl apply --server-side=true -f crd.yaml

The --server-side=true flag is recommended. Client-side application may fail or time out on objects of this size.

Install Controller Resources

Download the controller manifest file and apply it:

kubectl apply --server-side=true -f controller-resources.yaml

This creates the gridgain9-system namespace, a dedicated ServiceAccount, default roles and bindings, a metrics service, and the gridgain9-controller-manager Deployment.

Verify the Installation

Confirm that the CRD is registered and the controller is running:

# Checks if CRD is installed.
kubectl get crd gridgain9clusters.gridgain-9.gridgain.com
# Checks if the controller is created.
kubectl get deployment -n gridgain9-system gridgain9-controller-manager
# Checks if the controller pod is running.
kubectl get pods -n gridgain9-system

The gridgain9clusters resource should appear in the CRD list, and the controller pod should be in a Running state.

Deploy a Cluster

Create a License Secret

GridGain 9 requires a license for cluster initialization. In this tutorial, we will create a secret to safely manage the license. Create a Kubernetes Secret from your license file:

kubectl create secret generic gridgain-license \
  --from-file=license.conf=/path/to/your/license.json

The Secret must reside in the same namespace where you will create the GridGain9Cluster resource.

For quick tests or demos, you can skip the Secret and embed the license content directly in the manifest using spec.license.content.

Apply the Cluster Manifest

Create a file named simple-cluster.yaml with the following content:

apiVersion: gridgain-9.gridgain.com/v1
kind: GridGain9Cluster
metadata:
  name: simple-cluster
spec:
  replicas: 3
  image:
    registry: docker.io
    repository: gridgain/gridgain9
    tag: "9.1.22"
  persistence:
    enabled: true
    size: 20Gi
  license:
    secretName: gridgain-license
    secretKey: license.conf
    mountPath: /opt/gridgain/etc/license.conf

Then, apply it:

kubectl apply -f simple-cluster.yaml

This deploys a three-node cluster as specified in the replicas configuration, with 20Gi persistent volumes for each. The operator creates a StatefulSet, a headless service for node discovery, and a Job to initialize the cluster with your license.

Verify the Deployment

Watch the cluster resource until the Phase shows Running:

kubectl get gg9 simple-cluster

Check that all pods are ready:

kubectl get pods -l app.kubernetes.io/instance=simple-cluster

Verify the cluster topology from inside a pod:

# Checks if all nodes are running, found each other and formed a topology
kubectl exec simple-cluster-0 -- /opt/gridgain9cli/bin/gridgain9 cluster topology physical
# Checks cluster status
kubectl exec simple-cluster-0 -- /opt/gridgain9cli/bin/gridgain9 cluster status
# Checks if all nodes are correctly included in the cluster
kubectl exec simple-cluster-0 -- /opt/gridgain9cli/bin/gridgain9 cluster topology logical

Use the CLI Tool

Once the cluster is running, the GridGain CLI tool is available inside each pod at /opt/gridgain9cli/bin/gridgain9. For this tutorial, we will connect to a node in the cluster, and then use the CLI tool to execute some simple queries.

First, open an interactive shell on one of the pods:
```
kubectl exec -it simple-cluster-0 -- bash
```
From inside the pod, start the CLI tool:
```
/opt/gridgain9cli/bin/gridgain9
```
Confirm the connection to the cluster, then enter the SQL REPL mode by typing sql.

Create a table:

CREATE TABLE IF NOT EXISTS Person (id int primary key, city varchar, name varchar, age int, company varchar);

Insert some data:

INSERT INTO Person (id, city, name, age, company) VALUES (1, 'London', 'John Doe', 42, 'Apache');
INSERT INTO Person (id, city, name, age, company) VALUES (2, 'New York', 'Jane Doe', 36, 'Apache');

Query the data:
```
SELECT * FROM Person;
```
To leave the SQL REPL mode, type exit;.

For more information about available SQL statements, see the SQL Reference section.

Clean Up

To remove the cluster and all resources the operator created for it:

kubectl delete gg9 simple-cluster

The operator uses a finalizer to ensure graceful shutdown and cleanup of all nodes.

The operator does not clean up persist files created for nodes. If the cluster is restarted later, it will use the same persistence. To fully clean up remaining files for a clean restart:

kubectl delete pvc persistence-simple-cluster-0 persistence-simple-cluster-1 persistence-simple-cluster-2

To remove the operator itself, remove the CRD and the resources:

kubectl delete -f controller-resources.yaml
kubectl delete -f crd.yaml

© 2026 GridGain Systems, Inc. All Rights Reserved. Privacy Policy | Legal Notices. GridGain® is a registered trademark of GridGain Systems, Inc.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.

Last updated on May 08, 2026