feat(gateway): URL-stable identity-based cluster naming for API-level upstreams

Derive API-level main/sandbox cluster names from sha256(apiID) instead of the backend URL, in both the Envoy xDS translator and the RuntimeDeployConfig transform path. The final name shape is main_<16hex> / sandbox_<16hex>; an API's main and sandbox clusters share the hash fragment (the env prefix provides the distinction), so an operator can pair an API's clusters at a glance in stats and config dumps. Because the name no longer encodes the URL, a host, port, or scheme edit is delivered to Envoy as an update to the same named cluster, which Envoy warms and swaps, instead of removing one cluster name and adding another, and a path-only edit touches just the route rewrite: routes never repoint, name-keyed stats stay continuous, and no request failures were observed while updating under continuous traffic. ClusterKey and EnvoyClusterName are unified to the same string so the policy engine's default upstream cluster always resolves to a real Envoy cluster, and the same API's main and sandbox upstreams can no longer collide into one cluster when they share a URL. Cross-API name uniqueness rests on the 64-bit hash truncation (collision-resistant, not impossible).

The integration test asserts cluster identity through the Envoy admin endpoint: identity-named clusters present, URL-derived names absent, and the exact cluster-name set unchanged across host-changing URL updates (a new capture/compare step pair), so the scenarios fail under the previous naming scheme. Rollout note: on upgrade, each existing API's main/sandbox clusters are renamed once on their next translation, so per-cluster connection pools and upstream_cluster metric labels churn once; dashboards keyed on the old cluster_<scheme>_<host> names need a one-time update. The data-model spec doc is updated to describe the new naming.

Author: mehara-rothila

gateway/gateway-controller/cmd/controller/main.go

@@ -38,10 +38,10 @@ import (
 	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/policyxds"
 	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/service/restapi"
 	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/storage"
-	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/webhooksecretxds"
 	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/transform"
 	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/utils"
 	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/version"
+	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/webhooksecretxds"
 	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/xds"
 )
 
@@ -407,6 +407,9 @@ func main() {
 	llmTransformer := transform.NewLLMTransformer(configStore, db, &cfg.Router, cfg, policyDefinitions, policyVersionResolver)
 	transformerRegistry := transform.NewRegistry(restTransformer, llmTransformer)
 	policyManager.SetTransformers(transformerRegistry)
+	// In this controller wiring, only policy xDS receives the transformer
+	// registry. Main Envoy xDS still translates RestAPI configs directly, so
+	// both paths must keep cluster-name derivation in sync.
 
 	// Load runtime configs from existing API configurations on startup.
 	// We write directly to runtimeStore to avoid triggering N separate snapshot updates;

gateway/gateway-controller/pkg/policyxds/policyxds_test.go

@@ -117,7 +117,7 @@ func TestTranslator_TranslateRuntimeConfigs(t *testing.T) {
 						OperationPath: "/users",
 						Vhost:         "localhost",
 						Upstream: models.RouteUpstream{
-							ClusterKey: "upstream_main_localhost_8080",
+							ClusterKey: "main_fixture",
 						},
 					},
 				},
@@ -129,7 +129,7 @@ func TestTranslator_TranslateRuntimeConfigs(t *testing.T) {
 					},
 				},
 				UpstreamClusters: map[string]*models.UpstreamCluster{
-					"upstream_main_localhost_8080": {
+					"main_fixture": {
 						BasePath:  "/",
 						Endpoints: []models.Endpoint{{Host: "localhost", Port: 8080}},
 					},

gateway/gateway-controller/pkg/transform/restapi.go

@@ -31,6 +31,7 @@ import (
 	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/config"
 	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/models"
 	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/utils"
+	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/utils/clusterkey"
 	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/xds"
 	policyv1alpha "github.com/wso2/api-platform/sdk/core/policy/v1alpha2"
 	policyenginev1 "github.com/wso2/api-platform/sdk/core/policyengine"
@@ -298,9 +299,10 @@ func (t *RestAPITransformer) buildPolicyChain(
 type upstreamClusterResult struct {
 	// ClusterKey is the internal key used in rdc.UpstreamClusters.
 	ClusterKey string
-	// EnvoyClusterName is the Envoy cluster name matching pkg/xds/translator.go's
-	// sanitizeClusterName format ("cluster_<scheme>_<sanitized_host>").
-	// This is the value Envoy knows the cluster by, so PE must use it for x-target-upstream.
+	// EnvoyClusterName is the Envoy cluster name. For API-level upstreams it is
+	// the URL-stable hashed name "<env>_<16-hex>" (matching ClusterKey). This is
+	// the value Envoy knows the cluster by, so the policy engine must use it for
+	// the x-target-upstream header.
 	EnvoyClusterName string
 	// BasePath is the URL path component of the upstream (e.g. "/anything/foo").
 	BasePath string
@@ -337,7 +339,12 @@ func (t *RestAPITransformer) addUpstreamCluster(
 		basePath = "/"
 	}
 
-	clusterKey := fmt.Sprintf("upstream_%s_%s_%d", upstreamName, parsedURL.Hostname(), port)
+	// URL-stable cluster naming: "<env>_<sha256(apiID) fragment>" so a URL edit
+	// updates the same named cluster instead of renaming it (routes and stats
+	// keys stay continuous). ClusterKey and EnvoyClusterName are intentionally
+	// the same string so the policy engine's `default_upstream_cluster` metadata
+	// points at the actual Envoy cluster.
+	clusterKey := upstreamName + "_" + clusterkey.APILevel(rdc.Metadata.UUID)
 
 	rdc.UpstreamClusters[clusterKey] = &models.UpstreamCluster{
 		BasePath: basePath,
@@ -348,21 +355,17 @@ func (t *RestAPITransformer) addUpstreamCluster(
 		TLS: &models.UpstreamTLS{Enabled: parsedURL.Scheme == "https"},
 	}
 
+	// ClusterKey and EnvoyClusterName must be the same string. If they differ,
+	// the default_upstream_cluster metadata written by the policy engine will
+	// not match the Envoy cluster name, producing 503 NoRoute when the default
+	// upstream path is taken.
 	return &upstreamClusterResult{
 		ClusterKey:       clusterKey,
-		EnvoyClusterName: sanitizeEnvoyClusterName(parsedURL.Host, parsedURL.Scheme),
+		EnvoyClusterName: clusterKey,
 		BasePath:         basePath,
 	}, nil
 }
 
-// sanitizeEnvoyClusterName computes the Envoy cluster name from a URL host and scheme,
-// matching the sanitizeClusterName logic in pkg/xds/translator.go.
-func sanitizeEnvoyClusterName(host, scheme string) string {
-	name := strings.ReplaceAll(host, ".", "_")
-	name = strings.ReplaceAll(name, ":", "_")
-	return "cluster_" + scheme + "_" + name
-}
-
 // resolveUpstreamURL resolves the URL from an upstream (direct URL or ref). For a ref it
 // also returns the referenced definition's base path (from basePath, never the URL); for a
 // direct URL the returned base-path pointer is nil, signalling the caller to use the URL path.

gateway/gateway-controller/pkg/transform/restapi_test.go

@@ -20,13 +20,15 @@ package transform
 
 import (
 	"net/url"
+	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	api "github.com/wso2/api-platform/gateway/gateway-controller/pkg/api/management"
 	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/config"
 	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/models"
+	"github.com/wso2/api-platform/gateway/gateway-controller/pkg/utils/clusterkey"
 )
 
 // ptrStr is a helper to get a pointer to a string literal.
@@ -353,7 +355,6 @@ func TestRestAPITransformer_SandboxRouteClusterHeader(t *testing.T) {
 	defs := map[string]models.PolicyDefinition{}
 	const sandboxURL = "http://sandbox-backend:9080/sandbox"
 	const sandboxRouteKey = "GET|/test/hello|sandbox.local"
-	expectedSandboxCluster := sanitizeEnvoyClusterName("sandbox-backend:9080", "http")
 
 	t.Run("without upstreamDefinitions the sandbox route is static", func(t *testing.T) {
 		transformer := NewRestAPITransformer(testRouterCfg(), &config.Config{}, defs)
@@ -383,7 +384,139 @@ func TestRestAPITransformer_SandboxRouteClusterHeader(t *testing.T) {
 		r, exists := rdc.Routes[sandboxRouteKey]
 		require.True(t, exists, "sandbox route should exist")
 		assert.True(t, r.Upstream.UseClusterHeader)
-		assert.Equal(t, expectedSandboxCluster, r.Upstream.DefaultCluster,
-			"sandbox route must default to the sandbox cluster, not main")
+		assert.True(t, strings.HasPrefix(r.Upstream.DefaultCluster, "sandbox_"),
+			"sandbox route must default to the URL-stable sandbox cluster (sandbox_<hash>), not main; got %q", r.Upstream.DefaultCluster)
 	})
 }
+
+// makeRestAPIWithOps builds a RestAPI StoredConfig with caller-supplied operations
+// and both API-level main and sandbox upstreams configured.
+func makeRestAPIWithOps(ops []api.Operation) *models.StoredConfig {
+	apiData := api.APIConfigData{
+		DisplayName: "Test API",
+		Context:     "/test",
+		Version:     "1.0.0",
+		Operations:  ops,
+		Upstream: struct {
+			Main    api.Upstream  `json:"main" yaml:"main"`
+			Sandbox *api.Upstream `json:"sandbox,omitempty" yaml:"sandbox,omitempty"`
+		}{
+			Main:    api.Upstream{Url: ptrStr("http://api-main:8080")},
+			Sandbox: &api.Upstream{Url: ptrStr("http://api-sandbox:8080")},
+		},
+	}
+	restAPI := api.RestAPI{
+		Kind:     api.RestAPIKindRestApi,
+		Metadata: api.Metadata{Name: "test-api"},
+		Spec:     apiData,
+	}
+	return &models.StoredConfig{
+		UUID:          "test-api",
+		Kind:          string(api.RestAPIKindRestApi),
+		Configuration: restAPI,
+	}
+}
+
+// TestRestAPITransformer_APILevelClusterNameShape asserts the URL-stable cluster
+// naming contract for API-level main and sandbox upstreams:
+//   - cluster names are "<env>_<16-hex>" derived from sha256(apiID), shared by main and sandbox
+//   - ClusterKey and EnvoyClusterName are the SAME string (so the policy engine's
+//     default_upstream_cluster metadata resolves to a real Envoy cluster)
+func TestRestAPITransformer_APILevelClusterNameShape(t *testing.T) {
+	transformer := NewRestAPITransformer(testRouterCfg(), &config.Config{}, map[string]models.PolicyDefinition{})
+	cfg := makeRestAPIWithOps([]api.Operation{
+		{Method: "GET", Path: "/users"},
+	})
+
+	rdc, err := transformer.Transform(cfg)
+	require.NoError(t, err)
+
+	expectedMain := "main_" + clusterkey.APILevel(cfg.UUID)
+	expectedSandbox := "sandbox_" + clusterkey.APILevel(cfg.UUID)
+
+	mainRoute := rdc.Routes["GET|/test/users|main.local"]
+	require.NotNil(t, mainRoute, "main route must exist")
+	assert.Equal(t, expectedMain, mainRoute.Upstream.ClusterKey,
+		"main cluster name should be <env>_<hash> derived from sha256(apiID)")
+
+	sandboxRoute := rdc.Routes["GET|/test/users|sandbox.local"]
+	require.NotNil(t, sandboxRoute, "sandbox route must exist")
+	assert.Equal(t, expectedSandbox, sandboxRoute.Upstream.ClusterKey,
+		"sandbox cluster name should be <env>_<hash> derived from sha256(apiID)")
+
+	_, mainExists := rdc.UpstreamClusters[expectedMain]
+	require.True(t, mainExists, "main cluster %q must be registered in UpstreamClusters", expectedMain)
+	_, sandboxExists := rdc.UpstreamClusters[expectedSandbox]
+	require.True(t, sandboxExists, "sandbox cluster %q must be registered in UpstreamClusters", expectedSandbox)
+}
+
+// TestRestAPITransformer_APILevelDefaultClusterMatchesRealCluster verifies that
+// route.Upstream.DefaultCluster matches a cluster registered in
+// rdc.UpstreamClusters whenever UseClusterHeader is enabled. The policy engine
+// writes DefaultCluster into the x-target-upstream header and Envoy looks up
+// the cluster by that value; if the name does not match a registered cluster,
+// Envoy returns 503 NoRoute.
+func TestRestAPITransformer_APILevelDefaultClusterMatchesRealCluster(t *testing.T) {
+	transformer := NewRestAPITransformer(testRouterCfg(), &config.Config{}, map[string]models.PolicyDefinition{})
+	cfg := makeRestAPIWithOps([]api.Operation{
+		{Method: "GET", Path: "/users"},
+	})
+	// Add an upstreamDefinition so UseClusterHeader becomes true and
+	// DefaultCluster is actually populated.
+	spec := cfg.Configuration.(api.RestAPI)
+	spec.Spec.UpstreamDefinitions = &[]api.UpstreamDefinition{
+		{
+			Name: "stub-def",
+			Upstreams: []struct {
+				Url    string `json:"url" yaml:"url"`
+				Weight *int   `json:"weight,omitempty" yaml:"weight,omitempty"`
+			}{
+				{Url: "http://stub-def-svc:8080"},
+			},
+		},
+	}
+	cfg.Configuration = spec
+
+	rdc, err := transformer.Transform(cfg)
+	require.NoError(t, err)
+
+	mainRoute := rdc.Routes["GET|/test/users|main.local"]
+	require.NotNil(t, mainRoute)
+	require.True(t, mainRoute.Upstream.UseClusterHeader,
+		"upstreamDefinitions present, UseClusterHeader should be true so DefaultCluster is meaningful")
+	require.NotEmpty(t, mainRoute.Upstream.DefaultCluster,
+		"DefaultCluster must be populated when UseClusterHeader is true")
+
+	_, exists := rdc.UpstreamClusters[mainRoute.Upstream.DefaultCluster]
+	assert.True(t, exists,
+		"DefaultCluster %q must reference a real registered cluster in UpstreamClusters "+
+			"(prevents 503 NoRoute when policy engine writes x-target-upstream)",
+		mainRoute.Upstream.DefaultCluster)
+	assert.Equal(t, mainRoute.Upstream.ClusterKey, mainRoute.Upstream.DefaultCluster,
+		"DefaultCluster and ClusterKey must be the same string")
+}
+
+// TestRestAPITransformer_APILevelURLStableAcrossURLEdit asserts that editing the
+// API-level main upstream URL does NOT change the cluster name. This is the
+// URL-stable contract: the route keeps pointing at the same named cluster and
+// name-keyed stats stay continuous across URL edits.
+func TestRestAPITransformer_APILevelURLStableAcrossURLEdit(t *testing.T) {
+	transformer := NewRestAPITransformer(testRouterCfg(), &config.Config{}, map[string]models.PolicyDefinition{})
+
+	cfgA := makeRestAPIWithOps([]api.Operation{{Method: "GET", Path: "/users"}})
+	rdcA, err := transformer.Transform(cfgA)
+	require.NoError(t, err)
+
+	cfgB := makeRestAPIWithOps([]api.Operation{{Method: "GET", Path: "/users"}})
+	specB := cfgB.Configuration.(api.RestAPI)
+	specB.Spec.Upstream.Main.Url = ptrStr("http://api-main-v2:9090")
+	cfgB.Configuration = specB
+	rdcB, err := transformer.Transform(cfgB)
+	require.NoError(t, err)
+
+	nameA := rdcA.Routes["GET|/test/users|main.local"].Upstream.ClusterKey
+	nameB := rdcB.Routes["GET|/test/users|main.local"].Upstream.ClusterKey
+	assert.Equal(t, nameA, nameB,
+		"API-level main cluster name must not depend on URL "+
+			"(URL-stable contract: the name must survive URL edits)")
+}

gateway/gateway-controller/pkg/utils/clusterkey/clusterkey.go

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com).
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+// Package clusterkey produces deterministic, hex-encoded cluster-key fragments
+// used by the gateway-controller to name Envoy clusters. It is a leaf package
+// (stdlib imports only) so both xDS builders (pkg/xds and pkg/transform) can
+// share one naming source without import cycles.
+package clusterkey
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+)
+
+// APILevel returns a deterministic, hex-encoded cluster-key fragment for an
+// API-level upstream cluster. The key is derived from SHA-256 of the apiID
+// alone, so an API's main and sandbox clusters share the same fragment and an
+// operator can pair them at a glance; the env prefix the caller prepends
+// ("main_"/"sandbox_") distinguishes them. The backend URL is deliberately
+// excluded from the input so the cluster NAME stays stable across URL edits:
+// host, port, or scheme changes reach Envoy as an update to the same named
+// cluster (warmed and swapped) instead of removing one cluster name and
+// adding another, and path-only changes touch just the route rewrite, leaving
+// the cluster untouched. Routes and name-keyed stats stay continuous either
+// way. Cross-API uniqueness rests on the 8-byte (64-bit) truncation, which
+// makes collisions between distinct apiIDs cryptographically unlikely, not
+// impossible.
+func APILevel(apiID string) string {
+	sum := sha256.Sum256([]byte(apiID))
+	return hex.EncodeToString(sum[:8])
+}

gateway/gateway-controller/pkg/utils/clusterkey/clusterkey_test.go

@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2026, WSO2 LLC. (https://www.wso2.com).
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package clusterkey
+
+import (
+	"regexp"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// hexShape16 matches exactly 16 lowercase hex characters - the cluster-key
+// fragment shape produced by APILevel.
+var hexShape16 = regexp.MustCompile("^[a-f0-9]{16}$")
+
+// TestAPILevel validates the contract for API-level cluster naming:
+//   - deterministic for identical input
+//   - distinct for distinct apiIDs
+//   - 16 hex chars from SHA-256[:8]
+//
+// The fragment is shared by an API's main and sandbox clusters by design (the
+// env prefix the caller prepends provides the distinction), so an operator
+// can pair an API's clusters at a glance.
+func TestAPILevel(t *testing.T) {
+	t.Run("deterministic for identical input", func(t *testing.T) {
+		a := APILevel("api-1")
+		b := APILevel("api-1")
+		assert.Equal(t, a, b, "same input must produce same hash")
+		assert.Regexp(t, hexShape16, a, "hash must be exactly 16 lowercase hex characters")
+	})
+
+	t.Run("different apiID produces different hash", func(t *testing.T) {
+		a := APILevel("api-1")
+		b := APILevel("api-2")
+		assert.NotEqual(t, a, b)
+	})
+}