Add aosm extension

.flake8

@@ -2,13 +2,20 @@
 max-line-length = 120
 max-complexity = 10
 ignore =
-    E501,  # line too long, it is covered by pylint
-    E722,  # bare except, bad practice, to be removed in the future
-    F401,  # imported but unused, too many violations, to be removed in the future
-    F811,  # redefinition of unused, to be removed in the future
-    C901   # code flow is too complex, too many violations, to be removed in the future
-    W503   # line break before binary operator effect on readability is subjective
-    W504   # line break after binary operator effect on readability is subjective
+    # line too long, it is covered by pylint
+    E501,
+    # bare except, bad practice, to be removed in the future
+    E722,
+    # imported but unused, too many violations, to be removed in the future
+    F401,
+    # redefinition of unused, to be removed in the future
+    F811,
+    # code flow is too complex, too many violations, to be removed in the future
+    C901,
+    # line break before binary operator effect on readability is subjective   
+    W503,
+    # line break after binary operator effect on readability is subjective
+    W504
 exclude =
     */vendored_sdks
     docs

.github/CODEOWNERS

@@ -292,6 +292,8 @@
 
 /src/alb/ @jaishals
 
+/src/aosm/ @sunnycarter
+
 /src/managedccfs/ @msftsettiy
 
 /src/acrquery/ @CarolineNB

src/aosm/HISTORY.rst

@@ -0,0 +1,10 @@
+.. :changelog:
+
+Release History
+===============
+
+1.0.0b1
+++++++++
+* Initial release - beta quality
+    * `az aosm nfd|nsd generate-config` to generate an example config file to fill in for an NFD or NSD
+    * `az aosm nfd|nsd build|publish|delete` to prepare files for, publish or delete an NFD or NSD

src/aosm/README.md

@@ -0,0 +1,203 @@
+# Microsoft Azure CLI 'aosm' Extension
+
+This package is for the 'aosm' extension to support Azure Operator Service Manager 
+functions.
+i.e. `az aosm`
+
+## Background
+
+The `az aosm` extension is intended to provide support for working with AOSM
+resources and definitions. Currently it only implements commands which aid the
+process of publishing Network Function Definitions and Network Service Designs to
+use with Azure Operator Service Manager or Network Function Manager.
+
+## Installation
+
+`az extension add --name aosm`
+
+For CNFs you will also need helm, and possibly docker installed. See [CNFs](#cnfs) below for details.
+
+# nfd and nsd commands
+
+These commands help with the publishing of Network Function Definition and Network
+Service Design resources.
+
+## Overview of function
+A generic workflow of using the tool would be:
+- Find the pre-requisite items you require for your use-case
+- Run a `generate-config` command to output an example JSON config file for subsequent commands
+- Fill in the config file
+- Run a `build` command to output one or more bicep templates for your Network Function Definition or Network Service Design
+- Review the output of the build command, edit the output as necessary for your requirements
+- Run a `publish` command to:
+    * Create all pre-requisite resources such as Resource Group, Publisher, Artifact Stores, Groups
+    * Deploy those bicep templates
+    * Upload artifacts to the artifact stores
+
+### Pre-requisites
+
+#### VNFs
+
+For VNFs, you will need a single ARM template which would create the Azure resources
+for your VNF, for example a Virtual Machine, disks and NICs. You'll also need a VHD
+image that would be used for the VNF Virtual Machine.
+
+#### CNFs
+
+For CNFs you must have these packages installed on the machine you are running the CLI from:
+-  `helm` package installed . Instructions on how to do this can be found [here](https://helm.sh/docs/intro/install/).
+-  `docker` installed only in some circumstances, those being if the source image is in your local docker repository, or you do not have subscription-wide permissions required to push charts and images. See the remainder of this section for further details. Docker provides packages that easily configure docker on [Windows](https://docs.docker.com/docker-for-windows/), or [Linux](https://docs.docker.com/engine/install/#supported-platforms) systems.
+
+For CNFs, you must provide:
+* helm packages with an associated schema. These files must be on your disk and will be referenced in the `input.json` config file. 
+* images for your CNF.  For these you have the following options:
+  - a reference to an existing Azure Container Registry which contains the images for your CNF. Currently, only one ACR and namespace is supported per CNF. The images to be copied from this ACR are populated automatically based on the helm package schema. You must have Reader/AcrPull permissions on this ACR. To use this option, fill in `source_registry` and optionally `source_registry_namespace` in the input.json file.
+  - or, the image name of the source docker image from local machine. This is for a limited use case where the CNF only requires a single docker image which exists in the local docker repository. To use this option, fill in `source_local_docker_image` in the input.json file. This requires docker to be installed.
+* optionally, you can provide a file (on disk) path_to_mappings which is a copy of values.yaml with your chosen values replaced by deployment parameters, thus exposing them as parameters to the CNF. You can get this file auto-generated by leaving the value as a blank string, either having every value as a deployment parameter, or using `--interactive` to interactively choose.
+When filling in the input.json file, you must list helm packages in the order they are to be deployed. For example, if A must be deployed before B, your input.json should look something like this:
+
+        "helm_packages": [
+            {
+                "name": "A",
+                "path_to_chart": "Path to package A",
+                "path_to_mappings": "Path to package A mappings",
+                "depends_on": [
+                    "Names of the Helm packages this package depends on"
+                ]
+            },
+            {
+                "name": "B",
+                "path_to_chart": "Path to package B",
+                "path_to_mappings": "Path to package B mappings",
+                "depends_on": [
+                    "Names of the Helm packages this package depends on"
+                ]
+            },
+
+##### Permissions for publishing CNFs
+If sourcing the CNF images from an existing ACR, you need to have `Reader`/`AcrPull` permissions
+from this ACR, and ideally, `Contributor` role + `AcrPush` role (or a custom role that allows the `importImage` action and `AcrPush`) over the whole subscription in order to be able to import to the new Artifact store. If you have these, you 
+do not need docker to be installed locally, and the image copy is very quick.
+
+If you do not have the subscription-wide permissions then you can run the `az aosm nfd publish` command using the `--no-subscription-permissions` flag to pull the image to your local machine and then push it to the Artifact Store using manifest credentials scoped only to the store. This requires docker to be installed locally.
+
+#### NSDs
+For NSDs, you will need to have a Resource Group with a deployed Publisher, Artifact Store, Network Function Definition and Network Function Definition Version. You can use the `az aosm nfd` commands to create all of these resources.
+
+
+### Command examples
+
+#### Before you start
+`az login` to login to the Azure CLI.
+`az account set --subscription <subscription>` to choose the subscription you will work on.
+
+#### NFDs
+
+Get help on command arguments
+
+`az aosm -h`
+`az aosm nfd -h`
+`az aosm nfd build -h`
+etc...
+
+All these commands take a `--definition-type` argument of `vnf` or `cnf`
+
+Create an example config file for building a definition
+
+`az aosm nfd generate-config`
+
+This will output a file called `input.json` which must be filled in. 
+Once the config file has been filled in the following commands can be run.
+
+Build an nfd definition locally
+
+`az aosm nfd build --config-file input.json`
+
+More options on building an nfd definition locally:
+
+Choose which of the VNF ARM template parameters you want to expose as NFD deploymentParameters, with the option of interactively choosing each one.
+
+`az aosm nfd build --config-file input.json --definition_type vnf --order_params`
+`az aosm nfd build --config-file input.json --definition_type vnf --order_params --interactive`
+
+Choose which of the CNF Helm values parameters you want to expose as NFD deploymentParameters.
+
+`az aosm nfd build --config-file input.json --definition_type cnf [--interactive]`
+
+Publish a pre-built definition
+
+`az aosm nfd publish --config-file input.json`
+
+Delete a published definition
+
+`az aosm nfd delete --config-file input.json`
+
+Delete a published definition and the publisher, artifact stores and NFD group
+
+`az aosm nfd delete --config-file input.json --clean`
+
+#### NSDs
+
+Get help on command arguments
+
+`az aosm -h`
+`az aosm nsd -h`
+`az aosm nsd build -h`
+etc...
+
+Create an example config file for building a definition
+
+`az aosm nsd generate-config`
+
+This will output a file called `input.json` which must be filled in. 
+Once the config file has been filled in the following commands can be run.
+
+Build an nsd locally
+
+`az aosm nsd build --config-file input.json`
+
+Publish a pre-built design
+
+`az aosm nsd publish --config-file input.json`
+
+Delete a published design
+
+`az aosm nsd delete --config-file input.json`
+
+Delete a published design and the publisher, artifact stores and NSD group
+
+`az aosm nsd delete --config-file input.json --clean`
+
+## Bug Reporting
+
+It would be much appreciated if you could report these so that we're aware of them!
+
+Please see [Logging](#logging) for how to view and collect logs. 
+
+Please describe what you are doing and if possible provide the input and output files.
+
+The (Microsoft internal) process for bug reporting during development is here:
+https://eng.ms/docs/strategic-missions-and-technologies/strategic-missions-and-technologies-organization/azure-for-operators/aiops/aiops-orchestration/aosm-product-docs/processes/bug_process
+
+CLI issues should be tagged and triaged as UX bugs.
+
+## Logging
+
+The CLI uses the standard Azure CLI logging mechanism. To enable logging to the console, you can use the following flags depending on the desired level of logging:
+- `--verbose` - This flag changes the logging level to Info and above.
+- `--debug` - This flag changes the logging level to Debug and above.
+- `--only-show-errors` - This flag changes the logging level to Error only, suppressing Warning.
+
+It is also possible to enable logging to file by running the following command:
+```
+az config set logging.enable_log_file=true
+```
+This will create a log file in the `~/.azure/logs` directory. 
+
+**Note:** The above command will enable logging for all Azure CLI commands until the logging is disabled again by the user. Not disabling file logging could slow down the performance of the CLI. To disable file logging, run the following command:
+```
+az config set logging.enable_log_file=false
+```
+
+## Development
+Information about setting up and maintaining a development environment for this extension can be found [here](./development.md).

src/aosm/azext_aosm/__init__.py

@@ -0,0 +1,30 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from azure.cli.core import AzCommandsLoader
+
+from azext_aosm._help import helps  # pylint: disable=unused-import
+
+
+class AosmCommandsLoader(AzCommandsLoader):
+    def __init__(self, cli_ctx=None):
+        from azure.cli.core.commands import CliCommandType
+
+        aosm_custom = CliCommandType(operations_tmpl="azext_aosm.custom#{}")
+        super().__init__(cli_ctx=cli_ctx, custom_command_type=aosm_custom)
+
+    def load_command_table(self, args):
+        from azext_aosm.commands import load_command_table
+
+        load_command_table(self, args)
+        return self.command_table
+
+    def load_arguments(self, command):
+        from azext_aosm._params import load_arguments
+
+        load_arguments(self, command)
+
+
+COMMAND_LOADER_CLS = AosmCommandsLoader

src/aosm/azext_aosm/_client_factory.py

@@ -0,0 +1,42 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+from azure.cli.core.commands.client_factory import get_mgmt_service_client
+from azure.cli.core.profiles import ResourceType
+from azure.mgmt.containerregistry import ContainerRegistryManagementClient
+
+from .vendored_sdks import HybridNetworkManagementClient
+
+
+def cf_aosm(cli_ctx, *_) -> HybridNetworkManagementClient:
+    # By default, get_mgmt_service_client() sets a parameter called 'base_url' when creating
+    # the client. For us, doing so results in a key error. Setting base_url_bound=False prevents
+    # that from happening
+    return get_mgmt_service_client(cli_ctx, HybridNetworkManagementClient, base_url_bound=False)
+
+
+def cf_resources(cli_ctx, subscription_id=None):
+    return get_mgmt_service_client(
+        cli_ctx, ResourceType.MGMT_RESOURCE_RESOURCES, subscription_id=subscription_id
+    )
+
+
+def cf_features(cli_ctx, subscription_id=None):
+    """Return the client for checking feature enablement."""
+    return get_mgmt_service_client(
+        cli_ctx, ResourceType.MGMT_RESOURCE_FEATURES, subscription_id=subscription_id
+    )
+
+
+def cf_acr_registries(cli_ctx, *_) -> ContainerRegistryManagementClient:
+    """
+    Returns the client for managing container registries.
+
+    :param cli_ctx: CLI context
+    :return: ContainerRegistryManagementClient object
+    """
+    return get_mgmt_service_client(
+        cli_ctx, ResourceType.MGMT_CONTAINERREGISTRY
+    ).registries