Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Bicep resource definition
The connectedClusters resource type can be deployed with operations that target:
- Resource groups - See resource group deployment commands
For a list of changed properties in each API version, see change log.
Resource format
To create a Microsoft.Kubernetes/connectedClusters resource, add the following Bicep to your template.
resource symbolicname 'Microsoft.Kubernetes/connectedClusters@2025-12-01-preview' = {
identity: {
type: 'string'
}
kind: 'string'
location: 'string'
name: 'string'
properties: {
aadProfile: {
adminGroupObjectIDs: [
'string'
]
enableAzureRBAC: bool
tenantID: 'string'
}
agentPublicKeyCertificate: 'string'
arcAgentProfile: {
agentAutoUpgrade: 'string'
agentErrors: [
{}
]
desiredAgentVersion: 'string'
systemComponents: [
{
majorVersion: int
type: 'string'
userSpecifiedVersion: 'string'
}
]
}
arcAgentryConfigurations: [
{
feature: 'string'
protectedSettings: {
{customized property}: 'string'
}
settings: {
{customized property}: 'string'
}
}
]
azureHybridBenefit: 'string'
distribution: 'string'
distributionVersion: 'string'
gateway: {
enabled: bool
}
infrastructure: 'string'
oidcIssuerProfile: {
enabled: bool
selfHostedIssuerUrl: 'string'
}
privateLinkScopeResourceId: 'string'
privateLinkState: 'string'
provisioningState: 'string'
securityProfile: {
workloadIdentity: {
enabled: bool
}
}
}
tags: {
{customized property}: 'string'
}
}
Property Values
Microsoft.Kubernetes/connectedClusters
| Name | Description | Value |
|---|---|---|
| identity | The identity of the connected cluster. | ConnectedClusterIdentity (required) |
| kind | The kind of connected cluster. | 'AWS' 'GCP' 'ProvisionedCluster' |
| location | The geo-location where the resource lives | string (required) |
| name | The resource name | string (required) |
| properties | Describes the connected cluster resource properties. | ConnectedClusterProperties (required) |
| tags | Resource tags | Dictionary of tag names and values. See Tags in templates |
AadProfile
| Name | Description | Value |
|---|---|---|
| adminGroupObjectIDs | The list of AAD group object IDs that will have admin role of the cluster. | string[] |
| enableAzureRBAC | Whether to enable Azure RBAC for Kubernetes authorization. | bool |
| tenantID | The AAD tenant ID to use for authentication. If not specified, will use the tenant of the deployment subscription. | string |
AgentError
| Name | Description | Value |
|---|
ArcAgentProfile
| Name | Description | Value |
|---|---|---|
| agentAutoUpgrade | Indicates whether the Arc agents on the be upgraded automatically to the latest version. Defaults to Enabled. | 'Disabled' 'Enabled' |
| agentErrors | List of arc agentry and system components errors on the cluster resource. | AgentError[] |
| desiredAgentVersion | Version of the Arc agents to be installed on the cluster resource | string |
| systemComponents | List of system extensions that are installed on the cluster resource. | SystemComponent[] |
ArcAgentryConfigurations
| Name | Description | Value |
|---|---|---|
| feature | Specifies the name of the feature for the configuration setting. | string |
| protectedSettings | The configuration settings for the feature that contain any sensitive or secret information. | ArcAgentryConfigurationsProtectedSettings |
| settings | The configuration settings for the feature that do not contain any sensitive or secret information. | ArcAgentryConfigurationsSettings |
ArcAgentryConfigurationsProtectedSettings
| Name | Description | Value |
|---|
ArcAgentryConfigurationsSettings
| Name | Description | Value |
|---|
ConnectedClusterIdentity
| Name | Description | Value |
|---|---|---|
| type | The type of identity used for the connected cluster. The type 'SystemAssigned, includes a system created identity. The type 'None' means no identity is assigned to the connected cluster. | 'None' 'SystemAssigned' (required) |
ConnectedClusterProperties
| Name | Description | Value |
|---|---|---|
| aadProfile | AAD profile for the connected cluster. | AadProfile |
| agentPublicKeyCertificate | Base64 encoded public certificate used by the agent to do the initial handshake to the backend services in Azure. | string (required) |
| arcAgentProfile | Arc agentry configuration for the provisioned cluster. | ArcAgentProfile |
| arcAgentryConfigurations | Configuration settings for customizing the behavior of the connected cluster. | ArcAgentryConfigurations[] |
| azureHybridBenefit | Indicates whether Azure Hybrid Benefit is opted in | 'False' 'NotApplicable' 'True' |
| distribution | The Kubernetes distribution running on this connected cluster. | string |
| distributionVersion | The Kubernetes distribution version on this connected cluster. | string |
| gateway | Details of the gateway used by the Arc router for connectivity. | Gateway |
| infrastructure | The infrastructure on which the Kubernetes cluster represented by this connected cluster is running on. | string |
| oidcIssuerProfile | Open ID Connect (OIDC) Issuer Profile for the connected cluster. | OidcIssuerProfile |
| privateLinkScopeResourceId | This is populated only if privateLinkState is enabled. The resource id of the private link scope this connected cluster is assigned to, if any. | string |
| privateLinkState | Property which describes the state of private link on a connected cluster resource. | 'Disabled' 'Enabled' |
| provisioningState | Provisioning state of the connected cluster resource. | 'Accepted' 'Canceled' 'Deleting' 'Failed' 'Provisioning' 'Succeeded' 'Updating' |
| securityProfile | Security profile for the connected cluster. | SecurityProfile |
Gateway
| Name | Description | Value |
|---|---|---|
| enabled | Indicates whether the gateway for arc router connectivity is enabled. | bool |
OidcIssuerProfile
| Name | Description | Value |
|---|---|---|
| enabled | Whether to enable oidc issuer for workload identity integration. | bool |
| selfHostedIssuerUrl | The issuer url for public cloud clusters - AKS, EKS, GKE - used for the workload identity feature. | string |
SecurityProfile
| Name | Description | Value |
|---|---|---|
| workloadIdentity | The workload identity feature webhook. | SecurityProfileWorkloadIdentity |
SecurityProfileWorkloadIdentity
| Name | Description | Value |
|---|---|---|
| enabled | Whether to enable or disable the workload identity Webhook | bool |
SystemComponent
| Name | Description | Value |
|---|---|---|
| majorVersion | Major Version of the system extension that is currently installed on the cluster resource. | int |
| type | Type of the system extension | string |
| userSpecifiedVersion | Version of the system extension to be installed on the cluster resource. | string |
TrackedResourceTags
| Name | Description | Value |
|---|
Usage Examples
Bicep Samples
A basic example of deploying Arc Kubernetes Cluster.
param resourceName string = 'acctest0001'
param location string = 'westus'
resource connectedCluster 'Microsoft.Kubernetes/connectedClusters@2024-01-01' = {
name: '${resourceName}-cc'
location: location
kind: 'ProvisionedCluster'
properties: {
agentPublicKeyCertificate: ''
arcAgentProfile: {
agentAutoUpgrade: 'Enabled'
}
}
}
Azure Verified Modules
The following Azure Verified Modules can be used to deploy this resource type.
| Module | Description |
|---|---|
| Kubernetes Connected Cluster | AVM Resource Module for Kubernetes Connected Cluster |
Azure Quickstart Samples
The following Azure Quickstart templates contain Bicep samples for deploying this resource type.
| Bicep File | Description |
|---|---|
| Create a Kubernetes cluster on Azure Stack HCI | This template creates a Kubernetes cluster on Azure Stack HCI version 23H2+ |
ARM template resource definition
The connectedClusters resource type can be deployed with operations that target:
- Resource groups - See resource group deployment commands
For a list of changed properties in each API version, see change log.
Resource format
To create a Microsoft.Kubernetes/connectedClusters resource, add the following JSON to your template.
{
"type": "Microsoft.Kubernetes/connectedClusters",
"apiVersion": "2025-12-01-preview",
"name": "string",
"identity": {
"type": "string"
},
"kind": "string",
"location": "string",
"properties": {
"aadProfile": {
"adminGroupObjectIDs": [ "string" ],
"enableAzureRBAC": "bool",
"tenantID": "string"
},
"agentPublicKeyCertificate": "string",
"arcAgentProfile": {
"agentAutoUpgrade": "string",
"agentErrors": [
{
}
],
"desiredAgentVersion": "string",
"systemComponents": [
{
"majorVersion": "int",
"type": "string",
"userSpecifiedVersion": "string"
}
]
},
"arcAgentryConfigurations": [
{
"feature": "string",
"protectedSettings": {
"{customized property}": "string"
},
"settings": {
"{customized property}": "string"
}
}
],
"azureHybridBenefit": "string",
"distribution": "string",
"distributionVersion": "string",
"gateway": {
"enabled": "bool"
},
"infrastructure": "string",
"oidcIssuerProfile": {
"enabled": "bool",
"selfHostedIssuerUrl": "string"
},
"privateLinkScopeResourceId": "string",
"privateLinkState": "string",
"provisioningState": "string",
"securityProfile": {
"workloadIdentity": {
"enabled": "bool"
}
}
},
"tags": {
"{customized property}": "string"
}
}
Property Values
Microsoft.Kubernetes/connectedClusters
| Name | Description | Value |
|---|---|---|
| apiVersion | The api version | '2025-12-01-preview' |
| identity | The identity of the connected cluster. | ConnectedClusterIdentity (required) |
| kind | The kind of connected cluster. | 'AWS' 'GCP' 'ProvisionedCluster' |
| location | The geo-location where the resource lives | string (required) |
| name | The resource name | string (required) |
| properties | Describes the connected cluster resource properties. | ConnectedClusterProperties (required) |
| tags | Resource tags | Dictionary of tag names and values. See Tags in templates |
| type | The resource type | 'Microsoft.Kubernetes/connectedClusters' |
AadProfile
| Name | Description | Value |
|---|---|---|
| adminGroupObjectIDs | The list of AAD group object IDs that will have admin role of the cluster. | string[] |
| enableAzureRBAC | Whether to enable Azure RBAC for Kubernetes authorization. | bool |
| tenantID | The AAD tenant ID to use for authentication. If not specified, will use the tenant of the deployment subscription. | string |
AgentError
| Name | Description | Value |
|---|
ArcAgentProfile
| Name | Description | Value |
|---|---|---|
| agentAutoUpgrade | Indicates whether the Arc agents on the be upgraded automatically to the latest version. Defaults to Enabled. | 'Disabled' 'Enabled' |
| agentErrors | List of arc agentry and system components errors on the cluster resource. | AgentError[] |
| desiredAgentVersion | Version of the Arc agents to be installed on the cluster resource | string |
| systemComponents | List of system extensions that are installed on the cluster resource. | SystemComponent[] |
ArcAgentryConfigurations
| Name | Description | Value |
|---|---|---|
| feature | Specifies the name of the feature for the configuration setting. | string |
| protectedSettings | The configuration settings for the feature that contain any sensitive or secret information. | ArcAgentryConfigurationsProtectedSettings |
| settings | The configuration settings for the feature that do not contain any sensitive or secret information. | ArcAgentryConfigurationsSettings |
ArcAgentryConfigurationsProtectedSettings
| Name | Description | Value |
|---|
ArcAgentryConfigurationsSettings
| Name | Description | Value |
|---|
ConnectedClusterIdentity
| Name | Description | Value |
|---|---|---|
| type | The type of identity used for the connected cluster. The type 'SystemAssigned, includes a system created identity. The type 'None' means no identity is assigned to the connected cluster. | 'None' 'SystemAssigned' (required) |
ConnectedClusterProperties
| Name | Description | Value |
|---|---|---|
| aadProfile | AAD profile for the connected cluster. | AadProfile |
| agentPublicKeyCertificate | Base64 encoded public certificate used by the agent to do the initial handshake to the backend services in Azure. | string (required) |
| arcAgentProfile | Arc agentry configuration for the provisioned cluster. | ArcAgentProfile |
| arcAgentryConfigurations | Configuration settings for customizing the behavior of the connected cluster. | ArcAgentryConfigurations[] |
| azureHybridBenefit | Indicates whether Azure Hybrid Benefit is opted in | 'False' 'NotApplicable' 'True' |
| distribution | The Kubernetes distribution running on this connected cluster. | string |
| distributionVersion | The Kubernetes distribution version on this connected cluster. | string |
| gateway | Details of the gateway used by the Arc router for connectivity. | Gateway |
| infrastructure | The infrastructure on which the Kubernetes cluster represented by this connected cluster is running on. | string |
| oidcIssuerProfile | Open ID Connect (OIDC) Issuer Profile for the connected cluster. | OidcIssuerProfile |
| privateLinkScopeResourceId | This is populated only if privateLinkState is enabled. The resource id of the private link scope this connected cluster is assigned to, if any. | string |
| privateLinkState | Property which describes the state of private link on a connected cluster resource. | 'Disabled' 'Enabled' |
| provisioningState | Provisioning state of the connected cluster resource. | 'Accepted' 'Canceled' 'Deleting' 'Failed' 'Provisioning' 'Succeeded' 'Updating' |
| securityProfile | Security profile for the connected cluster. | SecurityProfile |
Gateway
| Name | Description | Value |
|---|---|---|
| enabled | Indicates whether the gateway for arc router connectivity is enabled. | bool |
OidcIssuerProfile
| Name | Description | Value |
|---|---|---|
| enabled | Whether to enable oidc issuer for workload identity integration. | bool |
| selfHostedIssuerUrl | The issuer url for public cloud clusters - AKS, EKS, GKE - used for the workload identity feature. | string |
SecurityProfile
| Name | Description | Value |
|---|---|---|
| workloadIdentity | The workload identity feature webhook. | SecurityProfileWorkloadIdentity |
SecurityProfileWorkloadIdentity
| Name | Description | Value |
|---|---|---|
| enabled | Whether to enable or disable the workload identity Webhook | bool |
SystemComponent
| Name | Description | Value |
|---|---|---|
| majorVersion | Major Version of the system extension that is currently installed on the cluster resource. | int |
| type | Type of the system extension | string |
| userSpecifiedVersion | Version of the system extension to be installed on the cluster resource. | string |
TrackedResourceTags
| Name | Description | Value |
|---|
Usage Examples
Azure Quickstart Templates
The following Azure Quickstart templates deploy this resource type.
| Template | Description |
|---|---|
Create a Kubernetes cluster on Azure Stack HCI |
This template creates a Kubernetes cluster on Azure Stack HCI version 23H2+ |
Terraform (AzAPI provider) resource definition
The connectedClusters resource type can be deployed with operations that target:
- Resource groups
For a list of changed properties in each API version, see change log.
Resource format
To create a Microsoft.Kubernetes/connectedClusters resource, add the following Terraform to your template.
resource "azapi_resource" "symbolicname" {
type = "Microsoft.Kubernetes/connectedClusters@2025-12-01-preview"
name = "string"
parent_id = "string"
identity {
type = "string"
identity_ids = [
"string"
]
}
location = "string"
tags = {
{customized property} = "string"
}
body = {
kind = "string"
properties = {
aadProfile = {
adminGroupObjectIDs = [
"string"
]
enableAzureRBAC = bool
tenantID = "string"
}
agentPublicKeyCertificate = "string"
arcAgentProfile = {
agentAutoUpgrade = "string"
agentErrors = [
{
}
]
desiredAgentVersion = "string"
systemComponents = [
{
majorVersion = int
type = "string"
userSpecifiedVersion = "string"
}
]
}
arcAgentryConfigurations = [
{
feature = "string"
protectedSettings = {
{customized property} = "string"
}
settings = {
{customized property} = "string"
}
}
]
azureHybridBenefit = "string"
distribution = "string"
distributionVersion = "string"
gateway = {
enabled = bool
}
infrastructure = "string"
oidcIssuerProfile = {
enabled = bool
selfHostedIssuerUrl = "string"
}
privateLinkScopeResourceId = "string"
privateLinkState = "string"
provisioningState = "string"
securityProfile = {
workloadIdentity = {
enabled = bool
}
}
}
}
}
Property Values
Microsoft.Kubernetes/connectedClusters
| Name | Description | Value |
|---|---|---|
| identity | The identity of the connected cluster. | ConnectedClusterIdentity (required) |
| kind | The kind of connected cluster. | 'AWS' 'GCP' 'ProvisionedCluster' |
| location | The geo-location where the resource lives | string (required) |
| name | The resource name | string (required) |
| properties | Describes the connected cluster resource properties. | ConnectedClusterProperties (required) |
| tags | Resource tags | Dictionary of tag names and values. |
| type | The resource type | "Microsoft.Kubernetes/connectedClusters@2025-12-01-preview" |
AadProfile
| Name | Description | Value |
|---|---|---|
| adminGroupObjectIDs | The list of AAD group object IDs that will have admin role of the cluster. | string[] |
| enableAzureRBAC | Whether to enable Azure RBAC for Kubernetes authorization. | bool |
| tenantID | The AAD tenant ID to use for authentication. If not specified, will use the tenant of the deployment subscription. | string |
AgentError
| Name | Description | Value |
|---|
ArcAgentProfile
| Name | Description | Value |
|---|---|---|
| agentAutoUpgrade | Indicates whether the Arc agents on the be upgraded automatically to the latest version. Defaults to Enabled. | 'Disabled' 'Enabled' |
| agentErrors | List of arc agentry and system components errors on the cluster resource. | AgentError[] |
| desiredAgentVersion | Version of the Arc agents to be installed on the cluster resource | string |
| systemComponents | List of system extensions that are installed on the cluster resource. | SystemComponent[] |
ArcAgentryConfigurations
| Name | Description | Value |
|---|---|---|
| feature | Specifies the name of the feature for the configuration setting. | string |
| protectedSettings | The configuration settings for the feature that contain any sensitive or secret information. | ArcAgentryConfigurationsProtectedSettings |
| settings | The configuration settings for the feature that do not contain any sensitive or secret information. | ArcAgentryConfigurationsSettings |
ArcAgentryConfigurationsProtectedSettings
| Name | Description | Value |
|---|
ArcAgentryConfigurationsSettings
| Name | Description | Value |
|---|
ConnectedClusterIdentity
| Name | Description | Value |
|---|---|---|
| type | The type of identity used for the connected cluster. The type 'SystemAssigned, includes a system created identity. The type 'None' means no identity is assigned to the connected cluster. | 'None' 'SystemAssigned' (required) |
ConnectedClusterProperties
| Name | Description | Value |
|---|---|---|
| aadProfile | AAD profile for the connected cluster. | AadProfile |
| agentPublicKeyCertificate | Base64 encoded public certificate used by the agent to do the initial handshake to the backend services in Azure. | string (required) |
| arcAgentProfile | Arc agentry configuration for the provisioned cluster. | ArcAgentProfile |
| arcAgentryConfigurations | Configuration settings for customizing the behavior of the connected cluster. | ArcAgentryConfigurations[] |
| azureHybridBenefit | Indicates whether Azure Hybrid Benefit is opted in | 'False' 'NotApplicable' 'True' |
| distribution | The Kubernetes distribution running on this connected cluster. | string |
| distributionVersion | The Kubernetes distribution version on this connected cluster. | string |
| gateway | Details of the gateway used by the Arc router for connectivity. | Gateway |
| infrastructure | The infrastructure on which the Kubernetes cluster represented by this connected cluster is running on. | string |
| oidcIssuerProfile | Open ID Connect (OIDC) Issuer Profile for the connected cluster. | OidcIssuerProfile |
| privateLinkScopeResourceId | This is populated only if privateLinkState is enabled. The resource id of the private link scope this connected cluster is assigned to, if any. | string |
| privateLinkState | Property which describes the state of private link on a connected cluster resource. | 'Disabled' 'Enabled' |
| provisioningState | Provisioning state of the connected cluster resource. | 'Accepted' 'Canceled' 'Deleting' 'Failed' 'Provisioning' 'Succeeded' 'Updating' |
| securityProfile | Security profile for the connected cluster. | SecurityProfile |
Gateway
| Name | Description | Value |
|---|---|---|
| enabled | Indicates whether the gateway for arc router connectivity is enabled. | bool |
OidcIssuerProfile
| Name | Description | Value |
|---|---|---|
| enabled | Whether to enable oidc issuer for workload identity integration. | bool |
| selfHostedIssuerUrl | The issuer url for public cloud clusters - AKS, EKS, GKE - used for the workload identity feature. | string |
SecurityProfile
| Name | Description | Value |
|---|---|---|
| workloadIdentity | The workload identity feature webhook. | SecurityProfileWorkloadIdentity |
SecurityProfileWorkloadIdentity
| Name | Description | Value |
|---|---|---|
| enabled | Whether to enable or disable the workload identity Webhook | bool |
SystemComponent
| Name | Description | Value |
|---|---|---|
| majorVersion | Major Version of the system extension that is currently installed on the cluster resource. | int |
| type | Type of the system extension | string |
| userSpecifiedVersion | Version of the system extension to be installed on the cluster resource. | string |
TrackedResourceTags
| Name | Description | Value |
|---|
Usage Examples
Terraform Samples
A basic example of deploying Arc Kubernetes Cluster.
terraform {
required_providers {
azapi = {
source = "Azure/azapi"
}
}
}
provider "azapi" {
skip_provider_registration = false
}
variable "resource_name" {
type = string
default = "acctest0001"
}
variable "location" {
type = string
default = "westus"
}
resource "azapi_resource" "resourceGroup" {
type = "Microsoft.Resources/resourceGroups@2020-06-01"
name = var.resource_name
location = var.location
}
resource "azapi_resource" "connectedCluster" {
type = "Microsoft.Kubernetes/connectedClusters@2024-01-01"
parent_id = azapi_resource.resourceGroup.id
name = "${var.resource_name}-cc"
location = var.location
identity {
type = "SystemAssigned"
identity_ids = []
}
body = {
kind = "ProvisionedCluster"
properties = {
agentPublicKeyCertificate = ""
arcAgentProfile = {
agentAutoUpgrade = "Enabled"
}
}
}
}