asoctl

Azure Service Operator Controller
$ asoctl
asoctl provides a cmdline interface for working with Azure Service Operator

Usage:
  asoctl [command]

Available Commands:
  clean       Clean Custom Resource Definitions (CRDs) prior to upgrade
  completion  Generate the autocompletion script for the specified shell
  export      Exports an ASO YAML file from a template
  help        Help about any command
  import      Imports ARM resources to YAML files containing ASO custom resource definitions
  version     Display version information

Flags:
      --quiet     Silence most logging
      --verbose   Enable verbose logging
  -h, --help      help for asoctl

Use "asoctl [command] --help" for more information about a command.

Installation

Download for AMD64:

$ curl -L https://github.com/Azure/azure-service-operator/releases/latest/download/asoctl-linux-amd64.gz -o asoctl.gz
$ gunzip asoctl.gz

Download for ARM64:

$ curl -L https://github.com/Azure/azure-service-operator/releases/latest/download/asoctl-linux-arm64.gz -o asoctl.gz
$ gunzip asoctl.gz

Install:

$ sudo install -o root -g root -m 0755 asoctl /usr/local/bin/asoctl`

Download for AMD64:

$ curl -L https://github.com/Azure/azure-service-operator/releases/latest/download/asoctl-darwin-amd64.gz -o asoctl.gz
$ gunzip asoctl.gz

Download for ARM64:

$ curl -L https://github.com/Azure/azure-service-operator/releases/latest/download/asoctl-darwin-arm64.gz -o asoctl.gz
$ gunzip asoctl.gz

Make the binary executable:

$ chmod +x ./asoctl

Move the binary to your PATH:

$ sudo mv ./asoctl /usr/local/bin/asoctl

Using a PowerShell command prompt, download the latest release to your current directory:

$ curl.exe -L https://github.com/Azure/azure-service-operator/releases/latest/download/asoctl-windows-amd64.zip -o asoctl.zip
$ Expand-Archive asoctl.zip . -Force

Append that directory to your PATH if desired.

Export template

The export template commands helps render a YAML file from the raw ASO published with each release.

Template creates a YAML file from the specified ASO yaml template

Usage:
  asoctl export template [--source <string> |--version <string>] [--crd-pattern <string>|--raw] [flags]

Examples:
asoctl export template --version v2.6.0 --crd-pattern "resources.azure.com/*" --crd-pattern "containerservice.azure.com/*"

With combined crd-pattern:
asoctl export template --version v2.6.0 --crd-pattern "resources.azure.com/*;containerservice.azure.com/*;keyvault.azure.com/*;managedidentity.azure.com/*;eventhub.azure.com/*"

With remote source:
asoctl export template --source https://github.com/Azure/azure-service-operator/releases/download/v2.6.0/azureserviceoperator_v2.6.0.yaml --crd-pattern "resources.azure.com/*" --crd-pattern "containerservice.azure.com/*"

With local source:
asoctl export template --source ~/Downloads/azureserviceoperator_v2.6.0.yaml --crd-pattern "resources.azure.com/*" --crd-pattern "containerservice.azure.com/*"

Raw:
asoctl export template --version v2.6.0  --raw

With kubectl:
asoctl export template --version v2.6.0 --crd-pattern "resources.azure.com/*;containerservice.azure.com/*;keyvault.azure.com/*;managedidentity.azure.com/*;eventhub.azure.com/*" | kubectl apply -f -

Flags:
  -p, --crd-pattern strings   What new CRDs to install. Existing ASO CRDs in the cluster will always be upgraded even if crdPattern is empty. See https://azure.github.io/azure-service-operator/guide/crd-management/ for more details.
  -h, --help                  help for template
      --raw                   Export the YAML without any variable replacements
  -s, --source string         File or URL path to the ASO YAML template. Use this if you've customized the base ASO YAML locally or are using a base YAML other than the one hosted at https://github.com/Azure/azure-service-operator/tags
  -v, --version string        Release version to use.

Global Flags:
      --quiet     Silence most logging
      --verbose   Enable verbose logging

–crd-pattern

From v2.10, asoctl does proactive checking of the --crd-pattern parameter to see how many CRDs are selected.

A warning is displayed if a pattern does not match any CRDs. This is nonfatal - the export of the template will proceed - as it’s possible the pattern will match a CRD included in a newer version of ASO.

Clean CRDs

This command can be used to prepare ASOv2 v1alpha1api(deprecated in v2.0.0) CustomResources and CustomResourceDefinitions for ASO v2.0.0 release. It ensures that any ASOv2 v1alpha1api deprecated version resources that may have been stored in etcd get migrated to v1beta version before upgrading ASO to v2.0.0.

$ asoctl clean crds --help
Clean deprecated CRD versions from cluster

Usage:
  asoctl clean crds [flags]

Flags:
      --dry-run   
  -h, --help      help for clean

Global Flags:
      --verbose   Enable verbose logging

--dry-run flag outputs about CRDs and CRs to be updated and does not modify any CRD and CRs.

Steps for migration using asoctl clean crds:

Prerequisite: Ensure the current ASO v2 version in your cluster is beta.5.

Run the migration tool:

$ asoctl clean crds

Once that’s successfully run, you can upgrade ASO to v2.0.0

Using asoctl clean crds is an important step if v1alpha1api resources have ever been present in the cluster. If not used correctly, operator pod will produce log error messages:

"msg"="failed to apply CRDs" "error"="failed to apply CRD storageaccountsqueueservicesqueues.storage.azure.com: CustomResourceDefinition.apiextensions.k8s.io \"storageaccountsqueueservicesqueues.storage.azure.com\" is invalid: status.storedVersions[0]: Invalid value: \"v1alpha1api20210401storage\": must appear in spec.versions" 

Example Output

$ asoctl clean crds
...
INF Starting cleanup crd-name=resourcegroups.resources.azure.com
INF Migration finished resource-count=1
INF Updated CRD status storedVersions crd-name=resourcegroups.resources.azure.com storedVersions=["v1beta20200601"]
INF Starting cleanup crd-name=roleassignments.authorization.azure.com
INF Migration finished resource-count=0
INF Updated CRD status storedVersions crd-name=roleassignments.authorization.azure.com storedVersions=["v1beta20200801previewstorage"]
INF Nothing to update crd-name=routetables.network.azure.com
INF Nothing to update crd-name=routetablesroutes.network.azure.com
INF Update finished crd-count=67

Import Azure Resource

When you have an existing Azure resource that needs to be managed by ASO, you can use the import command to generate a YAML file that can be used to create a new ASO resource. This is useful when:

  • You want to migrate an existing Azure resource from ASO v1 to ASO v2.
  • You have an existing Azure resource and want ASO to manage it.
  • You have a hand-configured Azure resource and you want to replicate it for development, staging, or production use.
$ asoctl import azure-resource --help
Imports ARM resources as Custom Resources.

This command requires you to authenticate with Azure using an identity which has access to the resource(s) you would
like to import. The following authentication modes are supported:

Az-login token: az login and then use asoctl.
Managed Identity: Set the AZURE_CLIENT_ID environment variable and run on a machine with access to the managed identity.
Service Principal: Set the AZURE_SUBSCRIPTION_ID, AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET environment variables,

The following environment variables can be used to configure which cloud to use with asoctl:

AZURE_RESOURCE_MANAGER_ENDPOINT: The Azure Resource Manager endpoint. 
If not specified, the default is the Public cloud resource manager endpoint.
See https://docs.microsoft.com/cli/azure/manage-clouds-azure-cli#list-available-clouds for details
about how to find available resource manager endpoints for your cloud. Note that the resource manager
endpoint is referred to as "resourceManager" in the Azure CLI.

AZURE_RESOURCE_MANAGER_AUDIENCE: The Azure Resource Manager AAD audience.
If not specified, the default is the Public cloud resource manager audience https://management.core.windows.net/.
See https://docs.microsoft.com/cli/azure/manage-clouds-azure-cli#list-available-clouds for details
about how to find available resource manager audiences for your cloud. Note that the resource manager
audience is referred to as "activeDirectoryResourceId" in the Azure CLI.

AZURE_AUTHORITY_HOST: The URL of the AAD authority.
If not specified, the default
is the AAD URL for the public cloud: https://login.microsoftonline.com/. See
https://docs.microsoft.com/azure/active-directory/develop/authentication-national-cloud

Usage:
  asoctl import azure-resource <ARM/ID/of/resource> [flags]

Flags:
  -a, --annotation strings     Add the specified annotations to the imported resources. Multiple comma-separated annotations can be specified (--annotation example.com/myannotation=foo,example.com/myannotation2=bar) or the --annotation (-a) argument can be used multiple times (-a example.com/myannotation=foo -a example.com/myannotation2=bar)
  -h, --help                   help for azure-resource
  -l, --label strings          Add the specified labels to the imported resources. Multiple comma-separated labels can be specified (--label example.com/mylabel=foo,example.com/mylabel2=bar) or the --label (-l) argument can be used multiple times (-l example.com/mylabel=foo -l example.com/mylabel2=bar)
  -n, --namespace string       Write the imported resources to the specified namespace
  -o, --output string          Write ARM resource CRDs to a single file
  -f, --output-folder string   Write ARM resource CRDs to individual files in a folder
  -w, --workers int            Specify the number of parallel workers to use when importing resources (default 4)
  
Global Flags:
      --quiet     Silence most logging
      --verbose   Enable verbose logging

The asoctl import azure-resource command will accept any number of ARM resource Ids.

Each ARM resource will be scanned for supported child or extension resources, and all the results combined together into a single YAML file. If asoctl encounters a resource type that it doesn’t support, details will be logged.

Example: Importing a PostgreSQL Server

To import the configuration of an existing PostgreSQL server, we’d run the following command:

$ asoctl import azure-resource /subscriptions/[redacted]/resourceGroups/aso-rg/providers/Microsoft.DBforPostgreSQL/flexibleServers/aso-pg --output aso.yaml
  • The parameter is the full ARM ID to the server; one way to find this is via the Azure Portal.
  • Multiple ARM IDs are permitted.
  • Here, the subscription ID has been redacted; in practice, you’d see your own subscription list

While asoctl import azure-resource runs, you’ll see progress shown dynamically as child and extension resources are found and imported:

Screenshot showing asoctl import azure-resource running

Once finished, you’ll see a list of all the imported resources, and the file they were written to:

14:43:34 INF Imported kind=FlexibleServer.dbforpostgresql.azure.com name=aso-pg
14:43:37 INF Imported kind=FlexibleServersFirewallRule.dbforpostgresql.azure.com name=AllowAllAzureServicesAndResourcesWithinAzureIps_2023-3-30_15-26-24
14:44:06 INF Imported kind=FlexibleServersConfiguration.dbforpostgresql.azure.com name=shared_preload_libraries
14:44:15 INF Imported kind=FlexibleServersConfiguration.dbforpostgresql.azure.com name=vacuum_cost_page_miss
14:44:18 INF Imported kind=FlexibleServersDatabase.dbforpostgresql.azure.com name=aso-demo
14:44:25 INF Writing to file path=aso.yaml
Import Azure Resources  [======================================================================================================================================================================] 100 %

The import found a total of five resources:

  • 1 x PostgreSQL Flexible Server (the one originally identified by ARM Id)
  • 1 x Firewall Rule
  • 2 x Configuration settings
  • 1 x Database

Not all resources found need to imported; to see more information about those resources, and why they were omitted, use the --verbose command line flag.

One situation where this happens is with the configuration of a PostgreSQL server, where most of the values are system defaults that don’t need to be explicitly specified.

14:47:56 DBG Skipped because="system-defaults don't need to be imported" kind=FlexibleServersConfiguration.dbforpostgresql.azure.com name=synchronous_commit
14:47:56 DBG Skipped because="system-defaults don't need to be imported" kind=FlexibleServersConfiguration.dbforpostgresql.azure.com name=tcp_keepalives_idle
14:47:57 DBG Skipped because="system-defaults don't need to be imported" kind=FlexibleServersConfiguration.dbforpostgresql.azure.com name=tcp_keepalives_count
14:47:57 DBG Skipped because="system-defaults don't need to be imported" kind=FlexibleServersConfiguration.dbforpostgresql.azure.com name=tcp_keepalives_interval
14:47:57 DBG Skipped because="system-defaults don't need to be imported" kind=FlexibleServersConfiguration.dbforpostgresql.azure.com name=temp_buffers
14:47:57 DBG Skipped because="system-defaults don't need to be imported" kind=FlexibleServersConfiguration.dbforpostgresql.azure.com name=temp_tablespaces

Another is when role assignments have been inherited by the resource:

14:48:03 DBG Skipped because="role assignment is inherited" kind=RoleAssignment.authorization.azure.com name=fe65ff58-[redacted]
14:48:03 DBG Skipped because="role assignment is inherited" kind=RoleAssignment.authorization.azure.com name=61681810-[redacted]
14:48:03 DBG Skipped because="role assignment is inherited" kind=RoleAssignment.authorization.azure.com name=06c013cb-[redacted]
14:48:03 DBG Skipped because="role assignment is inherited" kind=RoleAssignment.authorization.azure.com name=37047941-[redacted]
14:48:03 DBG Skipped because="role assignment is inherited" kind=RoleAssignment.authorization.azure.com name=b0b9667d-[redacted]
14:48:03 DBG Skipped because="role assignment is inherited" kind=RoleAssignment.authorization.azure.com name=88a998ec-[redacted]