azure.yaml schema change to support Java .jar packaging

[weikanglim]

Background

Java applications are most commonly packaged into a single .JAR / .EAR / .WAR archive file that is deployed.

When deployed as a docker container, this poses no issues as the user can explicitly define how packaging works in the Dockerfile. azd simply deploys the container produced.

However, when it comes to ZIP deployments for App service / function apps, azd requires understanding of how the application is packaged which is configured by the user in azure.yaml. Thus, additional configuration is required by the user to specify exactly how this is achieved.

Background: how azd packaging works

Currently, azd allows specifying dist as a relative path directory to create a ZIP deployment folder. This is the current schema description:

"dist": {
    "type": "string",
    "title": "Relative path to service deployment artifacts",
    "description": "The CLI will use files under this path to create the deployment artifact (ZIP file). If omitted, all files under service project directory will be included."
}

Background: how maven packaging works

Maven projects are encouraged to follow maven standard directory layout. target is the root directory of all build outputs and cannot be changed directly via a CLI parameter in mvn package (unlike dotnet publish -o <OUTPUT_DIRECTORY>). The build output directory can only be customized via changing the build configuration files itself.

The target directory contains all build outputs, as well as the final runnable JAR file that serves the application's entrypoint. An example is shown below with simple-todo-0.0.1-SNAPSHOT.jar being the final produced output:

Question: How should we treat dist for Java?

Option A: Implicit

• By default, dist is assumed to be <project>/target for Maven since this is the standard convention.

Option B: Explicit

dist is a required field for Java / maven. The help examples would point at the likely value being ./target.

Question: How should we package *.JAR files?

Option A: Implicit

By default, for Java projects, we will NOT include all files and directories under dist, but rather to include JAR files under dist.

Example:

  web:
    project: ./src/api
    language: java
    host: appservice

Will result in azd packaging the single JAR file found under <project>/target. If multiple JAR files are found, a packaging error is encountered during azd deploy.

Option B: Explicit via glob patterns

This introduces the notion of "globbing" patterns for azd. Without going into too much detail (like to just get agreement on this), we would introduce a globbing pattern mechanism similar how to most CI workflow tasks for packaging works. A set of glob patterns via distGlobPatterns can be defined that matches files relative to dist. When performing file copy, all files are copied to relative to the dist directory specified.

Example:

  web:
    project: ./src/api
    dist: target
    distGlobPatterns:
       - "!*.log"
       - *.jar
    language: java
    host: appservice

Will result in azd packaging the JAR files found under <project>/target. If multiple JAR files are found, a packaging error is encountered during azd deploy. This allows multiple files other than JAR to be included in the final zip directory (not sure how useful this is). It can also allow potentially resolving a single JAR if multiple JARs were present.

It is also an error if no JAR files were resolved. This would be enforced at packaging time. A potential compile-time schema validation could validate at least one expression has suffix .jar or * (less restrictive than actual).

For backcompat behavior, if no distGlobPatterns were specified, it is treated as if distGlobPatterns: ** was provided.

Furthermore, this can allow us to extract out implicit logic we currently have for python, js to exclude node_modules, __pycache__ and allow user to specify it directly.

We can also introduce a breaking change to simplify / refactor config if desirable:

  web:
    project: ./src/api
    dist:
        path: target
        globPatterns:
            - "!*.log"
            - "*.jar"
    language: java
    host: appservice

[ellismg]

Question: How should we treat dist for Java?

My thinking is that we should use Option A here and allow users who need to change this to just set dist explicitly. There's probably a model here where individual languages are able to provide their own default values, which are used when dist is not set.

Question: How should we package *.JAR files?

Here I also think the implicit strategy makes sense (including failing when multiple JAR files are detected in whatever folder dist ends up being), and allow the use of globPatterns for cases where you need to include additional artifacts or need pick a single JAR file from many, or you have multiple .jar files that you need to explicitly include for some reason. Guessing that we'd just want to use filepath.Glob/filepath.Match for the syntax here - but I could also imagine using the syntax from .gitignore.

FWIW - this feels somewhat similar to what we were discussing for project files for .NET based projects (where there could be multiple .{cs|vb|fs}proj files inside the project folder, which would lead to an error and require you to explicitly set a value). I'm not sure if we should try to harmonize these two cases further. I had envisioned that we would just support something like:

project: ./src/api/Todo.Api.csproj

but perhaps with the above design that should instead be something like:

project:
  path: ./src/api
  file: Todo.Api.csproj

I have a slight preference for just including the file name as part of the path component but would be open to something a little more verbose.

This also makes me wonder if we would want to support something like:

dist: ./target/simple-todo-0.0.1-SNAPSHOT.jar

For cases where there are multiple .jar's and you don't want to futz with globs? I know that the version number is baked into the file-name, so it's possible in practice folks would use a glob anyway. Perhaps we could do something like:

dist: ./target/simple-todo-*.jar

It feels like the general pattern here is: "implicit based on conventions from the tool/ecosystem we are interacting with by default, with overrides in azure.yaml for folks who need to provide explicit configuration or places where we can't come up with an answer implicitly (e.g. our heuristics identify multiple candidates, and we don't know what to pick).