diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java b/core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java index 17895ba6a3180..34f04c45a9230 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java +++ b/core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java @@ -69,7 +69,7 @@ final public class Constants { public static final String ANNOTATION_CONFIG_WITH_UNNAMED_KEY = "io.smallrye.config.WithUnnamedKey"; public static final Set SUPPORTED_ANNOTATIONS_TYPES = Set.of(ANNOTATION_BUILD_STEP, ANNOTATION_CONFIG_GROUP, - ANNOTATION_CONFIG_ROOT, ANNOTATION_RECORDER); + ANNOTATION_CONFIG_ROOT, ANNOTATION_RECORDER, ANNOTATION_CONFIG_MAPPING); public static final Map ALIASED_TYPES = Map.of( OptionalLong.class.getName(), Long.class.getName(), diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/ExtensionAnnotationProcessor.java b/core/processor/src/main/java/io/quarkus/annotation/processor/ExtensionAnnotationProcessor.java index 4c90d114a1600..8b74af6943cc2 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/ExtensionAnnotationProcessor.java +++ b/core/processor/src/main/java/io/quarkus/annotation/processor/ExtensionAnnotationProcessor.java @@ -145,6 +145,9 @@ public void doProcess(Set annotations, RoundEnvironment r trackAnnotationUsed(Constants.ANNOTATION_RECORDER); processRecorder(roundEnv, annotation); break; + case Constants.ANNOTATION_CONFIG_MAPPING: + trackAnnotationUsed(Constants.ANNOTATION_CONFIG_MAPPING); + break; } } } @@ -257,7 +260,7 @@ public FileVisitResult postVisitDirectory(final Path dir, final IOException exc) try { if (generateDocs) { final Set outputs = configDocItemScanner - .scanExtensionsConfigurationItems(javaDocProperties); + .scanExtensionsConfigurationItems(javaDocProperties, isAnnotationUsed(ANNOTATION_CONFIG_MAPPING)); for (ConfigDocGeneratedOutput output : outputs) { DocGeneratorUtil.sort(output.getConfigDocItems()); // sort before writing configDocWriter.writeAllExtensionConfigDocumentation(output); diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemFinder.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemFinder.java index 207574ad1ca44..a8beced189383 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemFinder.java +++ b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemFinder.java @@ -75,15 +75,18 @@ class ConfigDocItemFinder { private final Map configGroupQualifiedNameToTypeElementMap; private final FsMap allConfigurationGroups; private final FsMap allConfigurationRoots; + private final boolean configMapping; public ConfigDocItemFinder(Set configRoots, Map configGroupQualifiedNameToTypeElementMap, - Properties javaDocProperties, FsMap allConfigurationGroups, FsMap allConfigurationRoots) { + Properties javaDocProperties, FsMap allConfigurationGroups, FsMap allConfigurationRoots, + boolean configMapping) { this.configRoots = configRoots; this.configGroupQualifiedNameToTypeElementMap = configGroupQualifiedNameToTypeElementMap; this.javaDocProperties = javaDocProperties; this.allConfigurationGroups = allConfigurationGroups; this.allConfigurationRoots = allConfigurationRoots; + this.configMapping = configMapping; } /** @@ -97,7 +100,7 @@ ScannedConfigDocsItemHolder findInMemoryConfigurationItems() throws IOException ConfigPhase buildTime = ConfigPhase.BUILD_TIME; final List configDocItems = recursivelyFindConfigItems(entry.getValue(), EMPTY, EMPTY, buildTime, false, 1, - false); + false, configMapping); allConfigurationGroups.put(entry.getKey(), OBJECT_MAPPER.writeValueAsString(configDocItems)); } @@ -107,7 +110,7 @@ ScannedConfigDocsItemHolder findInMemoryConfigurationItems() throws IOException String rootName = configRootInfo.getName(); ConfigPhase configPhase = configRootInfo.getConfigPhase(); final List configDocItems = recursivelyFindConfigItems(element, rootName, rootName, configPhase, - false, sectionLevel, true); + false, sectionLevel, true, configMapping); holder.addConfigRootItems(configRootInfo, configDocItems); allConfigurationRoots.put(configRootInfo.getClazz().toString(), OBJECT_MAPPER.writeValueAsString(configDocItems)); } @@ -119,7 +122,8 @@ ScannedConfigDocsItemHolder findInMemoryConfigurationItems() throws IOException * Recursively find config item found in a config root or config group given as {@link Element} */ private List recursivelyFindConfigItems(Element element, String rootName, String parentName, - ConfigPhase configPhase, boolean withinAMap, int sectionLevel, boolean generateSeparateConfigGroupDocsFiles) + ConfigPhase configPhase, boolean withinAMap, int sectionLevel, boolean generateSeparateConfigGroupDocsFiles, + boolean configMapping) throws JsonProcessingException { List configDocItems = new ArrayList<>(); TypeElement asTypeElement = (TypeElement) element; @@ -138,7 +142,8 @@ private List recursivelyFindConfigItems(Element element, String r if (rawConfigItems == null) { // element not yet scanned Element superElement = ((DeclaredType) superType).asElement(); superTypeConfigItems = recursivelyFindConfigItems(superElement, rootName, parentName, - configPhase, withinAMap, sectionLevel, generateSeparateConfigGroupDocsFiles); + configPhase, withinAMap, sectionLevel, generateSeparateConfigGroupDocsFiles, + configMapping); } else { superTypeConfigItems = OBJECT_MAPPER.readValue(rawConfigItems, LIST_OF_CONFIG_ITEMS_TYPE_REF); } @@ -148,7 +153,7 @@ private List recursivelyFindConfigItems(Element element, String r } for (Element enclosedElement : element.getEnclosedElements()) { - if (!shouldProcessElement(enclosedElement)) { + if (!shouldProcessElement(enclosedElement, configMapping)) { continue; } @@ -261,7 +266,7 @@ private List recursivelyFindConfigItems(Element element, String r if (isConfigGroup(type)) { List groupConfigItems = readConfigGroupItems(configPhase, rootName, name, emptyList(), type, - configSection, withinAMap, generateSeparateConfigGroupDocsFiles); + configSection, withinAMap, generateSeparateConfigGroupDocsFiles, configMapping); DocGeneratorUtil.appendConfigItemsIntoExistingOnes(configDocItems, groupConfigItems); } else { final ConfigDocKey configDocKey = new ConfigDocKey(); @@ -292,7 +297,8 @@ private List recursivelyFindConfigItems(Element element, String r additionalNames = emptyList(); } List groupConfigItems = readConfigGroupItems(configPhase, rootName, name, - additionalNames, type, configSection, true, generateSeparateConfigGroupDocsFiles); + additionalNames, type, configSection, true, generateSeparateConfigGroupDocsFiles, + configMapping); DocGeneratorUtil.appendConfigItemsIntoExistingOnes(configDocItems, groupConfigItems); continue; } else { @@ -319,7 +325,7 @@ private List recursivelyFindConfigItems(Element element, String r configSection.setOptional(true); List groupConfigItems = readConfigGroupItems(configPhase, rootName, name, emptyList(), typeInString, configSection, withinAMap, - generateSeparateConfigGroupDocsFiles); + generateSeparateConfigGroupDocsFiles, configMapping); DocGeneratorUtil.appendConfigItemsIntoExistingOnes(configDocItems, groupConfigItems); continue; } else if ((typeInString.startsWith(List.class.getName()) @@ -423,11 +429,15 @@ private boolean isConfigGroup(String type) { return configGroupQualifiedNameToTypeElementMap.containsKey(type) || allConfigurationGroups.hasKey(type); } - private boolean shouldProcessElement(final Element enclosedElement) { + private boolean shouldProcessElement(final Element enclosedElement, final boolean configMapping) { if (enclosedElement.getKind().isField()) { return true; } + if (!configMapping && enclosedElement.getKind() == ElementKind.METHOD) { + return false; + } + // A ConfigMapping method if (enclosedElement.getKind().equals(ElementKind.METHOD)) { ExecutableElement method = (ExecutableElement) enclosedElement; @@ -536,7 +546,8 @@ private List readConfigGroupItems( String configGroup, ConfigDocSection configSection, boolean withinAMap, - boolean generateSeparateConfigGroupDocs) + boolean generateSeparateConfigGroupDocs, + boolean configMapping) throws JsonProcessingException { configSection.setConfigGroupType(configGroup); @@ -556,7 +567,7 @@ private List readConfigGroupItems( } else { TypeElement configGroupTypeElement = configGroupQualifiedNameToTypeElementMap.get(configGroup); groupConfigItems = recursivelyFindConfigItems(configGroupTypeElement, EMPTY, EMPTY, configPhase, - false, 1, generateSeparateConfigGroupDocs); + false, 1, generateSeparateConfigGroupDocs, configMapping); allConfigurationGroups.put(configGroup, OBJECT_MAPPER.writeValueAsString(groupConfigItems)); } diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemScanner.java b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemScanner.java index 317b7767864fc..4881cf3e87478 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemScanner.java +++ b/core/processor/src/main/java/io/quarkus/annotation/processor/generate_doc/ConfigDocItemScanner.java @@ -118,12 +118,12 @@ public void addConfigRoot(final PackageElement pkg, TypeElement clazz) { } } - public Set scanExtensionsConfigurationItems(Properties javaDocProperties) + public Set scanExtensionsConfigurationItems(Properties javaDocProperties, boolean configMapping) throws IOException { Set configDocGeneratedOutputs = new HashSet<>(); final ConfigDocItemFinder configDocItemFinder = new ConfigDocItemFinder(configRoots, configGroupsToTypeElement, - javaDocProperties, allConfigGroupGeneratedDocs, allExtensionGeneratedDocs); + javaDocProperties, allConfigGroupGeneratedDocs, allExtensionGeneratedDocs, configMapping); final ScannedConfigDocsItemHolder inMemoryScannedItemsHolder = configDocItemFinder.findInMemoryConfigurationItems(); if (!inMemoryScannedItemsHolder.isEmpty()) { diff --git a/docs/downstreamdoc.yaml b/docs/downstreamdoc.yaml index d0c1f3370ea3c..3f9bc5e52730f 100644 --- a/docs/downstreamdoc.yaml +++ b/docs/downstreamdoc.yaml @@ -17,5 +17,3 @@ guides: - src/main/asciidoc/security-openid-connect-client-reference.adoc - src/main/asciidoc/security-overview.adoc - src/main/asciidoc/security-proactive-authentication.adoc - - src/main/asciidoc/security-vulnerability-detection.adoc - - src/main/asciidoc/update-quarkus.adoc diff --git a/docs/src/main/asciidoc/datasource.adoc b/docs/src/main/asciidoc/datasource.adoc index d5afd66cfb894..684fe97a8c08a 100644 --- a/docs/src/main/asciidoc/datasource.adoc +++ b/docs/src/main/asciidoc/datasource.adoc @@ -9,7 +9,7 @@ include::_attributes.adoc[] :diataxis-type: reference :categories: data,getting-started,reactive -Use a unified configuration model to define datasources for Java Database Connectivity (JDBC) and Reactive drivers. +Use a unified configuration model to define data sources for Java Database Connectivity (JDBC) and Reactive drivers. //// Note for contributors and writers: @@ -20,38 +20,36 @@ See, https://docs.oracle.com/javase/tutorial/jdbc/basics/connecting.html Applications use datasources to access relational databases. Quarkus provides a unified configuration model to define datasources for Java Database Connectivity (JDBC) and Reactive database drivers. -Quarkus uses link:https://agroal.github.io/[Agroal] and link:https://vertx.io/[Vert.x] to provide high-performance, scaleable data source connection pooling for JDBC and reactive drivers. +Quarkus uses link:https://agroal.github.io/[Agroal] and link:https://vertx.io/[Vert.x] to provide high-performance, scalable data source connection pooling for JDBC and reactive drivers. The `jdbc-\*` and `reactive-*` extensions provide build time optimizations and integrate configured data sources with Quarkus features like security, health checks, and metrics. -For more information on consuming and using a reactive datasource, consult the Quarkus xref:reactive-sql-clients.adoc[Reactive SQL clients] guide. +For more information about consuming and using a reactive datasource, see the Quarkus xref:reactive-sql-clients.adoc[Reactive SQL clients] guide. Additionally, refer to the Quarkus xref:hibernate-orm.adoc[Hibernate ORM] guide for information on consuming and using a JDBC datasource. -//// -Future references to all other parts of this doc. -//// - == Get started with configuring `datasources` in Quarkus For rapid configuration of datasources, this section offers a brief overview and code samples for testing and utilization, suitable for users familiar with the fundamentals. -For more advanced configuration with examples, see xref:datasource-reference[Datasource references]. +For more advanced configuration with examples, see <>. [[dev-services]] === Zero-config setup in development mode -Quarkus simplifies database configuration by offering the Dev Services feature, enabling zero-config database setup for testing or running in dev mode. +Quarkus simplifies database configuration by offering the Dev Services feature, enabling zero-config database setup for testing or running in development (dev) mode. In dev mode, the suggested approach is to use DevServices and let Quarkus handle the database for you, whereas for production mode, you provide explicit database configuration details pointing to a database managed outside of Quarkus. To use Dev Services, add the appropriate driver extension, such as `jdbc-postgresql`, for your desired database type to the `pom.xml` file. -In Dev mode, if you do not provide any explicit database connection details, Quarkus automatically handles the database setup and provides the wiring between the application and the database. +In dev mode, if you do not provide any explicit database connection details, Quarkus automatically handles the database setup and provides the wiring between the application and the database. + If you provide user credentials, the underlying database will be configured to use them. This is useful if you want to connect to the database with an external tool. To utilize this feature, ensure a Docker or Podman container runtime is installed, depending on the database type. Certain databases, such as H2, operate in in-memory mode and do not require a container runtime. -TIP: Prefix the actual connection details for Prod mode with `%prod.` to ensure they are not applied in Dev mode. For more information, see the xref:config-reference.adoc#profiles[Profiles] section of the xref:config-reference.adoc[Configuration reference] guide. +TIP: Prefix the actual connection details for prod mode with `%prod.` to ensure they are not applied in dev mode. +For more information, see the xref:config-reference.adoc#profiles[Profiles] section of the "Configuration reference" guide. For more information about Dev Services, see xref:dev-services.adoc[Dev Services overview]. @@ -85,7 +83,17 @@ quarkus.datasource.jdbc.max-size=16 <1> This configuration value is only required if there is more than one database extension on the classpath. If only one viable extension is available, Quarkus assumes this is the correct one. -If a driver has been added to the test scope, Quarkus automatically includes the driver in testing. +When you add a driver to the test scope, Quarkus automatically includes the specified driver in testing. + +==== JDBC connection pool size adjustment + +To protect your database from overloading during load peaks, size the pool adequately to throttle the database load. +The optimal pool size depends on many factors, such as the number of parallel application users or the nature of the workload. + +Be aware that setting the pool size too low might cause some requests to time out while waiting for a connection. + +For more information about pool size adjustment properties, see the <> section. + === Configure a reactive datasource @@ -175,7 +183,6 @@ JDBC is the most common database connection pattern, typically needed when used .. For use with a built-in JDBC driver, choose and add the Quarkus extension for your relational database driver from the list below: + - * Derby - `jdbc-derby` * H2 - `jdbc-h2` + @@ -206,6 +213,7 @@ Using a built-in JDBC driver extension automatically includes the Agroal extensi However, for custom drivers, Agroal needs to be added explicitly. ==== + .. For use with a custom JDBC driver, add the `quarkus-agroal` dependency to your project alongside the extension for your relational database driver: + [source,bash] @@ -236,7 +244,8 @@ For more information about configuring JDBC, see <> section. + + ==== JDBC and reactive datasources simultaneously When a JDBC extension - along with Agroal - and a reactive datasource extension handling the given database kind are included, they will both be created by default. @@ -421,7 +438,7 @@ Conversely, setting `quarkus.datasource.jdbc.enable-metrics` to `true`, or `quar This can be useful if you need to access the collected metrics programmatically. They are available after calling `dataSource.getMetrics()` on an injected `AgroalDataSource` instance. -If the metrics collection for this datasource is disabled, all values result to zero. +If the metrics collection for this datasource is disabled, all values result in zero. === Narayana transaction manager integration @@ -429,7 +446,7 @@ Integration is automatic if the Narayana JTA extension is also available. You can override this by setting the `transactions` configuration property: -* `quarkus.datasource.jdbc.transactions` for default unnamend datasource +* `quarkus.datasource.jdbc.transactions` for default unnamed datasource * `quarkus.datasource.__.jdbc.transactions` for named datasource For more information, see the <> section below. @@ -450,19 +467,17 @@ Some databases like H2 and Derby are commonly used in the _embedded mode_ as a f The recommended approach is to use the real database you intend to use in production, especially when xref:databases-dev-services.adoc[Dev Services provide a zero-config database for testing], and running tests against a container is relatively quick and produces expected results on an actual environment. However, it is also possible to use JVM-powered databases for scenarios when the ability to run simple integration tests is required. -NOTE: While configuring Derby to use the embedded engine works as usual in JVM mode, such an application will not compile into a native executable. It is because Quarkus Derby extensions do not support embedding the entire database engine into a native executable, and it only covers making the JDBC client code compatible with the native compilation step. ==== Support and limitations Embedded databases (H2 and Derby) work in JVM mode. For native mode, the following limitations apply: -* Derby cannot be embedded into the application in native mode, and only remote connection is supported. -[IMPORTANT] -==== -Embedding H2 within your native image is not recommended. +* Derby cannot be embedded into the application in native mode. +However, the Quarkus Derby extension allows native compilation of the Derby JDBC *client*, supporting *remote* connections. + +* Embedding H2 within your native image is not recommended. Consider using an alternative approach, for example, using a remote connection to a separate database instead. -==== ==== Run an integration test diff --git a/docs/src/main/asciidoc/hibernate-reactive.adoc b/docs/src/main/asciidoc/hibernate-reactive.adoc index 23f984c8737ae..e3afb738ca620 100644 --- a/docs/src/main/asciidoc/hibernate-reactive.adoc +++ b/docs/src/main/asciidoc/hibernate-reactive.adoc @@ -4,10 +4,11 @@ and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// = Using Hibernate Reactive - include::_attributes.adoc[] :config-file: application.properties :reactive-doc-url-prefix: https://hibernate.org/reactive/documentation/1.1/reference/html_single/#getting-started +:extension-status: preview + link:https://hibernate.org/reactive/[Hibernate Reactive] is a reactive API for Hibernate ORM, supporting non-blocking database drivers and a reactive style of interaction with the database. @@ -19,6 +20,8 @@ xref:hibernate-orm.adoc[Hibernate ORM guide]. This guide will only focus on what for Hibernate Reactive. ==== +include::{includes}/extension-status.adoc[] + == Solution We recommend that you follow the instructions in the next sections and create the application step by step. diff --git a/docs/src/main/asciidoc/logging.adoc b/docs/src/main/asciidoc/logging.adoc index a25f8d88588c9..1754ca8a8b1eb 100644 --- a/docs/src/main/asciidoc/logging.adoc +++ b/docs/src/main/asciidoc/logging.adoc @@ -16,7 +16,7 @@ Quarkus supports the JBoss Logging API as well as multiple other logging APIs, s You can use any of the <>: * link:https://github.com/jboss-logging/jboss-logging[JBoss Logging] -* JDK `java.util.logging` (JUL) +* link:https://docs.oracle.com/en/java/javase/11/docs/api/java.logging/java/util/logging/package-summary.html[JDK `java.util.logging` (JUL)] * link:https://www.slf4j.org/[SLF4J] * link:https://commons.apache.org/proper/commons-logging/[Apache Commons Logging] * link:https://logging.apache.org/log4j/2.x/[Apache Log4j 2] @@ -241,13 +241,35 @@ All potential properties are listed in the <>. +.An example of a global configuration that applies to all categories: +==== +[source, properties] +---- +quarkus.log.handlers=console,mylog +---- + +In this example, the root category is configured to use two handlers: `console` and `mylog`. +==== + +.An example of a per-category configuration: +==== +[source, properties] +---- +quarkus.log.category."org.apache.kafka.clients".level=INFO +quarkus.log.category."org.apache.kafka.common.utils".level=INFO +---- + +This example shows how you can configure the minimal log level on the categories `org.apache.kafka.clients` and `org.apache.kafka.common.utils`. +==== + +For more information, see <>. If you want to configure something extra for a specific category, create a named handler like `quarkus.log.handler.[console|file|syslog]..*` and set it up for that category by using `quarkus.log.category..handlers`. diff --git a/docs/src/main/asciidoc/security-architecture.adoc b/docs/src/main/asciidoc/security-architecture.adoc index f74b2e68a47a2..ef3bcebd2dffa 100644 --- a/docs/src/main/asciidoc/security-architecture.adoc +++ b/docs/src/main/asciidoc/security-architecture.adoc @@ -73,11 +73,11 @@ You can customize the following core security components of Quarkus: * `IdentityProvider` * `SecurityidentityAugmentor` -For more information about customizing Quarkus Security, including reactive security and how to register a security provider, see the Quarkus link:{url-quarkusio-guides}security-customization[Security tips and tricks] guide. +For more information about customizing Quarkus Security, including reactive security and how to register a security provider, see the Quarkus xref:security-customization.adoc[Security tips and tricks] guide. == References * xref:security-overview.adoc[Quarkus Security overview] * xref:security-authentication-mechanisms.adoc#other-supported-authentication-mechanisms[Other supported authentication mechanisms] * xref:security-identity-providers.adoc[Identity providers] -* xref:security-authorize-web-endpoints-reference.adoc[Authorization of web endpoints] \ No newline at end of file +* xref:security-authorize-web-endpoints-reference.adoc[Authorization of web endpoints] diff --git a/docs/src/main/asciidoc/security-authentication-mechanisms.adoc b/docs/src/main/asciidoc/security-authentication-mechanisms.adoc index f03870b451659..c2148ce5b858f 100644 --- a/docs/src/main/asciidoc/security-authentication-mechanisms.adoc +++ b/docs/src/main/asciidoc/security-authentication-mechanisms.adoc @@ -150,7 +150,7 @@ X509Certificate certificate = credential.getCertificate(); The information from the client certificate can be used to enhance Quarkus `SecurityIdentity`. For example, you can add new roles after checking a client certificate subject name, and so on. -For more information about customizing `SecurityIdentity`, see the link:{url-quarkusio-guides}security-customization#security-identity-customization[Security identity customization] section in the Quarkus "Security tips and tricks" guide. +For more information about customizing `SecurityIdentity`, see the xref:security-customization.adoc#security-identity-customization[Security identity customization] section in the Quarkus "Security tips and tricks" guide. [[other-supported-authentication-mechanisms]] == Other supported authentication mechanisms @@ -208,7 +208,7 @@ For more information about OIDC authentication and authorization methods that yo To enable the Quarkus OIDC extension at runtime, set `quarkus.oidc.tenant-enabled=false` at build time. Then re-enable it at runtime by using a system property. -For more information about managing the individual tenant configurations in multitenant OIDC deployments, see the link:{url-quarkusio-guides}security-openid-connect-multitenancy#disable-tenant[Disabling tenant configurations] section in the "Using OpenID Connect (OIDC) multi-tenancy" guide. +For more information about managing the individual tenant configurations in multitenant OIDC deployments, see the xref:security-openid-connect-multitenancy.adoc#disable-tenant[Disabling tenant configurations] section in the "Using OpenID Connect (OIDC) multi-tenancy" guide. ==== ==== OpenID Connect client and filters diff --git a/docs/src/main/asciidoc/security-basic-authentication-howto.adoc b/docs/src/main/asciidoc/security-basic-authentication-howto.adoc index b58298fa1a9f2..2f620a217c871 100644 --- a/docs/src/main/asciidoc/security-basic-authentication-howto.adoc +++ b/docs/src/main/asciidoc/security-basic-authentication-howto.adoc @@ -8,7 +8,7 @@ Enable xref:security-basic-authentication.adoc[Basic authentication] for your Qu == Prerequisites -* You have installed at least one extension that provides an `IdentityProvider` based on username and password, such as link:{url-quarkusio-guides}security-jdbc[Elytron JDBC]. +* You have installed at least one extension that provides an `IdentityProvider` based on username and password, such as xref:security-jdbc.adoc[Elytron JDBC]. == Procedure diff --git a/docs/src/main/asciidoc/security-oidc-bearer-token-authentication-tutorial.adoc b/docs/src/main/asciidoc/security-oidc-bearer-token-authentication-tutorial.adoc index af89c72b431a0..8921ec8696429 100644 --- a/docs/src/main/asciidoc/security-oidc-bearer-token-authentication-tutorial.adoc +++ b/docs/src/main/asciidoc/security-oidc-bearer-token-authentication-tutorial.adoc @@ -9,84 +9,105 @@ include::_attributes.adoc[] :diataxis-type: tutorial :categories: security -Here, you use the Quarkus OpenID Connect (OIDC) extension to secure a Jakarta REST application using Bearer token authentication. +Use the Quarkus OpenID Connect (OIDC) extension to secure a Jakarta REST application with Bearer token authentication. The bearer tokens are issued by OIDC and OAuth 2.0 compliant authorization servers, such as link:https://www.keycloak.org[Keycloak]. -To better understand OIDC Bearer token authentication, see xref:security-oidc-bearer-token-authentication.adoc[OIDC Bearer token authentication]. +For more information about OIDC Bearer token authentication, see the Quarkus xref:security-oidc-bearer-token-authentication.adoc[OpenID Connect (OIDC) Bearer token authentication] guide. -If you want to protect web applications by using OIDC Authorization Code Flow authentication, see xref:security-oidc-code-flow-authentication-concept.adoc[OIDC authorization code flow authentication]. +If you want to protect web applications by using OIDC Authorization Code Flow authentication, see the xref:security-oidc-code-flow-authentication.adoc[OpenID Connect authorization code flow mechanism for protecting web applications] guide. == Prerequisites :prerequisites-docker: include::{includes}/prerequisites.adoc[] -* https://stedolan.github.io/jq/[jq tool] +* The https://stedolan.github.io/jq/[jq command-line processor tool] == Architecture -In this example, we build a simple microservice which offers two endpoints: +This example shows how you can build a simple microservice that offers two endpoints: * `/api/users/me` * `/api/admin` -These endpoints are protected and can only be accessed if a client is sending a bearer token along with the request, which must be valid (e.g.: signature, expiration and audience) and trusted by the microservice. +These endpoints are protected and can only be accessed if a client sends a bearer token along with the request, which must be valid (for example, signature, expiration, and audience) and trusted by the microservice. -The bearer token is issued by a Keycloak Server and represents the subject to which the token was issued for. For being an OAuth 2.0 Authorization Server, the token also references the client acting on behalf of the user. +The bearer token is issued by a Keycloak server and represents the subject for which the token was issued. +Because it is an OAuth 2.0 Authorization server, the token also references the client acting on the user's behalf. -The `/api/users/me` endpoint can be accessed by any user with a valid token. As a response, it returns a JSON document with details about the user where these details are obtained from the information carried on the token. +Any user with a valid token can access the `/api/users/me` endpoint. +As a response, it returns a JSON document with user details obtained from the information in the token. -The `/api/admin` endpoint is protected with RBAC (Role-Based Access Control) where only users granted with the `admin` role can access. At this endpoint, we use the `@RolesAllowed` annotation to declaratively enforce the access constraint. +The `/api/admin` endpoint is protected with RBAC (Role-Based Access Control), which only users with the `admin` role can access. +At this endpoint, the `@RolesAllowed` annotation is used to enforce the access constraint declaratively. == Solution -We recommend that you follow the instructions in the next sections and create the application step by step. -However, you can go right to the completed example. +Follow the instructions in the next sections and create the application step by step. +You can also go straight to the completed example. -Clone the Git repository: `git clone {quickstarts-clone-url}`, or download an {quickstarts-archive-url}[archive]. +You can clone the Git repository by running the command `git clone {quickstarts-clone-url}`, or you can download an {quickstarts-archive-url}[archive]. The solution is located in the `security-openid-connect-quickstart` link:{quickstarts-tree-url}/security-openid-connect-quickstart[directory]. == Procedure +:sectnums: +:sectnumlevels: 3 === Create the Maven project -First, we need a new project. Create a new project with the following command: +You can either create a new Maven project with the `oidc` extension or you can add the extension to an existing Maven project. +Complete one of the following commands: +* To create a new Maven project, use the following command: ++ +==== :create-app-artifact-id: security-openid-connect-quickstart :create-app-extensions: oidc,resteasy-reactive-jackson include::{includes}/devtools/create-app.adoc[] - +==== This command generates a Maven project, importing the `oidc` extension which is an implementation of OIDC for Quarkus. -If you already have your Quarkus project configured, you can add the `oidc` extension +* If you already have your Quarkus project configured, you can add the `oidc` extension to your project by running the following command in your project base directory: - ++ +==== :add-extension-extensions: oidc include::{includes}/devtools/extension-add.adoc[] +==== +The following configuration gets added to your build file: -This will add the following to your build file: - +* Using Maven (pom.xml): ++ +==== +-- [source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"] -.pom.xml ---- io.quarkus quarkus-oidc ---- - +-- +==== ++ +* Using Gradle (build.gradle): ++ +==== +-- [source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"] -.build.gradle ---- implementation("io.quarkus:quarkus-oidc") ---- +-- +==== === Write the application -Let's start by implementing the `/api/users/me` endpoint. As you can see from the source code below it is just a regular Jakarta REST resource: - +. Implement the `/api/users/me` endpoint as shown in the following example, which is a regular Jakarta REST resource: ++ +==== [source,java] ---- package org.acme.security.openid.connect; @@ -127,9 +148,10 @@ public class UsersResource { } } ---- - -The source code for the `/api/admin` endpoint is also very simple. The main difference here is that we are using a `@RolesAllowed` annotation to make sure that only users granted with the `admin` role can access the endpoint: - +==== +. Implement the `/api/admin` endpoint as shown in the following simple example: ++ +==== [source,java] ---- package org.acme.security.openid.connect; @@ -151,13 +173,20 @@ public class AdminResource { } } ---- +==== ++ +[NOTE] +==== +The main difference in this example is that the `@RolesAllowed` annotation is used to verify that only users granted the `admin` role can access the endpoint. +==== Injection of the `SecurityIdentity` is supported in both `@RequestScoped` and `@ApplicationScoped` contexts. === Configure the application -Configure the Quarkus OpenID Connect (OIDC) extension by setting the following configuration properties in the `src/main/resources/application.properties` file. - +* Configure the Quarkus OpenID Connect (OIDC) extension by setting the following configuration properties in the `src/main/resources/application.properties` file. ++ +==== [source,properties] ---- %prod.quarkus.oidc.auth-server-url=http://localhost:8180/realms/quarkus @@ -169,107 +198,127 @@ quarkus.oidc.credentials.secret=secret quarkus.keycloak.devservices.realm-path=quarkus-realm.json ---- +==== Where: -* `%prod.quarkus.oidc.auth-server-url` sets the base URL of the OpenID Connect (OIDC) server. The `%prod.` profile prefix ensures that `Dev Services for Keycloak` launches a container when you run the application in dev mode. -See xref:keycloak-dev-mode[Running the Application in Dev mode] section below for more information. -* `quarkus.oidc.client-id` sets a client-id that identifies the application. +* `%prod.quarkus.oidc.auth-server-url` sets the base URL of the OpenID Connect (OIDC) server. +The `%prod.` profile prefix ensures that `Dev Services for Keycloak` launches a container when you run the application in development (dev) mode. +For more information, see the <> section. + +* `quarkus.oidc.client-id` sets a client-ID that identifies the application. * `quarkus.oidc.credentials.secret` sets the client secret, which is used by the `client_secret_basic` authentication method. -For more information, see xref:security-openid-connect-oidc-configuration-properties-reference.adoc[OpenID Connect (OIDC) configuration properties]. +For more information, see the Quarkus xref:security-oidc-configuration-properties-reference.adoc[OpenID Connect (OIDC) configuration properties] guide. -=== Start and configure the Keycloak server -Before you start with configuration, put the link:{quickstarts-tree-url}/security-openid-connect-quickstart/config/quarkus-realm.json[realm configuration file] on the classpath (`target/classes` directory) to import it automatically when running in dev mode - unless you have already built a link:{quickstarts-tree-url}/security-openid-connect-quickstart[complete solution]. -In this case, the realm file is added to the classpath during the build. +=== Start and configure the Keycloak server +. Put the link:{quickstarts-tree-url}/security-openid-connect-quickstart/config/quarkus-realm.json[realm configuration file] on the classpath (`target/classes` directory) so that it gets imported automatically when running in dev mode. +You do not need to do this if you have already built a link:{quickstarts-tree-url}/security-openid-connect-quickstart[complete solution], in which case, this realm file is added to the classpath during the build. ++ [NOTE] ==== -Do not start the Keycloak server when you run the application in a dev mode - `Dev Services for Keycloak` will launch a container. -See the xref:keycloak-dev-mode[Running the Application in Dev mode] section below for more information. +Do not start the Keycloak server when you run the application in dev mode; `Dev Services for Keycloak` will start a container. +For more information, see the <> section. +==== ++ +. To start a Keycloak server, you can use Docker to run the following command: ++ ==== - -To start a Keycloak Server, you can use Docker and just run the following command: - [source,bash,subs=attributes+] ---- docker run --name keycloak -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin -p 8180:8080 quay.io/keycloak/keycloak:{keycloak.version} start-dev ---- +==== +* Where the `keycloak.version` is set to version `17.0.0` or later. +. You can access your Keycloak Server at http://localhost:8180[localhost:8180]. +. To access the Keycloak Administration Console, log in as the `admin` user by using the following login credentials: -where `keycloak.version` should be set to `17.0.0` or higher. - -You should be able to access your Keycloak Server at http://localhost:8180[localhost:8180]. - -Log in as the `admin` user to access the Keycloak Administration Console. Username should be `admin` and password `admin`. +* Username: `admin` +* Password: `admin` -Import the link:{quickstarts-tree-url}/security-openid-connect-quickstart/config/quarkus-realm.json[realm configuration file] to create a new realm. -For more details, see the Keycloak documentation about how to link:https://www.keycloak.org/docs/latest/server_admin/index.html#_create-realm[create a new realm]. +. Import the link:{quickstarts-tree-url}/security-openid-connect-quickstart/config/quarkus-realm.json[realm configuration file] from the upstream community repository to create a new realm. -NOTE: If you want to use the Keycloak Admin Client to configure your server from your application, include the -either `quarkus-keycloak-admin-client` or the `quarkus-keycloak-admin-client-reactive` (if the application uses `quarkus-rest-client-reactive`) extension. -See the xref:security-keycloak-admin-client.adoc[Quarkus Keycloak Admin Client] guide for more information. +For more information, see the Keycloak documentation about link:https://www.keycloak.org/docs/latest/server_admin/index.html#_create-realm[creating a new realm]. -[[keycloak-dev-mode]] -=== Run the application in Dev mode -To run the application in a dev mode, use: +[NOTE] +==== +If you want to use the Keycloak Admin Client to configure your server from your application, you need to include either the `quarkus-keycloak-admin-client` or the `quarkus-keycloak-admin-client-reactive` (if the application uses `quarkus-rest-client-reactive`) extension. +For more information, see the link:{url-quarkusio-guides}security-keycloak-admin-client[Quarkus Keycloak Admin Client] guide. -include::{includes}/devtools/dev.adoc[] +==== -xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak] will launch a Keycloak container and import a `quarkus-realm.json`. -Open a xref:dev-ui.adoc[Dev UI] available at http://localhost:8080/q/dev-v1[/q/dev-v1] and click on a `Provider: Keycloak` link in an `OpenID Connect` `Dev UI` card. +[[keycloak-dev-mode]] +=== Run the application in dev mode -You will be asked to log in into a `Single Page Application` provided by `OpenID Connect Dev UI`: +. To run the application in dev mode, run the following commands: ++ +==== +include::{includes}/devtools/dev.adoc[] +==== +* link:{quarkusio-guides}/security-openid-connect-dev-services[Dev Services for Keycloak] will start a Keycloak container and import a `quarkus-realm.json`. +. Open a link:{url-quarkusio-guides}dev-ui[Dev UI], which you can find at http://localhost:8080/q/dev-v1[/q/dev-v1], then click a `Provider: Keycloak` link in an `OpenID Connect` `Dev UI` card. +. When prompted to log in to a `Single Page Application` provided by `OpenID Connect Dev UI`, do the following steps: - * Login as `alice` (password: `alice`) who has a `user` role - ** accessing `/api/admin` will return `403` - ** accessing `/api/users/me` will return `200` - * Logout and login as `admin` (password: `admin`) who has both `admin` and `user` roles - ** accessing `/api/admin` will return `200` - ** accessing `/api/users/me` will return `200` + * Log in as `alice` (password: `alice`), who has a `user` role. + ** Accessing `/api/admin` returns `403`. + ** Accessing `/api/users/me` returns `200`. + * Log out and log in as `admin` (password: `admin`), who has both `admin` and `user` roles. + ** Accessing `/api/admin` returns `200`. + ** Accessing `/api/users/me` returns `200`. === Run the Application in JVM mode -When you're done playing with the `dev` mode" you can run it as a standard Java application. - -First compile it: +When you are done with dev mode, you can run the application as a standard Java application. +. Compile the application: ++ +==== include::{includes}/devtools/build.adoc[] - -Then run it: - +==== +. Run the application: ++ +==== [source,bash] ---- java -jar target/quarkus-app/quarkus-run.jar ---- +==== -=== Run the application in Native mode +=== Run the application in native mode -This same demo can be compiled into native code: no modifications required. +You can compile this same demo as-is into native mode without needing any modifications. +This implies that you no longer need to install a JVM on your production environment. +The runtime technology is included in the produced binary and optimized to run with minimal resources required. -This implies that you no longer need to install a JVM on your production environment, as the runtime technology is included in the produced binary, and optimized to run with minimal resource overhead. +Compilation takes a bit longer, so this step is disabled by default. -Compilation will take a bit longer, so this step is disabled by default; -let's build again by enabling the `native` profile: +. Build your application again by enabling the `native` profile: ++ +==== include::{includes}/devtools/build-native.adoc[] - -After getting a cup of coffee, you'll be able to run this binary directly: - +==== +. After waiting a little while, you run the following binary directly: ++ +==== [source,bash] ---- ./target/security-openid-connect-quickstart-1.0.0-SNAPSHOT-runner ---- +==== === Test the application -See the <> section above about testing your application in a dev mode. +For information about testing your application in dev mode, see the preceding <> section. You can test the application launched in JVM or Native modes with `curl`. -The application is using Bearer token authentication and the first thing to do is obtain an access token from the Keycloak Server in order to access the application resources: +* Because the application uses Bearer token authentication, you first need to obtain an access token from the Keycloak server to access the application resources: +==== [source,bash] ---- @@ -280,10 +329,11 @@ export access_token=$(\ -d 'username=alice&password=alice&grant_type=password' | jq --raw-output '.access_token' \ ) ---- +==== -The example above obtains an access token for user `alice`. +The preceding example obtains an access token for the user `alice`. -Any user is allowed to access the `http://localhost:8080/api/users/me` endpoint, which basically returns a JSON payload with details about the user. +* Any user can access the `http://localhost:8080/api/users/me` endpoint, which returns a JSON payload with details about the user. [source,bash] ---- @@ -292,8 +342,8 @@ curl -v -X GET \ -H "Authorization: Bearer "$access_token ---- -The `http://localhost:8080/api/admin` endpoint can only be accessed by users with the `admin` role. -If you try to access this endpoint with the previously issued access token, you should get a `403` response from the server. +* Only users with the `admin` role can access the `http://localhost:8080/api/admin` endpoint. +If you try to access this endpoint with the previously-issued access token, you get a `403` response from the server. [source,bash] ---- @@ -302,7 +352,7 @@ curl -v -X GET \ -H "Authorization: Bearer "$access_token ---- -In order to access the admin endpoint, you should obtain a token for the `admin` user: +* To access the admin endpoint, obtain a token for the `admin` user: [source,bash] ---- @@ -314,12 +364,14 @@ export access_token=$(\ ) ---- -Please also see the xref:security-oidc-bearer-token-authentication.adoc#integration-testing-keycloak-devservices[OIDC Bearer token authentication, Dev Services for Keycloak] section, about writing the integration tests which depend on `Dev Services for Keycloak`. +For information about writing integration tests that depend on `Dev Services for Keycloak`, see the xref:security-oidc-bearer-token-authentication.adoc#integration-testing-keycloak-devservices[Dev Services for Keycloak] section of the "OpenID Connect (OIDC) Bearer token authentication" guide. + +:sectnums!: == References * xref:security-oidc-configuration-properties-reference.adoc[OIDC configuration properties] -* xref:security-oidc-bearer-token-authentication.adoc[OIDC Bearer token authentication] +* xref:security-oidc-bearer-token-authentication.adoc[OpenID Connect (OIDC) Bearer token authentication] * link:https://www.keycloak.org/documentation.html[Keycloak Documentation] * link:https://openid.net/connect/[OpenID Connect] * link:https://tools.ietf.org/html/rfc7519[JSON Web Token] @@ -327,5 +379,5 @@ Please also see the xref:security-oidc-bearer-token-authentication.adoc#integrat * xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak] * xref:security-jwt-build.adoc[Sign and encrypt JWT tokens with SmallRye JWT Build] * xref:security-authentication-mechanisms.adoc#combining-authentication-mechanisms[Combining authentication mechanisms] -* xref:security-overview.adoc[Quarkus Security] +* xref:security-overview.adoc[Quarkus Security overview] * xref:security-keycloak-admin-client.adoc[Quarkus Keycloak Admin Client] diff --git a/extensions/azure-functions/deployment/src/main/java/io/quarkus/azure/functions/deployment/AzureFunctionsConfig.java b/extensions/azure-functions/deployment/src/main/java/io/quarkus/azure/functions/deployment/AzureFunctionsConfig.java index 049684836a21d..7e324cbee2d0b 100644 --- a/extensions/azure-functions/deployment/src/main/java/io/quarkus/azure/functions/deployment/AzureFunctionsConfig.java +++ b/extensions/azure-functions/deployment/src/main/java/io/quarkus/azure/functions/deployment/AzureFunctionsConfig.java @@ -70,6 +70,7 @@ public class AzureFunctionsConfig { /** * Specifies the instrumentation key of application insights which will bind to your function app */ + @ConfigItem public Optional appInsightsKey; public RuntimeConfig runtime; @@ -85,15 +86,18 @@ public class AzureFunctionsConfig { /** * */ + @ConfigItem public Optional appServicePlanResourceGroup; /** * Azure subscription id. Required only if there are more than one subscription in your account */ + @ConfigItem public Optional subscriptionId; /** * */ + @ConfigItem public Optional pricingTier; /** @@ -233,6 +237,7 @@ public static class AuthConfig { /** * Filesystem path to properties file if using file type */ + @ConfigItem public Optional path; /** diff --git a/extensions/container-image/container-image-docker/deployment/src/main/java/io/quarkus/container/image/docker/deployment/DockerConfig.java b/extensions/container-image/container-image-docker/deployment/src/main/java/io/quarkus/container/image/docker/deployment/DockerConfig.java index fa13ce661509e..cf06381a8aca5 100644 --- a/extensions/container-image/container-image-docker/deployment/src/main/java/io/quarkus/container/image/docker/deployment/DockerConfig.java +++ b/extensions/container-image/container-image-docker/deployment/src/main/java/io/quarkus/container/image/docker/deployment/DockerConfig.java @@ -49,6 +49,7 @@ public class DockerConfig { /** * The networking mode for the RUN instructions during build */ + @ConfigItem public Optional network; /** diff --git a/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourceRuntimeConfig.java b/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourceRuntimeConfig.java index d22a84034e54f..a2e4d4ee5c6c7 100644 --- a/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourceRuntimeConfig.java +++ b/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourceRuntimeConfig.java @@ -32,10 +32,11 @@ public class DataSourceRuntimeConfig { /** * The credentials provider bean name. *

- * It is the {@code @Named} value of the credentials provider bean. It is used to discriminate if multiple - * CredentialsProvider beans are available. + * This is a bean name (as in {@code @Named}) of a bean that implements {@code CredentialsProvider}. + * It is used to select the credentials provider bean when multiple exist. + * This is unnecessary when there is only one credentials provider available. *

- * For Vault it is: vault-credentials-provider. Not necessary if there is only one credentials provider available. + * For Vault, the credentials provider bean name is {@code vault-credentials-provider}. */ @ConfigItem @ConvertWith(TrimmedStringConverter.class) diff --git a/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourcesBuildTimeConfig.java b/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourcesBuildTimeConfig.java index 9cd6144e4b62b..c80cac6d66bdd 100644 --- a/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourcesBuildTimeConfig.java +++ b/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DataSourcesBuildTimeConfig.java @@ -29,7 +29,7 @@ public class DataSourcesBuildTimeConfig { public Map namedDataSources; /** - * Whether or not an health check is published in case the smallrye-health extension is present. + * Whether or not a health check is published in case the smallrye-health extension is present. *

* This is a global setting and is not specific to a datasource. */ diff --git a/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DevServicesBuildTimeConfig.java b/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DevServicesBuildTimeConfig.java index d06573c422c20..a4e7038d83851 100644 --- a/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DevServicesBuildTimeConfig.java +++ b/extensions/datasource/runtime/src/main/java/io/quarkus/datasource/runtime/DevServicesBuildTimeConfig.java @@ -11,19 +11,19 @@ public class DevServicesBuildTimeConfig { /** - * If DevServices has been explicitly enabled or disabled. DevServices is generally enabled - * by default, unless there is an existing configuration present. + * If DevServices has been explicitly enabled or disabled. + * DevServices is generally enabled by default unless an existing configuration is present. * - * When DevServices is enabled Quarkus will attempt to automatically configure and start - * a database when running in Dev or Test mode. + * When DevServices is enabled, Quarkus will attempt to automatically configure and start a database when running in Dev or + * Test mode. */ @ConfigItem public Optional enabled = Optional.empty(); /** - * The container image name to use, for container based DevServices providers. + * The container image name for container-based DevServices providers. * - * If the provider is not container based (e.g. a H2 Database) then this has no effect. + * This has no effect if the provider is not a container-based database, such as H2 or Derby. */ @ConfigItem public Optional imageName; @@ -37,8 +37,8 @@ public class DevServicesBuildTimeConfig { /** * Generic properties that are passed for additional container configuration. *

- * Properties defined here are database specific and are interpreted specifically in each database dev service - * implementation. + * Properties defined here are database-specific + * and are interpreted specifically in each database dev service implementation. */ @ConfigItem public Map containerProperties; @@ -58,15 +58,15 @@ public class DevServicesBuildTimeConfig { public OptionalInt port; /** - * The container start command to use, for container based DevServices providers. + * The container start command to use for container-based DevServices providers. * - * If the provider is not container based (e.g. a H2 Database) then this has no effect. + * This has no effect if the provider is not a container-based database, such as H2 or Derby. */ @ConfigItem public Optional command; /** - * The name of the database to use if this Dev Service supports overriding it. + * The database name to use if this Dev Service supports overriding it. */ @ConfigItem public Optional dbName; @@ -84,22 +84,23 @@ public class DevServicesBuildTimeConfig { public Optional password; /** - * Path to a SQL script that will be loaded from the classpath and applied to the Dev Service database + * The path to a SQL script to be loaded from the classpath and applied to the Dev Service database. * - * If the provider is not container based (e.g. an H2 or Derby Database) then this has no effect. + * This has no effect if the provider is not a container-based database, such as H2 or Derby. */ @ConfigItem public Optional initScriptPath; /** - * The volumes to be mapped to the container. The map key corresponds to the host location and the map value is the - * container location. If the host location starts with "classpath:", then the mapping will load the resource from the - * classpath with read-only permission. + * The volumes to be mapped to the container. + * The map key corresponds to the host location; the map value is the container location. + * If the host location starts with "classpath:", + * the mapping loads the resource from the classpath with read-only permission. * - * When using a file system location, the volume will be created with read-write permission, so the data in your file - * system might be wiped out or altered. + * When using a file system location, the volume will be generated with read-write permission, + * potentially leading to data loss or modification in your file system. * - * If the provider is not container based (e.g. an H2 or Derby Database) then this has no effect. + * This has no effect if the provider is not a container-based database, such as H2 or Derby. */ @ConfigItem public Map volumes; diff --git a/extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmConfigPersistenceUnit.java b/extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmConfigPersistenceUnit.java index 7462c4b1308c9..be2da22d14f81 100644 --- a/extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmConfigPersistenceUnit.java +++ b/extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmConfigPersistenceUnit.java @@ -28,12 +28,14 @@ public class HibernateOrmConfigPersistenceUnit { *

* If undefined, it will use the default datasource. */ + @ConfigItem @ConvertWith(TrimmedStringConverter.class) public Optional datasource; /** * The packages in which the entities affected to this persistence unit are located. */ + @ConfigItem @ConvertWith(TrimmedStringConverter.class) public Optional> packages; @@ -195,6 +197,7 @@ public class HibernateOrmConfigPersistenceUnit { /** * Caching configuration */ + @ConfigItem @ConfigDocSection public Map cache; diff --git a/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientsBuildTimeConfig.java b/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientsBuildTimeConfig.java index d14a2dbc9fd29..c5e95b471c827 100644 --- a/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientsBuildTimeConfig.java +++ b/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientsBuildTimeConfig.java @@ -24,7 +24,7 @@ public class InfinispanClientsBuildTimeConfig { public Map namedInfinispanClients; /** - * Whether or not an health check is published in case the smallrye-health extension is present. + * Whether or not a health check is published in case the smallrye-health extension is present. *

* This is a global setting and is not specific to an Infinispan Client. */ diff --git a/extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/AutoScalingConfig.java b/extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/AutoScalingConfig.java index 303eb62c0a330..00ca52ebb69c1 100644 --- a/extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/AutoScalingConfig.java +++ b/extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/AutoScalingConfig.java @@ -4,6 +4,7 @@ import java.util.Optional; import io.quarkus.runtime.annotations.ConfigGroup; +import io.quarkus.runtime.annotations.ConfigItem; @ConfigGroup public class AutoScalingConfig { @@ -16,6 +17,7 @@ public class AutoScalingConfig { * * @return The autoscaler class. */ + @ConfigItem Optional autoScalerClass; /** @@ -24,6 +26,7 @@ public class AutoScalingConfig { * * @return The cpu metric or NONE if no metric has been selected. */ + @ConfigItem Optional metric; /** @@ -31,6 +34,7 @@ public class AutoScalingConfig { * * @return the selected target or zero if no target is selected. */ + @ConfigItem Optional target; /** @@ -39,10 +43,12 @@ public class AutoScalingConfig { * * @return the container concurrency, or zero if it is not bound. */ + @ConfigItem Optional containerConcurrency; /** * This value specifies a percentage of the target to actually be targeted by the autoscaler. */ + @ConfigItem Optional targetUtilizationPercentage; } diff --git a/extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/GlobalAutoScalingConfig.java b/extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/GlobalAutoScalingConfig.java index 1ad74874d6a0b..766b8cf83e596 100644 --- a/extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/GlobalAutoScalingConfig.java +++ b/extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/GlobalAutoScalingConfig.java @@ -3,6 +3,7 @@ import java.util.Optional; import io.quarkus.runtime.annotations.ConfigGroup; +import io.quarkus.runtime.annotations.ConfigItem; @ConfigGroup public class GlobalAutoScalingConfig { @@ -15,6 +16,7 @@ public class GlobalAutoScalingConfig { * * @return The autoscaler class. */ + @ConfigItem Optional autoScalerClass; /** @@ -25,16 +27,19 @@ public class GlobalAutoScalingConfig { * concurrency: Hard Limit * @return the container concurrency, or zero if it is not bound. */ + @ConfigItem Optional containerConcurrency; /** * This value specifies a percentage of the target to actually be targeted by the autoscaler. */ + @ConfigItem Optional targetUtilizationPercentage; /** * The requests per second per replica. */ + @ConfigItem Optional requestsPerSecond; } diff --git a/extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/KnativeConfig.java b/extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/KnativeConfig.java index 303fbe7edd86e..dd59b667f93f9 100644 --- a/extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/KnativeConfig.java +++ b/extensions/kubernetes/vanilla/deployment/src/main/java/io/quarkus/kubernetes/deployment/KnativeConfig.java @@ -473,11 +473,13 @@ public EnvVarsConfig getEnv() { /** * The name of the revision. */ + @ConfigItem Optional revisionName; /** * Traffic configuration. */ + @ConfigItem Map traffic; /** diff --git a/extensions/mongodb-client/runtime/src/main/java/io/quarkus/mongodb/runtime/CredentialConfig.java b/extensions/mongodb-client/runtime/src/main/java/io/quarkus/mongodb/runtime/CredentialConfig.java index 43bce59565cd7..8c38177b13952 100644 --- a/extensions/mongodb-client/runtime/src/main/java/io/quarkus/mongodb/runtime/CredentialConfig.java +++ b/extensions/mongodb-client/runtime/src/main/java/io/quarkus/mongodb/runtime/CredentialConfig.java @@ -37,7 +37,8 @@ public class CredentialConfig { /** * Configures the source of the authentication credentials. - * This is typically the database that the credentials have been created. The value defaults to the database + * This is typically the database where the credentials have been created. + * The value defaults to the database * specified in the path portion of the connection string or in the 'database' configuration property. * If the database is specified in neither place, the default value is {@code admin}. This option is only * respected when using the MONGO-CR mechanism (the default). @@ -61,10 +62,11 @@ public class CredentialConfig { /** * The credentials provider bean name. *

- * It is the {@code @Named} value of the credentials provider bean. It is used to discriminate if multiple - * CredentialsProvider beans are available. + * This is a bean name (as in {@code @Named}) of a bean that implements {@code CredentialsProvider}. + * It is used to select the credentials provider bean when multiple exist. + * This is unnecessary when there is only one credentials provider available. *

- * For Vault it is: vault-credentials-provider. Not necessary if there is only one credentials provider available. + * For Vault, the credentials provider bean name is {@code vault-credentials-provider}. */ @ConfigItem @ConvertWith(TrimmedStringConverter.class) diff --git a/extensions/smallrye-openapi-common/deployment/src/main/java/io/quarkus/smallrye/openapi/common/deployment/SmallRyeOpenApiConfig.java b/extensions/smallrye-openapi-common/deployment/src/main/java/io/quarkus/smallrye/openapi/common/deployment/SmallRyeOpenApiConfig.java index 59c333fc96e20..087b9dc7cf1cf 100644 --- a/extensions/smallrye-openapi-common/deployment/src/main/java/io/quarkus/smallrye/openapi/common/deployment/SmallRyeOpenApiConfig.java +++ b/extensions/smallrye-openapi-common/deployment/src/main/java/io/quarkus/smallrye/openapi/common/deployment/SmallRyeOpenApiConfig.java @@ -54,6 +54,7 @@ public final class SmallRyeOpenApiConfig { /** * Add a certain SecurityScheme with config */ + @ConfigItem public Optional securityScheme; /** diff --git a/extensions/smallrye-reactive-messaging-rabbitmq/deployment/src/main/java/io/quarkus/smallrye/reactivemessaging/rabbitmq/deployment/RabbitMQBuildTimeConfig.java b/extensions/smallrye-reactive-messaging-rabbitmq/deployment/src/main/java/io/quarkus/smallrye/reactivemessaging/rabbitmq/deployment/RabbitMQBuildTimeConfig.java index 553c6e3ff8425..2368c16e6e40e 100644 --- a/extensions/smallrye-reactive-messaging-rabbitmq/deployment/src/main/java/io/quarkus/smallrye/reactivemessaging/rabbitmq/deployment/RabbitMQBuildTimeConfig.java +++ b/extensions/smallrye-reactive-messaging-rabbitmq/deployment/src/main/java/io/quarkus/smallrye/reactivemessaging/rabbitmq/deployment/RabbitMQBuildTimeConfig.java @@ -10,7 +10,8 @@ public class RabbitMQBuildTimeConfig { /** - * Configuration for DevServices. DevServices allows Quarkus to automatically start a RabbitMQ broker in dev and test mode. + * Configuration for DevServices. + * DevServices allows Quarkus to start a RabbitMQ broker in dev and test mode automatically. */ @ConfigItem public RabbitMQDevServicesBuildTimeConfig devservices; @@ -24,10 +25,11 @@ public class RabbitMQBuildTimeConfig { /** * The credentials provider bean name. *

- * It is the {@code @Named} value of the credentials provider bean. It is used to discriminate if multiple - * CredentialsProvider beans are available. + * This is a bean name (as in {@code @Named}) of a bean that implements {@code CredentialsProvider}. + * It is used to select the credentials provider bean when multiple exist. + * This is unnecessary when there is only one credentials provider available. *

- * For Vault it is: vault-credentials-provider. Not necessary if there is only one credentials provider available. + * For Vault, the credentials provider bean name is {@code vault-credentials-provider}. */ @ConfigItem public Optional credentialsProviderName = Optional.empty(); diff --git a/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/CertificateConfig.java b/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/CertificateConfig.java index ede0b22e7e484..553e1f5840fe5 100644 --- a/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/CertificateConfig.java +++ b/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/CertificateConfig.java @@ -10,7 +10,8 @@ import io.quarkus.runtime.configuration.TrimmedStringConverter; /** - * A certificate configuration. Either the certificate and key files must be given, or a key store must be given. + * A certificate configuration. + * Provide either the certificate and key files or a keystore. */ @ConfigGroup @SuppressWarnings("OptionalUsedAsFieldOrParameterType") @@ -18,8 +19,8 @@ public class CertificateConfig { /** * The {@linkplain CredentialsProvider}. - * If this property is configured then a matching 'CredentialsProvider' will be used - * to get the keystore, keystore key and truststore passwords unless these passwords have already been configured. + * If this property is configured, then a matching 'CredentialsProvider' will be used + * to get the keystore, keystore key, and truststore passwords unless these passwords have already been configured. * * Please note that using MicroProfile {@linkplain ConfigSource} which is directly supported by Quarkus Configuration * should be preferred unless using `CredentialsProvider` provides for some additional security and dynamism. @@ -31,10 +32,11 @@ public class CertificateConfig { /** * The credentials provider bean name. *

- * It is the {@code @Named} value of the credentials provider bean. It is used to discriminate if multiple - * CredentialsProvider beans are available. - * It is recommended to set this property even if there is only one credentials provider currently available - * to ensure the same provider is always found in deployments where more than one provider may be available. + * This is a bean name (as in {@code @Named}) of a bean that implements {@code CredentialsProvider}. + * It is used to select the credentials provider bean when multiple exist. + * This is unnecessary when there is only one credentials provider available. + *

+ * For Vault, the credentials provider bean name is {@code vault-credentials-provider}. */ @ConfigItem @ConvertWith(TrimmedStringConverter.class) @@ -51,7 +53,7 @@ public class CertificateConfig { /** * The list of path to server certificates using the PEM format. - * Specifying multiple files require SNI to be enabled. + * Specifying multiple files requires SNI to be enabled. */ @ConfigItem public Optional> files; @@ -66,8 +68,8 @@ public class CertificateConfig { public Optional keyFile; /** - * The list of path to server certificates private key file using the PEM format. - * Specifying multiple files require SNI to be enabled. + * The list of path to server certificates private key files using the PEM format. + * Specifying multiple files requires SNI to be enabled. * * The order of the key files must match the order of the certificates. */ @@ -75,28 +77,28 @@ public class CertificateConfig { public Optional> keyFiles; /** - * An optional key store which holds the certificate information instead of specifying separate files. + * An optional key store that holds the certificate information instead of specifying separate files. */ @ConfigItem public Optional keyStoreFile; /** - * An optional parameter to specify type of the key store file. If not given, the type is automatically detected - * based on the file name. + * An optional parameter to specify the type of the key store file. + * If not given, the type is automatically detected based on the file name. */ @ConfigItem public Optional keyStoreFileType; /** - * An optional parameter to specify a provider of the key store file. If not given, the provider is automatically detected - * based on the key store file type. + * An optional parameter to specify a provider of the key store file. + * If not given, the provider is automatically detected based on the key store file type. */ @ConfigItem public Optional keyStoreProvider; /** - * A parameter to specify the password of the key store file. If not given, and if it can not be retrieved from - * {@linkplain CredentialsProvider}. + * A parameter to specify the password of the key store file. + * If not given, and if it can not be retrieved from {@linkplain CredentialsProvider}. * * @see {@link #credentialsProvider} */ @@ -104,9 +106,9 @@ public class CertificateConfig { public Optional keyStorePassword; /** - * A parameter to specify a {@linkplain CredentialsProvider} property key which can be used to get the password of the key - * store file - * from {@linkplain CredentialsProvider}. + * A parameter to specify a {@linkplain CredentialsProvider} property key, + * which can be used to get the password of the key + * store file from {@linkplain CredentialsProvider}. * * @see {@link #credentialsProvider} */ @@ -114,15 +116,17 @@ public class CertificateConfig { public Optional keyStorePasswordKey; /** - * An optional parameter to select a specific key in the key store. When SNI is disabled, if the key store contains multiple - * keys and no alias is specified, the behavior is undefined. + * An optional parameter to select a specific key in the key store. + * When SNI is disabled, and the key store contains multiple + * keys and no alias is specified; the behavior is undefined. */ @ConfigItem public Optional keyStoreKeyAlias; /** - * An optional parameter to define the password for the key, in case it's different from {@link #keyStorePassword} - * If not given then it may be retrieved from {@linkplain CredentialsProvider}. + * An optional parameter to define the password for the key, + * in case it is different from {@link #keyStorePassword} + * If not given, it might be retrieved from {@linkplain CredentialsProvider}. * * @see {@link #credentialsProvider}. */ @@ -130,8 +134,8 @@ public class CertificateConfig { public Optional keyStoreKeyPassword; /** - * A parameter to specify a {@linkplain CredentialsProvider} property key which can be used to get the password for the key - * from {@linkplain CredentialsProvider}. + * A parameter to specify a {@linkplain CredentialsProvider} property key, + * which can be used to get the password for the key from {@linkplain CredentialsProvider}. * * @see {@link #credentialsProvider} */ @@ -139,28 +143,28 @@ public class CertificateConfig { public Optional keyStoreKeyPasswordKey; /** - * An optional trust store which holds the certificate information of the certificates to trust. + * An optional trust store that holds the certificate information of the trusted certificates. */ @ConfigItem public Optional trustStoreFile; /** - * An optional parameter to specify type of the trust store file. If not given, the type is automatically detected - * based on the file name. + * An optional parameter to specify the type of the trust store file. + * If not given, the type is automatically detected based on the file name. */ @ConfigItem public Optional trustStoreFileType; /** - * An optional parameter to specify a provider of the trust store file. If not given, the provider is automatically detected - * based on the trust store file type. + * An optional parameter to specify a provider of the trust store file. + * If not given, the provider is automatically detected based on the trust store file type. */ @ConfigItem public Optional trustStoreProvider; /** * A parameter to specify the password of the trust store file. - * If not given then it may be retrieved from {@linkplain CredentialsProvider}. + * If not given, it might be retrieved from {@linkplain CredentialsProvider}. * * @see {@link #credentialsProvider}. */ @@ -168,9 +172,8 @@ public class CertificateConfig { public Optional trustStorePassword; /** - * A parameter to specify a {@linkplain CredentialsProvider} property key which can be used to get the password of the trust - * store file - * from {@linkplain CredentialsProvider}. + * A parameter to specify a {@linkplain CredentialsProvider} property key, + * which can be used to get the password of the trust store file from {@linkplain CredentialsProvider}. * * @see {@link #credentialsProvider} */ @@ -178,8 +181,8 @@ public class CertificateConfig { public Optional trustStorePasswordKey; /** - * An optional parameter to trust only one specific certificate in the trust store (instead of trusting all certificates in - * the store). + * An optional parameter to trust a single certificate from the trust store rather than trusting all certificates in the + * store. */ @ConfigItem public Optional trustStoreCertAlias;