Add func workload design proposal#4923
Conversation
Use a versioned JSON Schema URL ('https://aka.ms/func-workloads/v1/schema.json')
instead of an opaque integer. Matches tsconfig.json / azure-pipelines.yml /
dotnet/global.json convention so editors and validators can consume the
schema directly, and breaking changes ship under a new URL path.
liliankasem
force-pushed
the
liliankasem/docs/workload-spec
branch
from
e587b80 to
28f3452
Compare
|
|
||
| | Command | Behavior | | ||
| |----------------------------------------|-------------------------------------------------------------------| | ||
| | `func workload list` | List installed workloads with id, version, capabilities, install path. | |
There was a problem hiding this comment.
A command to check if a specific workload (with optional version) is installed would be useful for desired-state scripts.
There was a problem hiding this comment.
Do we want this to be a new command, or can we just make this a property of list?
Option A: New dedicated subcommand
func workload check <id> [--version <v>]
Exit 0 if the workload (and optional version) is installed; non-zero otherwise. Prints nothing by default;
--verboseprints resolved version.
Option B: Flag on list
func workload list <id> [--version <v>] --exists # exit code only
|
|
||
| - If no workload is installed for the requested runtime, the Func CLI **must** | ||
| print an actionable hint with the exact command to install one (e.g. | ||
| `func workload install python`) and exit with a clear error. |
There was a problem hiding this comment.
How is the CLI going to know what workload the user is missing?
There was a problem hiding this comment.
That's a good question - I am not sure that this is going to be possible for every command, but I think we can do some basic project detection to say "looks like this might be a python function app, install the python workload". I just want us to be able to provide clear signposting for the basic commands to help onboard folks to the new cli
There was a problem hiding this comment.
We can use:
- An explicit --stack flag, if provided.
- FUNCTIONS_WORKER_RUNTIME from local.settings.json, if present.
- Lightweight project-marker detection (e.g. presence of *.csproj, requirements.txt, package.json) to make a best-effort guess.
I am not sure about other workloads, but I at least want to ensure the base important ones are signposted.
Another idea I have here is that we can have some list or legacy map of previous commands from v4 that are now workloads, so if someone tries to run func azure or func kubernetes we should say "this is now a workload, please install _"
| - `version` → semver, the workload version. | ||
| - `title` → display name shown in `func workload list`. | ||
| - `description` → one-line summary shown in `func workload list`. | ||
| - `tags` → space-separated short aliases (e.g. `dotnet csharp`) |
There was a problem hiding this comment.
We need a spec of the exact tags we will use for determining the alias, we can't use all the tags. Would it be a tag like alias:python?
There was a problem hiding this comment.
Good call out, we should document all planned tags here. For alias, I think alias:python makes sense. But I recall we discussed having a func-workload tag as well for easier discoverability of workloads in search
|
As I review more and more error handling, I think we need a spec for a diagnostics/verbose mode. Where we will collect errors/traces into a shareable log file users can attach to github issues. |
Co-authored-by: Jacob Viau <javia@microsoft.com>
Agree - would you be interested in throwing a quick spec for that together? |
2 participants
Proposed spec for the v5 workload extension model. Lives under
proposed/so it can be iterated on without affectingvnext.Highlights
IProjectInitializer,ITemplateProvider,IPackProvider) into a hosted DI container. Built-in commands consume those services viaIEnumerable<T>. No per-workload manifest file: workloads are pure NuGet packages with[assembly: ExportCliWorkload<T>].~/.azure-functions/workloads.jsonrecords what's installed; the loader is a single JSON read + N assembly loads, no filesystem walking.$schemaURL identifies the manifest format (https://aka.ms/func-workloads/v1/schema.json). Editors and validators consume it directly; breaking changes ship under a new versioned URL.packageType: FuncCliWorkloadis the discriminator on NuGet, mirroring howdotnetfinds tools (packageType=dotnettool).func new(no args) lists templates from every installed workload that targets the active stack (resolved vialocal.settings.jsonor.func/config.json).--stackreplaces--worker-runtimeas the user-facing language selector.Updates from earlier rounds
schemaVersion: <int>to$schema: <url>.packageTypefilter convention.--worker-runtimeto--stackthroughout.func newtemplate scoping by active stack.Base branch
Targets
docsso the proposal can be iterated on independently of code branches. Once accepted, content moves into the main spec underdocs/.