Code module: Scaling

This document explains how the Code module sizes and scales Kubernetes workloads based on CodeInstance scaling settings.

Key parameters

• spec.scaling.targetUserCount: sizing profile (expected user load). Supported values: 100, 1000, 3000, 5000 (10 exists for internal development use only; see warning below).
• spec.scaling.highAvailability: HA mode switch. When enabled, the operator creates and configures autoscaling and disruption-protection resources (see next section).
• spec.gitData.resources: manual override for Gitaly CPU/memory (takes precedence over spec.scaling.targetUserCount).
• spec.gitData.replicas: Gitaly replicas in HA mode (optional; if not set, the operator uses defaults for HA).

How HA and performance are achieved (what the operator configures)

When HA mode is enabled (spec.scaling.highAvailability: true), the operator uses standard Kubernetes primitives to improve resiliency and keep the system responsive under load:

• Multiple replicas (Deployments/StatefulSets): services run with more than one replica, so a single Pod/Node failure does not stop the service.
• Horizontal Pod Autoscaler (HPA): automatically increases/decreases replicas based on CPU metrics; tuned per targetUserCount for key components. This provides extra throughput during peaks without permanently overprovisioning.
• PodDisruptionBudget (PDB): limits how many Pods can be evicted during voluntary disruptions (node drain, upgrades), reducing the risk of downtime during maintenance.
• Pod anti-affinity (preferred): Pods are preferably spread across nodes (by kubernetes.io/hostname) to reduce blast radius of node failures and avoid contention/noisy-neighbor effects when there are enough nodes.

When HA mode is disabled, the operator keeps a simpler “standalone” topology (single replica for many services) and removes HPA/PDB objects.

Warning Any “burstable” instance types in cloud infrastructure are not recommended due to inconsistent performance.

spec.scaling.targetUserCount: 10 is intended exclusively for internal use by developers. Using this value in any other environments is not recommended and may lead to system instability or unexpected behavior.

Sizing reference (resources)

All calculations are based on spec.scaling.targetUserCount.

The tables below show resources for a single replica of each component. In HA mode, plan for at least 2 replicas for horizontally-scaled services (i.e. at least ~2× capacity vs. “one replica” numbers), plus headroom for autoscaling.

Standalone mode (spec.scaling.highAvailability: false)

HA mode (spec.scaling.highAvailability: true)

Optional components are marked with *.

Autoscaling (HA mode)

In HA mode, key components are configured with HPA. Some targetUserCount profiles have specific max replica limits.

Optional components are marked with *.

Tuning Git storage (Gitaly)

If you see a non-empty ‘OOM events’ table in Grafana or a firing GitalyCgroupMemoryOOM alert in Prometheus, you likely need to adjust the memory and CPU resources for Gitaly. Increase the spec.gitData.resources in your configuration ( e.g., set memory to 16Gi and CPU to 4). After updating, apply the changes and monitor Gitaly for improvements.

When scaling Git storage, the following parameter precedence must be observed:

1. spec.gitData.resources
2. spec.scaling.targetUserCount

Example 1:

`spec.gitData.resources.cpu`: 1  
`spec.gitData.resources.memory`: 1Gi  
`spec.scaling.targetUserCount`: 3000

Based on the resource table described above, we would expect:

• memory: 4Gi
• cpu: 2

However, due to parameter precedence, the actual result will be:

• memory: 1Gi
• cpu: 1

💡 Note: When a parameter is explicitly set in spec.gitData.resources, it always takes precedence over the automatic calculation.

Example 2:

`spec.gitData.resources.cpu`: 5  
`spec.gitData.resources.memory`: ***intentionally omitted***  
`spec.scaling.targetUserCount`: 3000

Based on the resource table described above, we would expect:

• memory: 4Gi
• cpu: 2

However, because of parameter precedence—and since spec.gitData.resources.memory was not specified—the actual result will be:

• memory: 4Gi (from the scaling table)
• cpu: 5 (from spec.gitData.resources.cpu)

💡 Important: If any resource (CPU or memory) is not specified in spec.gitData.resources, the value from the scaling table is applied.

For other profiles/components, the operator may use default HPA min/max values.