0
# Autokey Service
1

2
The Autokey Service provides automated key provisioning for Customer-Managed Encryption Keys (CMEK) that creates and manages keys automatically based on resource needs. It includes both key handle management through AutokeyClient and administrative configuration through AutokeyAdminClient.
3

4
## Capabilities
5

6
### Key Handle Management
7

8
Key handles represent automated key provisioning requests that trigger the creation of new CryptoKeys for CMEK use.
9

10
```python { .api }
11
class AutokeyClient:
12
    def create_key_handle(self, request: CreateKeyHandleRequest) -> KeyHandle:
13
        """
14
        Creates a new KeyHandle, triggering provisioning of a new CryptoKey for CMEK use.
15
        
16
        Parameters:
17
        - request.parent: Required. Project path (projects/{project}/locations/{location})
18
        - request.key_handle_id: Required. Unique ID for the KeyHandle
19
        - request.key_handle: Required. KeyHandle object to create
20
        
21
        Returns:
22
        Created KeyHandle object
23
        """
24

25
    def get_key_handle(self, request: GetKeyHandleRequest) -> KeyHandle:
26
        """
27
        Returns the KeyHandle.
28
        
29
        Parameters:
30
        - request.name: Required. KeyHandle resource name
31
        
32
        Returns:
33
        KeyHandle object with metadata
34
        """
35

36
    def list_key_handles(self, request: ListKeyHandlesRequest) -> ListKeyHandlesResponse:
37
        """
38
        Lists KeyHandles.
39
        
40
        Parameters:
41
        - request.parent: Required. Project path
42
        - request.page_size: Optional. Maximum results per page
43
        - request.page_token: Optional. Pagination token
44
        - request.filter: Optional. Filter expression
45
        
46
        Returns:
47
        List of KeyHandle objects with pagination
48
        """
49
```
50

51
### Autokey Configuration Management
52

53
Administrative configuration for Autokey functionality at the folder level.
54

55
```python { .api }
56
class AutokeyAdminClient:
57
    def update_autokey_config(self, request: UpdateAutokeyConfigRequest) -> AutokeyConfig:
58
        """
59
        Updates the AutokeyConfig for a folder.
60
        
61
        Parameters:
62
        - request.autokey_config: Required. Updated AutokeyConfig object
63
        - request.update_mask: Required. Fields to update
64
        
65
        Returns:
66
        Updated AutokeyConfig object
67
        """
68

69
    def get_autokey_config(self, request: GetAutokeyConfigRequest) -> AutokeyConfig:
70
        """
71
        Returns the AutokeyConfig for a folder.
72
        
73
        Parameters:
74
        - request.name: Required. AutokeyConfig resource name (folders/{folder}/autokeyConfig)
75
        
76
        Returns:
77
        AutokeyConfig object
78
        """
79

80
    def show_effective_autokey_config(self, request: ShowEffectiveAutokeyConfigRequest) -> ShowEffectiveAutokeyConfigResponse:
81
        """
82
        Returns the effective Cloud KMS Autokey configuration for a given project.
83
        
84
        Parameters:
85
        - request.parent: Required. Project path (projects/{project})
86
        
87
        Returns:
88
        ShowEffectiveAutokeyConfigResponse with effective configuration
89
        """
90
```
91

92
## Resource Types
93

94
### KeyHandle
95

96
```python { .api }
97
class KeyHandle:
98
    """
99
    Resource-oriented representation of an Autokey request.
100
    
101
    Attributes:
102
    - name: str - Resource name of the KeyHandle
103
    - kms_key: str - Name of the CryptoKey created for this KeyHandle
104
    - resource_type_selector: str - Selector for resource types that use this key
105
    """
106
```
107

108
### AutokeyConfig
109

110
```python { .api }
111
class AutokeyConfig:
112
    """
113
    Cloud KMS Autokey configuration for a folder.
114
    
115
    Attributes:
116
    - name: str - Resource name of the AutokeyConfig
117
    - key_project: str - Project that will host Autokey-created keys
118
    - state: State - Current state of the configuration
119
    """
120
    
121
    class State:
122
        """
123
        State of AutokeyConfig.
124
        
125
        Values:
126
        - STATE_UNSPECIFIED: Unspecified state
127
        - ACTIVE: Currently active and ready to provision keys
128
        - KEY_PROJECT_DELETED: Key project deleted, config unusable
129
        - UNINITIALIZED: Not initialized or reset to default
130
        """
131
```
132

133
### Request/Response Types
134

135
```python { .api }
136
class CreateKeyHandleRequest:
137
    """
138
    Request to create a KeyHandle.
139
    
140
    Attributes:
141
    - parent: str - Required. Project location path
142
    - key_handle_id: str - Required. Unique ID for KeyHandle
143
    - key_handle: KeyHandle - Required. KeyHandle to create
144
    """
145

146
class CreateKeyHandleMetadata:
147
    """
148
    Metadata for CreateKeyHandle long-running operation.
149
    """
150

151
class ListKeyHandlesRequest:
152
    """
153
    Request to list KeyHandles.
154
    
155
    Attributes:
156
    - parent: str - Required. Project path
157
    - page_size: int - Optional. Maximum results per page
158
    - page_token: str - Optional. Pagination token
159
    - filter: str - Optional. Filter expression
160
    """
161

162
class ListKeyHandlesResponse:
163
    """
164
    Response from listing KeyHandles.
165
    
166
    Attributes:
167
    - key_handles: List[KeyHandle] - List of KeyHandle objects
168
    - next_page_token: str - Token for next page
169
    """
170

171
class UpdateAutokeyConfigRequest:
172
    """
173
    Request to update AutokeyConfig.
174
    
175
    Attributes:
176
    - autokey_config: AutokeyConfig - Required. Updated config
177
    - update_mask: FieldMask - Required. Fields to update
178
    """
179

180
class ShowEffectiveAutokeyConfigRequest:
181
    """
182
    Request to show effective AutokeyConfig.
183
    
184
    Attributes:
185
    - parent: str - Required. Project path
186
    """
187

188
class ShowEffectiveAutokeyConfigResponse:
189
    """
190
    Response showing effective AutokeyConfig.
191
    
192
    Attributes:
193
    - key_project: str - Project hosting Autokey-created keys
194
    """
195
```
196

197
## Usage Examples
198

199
### Setting Up Autokey Configuration
200

201
```python
202
from google.cloud import kms
203

204
# Initialize the Autokey Admin client
205
admin_client = kms.AutokeyAdminClient()
206

207
# Configure Autokey for a folder
208
folder_id = "123456789"
209
key_project_id = "my-key-project"
210

211
autokey_config = kms.AutokeyConfig()
212
autokey_config.key_project = f"projects/{key_project_id}"
213

214
# Update the configuration
215
config_path = f"folders/{folder_id}/autokeyConfig"
216
updated_config = admin_client.update_autokey_config(
217
    request={
218
        "autokey_config": {
219
            "name": config_path,
220
            "key_project": f"projects/{key_project_id}",
221
        },
222
        "update_mask": {"paths": ["key_project"]},
223
    }
224
)
225

226
print(f"Autokey configured for folder {folder_id}")
227
print(f"Keys will be created in project: {updated_config.key_project}")
228
```
229

230
### Creating a Key Handle
231

232
```python
233
from google.cloud import kms
234

235
# Initialize the Autokey client
236
client = kms.AutokeyClient()
237

238
# Create a key handle for automatic key provisioning
239
project_id = "my-project"
240
location_id = "global"
241
key_handle_id = "example-key-handle"
242

243
key_handle = kms.KeyHandle()
244
key_handle.resource_type_selector = "compute.googleapis.com/Disk"
245

246
# Create the key handle
247
parent = f"projects/{project_id}/locations/{location_id}"
248
created_handle = client.create_key_handle(
249
    request={
250
        "parent": parent,
251
        "key_handle_id": key_handle_id,
252
        "key_handle": key_handle,
253
    }
254
)
255

256
print(f"Created KeyHandle: {created_handle.name}")
257
print(f"Associated CryptoKey: {created_handle.kms_key}")
258
```
259

260
### Listing Key Handles
261

262
```python
263
from google.cloud import kms
264

265
# Initialize the Autokey client
266
client = kms.AutokeyClient()
267

268
# List all key handles in a project
269
project_id = "my-project"
270
parent = f"projects/{project_id}/locations/-"
271

272
# Get all key handles
273
response = client.list_key_handles(
274
    request={
275
        "parent": parent,
276
        "page_size": 100,
277
    }
278
)
279

280
for key_handle in response.key_handles:
281
    print(f"KeyHandle: {key_handle.name}")
282
    print(f"  Associated Key: {key_handle.kms_key}")
283
    print(f"  Resource Type: {key_handle.resource_type_selector}")
284
```
285

286
### Checking Effective Autokey Configuration
287

288
```python
289
from google.cloud import kms
290

291
# Initialize the Autokey Admin client
292
admin_client = kms.AutokeyAdminClient()
293

294
# Check effective configuration for a project
295
project_id = "my-project"
296
project_path = f"projects/{project_id}"
297

298
effective_config = admin_client.show_effective_autokey_config(
299
    request={"parent": project_path}
300
)
301

302
if effective_config.key_project:
303
    print(f"Autokey is configured for project {project_id}")
304
    print(f"Keys will be created in: {effective_config.key_project}")
305
else:
306
    print(f"No Autokey configuration found for project {project_id}")
307
```
308

309
## Common Patterns
310

311
### Error Handling
312

313
```python
314
from google.cloud import kms
315
from google.api_core import exceptions
316

317
client = kms.AutokeyClient()
318

319
try:
320
    key_handle = client.get_key_handle(
321
        request={"name": "projects/my-project/locations/global/keyHandles/nonexistent"}
322
    )
323
except exceptions.NotFound:
324
    print("KeyHandle not found")
325
except exceptions.PermissionDenied:
326
    print("Permission denied - check IAM roles")
327
except Exception as e:
328
    print(f"Unexpected error: {e}")
329
```
330

331
### Long-running Operations
332

333
```python
334
from google.cloud import kms
335

336
client = kms.AutokeyClient()
337

338
# Create key handle (returns a long-running operation)
339
operation = client.create_key_handle(
340
    request={
341
        "parent": f"projects/{project_id}/locations/{location_id}",
342
        "key_handle_id": key_handle_id,
343
        "key_handle": key_handle,
344
    }
345
)
346

347
# Wait for completion
348
print("Waiting for key handle creation...")
349
result = operation.result()
350
print(f"KeyHandle created: {result.name}")
351
```