> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/set-up-build-infrastructure/k8s-build-infrastructure/customize-podspec.md).

# Customize the PodSpec in Kubernetes build infrastructure

Harness CI supports advanced customization of the Kubernetes PodSpec used for your build pods. You can use this to apply configurations like projected volumes, custom security contexts, node selectors, and topology spread constraints.

{% hint style="info" %}
**FEATURE FLAG REQUIRED**

This feature is gated by the feature flag `CI_K8S_OVERLAY_YAML` and requires Harness Delegate version `863xx` or higher.
{% endhint %}

### Overview <a href="#overview" id="overview"></a>

Once the `CI_K8S_OVERLAY_YAML` flag is enabled, you can reuse the **Pod Spec Overlay** field in the build infrastructure settings to pass a partial Kubernetes Pod YAML that overrides the default pod created by Harness CI.

* The YAML must follow the standard Kubernetes PodSpec structure.
* You only need to specify the fields you want to override.
* `spec.containers` is supported (for existing containers only).
* Fields like `spec.initContainers` are **ignored** if passed — you can't override them.

### Examples <a href="#examples" id="examples"></a>

#### Add a projected volume <a href="#add-a-projected-volume" id="add-a-projected-volume"></a>

```yaml
spec:
  volumes:
    - name: projected-vol
      projected:
        sources:
          - configMap:
              name: my-config
          - secret:
              name: my-secret
```

#### Set a primary group ID for the build container <a href="#set-a-primary-group-id-for-the-build-container" id="set-a-primary-group-id-for-the-build-container"></a>

```yaml
spec:
  securityContext:
    runAsGroup: 15
```

#### Override container resources (ephemeral-storage) for an existing step <a href="#override-container-resources-ephemeral-storage-for-an-existing-step" id="override-container-resources-ephemeral-storage-for-an-existing-step"></a>

```yaml
spec:
  containers:
    - name: container-blah
      image: nginx:1.14
      ports:
        - containerPort: 80
    - name: step-1
      resources:
        requests:
          ephemeral-storage: "400Mi"   
        limits:
          ephemeral-storage: "500Mi"
```

### Transition from legacy format <a href="#transition-from-legacy-format" id="transition-from-legacy-format"></a>

Previously, the Pod Spec Overlay field only supported `topologySpreadConstraints`, and you could pass them without nesting under `spec:`. That changes with the feature flag.

#### Before (feature flag OFF) <a href="#before-feature-flag-off" id="before-feature-flag-off"></a>

When the feature flag is off, you can pass fields directly like this:

```yaml
topologySpreadConstraints:
  - maxSkew: 3
    minDomains: 2
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: DoNotSchedule
    labelSelector:
      matchExpressions:
        - key: app
          operator: In
          values:
            - my-app
```

Harness automatically injected this into the pod under the hood.

#### After (feature flag ON) <a href="#after-feature-flag-on" id="after-feature-flag-on"></a>

Once the feature flag is on, Harness expects a proper PodSpec YAML structure. You must wrap your fields inside a `spec:` block:

```yaml
spec:
  topologySpreadConstraints:
    - maxSkew: 3
      minDomains: 2
      topologyKey: topology.kubernetes.io/zone
      whenUnsatisfiable: DoNotSchedule
      labelSelector:
        matchExpressions:
          - key: app
            operator: In
            values:
              - my-app
```

{% hint style="warning" %}
If you leave out the `spec:` wrapper while the feature flag is on, the pod override will fail and your build will likely error out.
{% endhint %}

Best Practices

* Only include the fields you want to override.
* Always use the `spec:` wrapper if the feature flag is enabled.
* You can override both pod-level and container-level fields. Non-existent container names are ignored.
* Do not pass `spec.initContainers` — this cannot be overridden.
* Invalid YAML or unsupported fields can cause your build to fail.

For more background, check out [Topology Spread Constraints](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/k8s-build-infrastructure/set-up-a-kubernetes-cluster-build-infrastructure.md#topology-spread-constraints) which were previously supported without this feature flag.