Create install-network-function-operator.md

new article

Author: msftadam

articles/operator-service-manager/install-network-function-operator.md

@@ -0,0 +1,199 @@
+---
+title: Manage network function operation extension
+description: Safely install or update the Azure Operator Service Manager network function operator extension.
+author: msftadam
+ms.author: adamdor
+ms.date: 09/16/2024
+ms.topic: how-to
+ms.service: azure-operator-service-manager
+---
+
+# Manage network function operator extension
+
+## Overview 
+This article guides user installation of the Azure Operator Service Manager (AOSM) network function operator (NFO) extension. This kubernetes cluster extension is used as part of the AOSM service offering to manage container based workloads hosted by the Azure Operator Nexus platform.
+
+## Create or update network function extension
+
+### Command
+```bash
+az k8s-extension create --cluster-name
+                        --cluster-type {connectedClusters}
+                        --extension-type {Microsoft.Azure.HybridNetwork}
+                        --name
+                        --resource-group
+                        --scope {cluster}
+                        --release-namespace {azurehybridnetwork}
+                        --release-train {preview, stable}
+                        --config Microsoft.CustomLocation.ServiceAccount=azurehybridnetwork-networkfunction-operator
+                        [--auto-upgrade {false, true}]
+                        [--config global.networkfunctionextension.enableClusterRegistry={false, true}]
+                        [--config global.networkfunctionextension.enableLocalRegistry={false, true}]
+                        [--config global.networkfunctionextension.enableEarlyLoading={false,true}]
+                        [--config global.networkfunctionextension.clusterRegistry.highAvailability.enabled={true, false}]
+                        [--config global.networkfunctionextension.clusterRegistry.autoScaling.enabled={true, false}]
+                        [--config global.networkfunctionextension.webhook.highAvailability.enabled={true, false}]
+                        [--config global.networkfunctionextension.webhook.autoScaling.enabled={true, false}]
+                        [--config global.networkfunctionextension.clusterRegistry.storageClassName=]
+                        [--config global.networkfunctionextension.clusterRegistry.storageSize=]
+                        [--config global.networkfunctionextension.webhook.pod.mutation.matchConditionExpression=]
+                        [--version]
+```
+
+### Required Parameters
+`--cluster-name -c`
+* Name of the Kubernetes cluster.
+
+`--cluster-type -t`
+* Specify Arc clusters or AKS managed clusters or Arc appliances or provisionedClusters.
+* Accepted values: connectedClusters.
+
+`--extension-type`
+* Name of the extension type.
+* Accepted values: Microsoft.Azure.HybridNetwork.
+
+`--name -n`
+* Name of the extension instance.
+
+`--resource-group -g`
+* Name of resource group. You can configure the default group using az configure --defaults group=<name>.
+  
+`--config Microsoft.CustomLocation.ServiceAccount=azurehybridnetwork-networkfunction-operator`
+* This configuration must be provided.
+
+### Optional Parameters
+`--auto-upgrade`
+* Automatically upgrade minor version of the extension instance.
+* Accepted values: false, true.
+* Default value: true.
+
+`--release-train`
+* Specify the release train for the extension type.
+* Accepted values: preview, stable.
+* Default value: stable.
+
+`--version` 
+* Specify the version to install for the extension instance if --auto-upgrade-minor-version is not enabled.
+* Availabe version can be found on [Network Function Extension Release notes]
+
+### Optional feature specific configurations
+
+#### Pod Mutating Webhook
+
+`--config global.networkfunctionextension.webhook.pod.mutation.matchConditionExpression=`
+* This configuration is an optional parameter. It comes into play when CNF is getting installed and as a part of its installation corresponding pods are spin up in the CNF's release namespace.  
+* This configuration configures more granular control on top of rules and namespaceSelectors defined in [Pod Mutating Webhook Configuration](https://dev.azure.com/msazuredev/AzureForOperatorsIndustry/_git/aosm-networkfunctionextension?version=GBmain&path=/src/NetworkFunctionExtension/config/default/networkfunction-operator/templates/webhook_pod/webhook_mutating_config.yaml).  
+* Default value:  
+  ```bash
+  "((object.metadata.namespace != \"kube-system\") ||  (object.metadata.namespace == \"kube-system\" && has(object.metadata.labels) && (has(object.metadata.labels.app) && (object.metadata.labels.app == \"commissioning\") || (has(object.metadata.labels.name) && object.metadata.labels.name == \"cert-exporter\") || (has(object.metadata.labels.app) && object.metadata.labels.app == \"descheduler\"))))"
+  ```  
+  The above matchCondition implies that the pods getting admitted in kube-system namespace will be mutated only if they have atleast one of the following labels:  
+  - app == "commissioning"  
+  - name == "cert-exporter"  
+  - app == "descheduler"  
+
+  else they will not be mutated and continue to be pulled from the original source as per the helm chart of CNF/Component/Application.  
+* Accepted value:  
+  Any valid [CEL expressions](https://kubernetes.io/docs/reference/using-api/cel/)  
+* To learn more about matchConditions [reference Kubernetes doc link](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#matching-requests-matchconditions).  
+* This is configurable parameter that can be set or updated during NF Extension's installation or update.  
+* Also, this condition comes into play only when the CNF/Component/Application is getting installed into the namespace as per the rules and namespaceSelectors defined in [Pod Mutating Webhook Configuration](https://dev.azure.com/msazuredev/AzureForOperatorsIndustry/_git/aosm-networkfunctionextension?version=GBmain&path=/src/NetworkFunctionExtension/config/default/networkfunction-operator/templates/webhook_pod/webhook_mutating_config.yaml). If there are more pods getting spin up in that namespace, this condition will still be applied to them.   
+
+#### Cluster registry
+
+`--config global.networkfunctionextension.enableClusterRegistry=`
+* This configuration will provision a regsitry in the cluster to locally cache artifacts.
+* By default this will enable lazy loading mode unless global.networkfunctionextension.enableEarlyLoading=true.
+* Accepted values: false, true.
+* Default value: false.
+
+`--config global.networkfunctionextension.clusterRegistry.highAvailability.enabled=`
+* This configuration will provision the cluster regsitry in high availability mode if cluster registry is enabled.
+* By default is true and uses NAKS nexus-shared volume on AKS recommendation is to set this as false.
+* Accepted values: true, false.
+* Default value: true.
+
+`--config global.networkfunctionextension.clusterRegistry.autoScaling.enabled=`
+* This configuration will provision the cluster registry pods with horizontal auto scaling.
+* Accepted values: true, false.
+* Default value: true.
+
+`--config global.networkfunctionextension.webhook.highAvailability.enabled=`
+* This configuration will provision multiple replicas of webhook for high availability.
+* Accepted values: true, false.
+* Default value: true.
+
+`--config global.networkfunctionextension.webhook.autoScaling.enabled=`
+* This configuration will provision the webhook pods with horizontal auto scaling.
+* Accepted values: true, false.
+* Default value: true.
+
+`--config global.networkfunctionextension.enableEarlyLoading=`
+* This configuration will enable artifacts early loading into cluster regsitry before helm installation or upgrade.
+* This configuration can only be enabled when global.networkfunctionextension.enableClusterRegistry=true.
+* Accetped values: false, true.
+* Default value: false.
+
+`--config global.networkfunctionextension.clusterRegistry.storageClassName=`
+* This configuration must be provided when global.networkfunctionextension.enableClusterRegistry=true. 
+* NetworkFunctionExtension will provision a PVC to local cache artifacts from this storage class.
+* Platform specific values
+  * AKS: managed-csi
+  * NAKS(Default): nexus-shared
+  * NAKS(Non-HA): nexus-volume
+  * ASE: managed-premium
+* Default value: nexus-shared.
+
+`--config global.networkfunctionextension.clusterRegistry.storageSize=`
+* This configuration must be provided when global.networkfunctionextension.enableClusterRegistry=true.
+* This configuration configures the size we reserve for cluster registry.
+* Recommend carefully choose a value that needed to cache artifacts.
+* Please notes to use unit as Gi and Ti for sizing. International system of unites: https://physics.nist.gov/cuu/Units/binary.html
+* Default value: 100Gi
+
+#### Side loading
+
+`--config global.networkfunctionextension.enableLocalRegistry=`
+* This configuration will allow artifacts to be delivered to edge via hardware drive.
+* It is only used for Tempnet with AP5GC.
+* Accepted values: false, true.
+* Default value: false.
+
+### Recommended NFO config for AKS
+
+The default NFO config is configured for HA on NAKS as none of the csi disk drives on AKS support ReadWriteX access mode, HA needs to be disabled on AKS.Use the following config options on AKS
+
+` --config global.networkfunctionextension.clusterRegistry.highAvailability.enabled=false`
+` --config global.networkfunctionextension.webhook.highAvailability.enabled=false` (optional)
+` --config global.networkfunctionextension.clusterRegistry.storageClassName=managed-csi`
+
+### Examples
+Create a network function extension with auto upgrade.
+```bash
+az k8s-extension create --resource-group myresourcegroup --cluster-name mycluster --name myextension --cluster-type connectedClusters --extension-type Microsoft.Azure.HybridNetwork --scope cluster --config Microsoft.CustomLocation.ServiceAccount=azurehybridnetwork-networkfunction-operator --release-namespace azurehybridnetwork
+```
+
+Create a network function extension with a pined version.
+```bash
+az k8s-extension create --resource-group myresourcegroup --cluster-name mycluster --name myextension --cluster-type connectedClusters --extension-type Microsoft.Azure.HybridNetwork --auto-upgrade-minor-version false --scope cluster --config Microsoft.CustomLocation.ServiceAccount=azurehybridnetwork-networkfunction-operator --release-namespace azurehybridnetwork --version 1.0.2711-7
+```
+
+Create a network function extension with cluster registry (default lazy loading mode) feature enabled on NAKS.
+```bash
+az k8s-extension create --resource-group myresourcegroup --cluster-name mycluster --name myextension --cluster-type connectedClusters --extension-type Microsoft.Azure.HybridNetwork --scope cluster --config Microsoft.CustomLocation.ServiceAccount=azurehybridnetwork-networkfunction-operator --release-namespace azurehybridnetwork --config global.networkfunctionextension.enableClusterRegistry=true --config global.networkfunctionextension.clusterRegistry.storageSize=100Gi
+```
+
+Create a network function extension with cluster registry (default lazy loading mode) feature enabled on AKS.
+```bash
+az k8s-extension create --resource-group myresourcegroup --cluster-name mycluster --name myextension --cluster-type connectedClusters --extension-type Microsoft.Azure.HybridNetwork --scope cluster --config Microsoft.CustomLocation.ServiceAccount=azurehybridnetwork-networkfunction-operator --release-namespace azurehybridnetwork --config global.networkfunctionextension.enableClusterRegistry=true --config global.networkfunctionextension.clusterRegistry.highAvailability.enabled=false --config global.networkfunctionextension.clusterRegistry.storageClassName=managed-csi --config global.networkfunctionextension.clusterRegistry.storageSize=100Gi
+```
+
+Create a network function extension with cluster registry (early loading) feature enabled.
+```bash
+az k8s-extension create --resource-group myresourcegroup --cluster-name mycluster --name myextension --cluster-type connectedClusters --extension-type Microsoft.Azure.HybridNetwork --scope cluster --config Microsoft.CustomLocation.ServiceAccount=azurehybridnetwork-networkfunction-operator --release-namespace azurehybridnetwork --config global.networkfunctionextension.enableClusterRegistry=true --config global.networkfunctionextension.enableEarlyLoading=true --config global.networkfunctionextension.clusterRegistry.storageClassName=managed-csi --config global.networkfunctionextension.clusterRegistry.storageSize=100Gi
+```
+
+Create a network function extension with side loading feature enabled.
+```bash
+az k8s-extension create --resource-group myresourcegroup --cluster-name mycluster --name myextension --cluster-type connectedClusters --extension-type Microsoft.Azure.HybridNetwork --scope cluster --config Microsoft.CustomLocation.ServiceAccount=azurehybridnetwork-networkfunction-operator --release-namespace azurehybridnetwork --config global.networkfunctionextension.enableLocalRegistry=true
+```