Azure connector settings reference

Harness uses Microsoft Azure connectors for activities such as pulling artifacts from Azure Container Registry (ACR), provisioning infrastructure with Azure Resource Manager (ARM) and Azure Blueprints, and deploying applications to Azure Kubernetes Service (AKS), Azure Web Apps, and virtual machines using SSH or WinRM.

This topic describes the roles and permissions required for each Azure service and advanced AKS authentication settings.

What you will learn from this topic

• The roles, permissions, and cluster requirements for ACR, AKS, Azure Web Apps, ARM, and Blueprints.

• How to install the kubelogin plugin on a delegate for AKS authentication using Kubernetes 1.22 and later.

• How to use ${HARNESS_KUBE_CONFIG_PATH} with Azure connector credentials in a Shell Script step.

Roles permissions and cluster requirements

This section covers the minimum Azure Role-Based Access Control (RBAC) roles and cluster configuration required for each Azure service. This section assumes you are familiar with Azure RBAC. Go to Assign Azure roles using the Azure portal for a refresher.

For security reasons, Harness uses an application object and service principal rather than a user identity. Go to Create a Microsoft Entra application and service principal that can access resources for details.

ACR role requirements

The Azure connector you use to connect Harness to ACR must have the Reader role at minimum. You can also use a custom role that includes the Reader permissions.

The following tabs describe the Reader role requirements and a sample custom role definition.

Reader role

Custom role

Assign the Reader role at the Subscription or Resource Group level for the Application (client) ID used in the Azure connector. The application must have permission to list all container registries.

• Do not assign the Reader role in a different IAM section of Azure.

• Do not assign only the AcrPull role instead of Reader. AcrPull grants access to a specific registry, but Harness requires the Reader role to list all registries.

The following permissions are required for any Service Principal or Managed Identity user, regardless of whether you use Kubernetes RBAC or Azure RBAC:

• Microsoft.ContainerRegistry/registries/read

• Microsoft.ContainerRegistry/registries/builds/read

• Microsoft.ContainerRegistry/registries/metadata/read

• Microsoft.ContainerRegistry/registries/pull/read

• Microsoft.ContainerService/managedClusters/read

• Microsoft.ContainerService/managedClusters/listClusterUserCredential/action

• Microsoft.Resource/subscriptions/resourceGroup/read

For Helm deployments, Helm version 3.2.0 or later is required and the HELM_VERSION_3_8_0 feature flag must be enabled.

You cannot use Pod Assigned Managed Identity and System Assigned Managed Identity on the same cluster.

The following JSON creates a custom role with the required permissions. Replace xxxx with your role name, subscription ID, and resource group ID.

Azure Web App role requirements

The Azure connector used to connect to Azure Web Apps with Service Principal or Managed Identity credentials must have the Contributor role at minimum. You can also use a custom role that includes the Contributor permissions.

The following tabs describe the Contributor role permissions and a sample custom role definition.

Connect Harness to Azure Kubernetes Service (AKS)

There are three options for connecting Harness to an AKS cluster. Each option differs in the type of credentials required and the delegate placement.

• Platform-agnostic Kubernetes cluster connector: install a Kubernetes delegate in the target AKS cluster and use the delegate's credentials. No Azure Service Principal or Managed Identity credentials are required.

• Microsoft Azure connector with a Kubernetes delegate: install a Kubernetes delegate in the AKS cluster. Provide the Azure environment and, for User Assigned Managed Identity, the Application (client) ID. You can create a connector referencing a non-existent delegate; Harness allows this so you can replace a delegate with one of the same name or tag.

• Microsoft Azure connector with Service Principal or Managed Identity credentials: assign the Owner role or an equivalent custom role as described in AKS role requirements.

AKS cluster setup requirements

The following AKS cluster configuration is required to use the Azure connector:

• AKS managed Azure Active Directory (AAD): enabled or disabled.

• Kubernetes RBAC: enabled.

• Azure RBAC: enabled or disabled.

Go to the Deployments (CD) section of the Kubernetes cluster connector settings reference for full details.

AKS role requirements

If you use the Microsoft Azure connector to connect to AKS with Service Principal or Managed Identity credentials, assign the Owner role or a custom role that includes the Owner permissions.

The following tabs provide example role definitions for AKS.

Azure Resource Management (ARM) role requirements

The roles required for ARM depend on the scope type of your ARM template:

• Resource group: requires the Contributor role.

• Subscription: requires the Contributor role.

• Management group: requires the Contributor role.

• Tenant: requires the Contributor or Owner role. Creating a Tenant requires Contributor, but creating role assignments requires Owner.

• Key Vault access: to enable access to Key Vaults from ARM templates, select the Azure Resource Manager for template deployment option in the Key Vault Access Policy.

Azure Blueprints role requirements

Go to Permissions in Azure Blueprints for the full list of roles required to create and delete Blueprints.

The Azure roles required on the service principal depend on the scope of your Blueprint definition.

Management scope:

• System-assigned managed identity: Contributor role at the management group scope where Blueprint definitions are created and published; Owner role at the subscription scope where the assignment is done.

• User-assigned managed identity: Contributor role at the management group scope where Blueprint definitions are created and published. Harness does not manage the lifecycle of user-managed identities; you are responsible for that.

Subscription scope:

• System-assigned managed identity: Owner role at the subscription scope.

• User-assigned managed identity: Contributor role to create and publish the Blueprint definition. Harness does not manage the lifecycle of user-managed identities; you are responsible for that.

Auth Provider API and TokenRequest API options

Harness supports both the Auth Provider API and the TokenRequest API for AKS authentication.

To select which API to use:

• Auth Provider API: the current default. You do not have to change the default settings of Harness connectors or the Harness delegates you use.

• TokenRequest API: you must install the provider-specific plugin on the Harness delegate to use the TokenRequest API introduced in Kubernetes 1.22.

Install the kubelogin client-go credential (exec) plugin on the delegate

When using the Harness Azure connector with Kubernetes version 1.22 or later, you can use the kubelogin client-go credential plugin to authenticate to an AKS cluster.

The Azure connector supports four authentication types. Install the following dependencies on the Harness delegates you use, or Harness will fall back to the Auth Provider API format.

• Secret (SERVICE_PRINCIPAL_SECRET): kubelogin binary.

• Certificate (SERVICE_PRINCIPAL_CERT): kubelogin binary and Azure CLI (required because kubelogin does not support PEM format certificates).

• System Assigned Managed Identity (MANAGED_IDENTITY_SYSTEM_ASSIGNED): kubelogin binary.

• User Assigned Managed Identity (MANAGED_IDENTITY_USER_ASSIGNED): kubelogin binary.

Secret and Certificate are available when you select Specify credentials here. System Assigned Managed Identity and User Assigned Managed Identity are available when you select Use the credentials of a specific Harness Delegate.

Perform the following steps to install kubelogin on the delegate using an immutable delegate image and INIT_SCRIPT:

Go to kubelogin releases on Azure and Delegate installation overview for further details.

Use ${HARNESS_KUBE_CONFIG_PATH} with Azure

The Harness expression ${HARNESS_KUBE_CONFIG_PATH} resolves to the path of a Harness-generated kubeconfig file containing the credentials you provided to the connector.

You can use these credentials with kubectl commands by exporting the expression value to the KUBECONFIG environment variable. For example, add the following to a Harness Shell Script step:

Go to Select delegates with selectors to run steps on a specific delegate.

Note the following for Azure deployments:

• If the Azure connector uses Azure Managed Identity for authentication, the Shell Script step must use a Delegate Selector for a delegate running in AKS.

• If the Azure connector uses Azure Service Principal for authentication, the Shell Script step can use any delegate.

Next steps

• Add a Microsoft Azure connector: Create an Azure connector using the Harness UI.