[tunnel] add agent connection labels for cluster liveness

Add a Labels field to AgentStatus and TunnelConfig so tunnel agent
connections carry metadata (e.g. "apoxy.dev/cluster") that the GC
controller can use to verify tunnel liveness before cleaning up
mirrored resources.

- Client serializes labels as label.* query params on connect
- Server extracts label.* params and stores them in AgentStatus
- Mirror controller sets mirror.apoxy.dev/cluster label on leases
- Runtime tunnel component threads labels from TunnelConfig

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: dilyevsky

api/config/v1alpha1/config_types.go

@@ -137,6 +137,10 @@ type TunnelConfig struct {
 	// Defaults to "127.0.0.1:8053". Set to empty string to disable.
 	// +optional
 	DNSAddr string `json:"dnsAddr,omitempty"`
+	// Labels are metadata key-value pairs attached to agent connections.
+	// Convention: set "apoxy.dev/cluster" to identify cluster membership.
+	// +optional
+	Labels map[string]string `json:"labels,omitempty"`
 }
 
 // TunnelMode is the mode of the tunnel.

api/config/v1alpha1/zz_generated.deepcopy.go

@@ -67,6 +67,11 @@ type AgentStatus struct {
 	// Extra addresses of the agent (for additional v4/v6 overlays, if configured).
 	// +optional
 	AgentAddresses []string `json:"agentAddresses,omitempty"`
+
+	// Labels are metadata key-value pairs associated with this agent connection.
+	// Used to identify cluster membership, failure domains, etc.
+	// +optional
+	Labels map[string]string `json:"labels,omitempty"`
 }
 
 type TunnelNodeCredentials struct {

api/core/v1alpha/tunnel_types.go

@@ -228,6 +228,9 @@ func (r *runtimeTunnelReconciler) reconcile(ctx context.Context, req ctrl.Reques
 		return ctrl.Result{RequeueAfter: time.Second}, nil
 	}
 	cOpts = append(cOpts, tunnel.WithAuthToken(tunnelNode.Status.Credentials.Token))
+	if len(r.tunCfg.Labels) > 0 {
+		cOpts = append(cOpts, tunnel.WithLabels(r.tunCfg.Labels))
+	}
 
 	var srvAddr string
 	if !r.cfg.IsLocalMode {

api/core/v1alpha/zz_generated.deepcopy.go

@@ -656,6 +656,9 @@ func (r *MirrorReconciler) renewLease(ctx context.Context, namespace, leaseName
 			ObjectMeta: metav1.ObjectMeta{
 				Name:      leaseName,
 				Namespace: namespace,
+				Labels: map[string]string{
+					labelCluster: r.clusterName,
+				},
 			},
 			Spec: k8scoordinationv1.LeaseSpec{
 				HolderIdentity:       ptr.To(r.clusterName),
@@ -674,6 +677,10 @@ func (r *MirrorReconciler) renewLease(ctx context.Context, namespace, leaseName
 		return fmt.Errorf("getting lease: %w", err)
 	}
 
+	if existing.Labels == nil {
+		existing.Labels = make(map[string]string)
+	}
+	existing.Labels[labelCluster] = r.clusterName
 	existing.Spec.RenewTime = &now
 	existing.Spec.HolderIdentity = ptr.To(r.clusterName)
 	existing.Spec.LeaseDurationSeconds = ptr.To(durationSecs)

pkg/cmd/run/tunnel.go

@@ -517,6 +517,8 @@ func TestRenewLease_CreatesNew(t *testing.T) {
 	assert.Equal(t, int32(30), *lease.Spec.LeaseDurationSeconds)
 	assert.NotNil(t, lease.Spec.AcquireTime)
 	assert.NotNil(t, lease.Spec.RenewTime)
+	// Cluster label.
+	assert.Equal(t, "test-cluster", lease.Labels[labelCluster])
 }
 
 func TestRenewLease_RenewsExisting(t *testing.T) {
@@ -551,6 +553,8 @@ func TestRenewLease_RenewsExisting(t *testing.T) {
 	// RenewTime should be updated to approximately now.
 	assert.True(t, lease.Spec.RenewTime.Time.After(before.Add(-time.Second)))
 	assert.Equal(t, "test-cluster", *lease.Spec.HolderIdentity)
+	// Cluster label set on update.
+	assert.Equal(t, "test-cluster", lease.Labels[labelCluster])
 }
 
 // --- reconcileTCPRoute (v1alpha2 round-trip) ---

pkg/kube-controller/controllers/mirror.go

@@ -69,6 +69,8 @@ type tunnelClientOptions struct {
 	preserveDefaultGwDsts []netip.Prefix
 	// Packet observer for TUI
 	packetObserver tunnelconn.PacketObserver
+	// Labels to send on tunnel connections.
+	labels map[string]string
 }
 
 func defaultClientOptions() *tunnelClientOptions {
@@ -152,6 +154,13 @@ func WithPacketObserver(obs tunnelconn.PacketObserver) TunnelClientOption {
 	}
 }
 
+// WithLabels sets metadata labels to send on tunnel connections.
+func WithLabels(labels map[string]string) TunnelClientOption {
+	return func(o *tunnelClientOptions) {
+		o.labels = labels
+	}
+}
+
 // BuildClientRouter builds a router for the client tunnel side using provided
 // options and sane defaults.
 func BuildClientRouter(opts ...TunnelClientOption) (router.Router, error) {
@@ -273,9 +282,11 @@ func (d *TunnelDialer) Dial(
 	q := addrUrl.Query()
 	if options.authToken != "" {
 		q.Add("token", options.authToken)
-		addrUrl.RawQuery = q.Encode()
 	}
-	addrUrl.RawQuery = addrUrl.Query().Encode()
+	for k, v := range options.labels {
+		q.Add("label."+k, v)
+	}
+	addrUrl.RawQuery = q.Encode()
 
 	tmpl, err := uritemplate.New(addrUrl.String())
 	if err != nil {

pkg/kube-controller/controllers/mirror_test.go

@@ -508,6 +508,13 @@ func (t *TunnelServer) makeSingleConnectHandler(ctx context.Context, qConn quic.
 			return
 		}
 
+		labels := make(map[string]string)
+		for key, values := range r.URL.Query() {
+			if strings.HasPrefix(key, "label.") && len(values) > 0 {
+				labels[strings.TrimPrefix(key, "label.")] = values[0]
+			}
+		}
+
 		connID := uuid.NewString()
 		// Sends connection ID information to the client so that it can
 		// track its connection status. This must be done before initializing the proxy.
@@ -538,6 +545,7 @@ func (t *TunnelServer) makeSingleConnectHandler(ctx context.Context, qConn quic.
 		agent := &corev1alpha.AgentStatus{
 			Name:        connID,
 			ConnectedAt: ptr.To(metav1.Now()),
+			Labels:      labels,
 		}
 		// TODO(dilyevsky): Support multiple external addresses in the Status.
 		if len(t.options.extAddrs) > 0 && t.options.extAddrs[0].IsValid() {