0
# Channel Builders
1

2
High-level builders for creating secure gRPC channels with ALTS authentication and automatic fallback mechanisms.
3

4
## Capabilities
5

6
### ALTS Channel Builder
7

8
Creates a pure ALTS channel with mandatory ALTS authentication for secure communication between Google Cloud VMs.
9

10
```java { .api }
11
/**
12
 * ALTS version of ManagedChannelBuilder that sets up secure and authenticated
13
 * communication between two cloud VMs using ALTS.
14
 */
15
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/4151")
16
public final class AltsChannelBuilder extends ForwardingChannelBuilder2<AltsChannelBuilder> {
17
    
18
    /**
19
     * Creates an ALTS channel builder for the given target
20
     * @param target the target URI or authority to connect to
21
     * @return AltsChannelBuilder instance
22
     */
23
    public static AltsChannelBuilder forTarget(String target);
24
    
25
    /**
26
     * Creates an ALTS channel builder for the given address and port
27
     * @param name the hostname or IP address
28
     * @param port the port number
29
     * @return AltsChannelBuilder instance
30
     */
31
    public static AltsChannelBuilder forAddress(String name, int port);
32
    
33
    /**
34
     * Adds an expected target service account. One of the added service accounts
35
     * should match the peer service account in the handshaker result.
36
     * @param targetServiceAccount the expected target service account
37
     * @return this builder for chaining
38
     */
39
    public AltsChannelBuilder addTargetServiceAccount(String targetServiceAccount);
40
    
41
    /**
42
     * Enables untrusted ALTS for testing. Disables Google Cloud Platform checks.
43
     * @return this builder for chaining
44
     */
45
    public AltsChannelBuilder enableUntrustedAltsForTesting();
46
    
47
    /**
48
     * Sets a custom handshaker service address for testing
49
     * @param handshakerAddress the handshaker service address
50
     * @return this builder for chaining
51
     */
52
    public AltsChannelBuilder setHandshakerAddressForTesting(String handshakerAddress);
53
    
54
    /**
55
     * Builds the managed channel with ALTS security
56
     * @return the configured ManagedChannel
57
     */
58
    public ManagedChannel build();
59
}
60
```
61

62
**Usage Examples:**
63

64
```java
65
import io.grpc.alts.AltsChannelBuilder;
66
import io.grpc.ManagedChannel;
67

68
// Basic ALTS channel
69
ManagedChannel channel = AltsChannelBuilder
70
    .forTarget("my-service:443")
71
    .build();
72

73
// ALTS channel with service account verification
74
ManagedChannel secureChannel = AltsChannelBuilder
75
    .forAddress("10.0.0.1", 8080)
76
    .addTargetServiceAccount("backend@my-project.iam.gserviceaccount.com")
77
    .addTargetServiceAccount("backup@my-project.iam.gserviceaccount.com")
78
    .build();
79

80
// Testing configuration
81
ManagedChannel testChannel = AltsChannelBuilder
82
    .forTarget("localhost:8080")
83
    .enableUntrustedAltsForTesting()
84
    .setHandshakerAddressForTesting("localhost:9999")
85
    .build();
86
```
87

88
### Compute Engine Channel Builder
89

90
Creates a channel that uses ALTS on Google Cloud Platform and automatically falls back to TLS in other environments.
91

92
```java { .api }
93
/**
94
 * Channel builder that automatically chooses ALTS on GCP and TLS elsewhere
95
 */
96
public final class ComputeEngineChannelBuilder extends ForwardingChannelBuilder<ComputeEngineChannelBuilder> {
97
    
98
    /**
99
     * Creates a Compute Engine channel builder for the given target
100
     * @param target the target URI or authority to connect to
101
     * @return ComputeEngineChannelBuilder instance
102
     */
103
    public static ComputeEngineChannelBuilder forTarget(String target);
104
    
105
    /**
106
     * Creates a Compute Engine channel builder for the given address and port
107
     * @param name the hostname or IP address
108
     * @param port the port number
109
     * @return ComputeEngineChannelBuilder instance
110
     */
111
    public static ComputeEngineChannelBuilder forAddress(String name, int port);
112
}
113
```
114

115
**Usage Examples:**
116

117
```java
118
import io.grpc.alts.ComputeEngineChannelBuilder;
119
import io.grpc.ManagedChannel;
120

121
// Automatic ALTS/TLS selection based on environment
122
ManagedChannel channel = ComputeEngineChannelBuilder
123
    .forTarget("my-service.googleapis.com:443")
124
    .build();
125

126
// Uses ALTS on GCP, TLS elsewhere
127
ManagedChannel flexibleChannel = ComputeEngineChannelBuilder
128
    .forAddress("backend-service", 8080)
129
    .build();
130
```
131

132
### Google Default Channel Builder
133

134
Creates a channel using the full Google Cloud authentication stack with support for both ALTS and OAuth credentials.
135

136
```java { .api }
137
/**
138
 * Channel builder for Google Cloud services with full authentication support
139
 */
140
public final class GoogleDefaultChannelBuilder extends ForwardingChannelBuilder<GoogleDefaultChannelBuilder> {
141
    
142
    /**
143
     * Creates a Google Default channel builder for the given target
144
     * @param target the target URI or authority to connect to
145
     * @return GoogleDefaultChannelBuilder instance
146
     */
147
    public static GoogleDefaultChannelBuilder forTarget(String target);
148
    
149
    /**
150
     * Creates a Google Default channel builder for the given address and port
151
     * @param name the hostname or IP address
152
     * @param port the port number
153
     * @return GoogleDefaultChannelBuilder instance
154
     */
155
    public static GoogleDefaultChannelBuilder forAddress(String name, int port);
156
}
157
```
158

159
**Usage Examples:**
160

161
```java
162
import io.grpc.alts.GoogleDefaultChannelBuilder;
163
import io.grpc.ManagedChannel;
164

165
// Full Google Cloud authentication
166
ManagedChannel channel = GoogleDefaultChannelBuilder
167
    .forTarget("pubsub.googleapis.com:443")
168
    .build();
169

170
// Works with Google Cloud APIs
171
ManagedChannel apiChannel = GoogleDefaultChannelBuilder
172
    .forTarget("storage.googleapis.com:443")
173
    .build();
174
```
175

176
## Builder Pattern
177

178
All channel builders follow the standard gRPC builder pattern:
179

180
1. **Create**: Use static factory methods (`forTarget()`, `forAddress()`)
181
2. **Configure**: Chain configuration methods for customization
182
3. **Build**: Call `build()` to create the final `ManagedChannel`
183
4. **Use**: Use the channel with gRPC stubs
184
5. **Cleanup**: Shutdown the channel when done
185

186
## Security Considerations
187

188
- **ALTS**: Only works on Google Cloud Platform between authenticated VMs
189
- **Service Account Verification**: Use `addTargetServiceAccount()` for additional security
190
- **Testing**: Never use testing methods (`enableUntrustedAltsForTesting()`) in production
191
- **Fallback**: Compute Engine and Google Default builders provide automatic fallback mechanisms