Merge pull request #218458 from Nickomang/aks-marketplace-updates

Kubernetes application for Azure Marketplace updates

Author: BCS2022

articles/marketplace/TOC.yml

@@ -215,8 +215,10 @@
           href: azure-container-plan-technical-configuration.md
         - name: Plan technical configuration for Kubernetes applications
           href: azure-container-plan-technical-configuration-kubernetes.md
-        - name: Container certification troubleshooting
-          href: azure-container-certification-faq.yml
+    - name: Container certification troubleshooting
+      href: azure-container-certification-faq.yml
+    - name: Kubernetes application publishing troubleshooting
+      href: azure-container-troubleshoot.md
   - name: Azure virtual machine offer
     items:
     - name: Plan the offer

articles/marketplace/azure-container-technical-assets-kubernetes.md

@@ -6,7 +6,7 @@ ms.subservice: partnercenter-marketplace-publisher
 ms.topic: conceptual
 author: nickomang
 ms.author: nickoman
-ms.date: 09/27/2022
+ms.date: 11/30/2022
 ---
 
 # Prepare Azure container technical assets for a Kubernetes app
@@ -57,10 +57,15 @@ In addition to your solution domain, your engineering team should have knowledge
 
 ## Publishing overview
 
-The first step to publish your Kubernetes app-based Container offer on the Azure Marketplace is to package your application as a [Cloud Native Application Bundle (CNAB)][cnab]. This CNAB, comprised of your application’s artifacts, will be first published to your private Azure Container Registry (ACR) and later pushed to an Azure Marketplace-specific public ACR and will be used as the single artifact you reference in Partner Center.
+The first step to publish your Kubernetes app-based Container offer on the Azure Marketplace is to package your application as a [Cloud Native Application Bundle (CNAB)][cnab]. This CNAB, comprised of your application’s artifacts, will be first published to your private Azure Container Registry (ACR) and later pushed to a Microsoft-owned ACR and will be used as the single artifact you reference in Partner Center.
+
+From there, vulnerability scanning is performed to ensure images are secure. Finally, the Kubernetes application is registered as an extension type for an Azure Kubernetes Service (AKS) cluster.
 
 Once your offer is published, your application will leverage the [cluster extensions for AKS][cluster-extensions] feature to manage your application lifecycle inside an AKS cluster.
 
+:::image type="content" source="./media/azure-container/bundle-processing.png" alt-text="A diagram showing the three stages of bundle processing, flowing from 'Copy the bundle to a Microsoft-owned registry' to 'Vulnerability scanning' to 'Extension type registration'.":::
+
+
 ## Grant access to your Azure Container Registry
 
 As part of the publishing process, Microsoft will deep copy your CNAB from your ACR to a Microsoft-owned, Azure Marketplace-specific ACR. This step requires you to grant Microsoft access to your registry.
@@ -264,6 +269,24 @@ The fields used in the manifest are as follows:
 
 For a sample configured for the voting app, see the following [manifest file example][manifest-sample].
 
+### User parameter flow
+
+It's important to understand how user parameters flow throughout the artifacts you're creating and packaging. Parameters are initially defined when creating the UI through a *createUiDefinition.json* file:
+
+:::image type="content" source="./media/azure-container/user-param-ui.png" alt-text="A screenshot of the createUiDefinition example linked in this article. Definitions for 'value1' and 'value2' are shown.":::
+
+and are exported via the `outputs` section:
+
+:::image type="content" source="./media/azure-container/user-param-ui-2.png" alt-text="A screenshot of the createUiDefinition example linked in this article. Output lines for application title, 'value1', and 'value2' are shown.":::
+
+From there, the values are passed to the Azure Resource Manager template and will be propagated to the Helm chart during deployment:
+
+:::image type="content" source="./media/azure-container/user-param-arm.png" alt-text="A screenshot of the Azure Resource Manager template example linked in this article. Under 'configurationSettings', the parameters for application title, 'value1', and 'value2' are shown.":::
+
+Finally, the values are consumed by the Helm chart:
+
+:::image type="content" source="./media/azure-container/user-param-helm.png" alt-text="A screenshot of the Helm chart example linked in this article. Values for application title, 'value1', and 'value2' are shown.":::
+
 ### Structure your application
 
 Place the createUiDefinition, ARM template, and manifest file beside your application's Helm chart.
@@ -289,6 +312,8 @@ The following Docker command pulls the latest packaging tool image and also moun
 Assuming `~\<path-to-content>` is a directory containing the contents to be packaged, the following docker command will mount `~/<path-to-content>` to `/data` in the container. Be sure to replace `~/<path-to-content>` with your own app's location.
 
 ```bash
+docker pull mcr.microsoft.com/container-package-app:latest
+
 docker run -it -v /var/run/docker.sock:/var/run/docker.sock -v ~/<path-to-content>:/data --entrypoint "/bin/bash" mcr.microsoft.com/container-package-app:latest 
 ```
 
@@ -297,6 +322,8 @@ docker run -it -v /var/run/docker.sock:/var/run/docker.sock -v ~/<path-to-conten
 Assuming `D:\<path-to-content>` is a directory containing the contents to be packaged, the following docker command will mount `d:/<path-to-content>` to `/data` in the container. Be sure to replace `d:/<path-to-content>` with your own app's location.
 
 ```bash
+docker pull mcr.microsoft.com/container-package-app:latest
+
 docker run -it -v /var/run/docker.sock:/var/run/docker.sock -v d:/<path-to-content>:/data --entrypoint "/bin/bash" mcr.microsoft.com/container-package-app:latest 
 ```
 

articles/marketplace/azure-container-troubleshoot.md

@@ -0,0 +1,50 @@
+---
+title: Troubleshoot publishing issues for a Kubernetes application based Container offer in Microsoft AppSource.
+description: Learn about potential issue and solutions when publishing a Kubernetes application based Container offer in Microsoft AppSource.
+ms.service: marketplace 
+ms.subservice: partnercenter-marketplace-publisher
+ms.topic: article
+author: nickomang
+ms.author: nickoman
+ms.date: 11/14/2022
+---
+
+# Troubleshoot issues while publishing a Kubernetes application-based Container offer
+
+Once published, a Kubernetes application based Container offer goes through the following high level flow for bundle processing. 
+
+:::image type="content" source="./media/azure-container/bundle-processing.png" alt-text="A diagram showing the three stages of bundle processing, flowing from 'Copy the bundle to a Microsoft-owned registry' to 'Vulnerability scanning' to 'Extension type registration'.":::
+
+First, the contents of the Cloud Native Application Bundle (CNAB) are copied from your own registry to a Microsoft-owned Azure Container Registry (ACR). From there, vulnerability scanning is performed to ensure images are secure. Finally, the Kubernetes application is registered as an [extension][cluster-extension] type for an Azure Kubernetes Service (AKS) cluster. If the publish fails, it may be an issue with one of these components. See below for common errors and related mitigation steps.
+
+## Common issues
+
+### Publishing fails with missing artifacts in the CNAB
+
+|Error|Description|Action|
+|--|:--|--|
+|"extensionRegistrationParameters cannot be null or empty in manifest.yaml of your package. For more details, please refer to https://aka.ms/K8sOfferAssets#create-the-manifest-file"|Kubernetes applications are packaged as AKS cluster extensions. The manifest file provides input for the Extension Type creation.|Read the description for each property and provide the information.|
+|"namespace cannot be null or empty for defaultScope as cluster in extensionRegistrationParameters in manifest.yaml of your package. For more details, please refer to https://aka.ms/K8sOfferAssets#create-the-manifest-file"|Kubernetes applications that are installed at Cluster scope will use the default scope provided as the namespace.|Be sure to provide a namespace in the `extensionRegistrationParameters` section in your manifest file|
+
+### Publishing fails while copying the artifacts from your ACR to a Microsoft-owned ACR
+
+|Error|Description|Action|
+|--|--|--|
+|"Access to registry {sourceACRName} was denied. Please provide MarketPlace access to registry. please refer: https://aka.ms/K8sOfferAssets#grant-access-to-your-azure-container-registry"|During the publishing process, Microsoft moves your Kubernetes application, which is packaged as a CNAB and uploaded to an ACR, to a Microsoft-owned registry. <br><br/> To do so, Microsoft's first party app responsible for this process must be provided with permissions. This error appears if the Marketplace publishing was done without providing the permissions.|[Provide Microsoft's first party app with the proper permissions][grant-access].|
+|"CNAB repository {cnabBundle} cannot be found in registry {sourceACRName}. Please provide MarketPlace access to registry. please refer: https://aka.ms/K8sOfferAssets#grant-access-to-your-azure-container-registry"|The Kubernetes application that has been packaged using the CPA tool can't be found in your ACR.|Ensure the bundle has been successfully uploaded to your registry, and [provide Microsoft's first party app with the proper permissions][grant-access].|
+|"The CNAB repository name {cnabBundle} with digest {targetDigest} already exists and is different than your provided CNAB digest {sourcedigest}."|A plan with the same version is already published using a different CNAB.|If your CNAB contents have changed, increment the plan version and try publishing again.|
+
+### Publishing fails with Platform errors
+
+|Error|Description|Action|
+|--|--|--|
+|Internal server error|May be a transient error.|Try publishing again.|
+
+### Vulnerability scanning
+
+You may also encounter errors due to vulnerabilities in your images. For more information on vulnerability scanning and how to mitigate issues, see [Container certification troubleshooting][container-certification-troubleshooting].
+
+<!-- LINKS -->
+[container-certification-troubleshooting]: ./azure-container-certification-faq.yml
+[cluster-extension]: /azure/aks/integrations#extensions/
+[grant-access]: ./azure-container-technical-assets-kubernetes.md#grant-access-to-your-azure-container-registry