[App Service] Add deployment guidance, warnings, and container image fix for Linux web apps

src/azure-cli/azure/cli/command_modules/appservice/_help.py

@@ -1874,7 +1874,17 @@
 helps['webapp create'] = """
 type: command
 short-summary: Create a web app.
-long-summary: The web app's name must be able to produce a unique FQDN as AppName.azurewebsites.net.
+long-summary: |
+    The web app's name must be able to produce a unique FQDN as AppName.azurewebsites.net.
+
+    This command creates the web app resource but does not deploy code.
+
+    Suggested next steps after creation:
+    - Deploy your code:
+        az webapp deploy -g MyResourceGroup -n MyAppName --src-path app.zip --type zip
+    - For Linux apps loading large models or dependencies at startup, increase the container
+      start time limit (default 230s, max 1800s):
+        az webapp config appsettings set -g MyResourceGroup -n MyAppName --settings WEBSITES_CONTAINER_START_TIME_LIMIT=1800
 examples:
   - name: Create a web app with the default configuration.
     text: >
@@ -1910,6 +1920,9 @@
   - name: Create a web app with end-to-end encryption enabled and minimum TLS version 1.2
     text: >
         az webapp create -g MyResourceGroup -p MyPlan -n MyUniqueAppName --end-to-end-encryption-enabled true --min-tls-version 1.2
+  - name: Create a Linux Python web app with a custom startup command.
+    text: >
+        az webapp create -g MyResourceGroup -p MyLinuxPlan -n MyUniqueAppName --runtime "PYTHON:3.14" --startup-file "gunicorn --bind=0.0.0.0 app:app"
 """
 
 helps['webapp create-remote-connection'] = """
@@ -1985,7 +1998,9 @@
 
 helps['webapp deployment list-publishing-credentials'] = """
 type: command
-short-summary: Get the details for available web app publishing credentials
+short-summary: Get the details for available web app publishing credentials.
+long-summary: |
+    Note: SCM basic authentication must be enabled to use these credentials for deployment.
 examples:
   - name: Get the details for available web app publishing credentials (autogenerated)
     text: az webapp deployment list-publishing-credentials --name MyWebapp --resource-group MyResourceGroup --subscription MySubscription
@@ -2070,6 +2085,10 @@
 helps['webapp deployment source config-local-git'] = """
 type: command
 short-summary: Get a URL for a git repository endpoint to clone and push to for web app deployment.
+long-summary: |
+    Note: The default deployment branch is 'master'. If your local branch is 'main',
+    either push with: git push azure main:master, or set the app setting
+    DEPLOYMENT_BRANCH=main to change the deployment branch.
 examples:
   - name: Get an endpoint and add it as a git remote.
     text: >
@@ -2592,6 +2611,10 @@
     Each time the command is successfully run, default argument values for resource group, sku, location, plan, and name are saved for the current directory.
     These defaults are then used for any arguments not provided on subsequent runs of the command in the same directory.  Use 'az configure' to manage defaults.
     Run this command with the --debug parameter to see the API calls and parameters values being used.
+long-summary: |
+    Usage notes:
+    - If the app already exists, the existing SKU is kept — the --sku flag is ignored for existing apps.
+    - Progress messages appear as WARNING level — these are informational, not errors.
 
 examples:
   - name: View the details of the app that will be created, without actually running the operation
@@ -2603,6 +2626,12 @@
   - name: Create a web app with a specified name
     text: >
         az webapp up -n MyUniqueAppName
+  - name: Deploy a Python app to Linux with explicit runtime and plan name.
+    text: >
+        az webapp up -n MyApp --runtime "PYTHON:3.14" --plan MyPlan --sku P1v3
+  - name: Deploy a .NET app to Linux (must specify --os-type linux).
+    text: >
+        az webapp up -n MyDotnetApp --runtime "DOTNETCORE:10.0" --os-type linux --plan MyPlan
   - name: Create a web app with a specified name and a Java 11 runtime
     text: >
         az webapp up -n MyUniqueAppName --runtime "java:11:Java SE:11"
@@ -2674,6 +2703,9 @@
 helps['webapp webjob'] = """
 type: group
 short-summary: Allows management operations for webjobs on a web app.
+long-summary: |
+    To create WebJobs, use the Azure portal. For more information and other options,
+    see: https://learn.microsoft.com/azure/app-service/webjobs-create
 """
 
 helps['webapp webjob continuous'] = """
@@ -3287,7 +3319,27 @@
 helps['webapp deploy'] = """
     type: command
     short-summary: Deploys a provided artifact to Azure Web Apps.
+    long-summary: |
+        Deploys a zip, war, jar, ear, static file, startup script, or library to an existing Azure Web App.
+        The web app must already exist — use 'az webapp create' to create one first.
+
+        IMPORTANT: For apps that require dependency installation during deployment (Python, Node.js,
+        PHP), zip deployment does NOT automatically install dependencies. You must set the
+        app setting SCM_DO_BUILD_DURING_DEPLOYMENT=true before deploying:
+
+            az webapp config appsettings set -g ResourceGroup -n AppName --settings SCM_DO_BUILD_DURING_DEPLOYMENT=true
+
+        Alternatively, use 'az webapp up' which handles resource creation, zipping, and build automatically.
+
+        Supported --type values: zip, war, jar, ear, lib, static, startup.
+
+        Note: Progress messages may appear as WARNING level — these are informational and do not
+        indicate errors.
     examples:
+    - name: Deploy a Python/Node.js app from a zip file (must enable build first).
+      text: |
+        az webapp config appsettings set -g ResourceGroup -n AppName --settings SCM_DO_BUILD_DURING_DEPLOYMENT=true
+        az webapp deploy -g ResourceGroup -n AppName --src-path app.zip --type zip
     - name: Deploy a war file asynchronously.
       text: az webapp deploy --resource-group ResourceGroup --name AppName --src-path SourcePath --type war --async true
     - name: Deploy a static text file to wwwroot/staticfiles/test.txt

src/azure-cli/azure/cli/command_modules/appservice/_params.py

@@ -156,10 +156,11 @@ def load_arguments(self, _):
                    help="Storage mount configurations. Provide key-value pairs for `name=<name> source=<source> type=<type> destination-path=<path> credentials-secret-uri=<uri>`.")
 
     with self.argument_context('appservice plan update') as c:
-        c.argument('sku', arg_type=sku_arg_type)
+        c.argument('sku', arg_type=sku_arg_type,
+                   help='SKU of the app service plan. Use this to scale up (change machine size), e.g. --sku P1v3.')
         c.argument('elastic_scale', arg_type=get_three_state_flag(), help='Enable or disable automatic scaling. Set to "true" to enable elastic scale for this plan, or "false" to disable elastic scale for this plan. The SKU must be a Premium V2 SKU (P1V2, P2V2, P3V2) or a Premium V3 SKU (P1V3, P2V3, P3V3)')
         c.argument('max_elastic_worker_count', options_list=['--max-elastic-worker-count', '-m'], type=int, help='Maximum number of instances that the plan can scale out to. The plan must be an elastic scale plan.')
-        c.argument('number_of_workers', type=int, help='Number of workers to be allocated.')
+        c.argument('number_of_workers', type=int, help='Number of workers to be allocated. Use this to scale out (add instances), e.g. --number-of-workers 3.')
         c.ignore('allow_pending_state')
         c.argument('async_scaling_enabled', arg_type=get_three_state_flag(), help='Enables async scaling for the app service plan. Set to "true" to create an async operation if there are insufficient workers to scale synchronously. The SKU must be Dedicated.')
         c.argument('default_identity', is_preview=True,
@@ -305,12 +306,18 @@ def load_arguments(self, _):
                    validator=validate_site_create,
                    local_context_attribute=LocalContextAttribute(name='web_name', actions=[LocalContextAction.SET],
                                                                  scopes=['webapp', 'cupertino']))
-        c.argument('startup_file', help="Linux only. The web's startup file")
+        c.argument('startup_file', help="Linux only. The web's startup command. "
+                                        "Required for FastAPI and other ASGI "
+                                        "frameworks (auto-detection is not supported). "
+                                        "Example for Flask: \"gunicorn --bind=0.0.0.0 --timeout 600 "
+                                        "app:app\". Example for FastAPI: \"gunicorn -k "
+                                        "uvicorn.workers.UvicornWorker app:app\". "
+                                        "Example startup script: \"./startup.sh\".")
         c.argument('sitecontainers_app', help="If true, a webapp which supports sitecontainers will be created", arg_type=get_three_state_flag())
         c.argument('deployment_container_image_name', options_list=['--deployment-container-image-name', '-i'], help='Container image name from container registry, e.g. publisher/image-name:tag', deprecate_info=c.deprecate(target='--deployment-container-image-name'))
         c.argument('container_registry_url', options_list=['--container-registry-url'], help='The container registry server url')
         c.argument('container_image_name', options_list=['--container-image-name', '-c'],
-                   help='The container custom image name and optionally the tag name (e.g., `<registry-name>/<image-name>:<tag>`)')
+                   help='The container custom image name and optionally the tag name (e.g., <registry-name>/<image-name>:<tag>). Note: if --container-registry-url is also provided, use <image-name>:<tag> without the registry name.')
         c.argument('container_registry_user', options_list=['--container-registry-user', '-s', c.deprecate(target='--docker-registry-server-user', redirect='--container-registry-user')], help='The container registry server username')
         c.argument('container_registry_password', options_list=['--container-registry-password', '-w', c.deprecate(target='--docker-registry-server-password', redirect='--container-registry-password')], help='The container registry server password. Required for private registries.')
         c.argument('multicontainer_config_type', options_list=['--multicontainer-config-type'], help="Linux only.", arg_type=get_enum_type(MULTI_CONTAINER_TYPES))
@@ -712,7 +719,7 @@ def load_arguments(self, _):
                    help='Container image name, e.g. publisher/image-name:tag', deprecate_info=c.deprecate(target='--deployment-container-image-name'))
         c.argument('container_registry_url', options_list=['--container-registry-url', '-r'], help='The container registry server url')
         c.argument('container_image_name', options_list=['--container-image-name', '-c'],
-                   help='The container custom image name and optionally the tag name (e.g., `<registry-name>/<image-name>:<tag>`)')
+                   help='The container custom image name and optionally the tag name (e.g., <registry-name>/<image-name>:<tag>). Note: if --container-registry-url is also provided, use <image-name>:<tag> without the registry name.')
         c.argument('container_registry_user', options_list=['--container-registry-user', '-u', c.deprecate(target='--docker-registry-server-user', redirect='--container-registry-user')], help='The container registry server username')
         c.argument('container_registry_password', options_list=['--container-registry-password', '-w', c.deprecate(target='--docker-registry-server-password', redirect='--container-registry-password')],
                    help='The container registry server password')
@@ -951,11 +958,15 @@ def load_arguments(self, _):
                                                                  scopes=['webapp', 'cupertino']))
         c.argument('plan', options_list=['--plan', '-p'],
                    completer=get_resource_name_completion_list('Microsoft.Web/serverFarms'),
-                   help="name of the app service plan associated with the webapp",
+                   help="name of the app service plan associated with the webapp. If not specified, a name is auto-generated.",
                    configured_default='appserviceplan')
         c.argument('sku', arg_type=sku_arg_type)
-        c.argument('os_type', options_list=['--os-type'], arg_type=get_enum_type(OS_TYPES), help="Set the OS type for the app to be created.")
-        c.argument('runtime', options_list=['--runtime', '-r'], help="canonicalized web runtime in the format of Framework:Version, e.g. \"PHP:7.2\"."
+        c.argument('os_type', options_list=['--os-type'], arg_type=get_enum_type(OS_TYPES),
+                   help="Set the OS type for the app to be created. Defaults to Linux for Python "
+                        "and Node.js runtimes, and to Windows for .NET and ASP.NET runtimes. "
+                        "Use 'linux' explicitly for .NET Linux deployments.")
+        c.argument('runtime', options_list=['--runtime', '-r'], help="canonicalized web runtime in the format of Framework:Version, e.g. \"PHP:7.2\". "
+                                                                     "Recommended: always specify explicitly for reliable results. Auto-detection from source files may pick the wrong version. "
                                                                      "Use `az webapp list-runtimes` for available list.")
         c.argument('dryrun', help="show summary of the create and deploy operation instead of executing it",
                    default=False, action='store_true')