Merge pull request #295170 from maud-lv/ml-scaks

Add more details about Service Connector for AKS

Author: ttorble

articles/service-connector/how-to-use-service-connector-in-aks.md

@@ -11,58 +11,117 @@ ms.author: honc
 
 # Use Service Connector in Azure Kubernetes Service (AKS)
 
-Azure Kubernetes Service (AKS) is one of the compute services supported by Service Connector. 
-This article aims to help you understand:
+Azure Kubernetes Service (AKS) is one of the compute services supported by Service Connector.
 
-* What operations are made on the cluster when creating a service connection.
-* How to use the Kubernetes resources created by Service Connector.
-* How to troubleshoot and view Service Connector logs in an AKS cluster.
+This article covers:
+
+* The differences between Service Connector for AKS and other compute services.
+* The operations executed on the cluster during the creation of a service connection.
+* The operations executed on the target services during the creation of a service connection.
+* Using the Kubernetes resources created by Service Connector.
+* Troubleshooting and viewing Service Connector logs in an AKS cluster.
 
 ## Prerequisites
 
 * This guide assumes that you already know the [basic concepts of Service Connector](concept-service-connector-internals.md).
 
+## Differences between Service Connector for AKS and other compute services
+
+Service Connector for AKS differs from how it operates with other [compute services supported by Service Connector](/azure/service-connector/overview#what-services-are-supported-by-service-connector) in several ways. The following outlines AKS-specific options and behaviors for each API operation.
+
+### Creation
+
+The AKS-specific creation options are listed below. Refer to the [Azure portal](/azure/service-connector/quickstart-portal-aks-connection) or [Azure CLI](/azure/service-connector/quickstart-cli-aks-connection) quickstarts to learn how to create a new connection in AKS.
+
+- Service Connector for AKS requires the `Kubernetes namespace` parameter to specify where to [create the Kubernetes resources](#creating-the-kubernetes-resources). By default, it uses the `default` namespace.
+- Service Connector for AKS supports `Workload Identity` as the secure credential authentication option, while other compute services offer `System Managed Identity` and `User Managed Identity` options.
+- When using Azure Key Vault as the target service with the Secret Store CSI Driver enabled, Service Connector uses the user-assigned managed identity from the AKS `azure-keyvault-secrets-provider` add-on for authentication, without requiring users to specify the authentication type.
+- Service Connector for AKS only supports the `Firewall Rules` networking option, whereas other compute services may also support `Private Link` and `Virtual Network` options.
+
+### List configurations
+
+Service Connector for AKS displays only non-credential configurations in the list configuration views. Users should manually check the credentials in the [associated Kubernetes resource](#creating-the-kubernetes-resources) if needed.
+
+Using the Azure CLI command [az aks connection list-configuration](/cli/azure/aks/connection?view=azure-cli-latest&preserve-view=true#az-aks-connection-list-configuration), the value of a credential configuration is an empty string. In the Azure portal, the value of a credential configuration is hidden, as shown below.
+
+:::image type="content" source="./media/aks-tutorial/aks-list-config.png" alt-text="Screenshot of the AKS connection listing configuration.":::
+
+### Validation
+
+Service Connector for AKS doesn't validate configuration value changes made within the user's cluster, whether they're credential or non-credential configurations. However, Service Connector performs the following validations, as it does for other compute services:
+
+- Verifying the existence of the target service
+- Checking IP firewall rules for access to the target service
+- Ensuring role assignment for workload identity to access the target service
+
+The output of the Azure CLI command [az aks connection validate](/cli/azure/aks/connection?view=azure-cli-latest&preserve-view=true#az-aks-connection-validate) is always `success`. The same applies to the Azure portal, as shown below.
+
+:::image type="content" source="./media/aks-tutorial/aks-validate.png" alt-text="Screenshot of the AKS connection validation.":::
+
 ## Operations performed by Service Connector on the AKS cluster
 
-Depending on the different target services and authentication types selected when creating a service connection, Service Connector makes different operations on the AKS cluster. The following lists the possible operations made by Service Connector.
+The operations performed by Service Connector on the AKS cluster vary depending on the target services and authentication types selected when creating a service connection. The following lists the possible operations made by Service Connector.
 
 ### Adding the Service Connector Kubernetes extension
 
-A Kubernetes extension named `sc-extension` is added to the cluster the first time a service connection is created. Later on, the extension helps create Kubernetes resources in user's cluster, whenever a service connection request comes to Service Connector. You can find the extension in your AKS cluster in the Azure portal, in the **Extensions + applications** menu.
+A Kubernetes extension named `sc-extension` is added to the cluster the first time a service connection is created. Later on, the extension helps create Kubernetes resources in the user's cluster, whenever a service connection request comes to Service Connector. The extension is found in the user's AKS cluster in the Azure portal, in the **Extensions + applications** menu.
 
 :::image type="content" source="./media/aks-tutorial/sc-extension.png" alt-text="Screenshot of the Azure portal, view AKS extension.":::
 
-The extension is also where the cluster connections metadata are stored. Uninstalling the extension makes all the connections in the cluster unavailable. The extension operator is hosted in the cluster namespace `sc-system`.
+The cluster connection's metadata are also stored in the extension. Uninstalling the extension renders all the connections in the cluster unavailable. The extension operator is hosted in the cluster namespace `sc-system`.
 
 ### Creating the Kubernetes resources
 
-Service Connector creates some Kubernetes resources to the namespace the user specified when creating a service connection. The Kubernetes resources store the connection information, which is needed by the user's workload definitions or application code to talk to target services. Depending on different authentication types, different Kubernetes resources are created. For the `Connection String` and `Service Principal` auth types, a Kubernetes secret is created. For the `Workload Identity` auth type, a Kubernetes service account is also created in addition to a Kubernetes secret.
+Service Connector creates Kubernetes resources in the namespace the user specifies when creating the service connection. The Kubernetes resources store the connection information needed by the user's workload definitions or application code to communicate with the target services. Depending on the authentication type, different Kubernetes resources are created. For the `Connection String` and `Service Principal` auth types, a Kubernetes secret is created. For the `Workload Identity` auth type, a Kubernetes service account is also created in addition to a Kubernetes secret.
 
 You can find the Kubernetes resources created by Service Connector for each service connection on the Azure portal in your Kubernetes resource, in the Service Connector menu.
 
 :::image type="content" source="./media/aks-tutorial/kubernetes-resources.png" alt-text="Screenshot of the Azure portal, view Service Connector created Kubernetes resources.":::
 
-Deleting a service connection doesn't delete the associated Kubernetes resource. If necessary, remove your resource manually, using for example the kubectl delete command.
+Deleting a service connection doesn't delete the associated Kubernetes resource. If necessary, remove your resource manually, using for example the `kubectl delete` command.
 
 ### Enabling the `azureKeyvaultSecretsProvider` add-on
 
-If target service is Azure Key Vault and the Secret Store CSI Driver is enabled when creating a service connection, Service Connector enables the `azureKeyvaultSecretsProvider` add-on for the cluster.
+If  the target service is Azure Key Vault and the Secret Store CSI Driver is enabled, Service Connector enables the `azureKeyvaultSecretsProvider` add-on for the cluster.
 
 :::image type="content" source="./media/aks-tutorial/keyvault-csi.png" alt-text="Screenshot of the Azure portal, enabling CSI driver for keyvault when creating a connection.":::
 
-Follow the [Connect to Azure Key Vault using CSI driver tutorial](./tutorial-python-aks-keyvault-csi-driver.md)to set up a connection to Azure Key Vault using Secret Store CSI driver.
+Follow the [Connect to Azure Key Vault using CSI driver tutorial](./tutorial-python-aks-keyvault-csi-driver.md) to set up a connection to Azure Key Vault using Secret Store CSI driver.
 
 ### Enabling workload identity and OpenID Connect (OIDC) issuer
 
-If the authentication type is `Workload Identity` when creating a service connection, Service Connector enables workload identity and OIDC issuer for the cluster.
+If the authentication type is `Workload Identity`, Service Connector enables workload identity and OIDC issuer for the cluster.
 
 :::image type="content" source="./media/aks-tutorial/workload-identity.png" alt-text="Screenshot of the Azure portal, using workload identity to create a connection.":::
 
-When the authentication type is `Workload Identity`, a user-assigned managed identity is needed to create the federated identity credential. Learn more from [what are workload identities](/entra/workload-id/workload-identities-overview), or follow the [tutorial](./tutorial-python-aks-storage-workload-identity.md)to set up a connection to Azure Storage using workload identity.
+If the authentication type is `Workload Identity`, a user-assigned managed identity is needed to create the federated identity credential. Learn more about [workload identities](/entra/workload-id/workload-identities-overview) or refer [the following tutorial](./tutorial-python-aks-storage-workload-identity.md) to set up a connection to Azure Storage using a workload identity.
+
+## Operations performed by Service Connector on the target services
+
+Service Connector for AKS performs the same operations on target services as other compute services. However, the operations vary depending on the target service types and authentication methods. The following lists some possible operations.
+
+### Get connection configurations
+
+Service Connector retrieves the required connection configurations from the target service and sets them as a Kubernetes secret in the user's cluster. The connection configurations vary based on the target service type and authentication method:
+
+- For the `Connection String` authentication type, the configuration typically includes a service secret or connection string.
+- For the `Workload Identity` authentication type, it usually contains the service endpoint.
+- For the `Service Principal` authentication type, it contains the service principal's tenant ID, client ID, and client secret. 
+
+For detailed information on specific target services, refer to the corresponding documentation, such as the [Azure AI services](/azure/service-connector/how-to-integrate-ai-services?tabs=dotnet#system-assigned-managed-identity-recommended) guide.
+
+### Create IP based firewall rules
+
+Service Connector retrieves the outbound public IP from the AKS cluster and creates IP firewall rules on the target service to allow network access from the cluster.
+
+### Create Microsoft Entra ID role assignments
+
+When using the `Workload Identity` authentication type, Service Connector automatically creates a role assignment for the identity. The assigned role varies based on the target service to ensure appropriate access.
+Users can also customize role assignments as needed. For more information, see [role customization](/azure/service-connector/concept-microsoft-entra-roles#role-customization).
 
 ## Use the Kubernetes resources created by Service Connector
 
-Various Kubernetes resources are created by Service Connector depending on the target service type and authentication type. The following sections show how to use the Kubernetes resources created by Service Connector in your cluster workloads definition and application code.
+Service Connector creates various Kubernetes resources depending on the target service type and authentication type selected. The following sections show how to use the Kubernetes resources created by Service Connector in your cluster workloads definition and application code.
 
 ### Kubernetes secret
 
@@ -124,7 +183,7 @@ If an error occurs and can't be resolved by retrying when creating a service con
 
 ### Check Service Connector Kubernetes extension
 
-The Service Connector Kubernetes extension is built on top of [Azure Arc-enabled Kubernetes cluster extensions](/azure/azure-arc/kubernetes/extensions). Use the following commands to check for any errors that occurred during the extension installation or update process.
+The Service Connector Kubernetes extension is built on top of [Azure Arc-enabled Kubernetes cluster extensions](/azure/azure-arc/kubernetes/extensions). Use the following commands to check for any errors occurring during the extension installation or update process.
 
 1. Install the `k8s-extension` Azure CLI extension.
 
@@ -193,7 +252,8 @@ If an error occurs during the extension installation and the error message in th
 
 **Error message:**
 
-`Unable to get a response from the agent in time`.
+- `Unable to get a response from the agent in time`.
+- `Extension pods can't be scheduled if all the node pools in the cluster are "CriticalAddonsOnly" tainted`
 
 **Mitigation:**
 
@@ -204,8 +264,15 @@ Refer to [extension creation errors](/troubleshoot/azure/azure-kubernetes/extens
 
 **Error messages:**
 
-- `Timed out waiting for resource readiness`
 - `Unable to download the Helm chart from the repo URL`
+
+This error is caused by connectivity problems that occur between the cluster and the firewall in addition to egress blocking problems. 
+To resolve this problem, see [Outbound network and FQDN rules for Azure Kubernetes Service (AKS) clusters](/azure/aks/outbound-rules-control-egress), 
+and add the FQDN required to pull Service Connector Helm chart: `scaksextension.azurecr.io`
+
+**Error messages:**
+
+- `Timed out waiting for resource readiness`
 - `Helm chart rendering failed with given values`
 - `Resource already exists in your cluster`
 - `Operation is already in progress for Helm`