Skip to main content

Add a Microsoft Azure connector

Last updated on

Use the Microsoft Azure connector to connect Harness to your Azure accounts and services. With this connector, Harness pipelines can pull artifacts from Azure Container Registry (ACR), provision infrastructure with Azure Resource Manager (ARM) and Azure Blueprints, and deploy applications to Azure Kubernetes Service (AKS), Azure Web Apps, Azure App Service Environments, and virtual machines using SSH or WinRM.

Use the Azure Repos connector to connect to Azure SCM repositories.

note

If you use Harness Cloud Cost Management (CCM), go to Set up Cloud Cost Management for Azure to configure the Azure connector for CCM.

What will you learn in this topic?​

Before you begin​

  • Azure subscription: Owner or Contributor access on the subscription or resource group where you want Harness to operate.
  • Microsoft Entra ID: Permission to create App Registrations or Managed Identities and assign roles. Go to Create a Microsoft Entra application and service principal to understand the required setup.
  • Harness delegate: A running Harness delegate connected to your Azure environment for delegate-based connectivity. Go to Delegate installation overview to install one.
  • Harness account ID (OIDC only): Navigate to Account Settings in Harness to find your account ID.

Auth Provider API and TokenRequest API options​

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

Auth Provider API vs. TokenRequest API

In Kubernetes 1.22, the Auth Provider API was deprecated and replaced with the TokenRequest API. The TokenRequest API lets client libraries and tools request an authentication token from the Kubernetes API server dynamically, based on audience, scopes, and other parameters.

The key advantages of the TokenRequest API are finer-grained control over authentication and easier integration with external identity providers such as OAuth 2.0 providers.

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:

RHEL 7
# Install dependencies
microdnf install --nodocs openssl util-linux unzip python2 && microdnf clean all

# Download kubelogin
curl https://github.com/Azure/kubelogin/releases/download/v0.0.27/kubelogin-linux-amd64.zip -L -o kubelogin.zip
unzip kubelogin.zip
chmod 755 /opt/harness-delegate/bin/linux_amd64/kubelogin

# Add the binary to PATH
mv ./bin/linux_amd64/kubelogin /usr/local/bin

# If the AKS cloud provider auth type is Certificate, install azure-cli
# because kubelogin does not support PEM format
rpm --import https://packages.microsoft.com/keys/microsoft.asc
echo -e "[azure-cli]
name=Azure CLI
baseurl=https://packages.microsoft.com/yumrepos/azure-cli
enabled=1
gpgcheck=1
gpgkey=https://packages.microsoft.com/keys/microsoft.asc" | tee /etc/yum.repos.d/azure-cli.repo
microdnf install azure-cli
Ubuntu
# Download kubelogin
curl https://github.com/Azure/kubelogin/releases/download/v0.0.27/kubelogin-linux-amd64.zip -L -o kubelogin.zip
unzip kubelogin.zip
chmod 755 /opt/harness-delegate/bin/linux_amd64/kubelogin

# Add the binary to PATH
mv ./bin/linux_amd64/kubelogin /usr/local/bin

# If the AKS cloud provider auth type is Certificate, install azure-cli
curl -sL https://aka.ms/InstallAzureCLIDeb | bash

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

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.

Azure RBAC hierarchy showing that Resources are managed by Resource groups, which are in turn managed by Subscriptions, and all of these are under a Management group.

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.

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.

ACR Reader role assignment in the Azure portal showing the Subscription scope.
tip
  • 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.
note

Harness supports up to 500 images from an ACR repo. If you do not see all your images, you may have exceeded this limit due to an Azure API restriction. If you connect to ACR via the platform-agnostic Docker connector, the limit is 100.

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.

The following are the Azure RBAC permissions used for System Assigned Managed Identity to perform Azure Web App deployments for container and non-container artifacts:

[
    "microsoft.web/sites/slots/deployments/read",
    "Microsoft.Web/sites/Read",
    "Microsoft.Web/sites/config/Read",
    "Microsoft.Web/sites/slots/config/Read",
    "microsoft.web/sites/slots/config/appsettings/read",
    "Microsoft.Web/sites/slots/*/Read",
    "Microsoft.Web/sites/slots/config/list/Action",
    "Microsoft.Web/sites/slots/stop/Action",
    "Microsoft.Web/sites/slots/start/Action",
    "Microsoft.Web/sites/slots/config/Write",
    "Microsoft.Web/sites/slots/Write",
    "microsoft.web/sites/slots/containerlogs/action",
    "Microsoft.Web/sites/config/Write",
    "Microsoft.Web/sites/slots/slotsswap/Action",
    "Microsoft.Web/sites/config/list/Action",
    "Microsoft.Web/sites/start/Action",
    "Microsoft.Web/sites/stop/Action",
    "Microsoft.Web/sites/Write",
    "microsoft.web/sites/containerlogs/action",
    "Microsoft.Web/sites/publish/Action",
    "Microsoft.Web/sites/slots/publish/Action"
]

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.

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.

The following permissions are required for any Service Principal or Managed Identity user, regardless of whether you use Kubernetes RBAC or Azure RBAC. Replace xxxx with your role name, subscription ID, and resource group ID.

{
    "id": "/subscriptions/xxxx/providers/Microsoft.Authorization/roleDefinitions/xxxx",
    "properties": {
        "roleName": "xxxx",
        "description": "",
        "assignableScopes": [
            "/subscriptions/xxxx/resourceGroups/xxxx"
        ],
        "permissions": [
            {
                "actions": [],
                "notActions": [],
                "dataActions": [
                    "Microsoft.ContainerService/managedClusters/configmaps/read",
                    "Microsoft.ContainerService/managedClusters/configmaps/write",
                    "Microsoft.ContainerService/managedClusters/configmaps/delete",
                    "Microsoft.ContainerService/managedClusters/secrets/read",
                    "Microsoft.ContainerService/managedClusters/secrets/write",
                    "Microsoft.ContainerService/managedClusters/secrets/delete",
                    "Microsoft.ContainerService/managedClusters/apps/deployments/read",
                    "Microsoft.ContainerService/managedClusters/apps/deployments/write",
                    "Microsoft.ContainerService/managedClusters/apps/deployments/delete",
                    "Microsoft.ContainerService/managedClusters/events/read",
                    "Microsoft.ContainerService/managedClusters/events/write",
                    "Microsoft.ContainerService/managedClusters/events/delete",
                    "Microsoft.ContainerService/managedClusters/namespaces/read",
                    "Microsoft.ContainerService/managedClusters/nodes/read",
                    "Microsoft.ContainerService/managedClusters/pods/read",
                    "Microsoft.ContainerService/managedClusters/pods/write",
                    "Microsoft.ContainerService/managedClusters/pods/delete",
                    "Microsoft.ContainerService/managedClusters/services/read",
                    "Microsoft.ContainerService/managedClusters/services/write",
                    "Microsoft.ContainerService/managedClusters/services/delete",
                    "Microsoft.ContainerService/managedClusters/apps/statefulsets/read",
                    "Microsoft.ContainerService/managedClusters/apps/statefulsets/write",
                    "Microsoft.ContainerService/managedClusters/apps/statefulsets/delete",
                    "Microsoft.ContainerService/managedClusters/apps/replicasets/read",
                    "Microsoft.ContainerService/managedClusters/apps/replicasets/write",
                    "Microsoft.ContainerService/managedClusters/apps/replicasets/delete"
                ],
                "notDataActions": []
            }
        ]
    }
}

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.
ARM Key Vault access policy setting showing the Azure Resource Manager for template deployment option.
note

The Azure roles provided in the connector must allow Harness to provision the Azure resources in your ARM templates. For example, to create a policy assignment, the Resource Policy Contributor role is required.

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.

Add an Azure connector​

You can add Azure connectors at the account, org, or project level at any time, or while setting up pipelines.

Perform the following steps to add an Azure connector:

  1. Navigate to Project Setup (or Account Settings or Organization Settings), then select Connectors.
  2. Select New Connector, then under Cloud Providers, select Azure Cloud Provider.
  3. Enter a Name. Harness automatically creates an Id based on the name using the Entity Identifier format. You can edit the ID before saving; once saved, the ID is immutable.
  4. Optionally, add a description and tags.
  5. Select Continue to configure credentials.

Configure credentials​

The Azure connector supports three credential methods. Select the method that matches your Azure setup.

Specify credentials​

Select Specify credentials here to authenticate using an Azure App Registration with a client secret or certificate. Provide the App Registration's Application (client) ID and Directory (tenant) ID.

A comparison of App Registration details and corresponding fields in the Harness connector settings.

Perform the following steps to configure credentials:

  1. In Microsoft Azure, go to the App Registration Overview page and note the Application (client) ID and Directory (tenant) ID.

    Microsoft Azure App Registration Overview page showing Application (client) ID and Directory (tenant) ID.

  2. In the Harness Azure connector settings, select the Environment: Azure Global or US Government.

  3. Enter the Application (client) ID in the Application Id field.

  4. Enter the Directory (tenant) ID in the Tenant Id field.

  5. For Authentication, select Secret or Certificate, then select or create a Harness Text Secret or Harness File Secret.

    Harness supports PEM files only. PFX files are not supported.

    To create a new client secret, go to App Registrations in Microsoft Entra ID, select your app, select Certificates & secrets, then select New client secret. Go to Creating a new application secret for steps.

    Azure App Registration Certificates and secrets panel showing the New client secret option.

  6. Select Continue.

Select connectivity mode​

The connectivity mode determines how Harness communicates with Azure. Perform the following steps to complete the connectivity configuration:

  1. Select how you want Harness to connect to Azure:

    • Connect through Harness Platform: direct, secure communication between Harness and Azure. This mode is required for Harness Cloud build infrastructure. Not available with OIDC authentication.
    • Connect through a Harness Delegate: Harness communicates with Azure through a Harness delegate in your Azure subscription or AKS cluster. Required when using inherited delegate credentials or OIDC authentication.

  2. If connecting through a Harness delegate, select one of the following:

    • Use any available Delegate: Harness selects an available delegate at runtime.
    • Only use Delegates with all of the following tags: use tags to target one or more specific delegates. You can also install a new delegate at this time.

  3. Select Save and Continue to run the connection test. If the test succeeds, select Finish. The connection test confirms that your authentication and delegate selections are valid.

    If the connection test fails, confirm that your delegate is running and that your credentials are valid. For example, check that the client secret has not expired in your App Registration.

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:

export KUBECONFIG=${HARNESS_KUBE_CONFIG_PATH} kubectl get pods -n <namespace>

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​

You have configured the Microsoft Azure connector. Continue your learning journey with the following:

Last updated on