[aks-preview] Add OpenTelemetry gRPC ports for metrics and logs/traces

Adds --opentelemetry-metrics-port-grpc and --opentelemetry-logs-traces-port-grpc
(preview) to 'az aks create/update', wiring the new grpc_port field on the
appMonitoring OpenTelemetry profiles (API 2026-04-02-preview).

- Validation: all four OTLP ports (metrics/logs x http/grpc) must be in 1..65535
  and distinct; grpc ports follow the same enable/disable gating as the http ports.
- Disable paths now clear both http_port and grpc_port, including when the parent
  Azure Monitor metrics/logs are disabled.
- Adds unit, validator, and live integration coverage; bumps version to 21.0.0b8
  and updates HISTORY.

Author: Christoph Butz

src/aks-preview/HISTORY.rst

@@ -12,6 +12,9 @@ To release a new version, please select a new version number (usually plus 1 to
 Pending
 +++++++
 
+* `az aks create` and `az aks update`: Add `--opentelemetry-metrics-port-grpc` and `--opentelemetry-logs-traces-port-grpc` (preview) to configure the gRPC ports for OpenTelemetry metrics and logs/traces collection, in addition to the existing HTTP/protobuf ports.
+* `az aks create` and `az aks update`: Rename the OpenTelemetry parameters, keeping the previous names as deprecated aliases: `--opentelemetry-metrics-port` -> `--opentelemetry-metrics-port-http`, `--opentelemetry-logs-port` -> `--opentelemetry-logs-traces-port-http`, `--enable-opentelemetry-logs` -> `--enable-opentelemetry-logs-traces`, `--disable-opentelemetry-logs` -> `--disable-opentelemetry-logs-traces`.
+
 21.0.0b9
 ++++++++
 * Update the minimum required cli core version to `2.85.0` (actually required since `20.0.0b5`).

src/aks-preview/azext_aks_preview/_help.py

@@ -633,6 +633,9 @@
         - name: --opentelemetry-metrics-port-http
           type: int
           short-summary: HTTP/protobuf port for OpenTelemetry metrics collection (default port will be used if not specified)
+        - name: --opentelemetry-metrics-port-grpc
+          type: int
+          short-summary: gRPC port for OpenTelemetry metrics collection (default port will be used if not specified)
         - name: --disable-opentelemetry-metrics
           type: bool
           short-summary: Disable OpenTelemetry metrics collection
@@ -642,6 +645,9 @@
         - name: --opentelemetry-logs-traces-port-http
           type: int
           short-summary: HTTP/protobuf port for OpenTelemetry logs and traces collection (default port will be used if not specified)
+        - name: --opentelemetry-logs-traces-port-grpc
+          type: int
+          short-summary: gRPC port for OpenTelemetry logs and traces collection (default port will be used if not specified)
         - name: --disable-opentelemetry-logs-traces
           type: bool
           short-summary: Disable OpenTelemetry logs and traces collection
@@ -831,6 +837,8 @@
           text: az aks create -g MyResourceGroup -n MyManagedCluster --enable-opentelemetry-metrics --opentelemetry-metrics-port-http 8888 --enable-azuremonitormetrics
         - name: Create a kubernetes cluster with OpenTelemetry logs and traces on custom port
           text: az aks create -g MyResourceGroup -n MyManagedCluster --enable-opentelemetry-logs-traces --opentelemetry-logs-traces-port-http 4317 --enable-azure-monitor-logs
+        - name: Create a kubernetes cluster with OpenTelemetry metrics on custom HTTP and gRPC ports
+          text: az aks create -g MyResourceGroup -n MyManagedCluster --enable-opentelemetry-metrics --opentelemetry-metrics-port-http 8888 --opentelemetry-metrics-port-grpc 8889 --enable-azuremonitormetrics
         - name: Create a kubernetes cluster with a nodepool having ip allocation mode set to "StaticBlock"
           text: az aks create -g MyResourceGroup -n MyManagedCluster --os-sku Ubuntu --max-pods MaxPodsPerNode --network-plugin azure --vnet-subnet-id /subscriptions/00000/resourceGroups/AnotherResourceGroup/providers/Microsoft.Network/virtualNetworks/MyVnet/subnets/NodeSubnet --pod-subnet-id /subscriptions/00000/resourceGroups/AnotherResourceGroup/providers/Microsoft.Network/virtualNetworks/MyVnet/subnets/PodSubnet --pod-ip-allocation-mode StaticBlock
         - name: Create a kubernetes cluster with a VirtualMachines nodepool
@@ -1376,6 +1384,9 @@
         - name: --opentelemetry-metrics-port-http
           type: int
           short-summary: HTTP/protobuf port for OpenTelemetry metrics collection (default port will be used if not specified)
+        - name: --opentelemetry-metrics-port-grpc
+          type: int
+          short-summary: gRPC port for OpenTelemetry metrics collection (default port will be used if not specified)
         - name: --disable-opentelemetry-metrics
           type: bool
           short-summary: Disable OpenTelemetry metrics collection
@@ -1385,6 +1396,9 @@
         - name: --opentelemetry-logs-traces-port-http
           type: int
           short-summary: HTTP/protobuf port for OpenTelemetry logs and traces collection (default port will be used if not specified)
+        - name: --opentelemetry-logs-traces-port-grpc
+          type: int
+          short-summary: gRPC port for OpenTelemetry logs and traces collection (default port will be used if not specified)
         - name: --disable-opentelemetry-logs-traces
           type: bool
           short-summary: Disable OpenTelemetry logs and traces collection
@@ -1635,6 +1649,8 @@
         text: az aks update -g MyResourceGroup -n MyManagedCluster --enable-opentelemetry-metrics --opentelemetry-metrics-port-http 8888
       - name: Configure OpenTelemetry logs and traces with custom port
         text: az aks update -g MyResourceGroup -n MyManagedCluster --enable-opentelemetry-logs-traces --opentelemetry-logs-traces-port-http 4317
+      - name: Configure OpenTelemetry metrics with custom HTTP and gRPC ports
+        text: az aks update -g MyResourceGroup -n MyManagedCluster --enable-opentelemetry-metrics --opentelemetry-metrics-port-http 8888 --opentelemetry-metrics-port-grpc 8889
       - name: Disable OpenTelemetry metrics collection on an existing cluster
         text: az aks update -g MyResourceGroup -n MyManagedCluster --disable-opentelemetry-metrics
       - name: Disable OpenTelemetry logs and traces collection on an existing cluster

src/aks-preview/azext_aks_preview/_params.py

@@ -1173,7 +1173,12 @@ def load_arguments(self, _):
                    type=int,
                    help="HTTP/protobuf port for OpenTelemetry metrics collection"
                    )
-
+        c.argument("opentelemetry_metrics_port_grpc",
+                   options_list=["--opentelemetry-metrics-port-grpc"],
+                   is_preview=True,
+                   type=int,
+                   help="gRPC port for OpenTelemetry metrics collection"
+                   )
         c.argument("disable_opentelemetry_metrics",
                    is_preview=True,
                    action="store_true",
@@ -1209,7 +1214,12 @@ def load_arguments(self, _):
                    type=int,
                    help="HTTP/protobuf port for OpenTelemetry logs and traces collection"
                    )
-
+        c.argument("opentelemetry_logs_traces_port_grpc",
+                   options_list=["--opentelemetry-logs-traces-port-grpc"],
+                   is_preview=True,
+                   type=int,
+                   help="gRPC port for OpenTelemetry logs and traces collection"
+                   )
         c.argument("disable_opentelemetry_logs",
                    options_list=["--disable-opentelemetry-logs-traces"],
                    is_preview=True,
@@ -1807,7 +1817,12 @@ def load_arguments(self, _):
                    type=int,
                    help="HTTP/protobuf port for OpenTelemetry metrics collection"
                    )
-
+        c.argument("opentelemetry_metrics_port_grpc",
+                   options_list=["--opentelemetry-metrics-port-grpc"],
+                   is_preview=True,
+                   type=int,
+                   help="gRPC port for OpenTelemetry metrics collection"
+                   )
         c.argument("disable_opentelemetry_metrics",
                    is_preview=True,
                    action="store_true",
@@ -1843,7 +1858,12 @@ def load_arguments(self, _):
                    type=int,
                    help="HTTP/protobuf port for OpenTelemetry logs and traces collection"
                    )
-
+        c.argument("opentelemetry_logs_traces_port_grpc",
+                   options_list=["--opentelemetry-logs-traces-port-grpc"],
+                   is_preview=True,
+                   type=int,
+                   help="gRPC port for OpenTelemetry logs and traces collection"
+                   )
         c.argument("disable_opentelemetry_logs",
                    options_list=["--disable-opentelemetry-logs-traces"],
                    is_preview=True,

src/aks-preview/azext_aks_preview/_validators.py

@@ -1077,24 +1077,31 @@ def validate_location_resource_group_cluster_parameters(namespace):
 
 
 def validate_opentelemetry_ports(namespace):
-    """Validate that OpenTelemetry metrics and logs ports don't conflict."""
-    metrics_port = getattr(namespace, 'opentelemetry_metrics_port', None)
-    logs_port = getattr(namespace, 'opentelemetry_logs_port', None)
-
-    # Check if both ports are specified and are the same
-    if metrics_port is not None and logs_port is not None and metrics_port == logs_port:
-        raise ArgumentUsageError(
-            "OpenTelemetry metrics port and logs port cannot be the same. "
-            "Please specify different ports for --opentelemetry-metrics-port-http and --opentelemetry-logs-traces-port-http."
-        )
+    """Validate that the OpenTelemetry HTTP and gRPC ports are in range and all distinct."""
+    ports = [
+        ("--opentelemetry-metrics-port-http", getattr(namespace, 'opentelemetry_metrics_port', None)),
+        ("--opentelemetry-metrics-port-grpc", getattr(namespace, 'opentelemetry_metrics_port_grpc', None)),
+        ("--opentelemetry-logs-traces-port-http", getattr(namespace, 'opentelemetry_logs_port', None)),
+        ("--opentelemetry-logs-traces-port-grpc", getattr(namespace, 'opentelemetry_logs_traces_port_grpc', None)),
+    ]
 
     # Validate port ranges
-    for port, port_name in [(metrics_port, 'metrics'), (logs_port, 'logs')]:
+    for flag, port in ports:
         if port is not None and not (1 <= port <= 65535):
             raise ArgumentUsageError(
-                f"OpenTelemetry {port_name} port must be between 1 and 65535, got {port}."
+                f"OpenTelemetry port {flag} must be between 1 and 65535, got {port}."
             )
 
+    # All specified OpenTelemetry ports (HTTP and gRPC, metrics and logs/traces) must be distinct
+    specified = [(flag, port) for flag, port in ports if port is not None]
+    for i in range(len(specified)):
+        for j in range(i + 1, len(specified)):
+            if specified[i][1] == specified[j][1]:
+                raise ArgumentUsageError(
+                    "OpenTelemetry ports must all be different. "
+                    f"{specified[i][0]} and {specified[j][0]} cannot both be set to {specified[i][1]}."
+                )
+
 
 def validate_opentelemetry_metrics_dependencies(namespace):
     """Validate OpenTelemetry metrics dependencies for create operations."""

src/aks-preview/azext_aks_preview/custom.py

@@ -1395,9 +1395,11 @@ def aks_create(
     # opentelemetry parameters
     enable_opentelemetry_metrics=False,
     opentelemetry_metrics_port=None,
+    opentelemetry_metrics_port_grpc=None,
     disable_opentelemetry_metrics=False,
     enable_opentelemetry_logs=False,
     opentelemetry_logs_port=None,
+    opentelemetry_logs_traces_port_grpc=None,
     disable_opentelemetry_logs=False,
     # opentelemetry deprecated aliases (merged into the parameters above by the validator)
     opentelemetry_metrics_port_deprecated=None,
@@ -1641,9 +1643,11 @@ def aks_update(
     # opentelemetry parameters
     enable_opentelemetry_metrics=False,
     opentelemetry_metrics_port=None,
+    opentelemetry_metrics_port_grpc=None,
     disable_opentelemetry_metrics=False,
     enable_opentelemetry_logs=False,
     opentelemetry_logs_port=None,
+    opentelemetry_logs_traces_port_grpc=None,
     disable_opentelemetry_logs=False,
     # opentelemetry deprecated aliases (merged into the parameters above by the validator)
     opentelemetry_metrics_port_deprecated=None,