---
sidebar_label: Configuration-based overrides
doc_id: f4ab9037-5cc8-47db-bc03-21cf9dda9cd2
description: >-
  Configure agent-backed scopes without code by adding a values.yaml file to
  override default settings and behavior.
keywords:
  - configuration
  - overrides
  - values.yaml
  - kubernetes
  - agent-backed-scopes
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';


# Make configuration-based overrides

Configuration-based overrides let you change how a scope behaves by updating its default settings
**without writing or editing any workflows or scripts**. All you need to do is add a `values.yaml` file to your
override repo.

This is a good option when you want to:
- Tweak default behavior
- Enable optional features
- Swap in your own manifest templates
  
## How it works

Each scope defines a set of configuration values it reads at runtime. When the scope runs, the agent checks if your
override repo contains a `values.yaml` file. If it does, your values will be merged with the base scope’s configuration.
Any matching keys in your file will override the default values.

You can see the default config values for the Kubernetes scope here:  
[nullplatform/scopes/k8s/values.yaml](https://github.com/nullplatform/scopes/blob/main/k8s/values.yaml)

:::important
After changing your override repo, you’ll need to [**refresh the agent sources**](/docs/agent/agent-refresh.md) so it
pulls the latest code.
:::

## Where to put `values.yaml`

Your override file should be placed at the **root** of your override repo.


### Example repo structure

```
your-override-repo/
├── values.yaml
```

> Need help setting up the repo and agent?  
> See the [environment setup guide](/docs/agent-backed-scopes/overrides/setup).


---

## Example 1: Add a label to your deployment

The Kubernetes base scope supports customizing **labels and annotations** for any Kubernetes object it creates, such
as Ingress, Service, or Deployment.

For example, if you want to label every deployment with the business unit it belongs to, use the `K8S_MODIFIERS`
key.

In your override repo’s `values.yaml`:

```yaml
configuration:
  K8S_MODIFIERS:
    deployment:
      labels:
        business_unit: payments
```

Now every deployment created by the scope will include this label.

```bash
kubectl get deployment -l "business_unit=payments"
```

This can be useful for filtering deployments or integrating with monitoring tools.

---

## Example 2: Use a different manifest template

The scope allows you to override the templates it uses to generate Kubernetes objects. This is helpful if you want to
change how resources like Ingresses or Services are created.

You can override the default manifest templates used by the scope. For example, if you want to replace the default
`Ingress` with Gateway API and Istio’s `HTTPRoute`.


In your override repo’s `values.yaml`:

```yaml
configuration:
  INITIAL_INGRESS_PATH: "$SERVICE_PATH/deployment/templates/istio/initial-httproute.yaml.tpl"
  BLUE_GREEN_INGRESS_PATH: "$SERVICE_PATH/deployment/templates/istio/blue-green-httproute.yaml.tpl"
```

This replaces the default ingress templates for both the initial and blue-green deployment strategies.

> The nullplatform Kubernetes scope includes example templates for this, check the
> [Istio templates here](https://github.com/nullplatform/scopes/tree/main/k8s/deployment/templates/istio).

---

## Example 3: Enable IAM Role for Service Accounts (IRSA)


The Kubernetes scope supports enabling IRSA. This feature lets you associate an AWS IAM Role with your scope,
so your applications can access cloud resources securely (e.g. S3, DynamoDB).

Here’s a simple example to enable IRSA and attach a policy:


```yaml
IAM:
  ENABLED: true
  PREFIX: nullplatform-scopes
  ROLE:
    POLICIES:
      - TYPE: arn
        VALUE: arn:aws:iam::aws:policy/AmazonS3FullAccess
```

You can include multiple policies:
- `TYPE: arn` (like in the example above)
- `TYPE: inline`: where `VALUE` contains the full JSON of the policy
- The scope also supports configuring an
[IAM permissions boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html)
if you need to restrict maximum permissions.

> For reference, see the [`values.yaml` file in our repo](https://github.com/nullplatform/scopes/blob/main/k8s/values.yaml).

---

## Example 4: Back up your manifests

The scope supports storing backups of all generated manifests in an S3 bucket. This is useful for disaster recovery
or audit trails.

To enable this, configure the `MANIFEST_BACKUP` block in your override `values.yaml`:

```yaml
MANIFEST_BACKUP:
  ENABLED: true
  TYPE: s3
  BUCKET: nullplatform-k8s-backups
  PREFIX: cluster-name/manifests
```

Once enabled, all generated manifests will be stored automatically.

---

## Next up: Behavior overrides

If configuration changes aren’t enough and you need to actually change what the scope does, you can create behavior
overrides by modifying or extending the scope's workflows.

- [Learn how to make behavior-based overrides](/docs/agent-backed-scopes/overrides/behavior).