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

     1  # Azure Service Operator
     2  
     3  ## Overview
     4  
     5  CAPZ interfaces with Azure to create and manage some types of resources using [Azure Service Operator
     6  (ASO)](https://azure.github.io/azure-service-operator/).
     7  
     8  More context around the decision for CAPZ to pivot towards using ASO can be found in the
     9  [proposal](https://github.com/kubernetes-sigs/cluster-api-provider-azure/blob/main/docs/proposals/20230123-azure-service-operator.md).
    10  
    11  [Visit this page](../managed/asomanagedcluster.md) to learn more about the AzureASOManaged cluster API which provisions an AKS cluster.
    12  
    13  ## Primary changes
    14  
    15  For most users, the introduction of ASO is expected to be fully transparent and backwards compatible. Changes
    16  that may affect specific use cases are described below.
    17  
    18  ### Installation
    19  
    20  Beginning with CAPZ v1.11.0, ASO's control plane will be installed automatically by `clusterctl` in the
    21  `capz-system` namespace alongside CAPZ's control plane components. When ASO is already installed on a cluster,
    22  installing ASO again with CAPZ is expected to fail and `clusterctl` cannot install CAPZ without ASO. The
    23  suggested workaround for users facing this issue is to uninstall the existing ASO control plane (but **keep**
    24  the ASO CRDs) and then to install CAPZ.
    25  
    26  ### Bring-your-own (BYO) resource
    27  
    28  CAPZ had already allowed users to pre-create some resources like resource groups and virtual networks and
    29  reference those resources in CAPZ resources. CAPZ will then use those existing resources without creating new
    30  ones and assume the user is responsible for managing them, so will not actively reconcile changes to or delete
    31  those resources.
    32  
    33  This use case is still supported with ASO installed. The main difference is that an ASO resource will be
    34  created for CAPZ's own bookkeeping, but configured not to be actively reconciled by ASO. When the Cluster API
    35  Cluster owning the resource is deleted, the ASO resource will also be deleted from the management cluster but
    36  the resource will not be deleted in Azure.
    37  
    38  Additionally, BYO resources may include ASO resources managed by the user. CAPZ will not modify or delete such
    39  resources. Note that `clusterctl move` will not move user-managed ASO resources.
    40  
    41  ## Configuration with Environment Variables
    42  
    43  These environment variables are passed through to the `aso-controller-settings` Secret to configure ASO when
    44  CAPZ is installed and are consumed by `clusterctl init`. They may also be modified directly in the Secret
    45  after installing ASO with CAPZ:
    46  
    47  - `AZURE_AUTHORITY_HOST`
    48  - `AZURE_RESOURCE_MANAGER_AUDIENCE`
    49  - `AZURE_RESOURCE_MANAGER_ENDPOINT`
    50  - `AZURE_SYNC_PERIOD`
    51  
    52  More details on each can be found in [ASO's documentation](https://azure.github.io/azure-service-operator/guide/aso-controller-settings-options/).
    53  
    54  ## Using ASO for non-CAPZ resources
    55  
    56  CAPZ's installation of ASO can be used directly to manage Azure resources outside the domain of
    57  Cluster API.
    58  
    59  ### Installing more CRDs
    60  
    61  #### For a fresh installation
    62  Before performing a `clusterctl init`, users can specify additional ASO CRDs to be installed in the management cluster by exporting `ADDITIONAL_ASO_CRDS` variable.
    63  For example, to install all the CRDs of `cache.azure.com` and `MongodbDatabase.documentdb.azure.com`:
    64  - `export ADDITIONAL_ASO_CRDS="cache.azure.com/*;documentdb.azure.com/MongodbDatabase"`
    65  - continue with the installation of CAPZ as specified here [Cluster API Quick Start](https://cluster-api.sigs.k8s.io/user/quick-start.html).
    66  
    67  #### For an existing CAPZ installation being upgraded to v1.14.0(or beyond)
    68  CAPZ's installation of ASO configures only the ASO CRDs that are required by CAPZ. To make more resource types available, export `ADDITIONAL_ASO_CRDS` and then upgrade CAPZ.
    69  For example, to install the all CRDs of `cache.azure.com` and `MongodbDatabase.documentdb.azure.com`, follow these steps:
    70  - `export ADDITIONAL_ASO_CRDS="cache.azure.com/*;documentdb.azure.com/MongodbDatabase"`
    71  - continue with the upgrade of CAPZ as specified [here](https://cluster-api.sigs.k8s.io/tasks/upgrading-cluster-api-versions.html?highlight=upgrade#when-to-upgrade]
    72  
    73  You will see that the `--crd-pattern` in Azure Service Operator's Deployment (in the `capz-system` namespace) looks like below:
    74     ```
    75     .
    76     - --crd-names=cache.azure.com/*;documentdb.azure.com/MongodbDatabase
    77     .
    78     ```
    79  
    80  More details about how ASO manages CRDs can be found [here](https://azure.github.io/azure-service-operator/guide/crd-management/).
    81  
    82  **Note:** To install the resource for the newly installed CRDs, make sure that the ASO operator has the authentication to install the resources. Refer [authentication in ASO](https://azure.github.io/azure-service-operator/guide/authentication/) for more details.
    83  An example configuration file and demo for `Azure Cache for Redis` can be found [here](https://github.com/Azure-Samples/azure-service-operator-samples/tree/master/azure-votes-redis).