[AKS] az aks create/update: Onboard Container Insights via azureMonitorProfile and deprecate the monitoring addon

src/aks-preview/HISTORY.rst

@@ -13,6 +13,15 @@ Pending
 +++++++
 * `az aks nodepool update`: Avoid applying VirtualMachines autoscaler profile conversions twice with newer Azure CLI versions while preserving compatibility with older CLI versions.
 
+21.0.0b14
+++++++++
+* `az aks create/update`: `--enable-azure-monitor-logs` / `--disable-azure-monitor-logs` now configure the modern ``azureMonitorProfile.containerInsights`` profile instead of the legacy ``addonProfiles.omsagent`` addon. The containerInsights path always uses managed-identity (MSI/AAD) auth.
+* `az aks create/update`: Add ``--syslog-port`` and ``--enable/--disable-prometheus-metrics-scraping`` controls for the Container Insights Azure Monitor profile.
+* `az aks create/update`: Reject the legacy ``--enable-msi-auth-for-monitoring`` flag when used with ``--enable-azure-monitor-logs`` because the Azure Monitor profile is managed-identity only.
+* `az aks update`: Reject migration of an already-enabled legacy shared-key monitoring addon through ``--enable-azure-monitor-logs`` with guidance to migrate the addon to managed-identity authentication first.
+* `az aks update`: Avoid DCR/DCRA postprocessing when Container Insights is disabled or has no workspace, and explicitly set container network logs to ``Disabled`` when Azure Monitor logs are disabled.
+* `az aks create --enable-addons monitoring` and `az aks enable-addons -a monitoring`: Show guidance toward ``--enable-azure-monitor-logs`` for the legacy ``monitoring`` addon and warn when ``--enable-msi-auth-for-monitoring`` is explicitly supplied.
+
 21.0.0b13
 ++++++++
 * `az aks maintenanceconfiguration add` and `az aks maintenanceconfiguration update`: Add `--maintenance-window-id` (preview) to link a maintenance configuration to a shared MaintenanceWindow resource. When set, the schedule lives in the referenced MaintenanceWindow and inline schedule arguments cannot be used; omit it for no shared resource. `--maintenance-window-id` cannot be combined with `--config-file` (set the `maintenanceWindowId` property in the JSON instead) and cannot be empty. Requires the `Microsoft.ContainerService/AKSSharedMaintenanceWindowPreview` feature to be registered on the subscription.

src/aks-preview/azext_aks_preview/_help.py

@@ -193,7 +193,17 @@
         - name: --enable-azure-monitor-logs
           type: bool
           short-summary: Enable Azure Monitor logs for the cluster.
-          long-summary: This is equivalent to using "--enable-addons monitoring". Turn on Log Analytics monitoring. Uses the Log Analytics Default Workspace if it exists, else creates one. Specify "--workspace-resource-id" to use an existing workspace. If monitoring addon is enabled --no-wait argument will have no effect
+          long-summary: Enables Container Insights logs for the cluster by configuring the azureMonitorProfile.containerInsights profile (managed-identity/MSI auth). This is the preferred way to onboard Container Insights and supersedes the deprecated "--enable-addons monitoring". Uses the Log Analytics Default Workspace if it exists, else creates one. Specify "--workspace-resource-id" to use an existing workspace. If monitoring is enabled --no-wait argument will have no effect
+        - name: --syslog-port
+          type: int
+          short-summary: Set the syslog host port for Azure Monitor Container Insights.
+          long-summary: Configures containerInsights.syslogPort. This controls the host port only and is distinct from --enable-syslog, which controls syslog collection in the DCR. If omitted, the service default is 28330.
+        - name: --enable-prometheus-metrics-scraping
+          type: bool
+          short-summary: Enable Prometheus metrics scraping for Azure Monitor Container Insights.
+        - name: --disable-prometheus-metrics-scraping
+          type: bool
+          short-summary: Disable Prometheus metrics scraping for Azure Monitor Container Insights.
         - name: --disable-rbac
           type: bool
           short-summary: Disable Kubernetes Role-Based Access Control.
@@ -1116,14 +1126,24 @@
         - name: --enable-azure-monitor-logs
           type: bool
           short-summary: Enable Azure Monitor logs for the cluster.
-          long-summary: This is equivalent to using "az aks enable-addons -a monitoring". Enables Log Analytics monitoring for the cluster. Uses the Log Analytics Default Workspace if it exists, else creates one. Specify "--workspace-resource-id" to use an existing workspace. If monitoring addon is enabled --no-wait argument will have no effect
+          long-summary: Enables Container Insights logs for the cluster by configuring the azureMonitorProfile.containerInsights profile (managed-identity/MSI auth). This is the preferred way to onboard Container Insights and supersedes the deprecated "az aks enable-addons -a monitoring". Uses the Log Analytics Default Workspace if it exists, else creates one. Specify "--workspace-resource-id" to use an existing workspace. If monitoring is enabled --no-wait argument will have no effect
         - name: --disable-azure-monitor-logs
           type: bool
           short-summary: Disable Azure Monitor logs for the cluster.
-          long-summary: This is equivalent to using "az aks disable-addons -a monitoring". Disables Log Analytics monitoring for the cluster.
+          long-summary: Disables Container Insights through azureMonitorProfile.containerInsights. The CLI also clears the legacy mirrored addon state when present for brownfield compatibility.
         - name: --workspace-resource-id
           type: string
           short-summary: The resource ID of an existing Log Analytics Workspace to use for storing monitoring data. If not specified, uses the default Log Analytics Workspace if it exists, otherwise creates one.
+        - name: --syslog-port
+          type: int
+          short-summary: Set the syslog host port for Azure Monitor Container Insights.
+          long-summary: Configures containerInsights.syslogPort. This controls the host port only and is distinct from --enable-syslog, which controls syslog collection in the DCR. If omitted, the service default is 28330.
+        - name: --enable-prometheus-metrics-scraping
+          type: bool
+          short-summary: Enable Prometheus metrics scraping for Azure Monitor Container Insights.
+        - name: --disable-prometheus-metrics-scraping
+          type: bool
+          short-summary: Disable Prometheus metrics scraping for Azure Monitor Container Insights.
         - name: --enable-msi-auth-for-monitoring
           type: bool
           short-summary: Send monitoring data to Log Analytics using the cluster's assigned identity (instead of the Log Analytics Workspace's shared key).

src/aks-preview/azext_aks_preview/_params.py

@@ -192,6 +192,8 @@
     validate_azure_monitor_and_opentelemetry_for_create,
     validate_azure_monitor_and_opentelemetry_for_update,
     validate_azure_monitor_logs_and_enable_addons,
+    validate_azure_monitor_logs_amp_controls_for_create,
+    validate_azure_monitor_logs_amp_controls_for_update,
     validate_azure_monitor_logs_enable_disable,
     validate_azuremonitorworkspaceresourceid,
     validate_cluster_id,
@@ -828,9 +830,33 @@ def load_arguments(self, _):
             "enable_azure_monitor_logs",
             action="store_true",
             validator=validate_azure_monitor_logs_and_enable_addons,
-            help="Enable Azure Monitor logs for the cluster. Equivalent to '--enable-addons monitoring'."
+            help="Enable Azure Monitor logs (Container Insights) for the cluster. Configures the "
+                 "azureMonitorProfile.containerInsights profile (managed-identity/MSI auth). Preferred "
+                 "over the deprecated '--enable-addons monitoring'."
         )
         c.argument("workspace_resource_id")
+        c.argument(
+            "syslog_port",
+            type=int,
+            is_preview=True,
+            validator=validate_azure_monitor_logs_amp_controls_for_create,
+            help="Syslog host port for Azure Monitor Container Insights. This configures the host "
+                 "port only; use --enable-syslog to control syslog collection."
+        )
+        c.argument(
+            "enable_prometheus_metrics_scraping",
+            action="store_true",
+            is_preview=True,
+            validator=validate_azure_monitor_logs_amp_controls_for_create,
+            help="Enable Prometheus metrics scraping for Azure Monitor Container Insights."
+        )
+        c.argument(
+            "disable_prometheus_metrics_scraping",
+            action="store_true",
+            is_preview=True,
+            validator=validate_azure_monitor_logs_amp_controls_for_create,
+            help="Disable Prometheus metrics scraping for Azure Monitor Container Insights."
+        )
         c.argument(
             "enable_msi_auth_for_monitoring",
             arg_type=get_three_state_flag(),
@@ -1562,13 +1588,39 @@ def load_arguments(self, _):
             "enable_azure_monitor_logs",
             action="store_true",
             validator=validate_azure_monitor_logs_enable_disable,
-            help="Enable Azure Monitor logs for the cluster. Equivalent to 'az aks enable-addons -a monitoring'."
+            help="Enable Azure Monitor logs (Container Insights) for the cluster. Configures the "
+                 "azureMonitorProfile.containerInsights profile (managed-identity/MSI auth). Preferred "
+                 "over the deprecated 'az aks enable-addons -a monitoring'."
         )
 # Monitoring parameters are inherited from base CLI
         c.argument(
             "disable_azure_monitor_logs",
             action="store_true",
-            help="Disable Azure Monitor logs for the cluster. Equivalent to 'az aks disable-addons -a monitoring'."
+            help="Disable Azure Monitor logs (Container Insights) for the cluster. Clears the "
+                 "azureMonitorProfile.containerInsights profile. Preferred over the deprecated "
+                 "'az aks disable-addons -a monitoring'."
+        )
+        c.argument(
+            "syslog_port",
+            type=int,
+            is_preview=True,
+            validator=validate_azure_monitor_logs_amp_controls_for_update,
+            help="Set the syslog host port for Azure Monitor Container Insights. This configures "
+                 "the host port only; use --enable-syslog to control syslog collection."
+        )
+        c.argument(
+            "enable_prometheus_metrics_scraping",
+            action="store_true",
+            is_preview=True,
+            validator=validate_azure_monitor_logs_amp_controls_for_update,
+            help="Enable Prometheus metrics scraping for Azure Monitor Container Insights."
+        )
+        c.argument(
+            "disable_prometheus_metrics_scraping",
+            action="store_true",
+            is_preview=True,
+            validator=validate_azure_monitor_logs_amp_controls_for_update,
+            help="Disable Prometheus metrics scraping for Azure Monitor Container Insights."
         )
         c.argument("enable_secret_rotation", action="store_true")
         c.argument("disable_secret_rotation", action="store_true")

src/aks-preview/azext_aks_preview/_validators.py

@@ -616,11 +616,17 @@ def validate_addon(namespace):
 
 
 def validate_addons(namespace):
-    if not hasattr(namespace, 'addons'):
+    addons = getattr(namespace, 'addons', None)
+    if addons is None:
+        addons = getattr(namespace, 'enable_addons', None)
+    if not addons:
         return
-    addons = namespace.addons
-    addon_args = addons.split(',')
+    addon_args = addons.split(',') if isinstance(addons, str) else list(addons)
     _recognize_addons(addon_args)
+    if 'monitoring' in addon_args:
+        _show_monitoring_addon_legacy_info()
+        if getattr(namespace, 'enable_msi_auth_for_monitoring', None) is not None:
+            _warn_legacy_msi_auth_flag_deprecated()
 
 
 def validate_pod_identity_pod_labels(namespace):
@@ -1201,15 +1207,50 @@ def validate_azure_monitor_and_opentelemetry_for_update(namespace):
     validate_opentelemetry_logs_dependencies_for_update(namespace)
 
 
+def _show_monitoring_addon_legacy_info():
+    """Point legacy monitoring-addon users to the strategic AMP onboarding command."""
+    logger.warning(
+        "The 'monitoring' addon is the legacy Container Insights onboarding path. "
+        "Use '--enable-azure-monitor-logs' / '--disable-azure-monitor-logs' to configure "
+        "the Azure Monitor profile."
+    )
+
+
+def _warn_legacy_msi_auth_flag_deprecated():
+    """Warn when the legacy monitoring addon explicitly selects an authentication mode."""
+    logger.warning(
+        "'--enable-msi-auth-for-monitoring' is deprecated on the legacy monitoring-addon path. "
+        "Managed-identity authentication through '--enable-azure-monitor-logs' is recommended."
+    )
+
+
 def validate_azure_monitor_logs_and_enable_addons(namespace):
     """Validate that enable_azure_monitor_logs and enable_addons don't conflict."""
+    enable_addons = getattr(namespace, 'enable_addons', None)
     if hasattr(namespace, 'enable_azure_monitor_logs') and namespace.enable_azure_monitor_logs:
-        if hasattr(namespace, 'enable_addons') and namespace.enable_addons:
-            if 'monitoring' in namespace.enable_addons:
-                raise ArgumentUsageError(
-                    "Cannot specify both '--enable-azure-monitor-logs' and '--enable-addons monitoring'. "
-                    "Use either '--enable-azure-monitor-logs' or '--enable-addons monitoring'."
-                )
+        if enable_addons and 'monitoring' in enable_addons:
+            raise ArgumentUsageError(
+                "Cannot specify both '--enable-azure-monitor-logs' and '--enable-addons monitoring'. "
+                "Use either '--enable-azure-monitor-logs' or '--enable-addons monitoring'."
+            )
+        # The containerInsights path is always MSI/AAD; legacy (non-MSI) auth cannot be expressed.
+        _validate_monitor_logs_requires_msi_auth(namespace)
+
+
+def _validate_monitor_logs_requires_msi_auth(namespace):
+    """--enable-azure-monitor-logs uses the containerInsights path, which is always MSI/AAD auth.
+
+    Auth selection has no representation on that surface, so reject any explicit use of the legacy
+    auth-selection flag alongside it.
+    """
+    disable_msi_auth = getattr(namespace, 'disable_msi_auth_for_monitoring', None)
+    enable_msi_auth = getattr(namespace, 'enable_msi_auth_for_monitoring', None)
+    if disable_msi_auth or enable_msi_auth is not None:
+        raise ArgumentUsageError(
+            "'--enable-azure-monitor-logs' onboards Container Insights via the azureMonitorProfile, "
+            "which always uses managed-identity (MSI/AAD) authentication. Do not combine it with "
+            "'--enable-msi-auth-for-monitoring'."
+        )
 
 
 def validate_azure_monitor_logs_enable_disable(namespace):
@@ -1220,6 +1261,58 @@ def validate_azure_monitor_logs_enable_disable(namespace):
             "Cannot specify both '--enable-azure-monitor-logs' and '--disable-azure-monitor-logs'. "
             "Use either '--enable-azure-monitor-logs' or '--disable-azure-monitor-logs'."
         )
+    if hasattr(namespace, 'enable_azure_monitor_logs') and namespace.enable_azure_monitor_logs:
+        _validate_monitor_logs_requires_msi_auth(namespace)
+
+
+def _validate_azure_monitor_logs_amp_controls(namespace):
+    """Validate static relationships for AMP-only Container Insights controls."""
+    syslog_port = getattr(namespace, 'syslog_port', None)
+    enable_prometheus_scraping = getattr(namespace, 'enable_prometheus_metrics_scraping', False)
+    disable_prometheus_scraping = getattr(namespace, 'disable_prometheus_metrics_scraping', False)
+
+    if syslog_port is not None and not 1 <= syslog_port <= 65535:
+        raise InvalidArgumentValueError("--syslog-port must be an integer between 1 and 65535.")
+
+    if enable_prometheus_scraping and disable_prometheus_scraping:
+        raise MutuallyExclusiveArgumentError(
+            "Cannot specify both '--enable-prometheus-metrics-scraping' and "
+            "'--disable-prometheus-metrics-scraping'."
+        )
+
+    amp_controls_requested = (
+        syslog_port is not None or
+        enable_prometheus_scraping or
+        disable_prometheus_scraping
+    )
+    if amp_controls_requested and getattr(namespace, 'disable_azure_monitor_logs', False):
+        raise MutuallyExclusiveArgumentError(
+            "Azure Monitor logs AMP controls cannot be combined with '--disable-azure-monitor-logs'."
+        )
+
+
+def validate_azure_monitor_logs_amp_controls_for_create(namespace):
+    """Validate AMP-only controls on create, where monitoring must be enabled in the same command."""
+    _validate_azure_monitor_logs_amp_controls(namespace)
+    amp_controls_requested = (
+        getattr(namespace, 'syslog_port', None) is not None or
+        getattr(namespace, 'enable_prometheus_metrics_scraping', False) or
+        getattr(namespace, 'disable_prometheus_metrics_scraping', False)
+    )
+    if amp_controls_requested and not getattr(namespace, 'enable_azure_monitor_logs', False):
+        raise RequiredArgumentMissingError(
+            "'--syslog-port' and Prometheus-scraping controls require "
+            "'--enable-azure-monitor-logs' on cluster create."
+        )
+
+
+def validate_azure_monitor_logs_amp_controls_for_update(namespace):
+    """Validate static AMP-control relationships on update.
+
+    Whether monitoring is already enabled is validated against the fetched cluster in the update
+    decorator.
+    """
+    _validate_azure_monitor_logs_amp_controls(namespace)
 
 
 def validate_nat_gateway_managed_outbound_ipv6_count(namespace):

src/aks-preview/azext_aks_preview/custom.py

@@ -1280,7 +1280,10 @@ def aks_create(
     enable_addons=None,  # pylint: disable=redefined-outer-name
     enable_azure_monitor_logs=False,
     workspace_resource_id=None,
-    enable_msi_auth_for_monitoring=True,
+    syslog_port=None,
+    enable_prometheus_metrics_scraping=False,
+    disable_prometheus_metrics_scraping=False,
+    enable_msi_auth_for_monitoring=None,
     enable_syslog=None,
     data_collection_settings=None,
     ampls_resource_id=None,
@@ -1570,6 +1573,9 @@ def aks_update(
     enable_azure_monitor_logs=False,
     disable_azure_monitor_logs=False,
     workspace_resource_id=None,
+    syslog_port=None,
+    enable_prometheus_metrics_scraping=False,
+    disable_prometheus_metrics_scraping=False,
     enable_msi_auth_for_monitoring=None,
     enable_syslog=None,
     data_collection_settings=None,
@@ -3589,7 +3595,7 @@ def aks_enable_addons(
     enable_secret_rotation=False,
     rotation_poll_interval=None,
     no_wait=False,
-    enable_msi_auth_for_monitoring=True,
+    enable_msi_auth_for_monitoring=None,
     dns_zone_resource_id=None,
     dns_zone_resource_ids=None,
     enable_syslog=None,
@@ -3604,6 +3610,10 @@ def aks_enable_addons(
     msi_auth = False
     if instance.service_principal_profile.client_id == "msi":
         msi_auth = True
+        if enable_msi_auth_for_monitoring is None:
+            # Preserve the legacy command's existing default while allowing validators to
+            # distinguish an omitted flag from an explicitly supplied true/false value.
+            enable_msi_auth_for_monitoring = True
     else:
         enable_msi_auth_for_monitoring = False