diff --git a/src/azure-cli/azure/cli/command_modules/appservice/_help.py b/src/azure-cli/azure/cli/command_modules/appservice/_help.py index e0dad92e98c..5b7b5b1da03 100644 --- a/src/azure-cli/azure/cli/command_modules/appservice/_help.py +++ b/src/azure-cli/azure/cli/command_modules/appservice/_help.py @@ -1874,7 +1874,18 @@ 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. + Use 'az webapp list-runtimes' to see available runtimes. + + Suggested next steps after creation: + - Deploy your code: + az webapp deploy -g MyResourceGroup -n MyAppName --src-path app.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 +1921,12 @@ - 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" + - name: Create a Linux Python web app with a startup script. + text: > + az webapp create -g MyResourceGroup -p MyLinuxPlan -n MyUniqueAppName --runtime "PYTHON:3.14" --startup-file "startup.sh" """ helps['webapp create-remote-connection'] = """ @@ -1985,7 +2002,10 @@ 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: These credentials require SCM basic authentication to be enabled. + To enable: az webapp update -g MyResourceGroup -n MyAppName --basic-auth Enabled 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 +2090,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 +2616,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. + - Use 'az webapp list-runtimes' to see available runtimes. examples: - name: View the details of the app that will be created, without actually running the operation @@ -2603,6 +2631,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 +2708,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 +3324,22 @@ 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: Zip deployment does NOT automatically run build automation (dependency installation, + compilation, etc.). If your package is not pre-built, 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 + + Supported --type values: zip, war, jar, ear, lib, static, startup. examples: + - name: Enable remote build and deploy an app from a zip file. + 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 - 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 diff --git a/src/azure-cli/azure/cli/command_modules/appservice/_params.py b/src/azure-cli/azure/cli/command_modules/appservice/_params.py index bd4dc0b7ea5..1544d99df6c 100644 --- a/src/azure-cli/azure/cli/command_modules/appservice/_params.py +++ b/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= source= type= destination-path= credentials-secret-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/down (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/in (add or remove 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,17 +306,23 @@ 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 or script file. " + "Required for FastAPI and other ASGI " + "frameworks (auto-detection is not supported). " + "Example command: \"gunicorn --bind=0.0.0.0 --timeout 600 " + "app:app\". Example for FastAPI: \"gunicorn -k " + "uvicorn.workers.UvicornWorker app:app\". " + "Example script file: \"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., `/:`)') + help='The container custom image name and optionally the tag name (e.g., `/:`). Note: if --container-registry-url is also provided, use `:` 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)) c.argument('multicontainer_config_file', options_list=['--multicontainer-config-file'], help="Linux only. Config file for multicontainer apps. (local or remote)") - c.argument('runtime', options_list=['--runtime', '-r'], help="canonicalized web runtime in the format of Framework:Version, e.g. \"PHP:7.2\"." + c.argument('runtime', options_list=['--runtime', '-r'], help="canonicalized web runtime in the format of Framework:Version, e.g. \"PYTHON:3.14\"." "Use `az webapp list-runtimes` for available list") # TODO ADD completer c.argument('plan', options_list=['--plan', '-p'], configured_default='appserviceplan', completer=get_resource_name_completion_list('Microsoft.Web/serverFarms'), @@ -327,7 +334,7 @@ def load_arguments(self, _): c.argument('acr_use_identity', action='store_true', help="Enable or disable pull image from acr use managed identity") c.argument('acr_identity', help='Accept system or user assigned identity which will be set for acr image pull. ' 'Use \'[system]\' to refer system assigned identity, or a resource id to refer user assigned identity.') - c.argument('basic_auth', help='Enable or disable basic auth for both SCM and FTP Basic Auth Publishing Credentials. Defaults to Enabled if not specified. See https://aka.ms/app-service-basic-auth to learn more.', arg_type=get_enum_type(BASIC_AUTH_TYPES)) + c.argument('basic_auth', help='Enable or disable basic auth for both SCM and FTP Basic Auth Publishing Credentials. Disabled by default for new apps. See https://aka.ms/app-service-basic-auth to learn more.', arg_type=get_enum_type(BASIC_AUTH_TYPES)) c.argument('auto_generated_domain_name_label_scope', options_list=['--domain-name-scope'], help="Specify the scope of uniqueness for the default hostname during resource creation.", arg_type=get_enum_type(AutoGeneratedDomainNameLabelScope)) c.argument('end_to_end_encryption_enabled', options_list=['--end-to-end-encryption-enabled', '-e'], help='Enable or disable end-to-end encryption between the Front End and the Workers.', @@ -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., `/:`)') + help='The container custom image name and optionally the tag name (e.g., `/:`). Note: if --container-registry-url is also provided, use `:` 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,16 @@ 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. " + "Use 'az webapp list-runtimes' to see available runtimes.") + c.argument('runtime', options_list=['--runtime', '-r'], help="canonicalized web runtime in the format of Framework:Version, e.g. \"PYTHON:3.14\". " + "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') diff --git a/src/azure-cli/azure/cli/command_modules/appservice/custom.py b/src/azure-cli/azure/cli/command_modules/appservice/custom.py index 386ba088608..dc510fe4d4b 100644 --- a/src/azure-cli/azure/cli/command_modules/appservice/custom.py +++ b/src/azure-cli/azure/cli/command_modules/appservice/custom.py @@ -147,9 +147,17 @@ def create_webapp(cmd, resource_group_name, name, plan, runtime=None, startup_fi container_registry_url = parse_docker_image_name(deployment_container_image_name) if container_image_name: - container_image_name = container_image_name if not container_registry_url else "{}/{}".format( - urlparse(container_registry_url).hostname, - container_image_name[1:] if container_image_name.startswith('/') else container_image_name) + if container_registry_url: + registry_host = urlparse(container_registry_url).hostname + # Warn if image name already includes the registry host + if registry_host and container_image_name.lower().startswith(registry_host.lower() + "/"): + logger.warning("Note: --container-image-name '%s' appears to include the registry host. " + "The --container-registry-url host is prepended automatically. " + "The resulting image will be: %s/%s", + container_image_name, registry_host, container_image_name) + container_image_name = container_image_name if not container_registry_url else "{}/{}".format( + urlparse(container_registry_url).hostname, + container_image_name[1:] if container_image_name.startswith('/') else container_image_name) if deployment_container_image_name: container_image_name = deployment_container_image_name @@ -363,6 +371,11 @@ def create_webapp(cmd, resource_group_name, name, plan, runtime=None, startup_fi update_site_configs(cmd, resource_group_name, name, acr_identity=acr_identity) _enable_basic_auth(cmd, name, None, resource_group_name, basic_auth.lower()) + # Only suggest deployment command when no deployment method is already configured + if not using_webapp_up and not any([container_image_name, deployment_container_image_name, + multicontainer_config_type, sitecontainers_app, + deployment_source_url, deployment_local_git]): + logger.warning("Webapp '%s' created. Deploy your code with: az webapp deploy", name) return webapp @@ -2816,6 +2829,9 @@ def delete_function_app(cmd, resource_group_name, name, keep_empty_plan=None, sl def delete_webapp(cmd, resource_group_name, name, keep_metrics=None, keep_empty_plan=None, keep_dns_registration=None, slot=None): # pylint: disable=unused-argument client = web_client_factory(cmd.cli_ctx) + if not keep_empty_plan and not slot: + logger.warning("Note: If this is the last app on the plan, the plan will also be deleted. " + "Use --keep-empty-plan to prevent this.") if slot: client.web_apps.delete_slot(resource_group_name, name, slot, delete_metrics=False if keep_metrics else None, @@ -3837,9 +3853,17 @@ def create_webapp_slot(cmd, resource_group_name, webapp, slot, configuration_sou container_registry_url = parse_docker_image_name(deployment_container_image_name) if container_image_name: - container_image_name = container_image_name if not container_registry_url else "{}/{}".format( - urlparse(container_registry_url).hostname, - container_image_name[1:] if container_image_name.startswith('/') else container_image_name) + if container_registry_url: + registry_host = urlparse(container_registry_url).hostname + # Warn if image name already includes the registry host + if registry_host and container_image_name.lower().startswith(registry_host.lower() + "/"): + logger.warning("Note: --container-image-name '%s' appears to include the registry host. " + "The --container-registry-url host is prepended automatically. " + "The resulting image will be: %s/%s", + container_image_name, registry_host, container_image_name) + container_image_name = container_image_name if not container_registry_url else "{}/{}".format( + urlparse(container_registry_url).hostname, + container_image_name[1:] if container_image_name.startswith('/') else container_image_name) if deployment_container_image_name: container_image_name = deployment_container_image_name @@ -4058,6 +4082,8 @@ def enable_local_git(cmd, resource_group_name, name, slot=None): site_config = get_site_configs(cmd, resource_group_name, name, slot) site_config.scm_type = 'LocalGit' _generic_site_operation(cmd.cli_ctx, resource_group_name, name, 'create_or_update_configuration', slot, site_config) + logger.warning("Note: The default deployment branch is 'master'. If your local branch is 'main', " + "either push with: git push azure main:master, or set app setting DEPLOYMENT_BRANCH=main.") return {'url': _get_local_git_url(cmd.cli_ctx, client, resource_group_name, name, slot)} @@ -4298,6 +4324,9 @@ def pre_operations(self): "storage_mounts": storage_mounts, }) + os_type = 'Linux' if is_linux else ('Hyper-V' if hyper_v else 'Windows') + logger.warning("Creating App Service Plan '%s' (%s).", name, os_type) + if no_wait: return poller.result() @@ -9099,6 +9128,8 @@ def webapp_up(cmd, name=None, resource_group_name=None, plan=None, location=None _create_new_app = _site_availability.name_available runtime = _StackRuntimeHelper.remove_delimiters(runtime) os_name = os_type if os_type else detect_os_from_src(src_dir, html, runtime) + if not os_type: + logger.warning("No --os-type specified. Defaulting to '%s'.", os_name) _is_linux = os_name.lower() == LINUX_OS_NAME helper = _StackRuntimeHelper(cmd, linux=_is_linux, windows=not _is_linux) @@ -9118,6 +9149,13 @@ def webapp_up(cmd, name=None, resource_group_name=None, plan=None, location=None _data = get_runtime_version_details(_lang_details.get('file_loc'), language, helper, _is_linux) version_used_create = _data.get('to_create') detected_version = _data.get('detected') + if language and language.lower() != 'static': + if not version_used_create or version_used_create == '-': + logger.warning("No --runtime specified. Could not auto-detect a valid %s version. " + "Please specify --runtime explicitly. " + "Use 'az webapp list-runtimes' for available options.", language.upper()) + else: + logger.warning("No --runtime specified. Using %s version: %s.", language, version_used_create) runtime_version = "{}|{}".format(language, version_used_create) if \ version_used_create != "-" else version_used_create @@ -9172,6 +9210,7 @@ def webapp_up(cmd, name=None, resource_group_name=None, plan=None, location=None loc = set_location(cmd, sku, location) rg_name = get_rg_to_use(user, resource_group_name) _create_new_rg = not check_resource_group_exists(cmd, rg_name) + _plan_not_provided = plan is None plan = get_plan_to_use(cmd=cmd, user=user, loc=loc, @@ -9181,6 +9220,8 @@ def webapp_up(cmd, name=None, resource_group_name=None, plan=None, location=None plan=plan, is_linux=_is_linux, client=client) + if _plan_not_provided: + logger.warning("No --plan specified. Auto-generated plan: '%s'.", plan) dry_run_str = r""" { "name" : "%s", "appserviceplan" : "%s", @@ -9206,7 +9247,7 @@ def webapp_up(cmd, name=None, resource_group_name=None, plan=None, location=None create_resource_group(cmd, rg_name, loc) logger.warning("Resource group creation complete") # create ASP - logger.warning("Creating AppServicePlan '%s' or Updating if already exists", plan) + logger.warning("Creating AppServicePlan '%s' in '%s' or Updating if already exists", plan, loc) # we will always call the ASP create or update API so that in case of re-deployment, if the SKU or plan setting are # updated we update those try: @@ -9524,6 +9565,15 @@ def perform_onedeploy_webapp(cmd, client = web_client_factory(cmd.cli_ctx) app = client.web_apps.get(resource_group_name, name) params.is_linux_webapp = is_linux_webapp(app) + + # Warn that zip deploy won't auto-build on Linux + if params.is_linux_webapp and artifact_type in (None, 'zip'): + logger.warning( + "Note: 'az webapp deploy' does not run build automation (dependency installation, " + "compilation, etc.) by default for Linux web apps. If your package is not pre-built, " + "set the app setting SCM_DO_BUILD_DURING_DEPLOYMENT=true to enable builds during deployment." + ) + params.is_functionapp = False return _perform_onedeploy_internal(params)