sigs.k8s.io/cluster-api-provider-azure@v1.17.0/docs/book/src/managed/adopting-clusters.md (about)

     1  ## Adopting Existing AKS Clusters
     2  
     3  ### Option 1: Using the new AzureASOManaged API
     4  
     5  <!-- markdown-link-check-disable-next-line -->
     6  The [AzureASOManagedControlPlane and related APIs](./asomanagedcluster.md) support
     7  adoption as a first-class use case. Going forward, this method is likely to be easier, more reliable, include
     8  more features, and better supported for adopting AKS clusters than Option 2 below.
     9  
    10  To adopt an AKS cluster into a full Cluster API Cluster, create an ASO ManagedCluster and associated
    11  ManagedClustersAgentPool resources annotated with `sigs.k8s.io/cluster-api-provider-azure-adopt=true`. The
    12  annotation may also be added to existing ASO resources to trigger adoption. CAPZ will automatically scaffold
    13  the Cluster API resources like the Cluster, AzureASOManagedCluster, AzureASOManagedControlPlane, MachinePools,
    14  and AzureASOManagedMachinePools. The [`asoctl import
    15  azure-resource`](https://azure.github.io/azure-service-operator/tools/asoctl/#import-azure-resource) command
    16  can help generate the required YAML.
    17  
    18  Caveats:
    19  - The `asoctl import azure-resource` command has at least [one known
    20    bug](https://github.com/Azure/azure-service-operator/issues/3805) requiring the YAML it generates to be
    21    edited before it can be applied to a cluster.
    22  - CAPZ currently only records the ASO resources in the CAPZ resources' `spec.resources` that it needs to
    23    function, which include the ManagedCluster, its ResourceGroup, and associated ManagedClustersAgentPools.
    24    Other resources owned by the ManagedCluster like Kubernetes extensions or Fleet memberships are not
    25    currently imported to the CAPZ specs.
    26  - Configuring the automatically generated Cluster API resources is not currently possible. If you need to
    27    change something like the `metadata.name` of a resource from what CAPZ generates, create the Cluster API
    28    resources manually referencing the pre-existing resources.
    29  - Adopting existing clusters created with the GA AzureManagedControlPlane API to the experimental API with
    30    this method is theoretically possible, but untested. Care should be taken to prevent CAPZ from reconciling
    31    two different representations of the same underlying Azure resources.
    32  
    33  ### Option 2: Using the current AzureManagedControlPlane API
    34  
    35  <aside class="note">
    36  
    37  <h1> Warning </h1>
    38  
    39  Note: This is a newly-supported feature in CAPZ that is less battle-tested than most other features. Potential
    40  bugs or misuse can result in misconfigured or deleted Azure resources. Use with caution.
    41  
    42  </aside>
    43  
    44  CAPZ can adopt some AKS clusters created by other means under its management. This works by crafting CAPI and
    45  CAPZ manifests which describe the existing cluster and creating those resources on the CAPI management
    46  cluster. This approach is limited to clusters which can be described by the CAPZ API, which includes the
    47  following constraints:
    48  
    49  - the cluster operates within a single Virtual Network and Subnet
    50  - the cluster's Virtual Network exists outside of the AKS-managed `MC_*` resource group
    51  - the cluster's Virtual Network and Subnet are not shared with any other resources outside the context of this cluster
    52  
    53  To ensure CAPZ does not introduce any unwarranted changes while adopting an existing cluster, carefully review
    54  the [entire AzureManagedControlPlane spec](../reference/v1beta1-api#infrastructure.cluster.x-k8s.io/v1beta1.AzureManagedControlPlaneSpec)
    55  and specify _every_ field in the CAPZ resource. CAPZ's webhooks apply defaults to many fields which may not
    56  match the existing cluster.
    57  
    58  Specific AKS features not represented in the CAPZ API, like those from a newer AKS API version than CAPZ uses,
    59  do not need to be specified in the CAPZ resources to remain configured the way they are. CAPZ will still not
    60  be able to manage that configuration, but it will not modify any settings beyond those for which it has
    61  knowledge.
    62  
    63  By default, CAPZ will not make any changes to or delete any pre-existing Resource Group, Virtual Network, or
    64  Subnet resources. To opt-in to CAPZ management for those clusters, tag those resources with the following
    65  before creating the CAPZ resources: `sigs.k8s.io_cluster-api-provider-azure_cluster_<CAPI Cluster name>: owned`.
    66  Managed Cluster and Agent Pool resources do not need this tag in order to be adopted.
    67  
    68  After applying the CAPI and CAPZ resources for the cluster, other means of managing the cluster should be
    69  disabled to avoid ongoing conflicts with CAPZ's reconciliation process.
    70  
    71  #### Pitfalls
    72  
    73  The following describes some specific pieces of configuration that deserve particularly careful attention,
    74  adapted from https://gist.github.com/mtougeron/1e5d7a30df396cd4728a26b2555e0ef0#file-capz-md.
    75  
    76  - Make sure `AzureManagedControlPlane.metadata.name` matches the AKS cluster name
    77  - Set the `AzureManagedControlPlane.spec.virtualNetwork` fields to match your existing VNET
    78  - Make sure the `AzureManagedControlPlane.spec.sshPublicKey` matches what was set on the AKS cluster. (including any potential newlines included in the base64 encoding)
    79    - NOTE: This is a required field in CAPZ, if you don't know what public key was used, you can _change_ or _set_ it via the Azure CLI however before attempting to import the cluster.
    80  - Make sure the `Cluster.spec.clusterNetwork` settings match properly to what you are using in AKS
    81  - Make sure the `AzureManagedControlPlane.spec.dnsServiceIP` matches what is set in AKS
    82  - Set the tag `sigs.k8s.io_cluster-api-provider-azure_cluster_<clusterName>` = `owned` on the AKS cluster
    83  - Set the tag `sigs.k8s.io_cluster-api-provider-azure_role` = `common` on the AKS cluster
    84  
    85  NOTE: Several fields, like `networkPlugin`, if not set on the AKS cluster at creation time, will mean that CAPZ will not be able to set that field. AKS doesn't allow such fields to be changed if not set at creation. However, if it was set at creation time, CAPZ will be able to successfully change/manage the field.