Skip to content

Commit 11ad0fd

Browse files
tzolovtzolov
committed
Fix azure docs numbering and top levers
1 parent 27694da commit 11ad0fd

File tree

2 files changed

+131
-121
lines changed

2 files changed

+131
-121
lines changed

‎docs/src/main/asciidoc/adapters/azure-intro.adoc‎

Lines changed: 44 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,25 @@
11
:branch: master
22

33
== Microsoft Azure Functions
4+
:sectnums:
45

5-
https://azure.microsoft.com[Azure] function adapter, that allows to deploy and run `Spring Cloud Function` applications as native Azure Java Functions.
6+
https://azure.microsoft.com[Azure] function adapter for deploying `Spring Cloud Function` applications as native Azure Java Functions.
67

7-
The Azure impose an annotation-based https://learn.microsoft.com/en-us/azure/azure-functions/functions-reference-java[programming model] for defining the function's handler methods and their input and output types.
8-
The Azure Maven (or Gradle) plugin is used to inspects the annotated classes and to generate the native Azure Function binding files and configurations.
9-
The Azure annotations are just a type-safe way to configure your java function (function that has no awareness of Azure) to be recognized as Azure function.
8+
The `Azure Functions` https://learn.microsoft.com/en-us/azure/azure-functions/functions-reference-java[programming model] relays, extensively, on Java https://learn.microsoft.com/en-us/java/api/com.microsoft.azure.functions.annotation?view=azure-java-stable[annotations] for defining the function's handler methods and their input and output types.
9+
At compile time the annotated classes are processed by the provided Azure Maven/Gradle plugins to generate the necessary Azure Function binding files, configurations and package artifacts.
10+
The Azure annotations are just a type-safe way to configure your java function to be recognized as Azure function.
1011

11-
The https://github.com/spring-cloud/spring-cloud-function/tree/main/spring-cloud-function-adapters/spring-cloud-function-adapter-azure[spring-cloud-function-adapter-azure] extends the basic programming model and provides fully fledged Spring and Spring Cloud Function programming model support.
12-
With the adapter you can build your Spring Cloud Function application using dependency injections and then auto-wire the necessary services to your Azure handler methods.
12+
The https://github.com/spring-cloud/spring-cloud-function/tree/main/spring-cloud-function-adapters/spring-cloud-function-adapter-azure[spring-cloud-function-adapter-azure] extends the basic programming model to provide Spring and Spring Cloud Function support.
13+
With the adapter you can build your Spring Cloud Function application using dependency injections and then auto-wire the necessary services into your Azure handler methods.
1314

14-
TIP: For Web-based applications, instead of the generic `adapter-azure`, you can opt for the specialized https://github.com/spring-cloud/spring-cloud-function/tree/main/spring-cloud-function-adapters/spring-cloud-function-adapter-azure-web[spring-cloud-function-adapter-azure-web] adapter.
15-
Later would allow you to get rid of the Azure Annotations completely in favor of the familiar Spring Web programming model.
16-
By applying the required dependency and configuring your Maven (or Gradle) Azure plugin, you can deploy any Spring Web application as an Azure, HttpTrigger function.
17-
The <<Azure Web Adapter>> section below provides additional information about this approach.
15+
TIP: For Web-based function applications, you can replace the generic `adapter-azure` with the specialized https://github.com/spring-cloud/spring-cloud-function/tree/main/spring-cloud-function-adapters/spring-cloud-function-adapter-azure-web[spring-cloud-function-adapter-azure-web].
16+
With the Azure Web Adapter you can deploy any Spring Web application as an Azure, HttpTrigger, function.
17+
This adapter hides the Azure annotations complexity and uses the familiar https://docs.spring.io/spring-boot/docs/current/reference/html/web.html[Spring Web] programming model instead.
18+
For further information follow the <<azure.web.adapter,Azure Web Adapter>> section below.
1819

1920
== Azure Adapter
2021

21-
Extends the Azure Functions programming model with fully fledged for Spring and Spring Cloud Function.
22+
Provides `Spring` & `Spring Cloud Function` integration for Azure Functions.
2223

2324
=== Dependencies
2425

@@ -120,7 +121,7 @@ public class HttpTriggerDemoApplication {
120121
}
121122
}
122123
----
123-
<1> The `@SpringBootApplication` annotated class is used as a `Main-Class` (or `Start-Class`) as explained in <<star-class-configuration, star class configuration>>.
124+
<1> The `@SpringBootApplication` annotated class is used as a `Main-Class` as explained in <<star-class-configuration, main class configuration>>.
124125
<2> Functions auto-wired and used in the Azure function handlers.
125126

126127
==== Accessing Azure ExecutionContext
@@ -161,17 +162,20 @@ public Function<Message<String>, String> uppercase(JsonMapper mapper) {
161162
----
162163
<1> Retrieve the ExecutionContext instance from the header.
163164

164-
=== Project Layout
165+
[[azure.configuration]]
166+
=== Configuration
165167

166-
In order to run Spring Cloud Function applications on Microsoft Azure, you have to use the Maven or Gradle plugins offered by Azure.
167-
Later imposes a specific https://learn.microsoft.com/en-us/azure/azure-functions/functions-reference-java?tabs=bash%2Cconsumption#folder-structure[package archive structure] that interferes with the `standard` Spring Boot package jars.
168-
The <<disable-spring-boot-plugin,Disable Spring Boot Plugin>> section below explains how to handle this.
169-
You have to provide Azure specific configurations such as the `resourceGroup`, `appName` and other optional properties.
170-
More information about the runtime configurations: https://learn.microsoft.com/en-us/azure/azure-functions/functions-reference-java?tabs=bash%2Cconsumption#java-versions[Java Versions], https://learn.microsoft.com/en-us/azure/azure-functions/functions-reference-java?tabs=bash%2Cconsumption#specify-the-deployment-os[Deployment OS].
168+
To run your function applications on Microsoft Azure, you have to provide the necessary configurations, such as `function.json` and `host.json`, and adhere to the compulsory https://learn.microsoft.com/en-us/azure/azure-functions/functions-reference-java?tabs=bash%2Cconsumption#folder-structure[packaging format].
169+
170+
Usually the Azure Maven (or Gradle) plugins are used to generate the necessary configurations from the annotated classes and to produce the required package format.
171171

172-
==== Azure Maven/Gradle Plugin
172+
IMPORTANT: The Azure https://learn.microsoft.com/en-us/azure/azure-functions/functions-reference-java?tabs=bash%2Cconsumption#folder-structure[packaging format] is not compatible with the default Spring Boot packaging (e.g. `uber jar`).
173+
The <<disable.spring.boot.plugin,Disable Spring Boot Plugin>> section below explains how to handle this.
173174

174-
Sample Azure Function (Maven/Gradle) configuration would like like:
175+
==== Azure Maven/Gradle Plugins
176+
177+
Azure provides https://github.com/microsoft/azure-maven-plugins/tree/develop/azure-functions-maven-plugin[Maven] and https://github.com/microsoft/azure-gradle-plugins/tree/master/azure-functions-gradle-plugin[Gradle] plugins to process the annotated classes, generate the necessary configurations and produce the expected package layout.
178+
Plugins are used to set the platform, runtime and app-settings properties like this:
175179

176180
====
177181
[source,xml,indent=0,subs="verbatim,attributes",role="primary"]
@@ -196,8 +200,6 @@ Sample Azure Function (Maven/Gradle) configuration would like like:
196200
<javaVersion>11</javaVersion>
197201
</runtime>
198202
199-
<funcPort>7072</funcPort>
200-
201203
<appSettings>
202204
<property>
203205
<name>FUNCTIONS_EXTENSION_VERSION</name>
@@ -232,13 +234,16 @@ azurefunctions {
232234
region = 'YOUR-AZURE-FUNCTION-APP-REGION'
233235
appServicePlanName = 'YOUR-AZURE-FUNCTION-APP-SERVICE-PLANE-NAME'
234236
pricingTier = 'YOUR-AZURE-FUNCTION-APP-SERVICE-PLANE-NAME'
237+
235238
runtime {
236239
os = 'linux'
237240
javaVersion = '11'
238241
}
242+
239243
auth {
240244
type = 'azure_cli'
241245
}
246+
242247
appSettings {
243248
FUNCTIONS_EXTENSION_VERSION = '~4'
244249
}
@@ -248,15 +253,15 @@ azurefunctions {
248253
----
249254
====
250255

251-
The complete plugin documentation is available at the https://github.com/microsoft/azure-maven-plugins/tree/develop/azure-functions-maven-plugin[Azure Maven] and https://github.com/microsoft/azure-gradle-plugins/tree/master/azure-functions-gradle-plugin[Azure Gradle] repositories.
252-
256+
More information about the runtime configurations: https://learn.microsoft.com/en-us/azure/azure-functions/functions-reference-java?tabs=bash%2Cconsumption#java-versions[Java Versions], https://learn.microsoft.com/en-us/azure/azure-functions/functions-reference-java?tabs=bash%2Cconsumption#specify-the-deployment-os[Deployment OS].
253257

258+
[[disable.spring.boot.plugin]]
254259
==== Disable Spring Boot Plugin
255260

256261
Expectedly, the Azure Functions run inside the Azure execution runtime, not inside the SpringBoot runtime!
257262
Furthermore, Azure expects a specific packaging format, generated by the Azure Maven/Gradle plugins, that is not compatible with the default Spring Boot packaging.
258263

259-
IMPORTANT: You have to either disable the SpringBoot Maven/Gradle plugin or use the https://github.com/dsyer/spring-boot-thin-launcher[Spring Boot Thin Launcher] as shown in this Maven snipped:
264+
You have to either disable the SpringBoot Maven/Gradle plugin or use the https://github.com/dsyer/spring-boot-thin-launcher[Spring Boot Thin Launcher] as shown in this Maven snippet:
260265

261266
[source,xml]
262267
----
@@ -308,7 +313,7 @@ For local runs, add the `MAIN_CLASS` variable to your `local.settings.json` file
308313

309314
IMPORTANT: If the `MAIN_CLASS` variable is not set, the Azure adapter lookups the `MANIFEST/META-INFO` attributes from the jars found on the classpath and selects the first `Main-Class:` annotated with either a `@SpringBootApplication` or `@SpringBootConfiguration` annotation.
310315

311-
==== Configuration Metadata
316+
==== Metadata Configuration
312317

313318
You can use a shared https://learn.microsoft.com/en-us/azure/azure-functions/functions-host-json[host.json] file to configure the function app.
314319

@@ -337,15 +342,14 @@ Here is a list of various Spring Cloud Function Azure Adapter samples you can ex
337342
- https://github.com/spring-cloud/spring-cloud-function/tree/main/spring-cloud-function-samples/function-sample-azure-timer-trigger[Timer Trigger (Maven)]
338343
- https://github.com/spring-cloud/spring-cloud-function/tree/main/spring-cloud-function-samples/function-sample-azure-kafka-trigger[ Kafka Trigger & Output Binding (Maven)].
339344

345+
[[azure.web.adapter]]
340346
== Azure Web Adapter
341347

342-
For web based function applications, the https://github.com/spring-cloud/spring-cloud-function/tree/main/spring-cloud-function-adapters/spring-cloud-function-adapter-azure-web[spring-cloud-function-adapter-azure-web] allows to replace completely the Azure's annotations model in favor of the familiar Spring Web programming model.
343-
The `spring-cloud-function-adapter-azure-web` requires the same package layout and build/deployment steps as the `spring-cloud-function-adapter-azure`.
348+
For, pure, Web-based function applications, you can replace the generic `adapter-azure` with the specialized https://github.com/spring-cloud/spring-cloud-function/tree/main/spring-cloud-function-adapters/spring-cloud-function-adapter-azure-web[spring-cloud-function-adapter-azure-web].
349+
The Azure Web Adapter can deploy any Spring Web application as a native Azure function, using the HttpTrigger internally.
350+
It hides the Azure annotations complexity and relies on the familiar https://docs.spring.io/spring-boot/docs/current/reference/html/web.html[Spring Web] programming model instead.
344351

345-
You can build or take an existing Spring Web application, add the azure-web adapter dependency, configure the necessarily Azure layout packaging and then you can deploy later as Azure Http-trigger function.
346-
347-
To enable the Azure Web Adapter, add the adapter dependency to your `pom.xml` or `build.gradle`
348-
files:
352+
To enable the Azure Web Adapter, add the adapter dependency to your `pom.xml` or `build.gradle` files:
349353

350354
====
351355
[source,xml,indent=0,subs="verbatim,attributes",role="primary"]
@@ -368,12 +372,16 @@ dependencies {
368372
----
369373
====
370374

375+
The same <<azure.configuration, Configuration>> and <<azure.usage,Usage>> instructions apply to the `Azure Web Adapter` as well.
376+
377+
371378
=== Samples
372379

373380
For further information, explore the following, Azure Web Adapter, sample:
374381

375382
- https://github.com/spring-cloud/spring-cloud-function/tree/main/spring-cloud-function-samples/function-sample-azure-web[ Azure Web Adapter (Maven)].
376383

384+
[[azure.usage]]
377385
== Usage
378386

379387
Common instructions for building and deploying both, `Azure Adapter` and `Azure Web Adapter` type of applications.
@@ -476,7 +484,7 @@ Alternatively and the `JAVA_OPTS` value to your `local.settings.json` like this:
476484
}
477485
----
478486

479-
Here is snipped for a `VSCode` remote debugging configuration:
487+
Here is snippet for a `VSCode` remote debugging configuration:
480488

481489
[source,json]
482490
----
@@ -494,8 +502,10 @@ Here is snipped for a `VSCode` remote debugging configuration:
494502
}
495503
----
496504

497-
== (Deprecated) FunctionInvoker
505+
== FunctionInvoker (deprecated)
498506

499507
WARNING: The legacy `FunctionInvoker` programming model is deprecated and will not be supported going forward.
500508

501509
For additional documentation and samples about the Function Integration approach follow the https://github.com/spring-cloud/spring-cloud-function/tree/main/spring-cloud-function-samples/function-sample-azure/[azure-sample] README and code.
510+
511+
:sectnums!:

0 commit comments

Comments
 (0)