feat: make zone field optional for uniform zone distribution (#1947)

## Summary

- Remove required zone validation from `DynamicNodePool.Validate()`,
making `providerSpec.zone` optional
- Add `TestOptionalZone` test to verify nodepools pass validation with
and without zone
- Update documentation to reflect optional zone field and automatic zone
distribution

## Related Issue

Partially addresses #1629 (Uniformly distribute nodes across zones by
default)

This PR completes the following exit criteria:
- [x] `providerSpec.zone` is optional
- [x] docs are updated

Remaining work (in berops/claudie-config#19):
- [x] nodes from a single nodepool are uniformly distributed across all
zones in the region

## Documentation Updates

- Updated API reference to mark zone as optional with explanation of
automatic distribution
- Updated provider docs (AWS, Azure, GCP, OCI) with zone-optional
examples
- Added note to Hetzner docs that zone is still required (no automatic
distribution support)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Zone field is now optional; omitting it distributes nodes across all
available zones for improved availability.

* **Documentation**
* Updated API reference and provider docs to clarify zone optionality
and auto-distribution across AWS, Azure, GCP, and OCI.

* **Tests**
  * Added validation tests to cover optional zone handling.

* **Chores**
* Updated project ignore rules and improved cross-platform build
scripting helper.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: Samuel STOLICNY (contractor) <samuel.stolicny@amadeus.com>

Author: samuelstolicny

.gitignore

@@ -1,22 +1,43 @@
+# IDE and editors
 .idea/
-*.ini
+.vscode/
+
+# Terraform
 .terraform*
-playground
-clusters
-.vscode
-mongodb
 *.tfstate*
-*.pem
+
+# Local development
+playground/
+clusters/
+mongodb/
+bin/
+
+# Kubernetes and cluster files
 kubeone.yaml
 cluster.tar.gz
 cluster-kubeconfig
+*.pem
 *.conf
+
+# Build artifacts
 __debug_bin
-services/testing-framework/test-sets
-services/terraformer/templates
+
+# OS-specific
+.DS_Store
+
+# Python/Documentation
 /venv/
 /site/
-bin
+
+# Configuration files
+*.ini
 .manifest*
-.DS_Store
-/services/terraformer/server/cache
+
+# Service-specific
+services/testing-framework/test-sets/
+services/terraformer/templates/
+/services/terraformer/server/cache/
+
+# Claude
+.claude/
+CLAUDE.md

Makefile

@@ -74,13 +74,15 @@ datastoreStop:
 TARGETARCH = $$(go env GOHOSTARCH)
 REV = $$(git rev-parse --short HEAD)
 SERVICES = $$(command ls services/)
+# macOS (BSD) sed requires -i '' while GNU sed uses -i
+SED_INPLACE := $(shell if [ "$$(uname)" = "Darwin" ]; then echo "sed -i ''"; else echo "sed -i"; fi)
 containerimgs:
-	sed -i "s/image: ghcr.io\/berops\/claudie\/autoscaler-adapter/&:$(REV)/" services/kuber/templates/cluster-autoscaler.goyaml
+	$(SED_INPLACE) "s/image: ghcr.io\/berops\/claudie\/autoscaler-adapter/&:$(REV)/" services/kuber/templates/cluster-autoscaler.goyaml
 	for service in $(SERVICES) ; do \
 		echo " --- building $$service --- "; \
 		DOCKER_BUILDKIT=1 docker build --build-arg=TARGETARCH="$(TARGETARCH)" -t "ghcr.io/berops/claudie/$$service:$(REV)" -f ./services/$$service/Dockerfile . ; \
 	done
-	sed -i "s/adapter:.*$$/adapter/" services/kuber/templates/cluster-autoscaler.goyaml
+	$(SED_INPLACE) "s/adapter:.*$$/adapter/" services/kuber/templates/cluster-autoscaler.goyaml
 
 kind-load-images:
 	for service in $(SERVICES) ; do \

docs/input-manifest/api-reference.md

@@ -296,9 +296,9 @@ Provider spec is an additional specification built on top of the data from any o
 
   Region of the nodepool.
 
-- `zone`
+- `zone` *(optional)*
 
-  Zone of the nodepool.
+  Zone of the nodepool. If not specified, nodes are automatically distributed across all available zones in the region using round-robin assignment. This provides better availability and fault tolerance by spreading nodes across multiple availability zones.
 
 ## Autoscaler Configuration
 

docs/input-manifest/example.md

@@ -85,7 +85,7 @@ spec:
     #     providerSpec:     # Provider specification for this nodepool.
     #       name:           # Name of the provider instance, referencing one of the providers define above.
     #       region:         # Region of the nodepool.
-    #       zone:           # Zone of the nodepool.
+    #       zone:           # Zone of the nodepool (optional). If omitted, nodes are distributed across zones automatically.
     #     count:            # Static number of nodes in this nodepool.
     #     serverType:       # Machine type of the nodes in this nodepool.
     #     image:            # OS image of the nodes in the nodepool.

docs/input-manifest/providers/aws.md

@@ -117,7 +117,7 @@ spec:
           name: aws-1
           # Region of the nodepool.
           region: eu-central-1
-          # Availability zone of the nodepool.
+          # Zone is optional. If omitted, nodes are distributed across all availability zones.
           zone: eu-central-1a
         count: 1
         # Instance type name.
@@ -132,7 +132,7 @@ spec:
           name: aws-1
           # Region of the nodepool.
           region: eu-west-2
-          # Availability zone of the nodepool.
+          # Zone is optional. If omitted, nodes are distributed across all availability zones.
           zone: eu-west-2a
         count: 2
         # Instance type name.
@@ -148,7 +148,7 @@ spec:
           name: aws-1
           # Region of the nodepool.
           region: eu-west-2
-          # Availability zone of the nodepool.
+          # Zone is optional. If omitted, nodes are distributed across all availability zones.
           zone: eu-west-2a
         count: 2
         # Instance type name.

docs/input-manifest/providers/azure.md

@@ -114,7 +114,7 @@ spec:
           name: azure-1
           # Location of the nodepool.
           region: North Europe
-          # Zone of the nodepool.
+          # Zone is optional. If omitted, nodes are distributed across zones.
           zone: "1"
         count: 2
         # VM size name.
@@ -128,7 +128,7 @@ spec:
           name: azure-1
           # Location of the nodepool.
           region: Germany West Central
-          # Zone of the nodepool.
+          # Zone is optional. If omitted, nodes are distributed across zones.
           zone: "1"
         count: 2
         # VM size name.
@@ -143,7 +143,7 @@ spec:
           name: azure-1
           # Location of the nodepool.
           region: North Europe
-          # Zone of the nodepool.
+          # Zone is optional. If omitted, nodes are distributed across zones.
           zone: "1"
         count: 2
         # VM size name.

docs/input-manifest/providers/gcp.md

@@ -102,7 +102,7 @@ spec:
           name: gcp-1
           # Region of the nodepool.
           region: europe-west1
-          # Zone of the nodepool.
+          # Zone is optional. If omitted, nodes are distributed across all zones in the region.
           zone: europe-west1-c
         count: 1
         # Machine type name.
@@ -116,7 +116,7 @@ spec:
           name: gcp-1
           # Region of the nodepool.
           region: europe-west3
-          # Zone of the nodepool.
+          # Zone is optional. If omitted, nodes are distributed across all zones in the region.
           zone: europe-west3-a
         count: 2
         # Machine type name.
@@ -131,7 +131,7 @@ spec:
           name: gcp-1
           # Region of the nodepool.
           region: europe-west2
-          # Zone of the nodepool.
+          # Zone is optional. If omitted, nodes are distributed across all zones in the region.
           zone: europe-west2-a
         count: 2
         # Machine type name.

docs/input-manifest/providers/oci.md

@@ -151,7 +151,7 @@ spec:
           name: oci-1
           # Region of the nodepool.
           region: eu-milan-1
-          # Availability domain of the nodepool.
+          # Zone is optional. If omitted, nodes are distributed across all availability domains.
           zone: hsVQ:EU-MILAN-1-AD-1
         count: 1
         # VM shape name.
@@ -167,7 +167,7 @@ spec:
           name: oci-1
           # Region of the nodepool.
           region: eu-frankfurt-1
-          # Availability domain of the nodepool.
+          # Zone is optional. If omitted, nodes are distributed across all availability domains.
           zone: hsVQ:EU-FRANKFURT-1-AD-1
         count: 2
         # VM shape name.
@@ -184,7 +184,7 @@ spec:
           name: oci-1
           # Region of the nodepool.
           region: eu-frankfurt-1
-          # Availability domain of the nodepool.
+          # Zone is optional. If omitted, nodes are distributed across all availability domains.
           zone: hsVQ:EU-FRANKFURT-1-AD-2
         count: 2
         # VM shape name.

internal/api/manifest/validate_node_pool.go

@@ -126,13 +126,6 @@ func (d *DynamicNodePool) Validate(m *Manifest) error {
 	}
 
 	validate := validator.New()
-	validate.RegisterStructValidation(func(sl validator.StructLevel) {
-		dnp := sl.Current().Interface().(DynamicNodePool)
-
-		if dnp.ProviderSpec.Zone == "" {
-			sl.ReportError(dnp.ProviderSpec.Zone, "Zone", "Zone", "required", "")
-		}
-	}, DynamicNodePool{})
 
 	if err := validate.RegisterValidation("external_net", validateExternalNet); err != nil {
 		return err

internal/api/manifest/validate_test.go

@@ -212,6 +212,8 @@ var (
 	testNpDiskSizeSuccessfulFifty   = DynamicNodePool{Name: "control-1", Count: 10, ServerType: "small", Image: "ubuntu", ProviderSpec: ProviderSpec{Name: "foo", Region: "north", Zone: "1"}, StorageDiskSize: newIntP(50)}
 	testNpDiskSizeSuccessfulDefault = DynamicNodePool{Name: "control-1", Count: 10, ServerType: "small", Image: "ubuntu", ProviderSpec: ProviderSpec{Name: "foo", Region: "north", Zone: "1"}}
 	testNpDiskSizeSuccessfulFail    = DynamicNodePool{Name: "control-1", Count: 10, ServerType: "small", Image: "ubuntu", ProviderSpec: ProviderSpec{Name: "foo", Region: "north", Zone: "1"}, StorageDiskSize: newIntP(10)}
+	testNodepoolWithoutZone         = &DynamicNodePool{Name: "Test", ServerType: "s1", Image: "ubuntu", StorageDiskSize: newIntP(50), Count: 1, ProviderSpec: ProviderSpec{Name: "p1", Region: "a"}}
+	testNodepoolWithZone            = &DynamicNodePool{Name: "Test", ServerType: "s1", Image: "ubuntu", StorageDiskSize: newIntP(50), Count: 1, ProviderSpec: ProviderSpec{Name: "p1", Region: "a", Zone: "1"}}
 )
 
 func newIntP(a int32) *int32 {
@@ -318,3 +320,12 @@ func TestStorageDiskSize(t *testing.T) {
 	r.NoError(testNpDiskSizeSuccessfulDefault.Validate(&Manifest{}))
 	r.Error(testNpDiskSizeSuccessfulFail.Validate(&Manifest{}))
 }
+
+// TestOptionalZone tests that the zone field is optional for uniform zone distribution.
+func TestOptionalZone(t *testing.T) {
+	r := require.New(t)
+	// Zone should be optional - nodepools without zone should pass validation
+	r.NoError(testNodepoolWithoutZone.Validate(&Manifest{}))
+	// Nodepools with zone should still pass validation
+	r.NoError(testNodepoolWithZone.Validate(&Manifest{}))
+}