Merge pull request #296463 from msftadam/patch-66

AnnaMHuff · web-flow · commit 14c41fa3041d · 2025-03-18T10:37:39.000-06:00
Update helm-requirements.md
diff --git a/articles/operator-service-manager/helm-requirements.md b/articles/operator-service-manager/helm-requirements.md
@@ -9,38 +9,34 @@ ms.service: azure-operator-service-manager
 ---
 
 # Helm requirements overview
-Helm is a package manager for Kubernetes that helps to simplify application lifecycle management. Helm packages are called charts and consist of YAML configuration and template files. Upon execution of a Helm operation, the charts are rendered into Kubernetes manifest files to trigger the appropriate application lifecycle action. For most efficient integration with Azure Operator Service Manager (AOSM), publisher's should consider certain best-practice considerations when developing Helm charts.
+Helm is a package manager for Kubernetes that helps to simplify application lifecycle management. Helm packages are called charts and consist of YAML configuration and template files. Upon execution of a Helm operation, the charts are rendered into Kubernetes manifest files to trigger the appropriate application lifecycle actions. For most efficient integration with Azure Operator Service Manager (AOSM), publisher's should consider certain best-practices when developing Helm charts.
 
-## Considerations for registryUrl and imagePullSecrets
-Every Helm chart generally requires a registryUrl and imagePullSecrets. Most commonly, a publisher exposes these parameters in the values.yaml. At first, AOSM depended upon the publisher exposing these values in a strict manner, so they could be substituted for the proper Azure values during deployment. Overtime, not all publishers could easily comply with the strict handling of these values required by AOSM. 
-* Some charts hide registryUrl and/or imagePullSecrets behind conditionals, or other values restrictions, which were not always met.
-* Some charts don't declare registryUrl and/or imagePullSecrets as the expected named string, instead as an array.
+## Considerations for registryPath and imagePullSecrets
+Every Helm chart generally requires a registryPath and imagePullSecrets. Most commonly, a publisher exposes these parameters in the values.yaml. At first, AOSM depended upon the publisher managing these values in a strict manner (legacy approach), to be substituted for the proper Azure values during deployment. Overtime, it was found that not all publishers could easily comply with the strict management of these values. Some charts hide registryPath and/or imagePullSecrets behind conditionals, or other values restrictions, which were not always met. Some charts don't declare registryPath and/or imagePullSecrets as the expected named string, instead as an array. To reduce the strict compliance requirements on publishers, AOSM  introduced two improved methods, injectArtifactStoreDetail and cluster registry. These newer methods do not depend upon the registryPath or imagePullSecrets which appear in the Helm package. Instead, these methods use a webhook to inject proper Azure values directly into pod operations.
 
-To reduce the strict compliance requirements on publishers, AOSM later introduced two improved methods of handling these values. First injectArtifactStoreDetail and finally Cluster Registry. These two newer methods do not depend upon valid registryUrl or imagePullSecrets appearing in the Helm package. Instead, these methods inject these values directly into pod operations, on behalf of the network function.
+### Method summary for registryPath and imagePullSecrets
+All three methods are presently supported as described in this article. A publisher should choose the best option for their (network function) NF and use-case. 
 
-### Method summary for registryUrl and imagePullSecrets
-All three methods are supported and described in this article. A publisher should choose the best option for their Network Function and use-case. 
-
-**Legacy.** 
-* Requires publisher to compliantly parameterize registryUrl & imagePullSecrets in helm values and deployment templates for substitution.
+**Legacy** 
+* Requires publisher to parameterize registryPath & imagePullSecrets in helm values and deployment templates for substitution.
 * Images are hosted in the publisher Azure Container Registry (ACR).
 
-**InjectArtifactStoreDetail.**  
-* Uses a webhook to inject registryUrl & imagePullSecrets directly into pod operations, with minimal dependencies on helm.
+**InjectArtifactStoreDetail**  
+* Uses a webhook to inject registryPath & imagePullSecrets directly into pod operations, with minimal dependencies on helm.
 * Images are still hosted in the publisher ACR.
 
-**Cluster Registry.** 
-* Uses a webhook to inject registryUrl & imagePullSecrets directly into pod operations, with no dependency on helm.
-* Images are hosted in the local NFO extension cluster registry.
+**Cluster Registry** 
+* Uses a webhook to inject registryPath & imagePullSecrets directly into pod operations, with no dependency on helm.
+* Images are hosted in the local network function operator (NFO) extension cluster registry.
 
 > [!NOTE]
-> In all three cases, AOSM is substituting AOSM values for whatever values a publisher exposes in templates. The only difference is method for substitution.
+> In all three cases, AOSM is substituting Azure values for whatever values a publisher exposes in templates. The only difference is method of substitution.
 
-## Legacy requirements for registryUrl and imagePullSecrets 
-Azure Operator Service Manager (AOSM) uses the Network Function Manager (NFM) service to deploy Containerized Network Functions (CNFs). With the legacy method, NFM substitutes the AOSM container registryUrl and imagePullSecrets values into the helm operation during Network Function (NF) deployment. 
+## Legacy requirements for registryPath and imagePullSecrets 
+Azure Operator Service Manager (AOSM) uses the Network Function Manager (NFM) service to deploy Containerized Network Functions (CNFs). With the legacy method, NFM substitutes the AOSM container registryPath and imagePullSecrets values into the helm operation during Network Function (NF) deployment. 
 
 ### Using legacy method
-The following helm deployment template shows an example of how a publisher should expose registryPath and imagePullSecrets for compatibility with AOSM legacy approach.
+The following `helm deployment` template shows an example of how a publisher should expose registryPath and imagePullSecrets.
 
 ```json
 apiVersion: apps/v1 
@@ -69,7 +65,15 @@ spec:
         - containerPort: 80 
 ```
 
-The following `values.schema.json` file shows an example of how a publisher can easily set registryPath and imagePullSecretsvalue requirements for compatibility with AOSM legacy approach.
+The following `values.yaml` template shows an example of how a publisher can provide the registryPath and imagePullSecretsvalue values. 
+
+```json
+global: 
+   imagePullSecrets: [] 
+   registryPath: “” 
+```
+
+The following `values.schema.json` file shows an example of how a publisher can easily define registryPath and imagePullSecretsvalue.
 
 ```json
 { 
@@ -91,46 +95,38 @@ The following `values.schema.json` file shows an example of how a publisher can
 
 ```
 
-The following `NFDVersion request payload` shows an example of how a publisher can provide the registryPath and imagePullSecretsvalue values for compatibility with AOSM legacy approach.
+The following `NFDV request payload` shows an example of how a publisher can provide the registryPath and imagePullSecretsvalue values at deployment.
 
 ```json
 "registryValuesPaths": [ "global.registryPath" ], 
 "imagePullSecretsValuesPaths": [ "global.imagePullSecrets" ], 
 ```
 
-The following `values.yaml` shows an example of how a publisher can provide the registryPath and imagePullSecretsvalue values for compatibility with AOSM legacy approach. 
-
-```json
-global: 
-   imagePullSecrets: [] 
-   registryPath: “” 
-```
-
 > [!NOTE]
 > * The registryPath is set without any prefix such as `https://` or `oci://`. If needed, publisher must define a prefix in the helm package. 
 > * imagePullSecrets and registryPath must be provided in the create NFDVersion onboarding step.
 
 ### Other considerations with Legacy method
-Publisher should additional consider the following recommendations when using the legacy method: 
+Publisher should consider the following recommendations when using the legacy method: 
 * Avoid references to external registry
-* Performa manual validations
+* Perform manual validations
 * Ensure static image repository and tags
 
 #### Avoid references to external registry
 Users should avoid using references to an external registry. For example, if deployment.yaml uses a hardcoded registry path or external registry references it fails validation.
 
 #### Perform manual validations
-Review the images and container specs created to ensure the images have prefix of registryURL and the imagePullSecrets are populated with secretName.
+Review the images and container specs created to ensure the images have prefix of registryPath and the imagePullSecrets are populated with secretName.
 
 ```shell
- helm template --set "global.imagePullSecrets[0].name=<secretName>" --set "global.registry.url=<registryURL>" <release-name> <chart-name> --dry-run
+ helm template --set "global.imagePullSecrets[0].name=<secretName>" --set "global.registry.url=<registryPath>" <release-name> <chart-name> --dry-run
 ```
 
 OR
 
 ```shell
- helm install --set "global.imagePullSecrets[0].name=<secretName>" --set "global.registry.url=<registryURL>" <release-name> <chart-name> --dry-run
- kubectl create secret <secretName> regcred --docker-server=<registryURL> --dockerusername=<regusername> --docker-password=<regpassword>
+ helm install --set "global.imagePullSecrets[0].name=<secretName>" --set "global.registry.url=<registryPath>" <release-name> <chart-name> --dry-run
+ kubectl create secret <secretName> regcred --docker-server=<registryPath> --dockerusername=<regusername> --docker-password=<regpassword>
 ```
 
 #### Ensure static image repository and tags
@@ -156,11 +152,22 @@ image:
 ```
 
 ```json
- image: http://myURL/{{ .Values.image.repository }}:{{ .Values.image.tag}}
+ image: http://myUrl/{{ .Values.image.repository }}:{{ .Values.image.tag}}
 ```
 
-## injectArtifactStoreDetails requirements for registryUrl and imagePullSecrets 
-In some cases, third-party helm charts may not be fully compliant with AOSM requirements for registryURL. In this case, the injectArtifactStoreDetails feature can be used to avoid making compliance changes to helm packages. With injectArtifactStoreDetails enabled, a webhook method is used to inject the proper registryUrl and imagePullSecrets dynamically during the pod operations.  This overrides the values which are configured in the helm package. 
+## injectArtifactStoreDetails requirements for registryPath and imagePullSecrets 
+In some cases, third-party helm charts may not be fully compliant with AOSM requirements for registryPath. In this case, the injectArtifactStoreDetails feature can be used to avoid making compliance changes to helm packages. With injectArtifactStoreDetails enabled, a webhook method is used to inject the proper registryPath and imagePullSecrets dynamically during the pod operations. This overrides the values which are configured in the helm package. A publisher still must use legal dummy values where registryPath and imagePullSecrets are referenced, usually in the global section of values.yaml.
+
+The following `values.yaml` shows an example of how a publisher can provide the registryPath and imagePullSecretsvalue values for compatibility with injectArtifactStoreDetails approach. 
+
+```json
+global: 
+   registryPath: “” 
+   imagePullSecrets: [] 
+```
+
+> [!NOTE]
+> If registryPath is left blank in underlying helm package, site network service (SNS) deployment fails while trying to download image.
 
 ### Using injectArtifactStoreDetails method
 To enable injectArtifactStoreDetails, set the installOptions parameter in the NF resource roleOverrides section to true, as shown in the following example.
@@ -188,10 +195,23 @@ resource networkFunction 'Microsoft.HybridNetwork/networkFunctions@2023-09-01' =
 ```
 
 > [!NOTE]
-> The helm chart package must still expose properly formatted registryURL and imagePullSecrets values.
+> The helm chart package must still expose properly formatted registryPath and imagePullSecrets values.
+
+## Cluster registry requirements for registryPath and imagePullSecrets 
+With cluster registry, images are copied from the publisher ACR to a local docker repository on the nexus AKS (NAKS) cluster. When enabled, a webhook method is used to inject the proper registryPath and imagePullSecrets dynamically during the pod operations. This overrides the values which are configured in the helm package. A publisher still must use legal dummy values where registryPath and imagePullSecrets are referenced, usually in global section of values.yaml. 
+
+The following `values.yaml` shows an example of how a publisher can provide the registryPath and imagePullSecretsvalue values for compatibility with cluster registry approach. 
+
+```json
+global: 
+   registryPath: “”
+   imagePullSecrets: [] 
+```
+
+> [!NOTE]
+> If registryPath is left blank in underlying helm package, SNS deployment fails while trying to download image.
 
-## Cluster registry requirements for registryUrl and imagePullSecrets 
-For information on using cluster registry, please see the [concept documentation](get-started-with-cluster-registry.md).
+For information on using cluster registry, see the [concept documentation](get-started-with-cluster-registry.md).
 
 ## Chart immutability restrictions
 Immutability restrictions prevent changes to a file or directory. For example, an immutable file can't be changed or renamed. Users should avoid using mutable tags such as latest, dev, or stable. For example, if deployment.yaml used 'latest' for the .Values.image.tag the deployment would fail.
