Deploy to Kubernetes

Deploying the gateway is flexible through different options tailored to diverse infrastructure needs. Users can choose from a multi-platform binary, allowing for installation directly on various operating systems, or opt for a Docker image that integrates seamlessly into containerized environments like Kubernetes. This flexibility enables teams to deploy the gateway in ways that best fit their workflow, whether running on local machines, cloud platforms, or hybrid infrastructures.

Kubernetes is a popular option for container orchestration and is widely adopted for its scalability, reliability, and powerful ecosystem. This ecosystem includes tools like Helm, which greatly simplifies the deployment and management of Kubernetes workloads by offering a templated, versioned, and reusable configuration framework. Helm enables users to package applications into charts, streamlining the deployment of complex workloads consistently across environments.

Grafbase offers an off-the-shelf Helm chart to simplify deploying the gateway. It is hosted on the GitHub Container Registry and adheres to Open Container Initiative (OCI). You can find the chart and its versions in the following location:

https://ghcr.io/grafbase/helm-charts/gateway

The chart comes with a default installation configuration, allowing you to quickly get the gateway up and running with minimal setup. This setup, although functional and easy to start with, requires fine-tuning to accommodate real use cases.

In the following steps, we will start by installing the default configuration and proceed with customizations to include specific settings for:

1. Number of replicas
2. Auto-scaling
3. Compute resources
4. External federated schema
5. External configuration

Before we begin deploying and customizing the deployment, ensure the following prerequisites are met:

1. Kubernetes Cluster: Access to a Kubernetes cluster to deploy the gateway. If you don’t have one available, you can set up a local cluster (e.g: kind).
2. helm: Should be installed. Get started here.
3. kubectl: Should be installed and pointing to the intended cluster. Get started here.

To get started with running the gateway we can simply do the following:

helm install test oci://ghcr.io/grafbase/helm-charts/gateway --version <version>

Once the above complete, verify the gateway is running doing:

kubectl get pods

If everything went accordingly, you should see a pod running with the name test-gateway.

Now that we have a running a gateway, lets leverage a Helm values file to customize the deployment to our needs.

# 1. number of desired replicas running
replicaCount: 2

# 2. auto-scaling behaviour
autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 70

# 3. compute resources
resources:
  limits:
    cpu: 2
    memory: 2Gi
  requests:
    cpu: 1
    memory: 1Gi

# 4. and 5. External schema and configuration from cluster configmaps
gateway:
  externalConfig: true
  externalSchema: true
  args:
    - --config
    - /etc/grafbase/config/config.toml
    - --schema
    - /etc/grafbase/schema/schema.sdl
volumes:
  - name: configuration
    configMap:
      name: grafbase-gateway-configuration
  - name: schema
    configMap:
      name: grafbase-gateway-schema
volumeMounts:
  - name: configuration
    mountPath: /etc/grafbase/config
  - name: schema
    mountPath: /etc/grafbase/schema

The above will:

1. Instruct the deployment to always keep 2 replicas of the gateway running
2. Configure auto-scaling to a minimum of 2 instances and maximum 10, scaling upwards when the deployment experiences 70% of cpu or memory usage across all running replicas.
3. Configure each running replica with at least 1CPU and 1GB of memory with ability to scale up a max of 2CPU and 2GB of memory.
4. Leverage existing cluster configmaps with the desired gateway configuration and federated schema. These are mounted on each running replica, in the configured paths, and made available via arguments when executing the gateway binary.

In order to view all values that can be customized, run the following command:

helm show values oci://ghcr.io/grafbase/helm-charts/gateway --version <version>

In order to reflect our desired customization, we should upgrade our running deployment. Store the customization in a file and run the following:

helm upgrade test oci://ghcr.io/grafbase/helm-charts/gateway --version <version> -f custom-values.yaml

Lets verify our deployment using helm:

helm list

kubectl get pods