0
# Configuration Management
1

2
Quarkus provides a comprehensive configuration system based on MicroProfile Config with build-time resolution, type-safe configuration mapping, and support for multiple configuration sources including environment variables, system properties, and configuration files.
3

4
## Configuration Injection
5

6
### @ConfigProperty Annotation
7

8
```java { .api }
9
@Target({ElementType.FIELD, ElementType.PARAMETER})
10
@Retention(RetentionPolicy.RUNTIME)
11
public @interface ConfigProperty {
12
    String name() default "";
13
    String defaultValue() default ConfigProperty.UNCONFIGURED_VALUE;
14
    String UNCONFIGURED_VALUE = "<<unset>>";
15
}
16
```
17

18
Injects configuration properties into fields or method parameters with optional default values.
19

20
**Usage Example:**
21
```java
22
@ApplicationScoped
23
public class DatabaseService {
24
    
25
    @ConfigProperty(name = "database.host", defaultValue = "localhost")
26
    String host;
27
    
28
    @ConfigProperty(name = "database.port", defaultValue = "5432")
29
    int port;
30
    
31
    @ConfigProperty(name = "database.username")
32
    String username;
33
    
34
    @ConfigProperty(name = "database.password")
35
    Optional<String> password;  // Optional for properties that may not be set
36
    
37
    public void connect() {
38
        System.out.println("Connecting to " + host + ":" + port);
39
    }
40
}
41
```
42

43
### Configuration with Profiles
44

45
```java
46
# application.properties
47
database.host=localhost
48
database.port=5432
49

50
# application-dev.properties  
51
%dev.database.host=dev-server
52
%dev.database.port=5433
53

54
# application-prod.properties
55
%prod.database.host=prod-server
56
%prod.database.port=5434
57
```
58

59
Configuration values can be overridden per profile using the `%{profile}.` prefix.
60

61
## Type-Safe Configuration Mapping
62

63
### @ConfigMapping Annotation
64

65
```java { .api }
66
@Target(ElementType.TYPE)
67
@Retention(RetentionPolicy.RUNTIME)
68
public @interface ConfigMapping {
69
    String prefix() default "";
70
    NamingStrategy namingStrategy() default NamingStrategy.KEBAB_CASE;
71
}
72

73
public enum NamingStrategy {
74
    KEBAB_CASE,
75
    SNAKE_CASE,
76
    VERBATIM
77
}
78
```
79

80
Maps configuration properties to type-safe configuration classes.
81

82
**Usage Example:**
83
```java
84
@ConfigMapping(prefix = "database")
85
public interface DatabaseConfig {
86
    String host();
87
    int port();
88
    Optional<String> username();
89
    Optional<String> password();
90
    ConnectionPool connectionPool();
91
    
92
    interface ConnectionPool {
93
        @WithDefault("10")
94
        int maxConnections();
95
        
96
        @WithDefault("PT30S")
97
        Duration timeout();
98
    }
99
}
100

101
// Usage in a service
102
@ApplicationScoped
103
public class DatabaseService {
104
    
105
    @Inject
106
    DatabaseConfig config;
107
    
108
    public void connect() {
109
        System.out.println("Connecting to " + config.host() + ":" + config.port());
110
        System.out.println("Max connections: " + config.connectionPool().maxConnections());
111
    }
112
}
113
```
114

115
### Configuration Mapping Annotations
116

117
```java { .api }
118
@Target({ElementType.METHOD, ElementType.PARAMETER})
119
@Retention(RetentionPolicy.RUNTIME)
120
public @interface WithDefault {
121
    String value();
122
}
123

124
@Target(ElementType.METHOD)
125
@Retention(RetentionPolicy.RUNTIME)
126
public @interface WithName {
127
    String value();
128
}
129

130
@Target({ElementType.TYPE, ElementType.METHOD})
131
@Retention(RetentionPolicy.RUNTIME)
132
public @interface WithParentName {
133
}
134
```
135

136
Annotations for customizing configuration mapping behavior.
137

138
**Usage Example:**
139
```java
140
@ConfigMapping(prefix = "server")
141
public interface ServerConfig {
142
    @WithName("listen-port")
143
    @WithDefault("8080")
144
    int port();
145
    
146
    @WithDefault("localhost")
147
    String host();
148
    
149
    Ssl ssl();
150
    
151
    @WithParentName
152
    interface Ssl {
153
        @WithDefault("false")
154
        boolean enabled();
155
        
156
        Optional<String> keystore();
157
        Optional<String> keystorePassword();
158
    }
159
}
160
```
161

162
## Programmatic Configuration Access
163

164
### ConfigProvider
165

166
```java { .api }
167
public class ConfigProvider {
168
    public static Config getConfig();
169
    public static Config getConfig(ClassLoader loader);
170
}
171
```
172

173
Provides programmatic access to the configuration.
174

175
### Config Interface
176

177
```java { .api }
178
public interface Config {
179
    <T> T getValue(String propertyName, Class<T> propertyType);
180
    <T> Optional<T> getOptionalValue(String propertyName, Class<T> propertyType);
181
    Iterable<String> getPropertyNames();
182
    Iterable<ConfigSource> getConfigSources();
183
}
184
```
185

186
Main configuration access interface.
187

188
**Usage Example:**
189
```java
190
@ApplicationScoped
191
public class ConfigService {
192
    
193
    public void printConfig() {
194
        Config config = ConfigProvider.getConfig();
195
        
196
        // Get required value
197
        String appName = config.getValue("app.name", String.class);
198
        
199
        // Get optional value
200
        Optional<String> version = config.getOptionalValue("app.version", String.class);
201
        
202
        // Get value with default
203
        int timeout = config.getOptionalValue("app.timeout", Integer.class).orElse(30);
204
        
205
        System.out.println("App: " + appName + ", Version: " + version.orElse("unknown"));
206
    }
207
}
208
```
209

210
## Configuration Sources
211

212
### Built-in Configuration Sources
213

214
1. **System Properties** (ordinal: 400)
215
2. **Environment Variables** (ordinal: 300)  
216
3. **application.properties** files (ordinal: 250)
217
4. **application.yaml** files (ordinal: 255)
218
5. **MicroProfile Config properties** (ordinal: 100)
219

220
### Custom Configuration Sources
221

222
```java { .api }
223
public interface ConfigSource {
224
    Map<String, String> getProperties();
225
    String getValue(String propertyName);
226
    String getName();
227
    default int getOrdinal() { return 100; }
228
}
229
```
230

231
Interface for implementing custom configuration sources.
232

233
**Usage Example:**
234
```java
235
public class DatabaseConfigSource implements ConfigSource {
236
    
237
    @Override
238
    public Map<String, String> getProperties() {
239
        // Load from database
240
        return loadFromDatabase();
241
    }
242
    
243
    @Override
244
    public String getValue(String propertyName) {
245
        return getProperties().get(propertyName);
246
    }
247
    
248
    @Override
249
    public String getName() {
250
        return "DatabaseConfigSource";
251
    }
252
    
253
    @Override
254
    public int getOrdinal() {
255
        return 200;  // Higher priority than default files
256
    }
257
}
258
```
259

260
### ConfigSourceProvider
261

262
```java { .api }
263
public interface ConfigSourceProvider {
264
    Iterable<ConfigSource> getConfigSources(ClassLoader forClassLoader);
265
}
266
```
267

268
Interface for providing multiple configuration sources.
269

270
## Configuration Validation
271

272
### @ConfigRoot Annotation
273

274
```java { .api }
275
@Target(ElementType.TYPE)
276
@Retention(RetentionPolicy.RUNTIME)
277
public @interface ConfigRoot {
278
    ConfigPhase phase() default ConfigPhase.RUN_TIME;
279
    String name() default "";
280
}
281

282
public enum ConfigPhase {
283
    BUILD_TIME,
284
    BUILD_TIME_AND_RUN_TIME,
285
    RUN_TIME
286
}
287
```
288

289
Marks configuration root classes for build-time processing.
290

291
### @ConfigGroup Annotation
292

293
```java { .api }
294
@Target(ElementType.TYPE)
295
@Retention(RetentionPolicy.RUNTIME)
296
public @interface ConfigGroup {
297
}
298
```
299

300
Groups related configuration properties together.
301

302
**Usage Example:**
303
```java
304
@ConfigRoot(phase = ConfigPhase.RUN_TIME)
305
public class AppConfig {
306
    
307
    @ConfigItem
308
    public String name;
309
    
310
    @ConfigItem(defaultValue = "INFO")
311
    public String logLevel;
312
    
313
    @ConfigItem
314
    public DatabaseConfig database;
315
}
316

317
@ConfigGroup
318
public class DatabaseConfig {
319
    
320
    @ConfigItem(defaultValue = "localhost")
321
    public String host;
322
    
323
    @ConfigItem(defaultValue = "5432")
324
    public int port;
325
}
326
```
327

328
## Configuration Profiles
329

330
### Profile Activation
331

332
Configuration profiles can be activated using:
333

334
1. **System property**: `-Dquarkus.profile=dev`
335
2. **Environment variable**: `QUARKUS_PROFILE=dev`
336
3. **application.properties**: `quarkus.profile=dev`
337
4. **Programmatically**: `System.setProperty("quarkus.profile", "dev")`
338

339
### Profile-Specific Configuration
340

341
```java
342
# Default configuration
343
app.timeout=30
344
database.pool.size=10
345

346
# Development profile
347
%dev.app.timeout=5
348
%dev.database.pool.size=5
349

350
# Production profile  
351
%prod.app.timeout=60
352
%prod.database.pool.size=50
353

354
# Test profile
355
%test.app.timeout=1
356
%test.database.pool.size=1
357
```
358

359
### ProfileManager
360

361
```java { .api }
362
public class ProfileManager {
363
    public static String getActiveProfile();
364
    public static List<String> getActiveProfiles();
365
    public static boolean isActiveProfile(String profile);
366
}
367
```
368

369
Utility class for profile management.
370

371
**Usage Example:**
372
```java
373
@ApplicationScoped
374
public class EnvironmentService {
375
    
376
    public void logEnvironment() {
377
        String profile = ProfileManager.getActiveProfile();
378
        System.out.println("Running in profile: " + profile);
379
        
380
        if (ProfileManager.isActiveProfile("dev")) {
381
            System.out.println("Development mode enabled");
382
        }
383
    }
384
}
385
```
386

387
## Configuration Converters
388

389
### Built-in Converters
390

391
Quarkus provides converters for common types:
392
- Primitives and their wrappers
393
- String
394
- Duration (ISO-8601 format)
395
- Enums
396
- Collections (comma-separated values)
397
- Optional wrapper types
398

399
### Custom Converters
400

401
```java { .api }
402
public interface Converter<T> {
403
    T convert(String value) throws IllegalArgumentException, NullPointerException;
404
}
405
```
406

407
Interface for implementing custom type converters.
408

409
**Usage Example:**
410
```java
411
public class UriConverter implements Converter<URI> {
412
    
413
    @Override
414
    public URI convert(String value) {
415
        try {
416
            return new URI(value);
417
        } catch (URISyntaxException e) {
418
            throw new IllegalArgumentException("Invalid URI: " + value, e);
419
        }
420
    }
421
}
422

423
// Register in META-INF/services/org.eclipse.microprofile.config.spi.Converter
424
```
425

426
## Configuration Secrets
427

428
### Encrypted Configuration
429

430
```java { .api }
431
@ConfigProperty(name = "database.password")
432
@Secret
433
String encryptedPassword;
434
```
435

436
Configuration values can be encrypted and automatically decrypted at runtime.
437

438
### Credential Providers
439

440
```java { .api }
441
public interface CredentialsProvider {
442
    Map<String, String> getCredentials(String credentialsProviderName);
443
}
444
```
445

446
Interface for implementing custom credential providers (e.g., HashiCorp Vault, AWS Secrets Manager).
447

448
## Configuration Documentation Generation
449

450
### @ConfigDocSection
451

452
```java { .api }
453
@Target({ElementType.TYPE, ElementType.FIELD})
454
@Retention(RetentionPolicy.RUNTIME)
455
public @interface ConfigDocSection {
456
    String name() default "";
457
    boolean generated() default false;
458
}
459
```
460

461
Annotation for documenting configuration sections in generated documentation.
462

463
### @ConfigDocMapKey
464

465
```java { .api }
466
@Target(ElementType.FIELD)
467
@Retention(RetentionPolicy.RUNTIME)
468
public @interface ConfigDocMapKey {
469
    String value();
470
}
471
```
472

473
Documents map-based configuration properties.
474

475
**Usage Example:**
476
```java
477
@ConfigRoot
478
@ConfigDocSection(name = "Application Configuration")
479
public class AppConfig {
480
    
481
    /**
482
     * The name of the application
483
     */
484
    @ConfigItem
485
    public String name;
486
    
487
    /**
488
     * HTTP server configuration
489
     */
490
    @ConfigItem
491
    @ConfigDocSection(name = "HTTP Server")
492
    public HttpConfig http;
493
    
494
    /**
495
     * Feature flags
496
     */
497
    @ConfigItem
498
    @ConfigDocMapKey("feature-name")
499
    public Map<String, Boolean> features;
500
}
501
```