0
# Instance Configuration
1

2
Instance configuration controls how the Spring Boot application identifies itself to the admin server, including URLs, metadata, and service discovery settings. All properties are prefixed with `spring.boot.admin.client.instance`.
3

4
## Configuration Properties
5

6
### Application Identity
7

8
```java { .api }
9
@ConfigurationProperties("spring.boot.admin.client.instance")
10
public class InstanceProperties {
11
    // Application name (defaults to spring.application.name)
12
    @Value("${spring.application.name:spring-boot-application}")
13
    private String name = "spring-boot-application";
14
    
15
    // Additional metadata to associate with this application
16
    private Map<String, String> metadata = new LinkedHashMap<>();
17
}
18
```
19

20
### Service URLs
21

22
```java { .api }
23
public class InstanceProperties {
24
    // Complete service URL (overrides auto-detection)
25
    private String serviceUrl;
26
    
27
    // Base URL for service (path auto-detected)
28
    private String serviceBaseUrl;
29
    
30
    // Service path (defaults to "/")
31
    private String servicePath;
32
}
33
```
34

35
### Management URLs
36

37
```java { .api }
38
public class InstanceProperties {
39
    // Complete management URL (overrides auto-detection)  
40
    private String managementUrl;
41
    
42
    // Base URL for management endpoints (path auto-detected)
43
    private String managementBaseUrl;
44
    
45
    // Health endpoint URL (overrides auto-detection)
46
    private String healthUrl;
47
}
48
```
49

50
### Host Resolution
51

52
```java { .api }
53
public class InstanceProperties {
54
    // How to resolve hostname for URLs (deprecated - use serviceHostType)
55
    @Deprecated
56
    private boolean preferIp = false;
57
    
58
    // Host type for building URLs
59
    private ServiceHostType serviceHostType = ServiceHostType.CANONICAL_HOST_NAME;
60
}
61

62
public enum ServiceHostType {
63
    IP,                    // Use IP address
64
    HOST_NAME,            // Use hostname
65
    CANONICAL_HOST_NAME   // Use canonical hostname (default)
66
}
67
```
68

69
## Property Configuration Examples
70

71
### Basic Instance Setup
72

73
```properties
74
# Application name
75
spring.boot.admin.client.instance.name=user-service
76

77
# Custom service URLs (useful for Docker/cloud deployments)
78
spring.boot.admin.client.instance.service-url=https://my-service.example.com
79
spring.boot.admin.client.instance.management-url=https://my-service.example.com/actuator
80
spring.boot.admin.client.instance.health-url=https://my-service.example.com/actuator/health
81
```
82

83
### Base URL Configuration
84

85
```properties
86
# Let Spring Boot Admin construct the full URLs
87
spring.boot.admin.client.instance.service-base-url=https://my-service.example.com
88
spring.boot.admin.client.instance.management-base-url=https://my-service.example.com
89

90
# Optional: custom service path
91
spring.boot.admin.client.instance.service-path=/api
92
```
93

94
### Host Resolution
95

96
```properties
97
# Use IP address instead of hostname
98
spring.boot.admin.client.instance.service-host-type=IP
99

100
# Use simple hostname
101
spring.boot.admin.client.instance.service-host-type=HOST_NAME
102

103
# Use canonical hostname (default)
104
spring.boot.admin.client.instance.service-host-type=CANONICAL_HOST_NAME
105
```
106

107
### Metadata Configuration
108

109
```properties
110
# Add custom metadata
111
spring.boot.admin.client.instance.metadata.environment=production
112
spring.boot.admin.client.instance.metadata.version=1.2.3
113
spring.boot.admin.client.instance.metadata.team=backend
114
spring.boot.admin.client.instance.metadata.region=us-east-1
115
```
116

117
### YAML Configuration
118

119
```yaml
120
spring:
121
  boot:
122
    admin:
123
      client:
124
        instance:
125
          name: user-service
126
          service-url: https://my-service.example.com
127
          management-url: https://my-service.example.com/actuator
128
          health-url: https://my-service.example.com/actuator/health
129
          service-host-type: CANONICAL_HOST_NAME
130
          metadata:
131
            environment: production
132
            version: 1.2.3
133
            team: backend
134
            region: us-east-1
135
```
136

137
## Auto-Detection Behavior
138

139
When URLs are not explicitly configured, Spring Boot Admin Client automatically detects them based on:
140

141
- **Service URL**: Constructed from server configuration and context path
142
- **Management URL**: Constructed from management server configuration and actuator base path  
143
- **Health URL**: Constructed from management URL and health endpoint path
144

145
## Docker and Cloud Deployment
146

147
For containerized deployments where internal and external URLs differ:
148

149
```properties
150
# External URLs that the admin server can reach
151
spring.boot.admin.client.instance.service-base-url=https://my-service.example.com
152
spring.boot.admin.client.instance.management-base-url=https://my-service.example.com
153

154
# Or complete URLs
155
spring.boot.admin.client.instance.service-url=https://my-service.example.com/api
156
spring.boot.admin.client.instance.management-url=https://my-service.example.com/actuator
157
spring.boot.admin.client.instance.health-url=https://my-service.example.com/actuator/health
158
```
159

160
## Metadata Usage
161

162
Metadata is displayed in the Spring Boot Admin UI and can be used for:
163

164
- **Environment identification**: `environment=production`
165
- **Version tracking**: `version=1.2.3`
166
- **Team assignment**: `team=backend`
167
- **Geographic location**: `region=us-east-1`
168
- **Custom tags**: Any key-value pairs relevant to your organization