0
# Instance Operations
1

2
Complete lifecycle management of Redis instances including creation, configuration updates, deletion, and status monitoring.
3

4
## Capabilities
5

6
### Instance Listing
7

8
List all Redis instances in a specified location with automatic pagination support.
9

10
```python { .api }
11
def list_instances(
12
    self,
13
    *,
14
    parent: str,
15
    page_size: Optional[int] = None,
16
    page_token: Optional[str] = None,
17
    **kwargs
18
) -> pagers.ListInstancesPager:
19
    """
20
    Lists all Redis instances owned by a project in a given location.
21

22
    Args:
23
        parent: Required. The resource name of the instance location using the form:
24
               "projects/{project_id}/locations/{location_id}"
25
        page_size: The maximum number of items to return. If not specified,
26
                  a default value is chosen by the service.
27
        page_token: The standard list page token.
28

29
    Returns:
30
        pagers.ListInstancesPager: An iterator of Instance objects.
31
        
32
    Raises:
33
        google.api_core.exceptions.GoogleAPICallError: If the request failed.
34
    """
35
```
36

37
### Instance Retrieval
38

39
Get detailed information about a specific Redis instance.
40

41
```python { .api }
42
def get_instance(self, *, name: str, **kwargs) -> cloud_redis.Instance:
43
    """
44
    Gets the details of a specific Redis instance.
45

46
    Args:
47
        name: Required. Redis instance resource name using the form:
48
             "projects/{project_id}/locations/{location_id}/instances/{instance_id}"
49

50
    Returns:
51
        cloud_redis.Instance: The Instance resource.
52

53
    Raises:
54
        google.api_core.exceptions.GoogleAPICallError: If the request failed.
55
        google.api_core.exceptions.NotFound: If the instance doesn't exist.
56
    """
57
```
58

59
### Instance Creation
60

61
Create a new Redis instance with specified configuration.
62

63
```python { .api }
64
def create_instance(
65
    self,
66
    *,
67
    parent: str,
68
    instance_id: str,
69
    instance: cloud_redis.Instance,
70
    **kwargs
71
) -> operation.Operation:
72
    """
73
    Creates a Redis instance based on the specified tier and memory size.
74

75
    Args:
76
        parent: Required. The resource name of the instance location using the form:
77
               "projects/{project_id}/locations/{location_id}"
78
        instance_id: Required. The logical name of the Redis instance in the customer project.
79
                    Must be 1-40 characters in length, alphanumeric and dashes only.
80
        instance: Required. A Redis Instance resource to be created.
81

82
    Returns:
83
        google.api_core.operation.Operation: A long-running operation object.
84
        The result will be an Instance object.
85

86
    Raises:
87
        google.api_core.exceptions.GoogleAPICallError: If the request failed.
88
        google.api_core.exceptions.AlreadyExists: If instance already exists.
89
    """
90
```
91

92
### Instance Updates
93

94
Update configuration of an existing Redis instance.
95

96
```python { .api }
97
def update_instance(
98
    self,
99
    *,
100
    update_mask: field_mask_pb2.FieldMask,
101
    instance: cloud_redis.Instance,
102
    **kwargs
103
) -> operation.Operation:
104
    """
105
    Updates the metadata and configuration of a Redis instance.
106

107
    Args:
108
        update_mask: Required. Mask of fields to update. At least one path must be supplied.
109
                    Valid field paths include: display_name, labels, memory_size_gb,
110
                    redis_config, replica_count, maintenance_policy, persistence_config.
111
        instance: Required. Update description. Only fields specified in update_mask are updated.
112

113
    Returns:
114
        google.api_core.operation.Operation: A long-running operation object.
115
        The result will be an Instance object.
116

117
    Raises:
118
        google.api_core.exceptions.GoogleAPICallError: If the request failed.
119
        google.api_core.exceptions.NotFound: If the instance doesn't exist.
120
    """
121
```
122

123
### Instance Deletion
124

125
Delete a Redis instance permanently.
126

127
```python { .api }
128
def delete_instance(self, *, name: str, **kwargs) -> operation.Operation:
129
    """
130
    Deletes a specific Redis instance. Instance stops serving and data is deleted.
131

132
    Args:
133
        name: Required. Redis instance resource name using the form:
134
             "projects/{project_id}/locations/{location_id}/instances/{instance_id}"
135

136
    Returns:
137
        google.api_core.operation.Operation: A long-running operation object.
138
        The result will be Empty.
139

140
    Raises:
141
        google.api_core.exceptions.GoogleAPICallError: If the request failed.
142
        google.api_core.exceptions.NotFound: If the instance doesn't exist.
143
    """
144
```
145

146
### Administrative Operations
147

148
Administrative operations for managing long-running operations and locations.
149

150
```python { .api }
151
def list_operations(
152
    self,
153
    *,
154
    name: str,
155
    filter: Optional[str] = None,
156
    page_size: Optional[int] = None,
157
    page_token: Optional[str] = None,
158
    **kwargs
159
) -> pagers.ListOperationsPager:
160
    """Lists operations for the Redis service."""
161

162
def get_operation(self, *, name: str, **kwargs) -> operations_pb2.Operation:
163
    """Gets the latest state of a long-running operation."""
164

165
def delete_operation(self, *, name: str, **kwargs) -> None:
166
    """Deletes a long-running operation."""
167

168
def cancel_operation(self, *, name: str, **kwargs) -> None:
169
    """Starts asynchronous cancellation on a long-running operation."""
170

171
def get_location(self, *, name: str, **kwargs) -> locations_pb2.Location:
172
    """Gets information about a location."""
173

174
def list_locations(
175
    self,
176
    *,
177
    name: str,
178
    filter: Optional[str] = None,
179
    page_size: Optional[int] = None,
180
    page_token: Optional[str] = None,
181
    **kwargs
182
) -> pagers.ListLocationsPager:
183
    """Lists information about supported locations."""
184
```
185

186
## Request and Response Types
187

188
### Request Types
189

190
```python { .api }
191
class ListInstancesRequest:
192
    parent: str
193
    page_size: int
194
    page_token: str
195

196
class GetInstanceRequest:
197
    name: str
198

199
class CreateInstanceRequest:
200
    parent: str
201
    instance_id: str
202
    instance: Instance
203

204
class UpdateInstanceRequest:
205
    update_mask: FieldMask
206
    instance: Instance
207

208
class DeleteInstanceRequest:
209
    name: str
210
```
211

212
### Response Types
213

214
```python { .api }
215
class ListInstancesResponse:
216
    instances: List[Instance]
217
    next_page_token: str
218
    unreachable: List[str]
219
```
220

221
## Usage Examples
222

223
### List All Instances
224

225
```python
226
from google.cloud.redis import CloudRedisClient
227

228
client = CloudRedisClient()
229
parent = "projects/my-project/locations/us-central1"
230

231
# List all instances
232
instances = client.list_instances(parent=parent)
233
for instance in instances:
234
    print(f"Name: {instance.name}")
235
    print(f"State: {instance.state}")
236
    print(f"Host: {instance.host}:{instance.port}")
237
    print(f"Memory: {instance.memory_size_gb}GB")
238
    print("---")
239

240
# List with pagination
241
instances = client.list_instances(parent=parent, page_size=10)
242
for page in instances.pages:
243
    for instance in page.instances:
244
        print(f"Instance: {instance.display_name}")
245
```
246

247
### Create a New Instance
248

249
```python
250
from google.cloud.redis import CloudRedisClient, Instance
251

252
client = CloudRedisClient()
253

254
# Define the instance
255
new_instance = Instance(
256
    display_name="My Redis Cache",
257
    tier=Instance.Tier.STANDARD_HA,
258
    memory_size_gb=2,
259
    redis_version="REDIS_6_X",
260
    authorized_network="projects/my-project/global/networks/default",
261
    connect_mode=Instance.ConnectMode.PRIVATE_SERVICE_ACCESS,
262
    auth_enabled=True,
263
    transit_encryption_mode=Instance.TransitEncryptionMode.SERVER_AUTHENTICATION,
264
    labels={
265
        "environment": "production",
266
        "team": "backend"
267
    }
268
)
269

270
# Create the instance
271
parent = "projects/my-project/locations/us-central1"
272
operation = client.create_instance(
273
    parent=parent,
274
    instance_id="my-production-cache",
275
    instance=new_instance
276
)
277

278
print(f"Creating instance: {operation.name}")
279

280
# Wait for completion
281
result = operation.result(timeout=1800)  # 30 minutes timeout
282
print(f"Instance created: {result.name}")
283
print(f"Host: {result.host}:{result.port}")
284
```
285

286
### Update Instance Configuration
287

288
```python
289
from google.cloud.redis import CloudRedisClient, Instance
290
from google.protobuf import field_mask_pb2
291

292
client = CloudRedisClient()
293

294
# Get the current instance
295
instance_name = "projects/my-project/locations/us-central1/instances/my-cache"
296
instance = client.get_instance(name=instance_name)
297

298
# Update memory size and labels
299
instance.memory_size_gb = 4
300
instance.labels["updated"] = "true"
301

302
# Create update mask
303
update_mask = field_mask_pb2.FieldMask()
304
update_mask.paths.extend(["memory_size_gb", "labels"])
305

306
# Perform the update
307
operation = client.update_instance(
308
    update_mask=update_mask,
309
    instance=instance
310
)
311

312
result = operation.result(timeout=1800)
313
print(f"Instance updated: {result.memory_size_gb}GB")
314
```
315

316
### Delete an Instance
317

318
```python
319
from google.cloud.redis import CloudRedisClient
320

321
client = CloudRedisClient()
322

323
instance_name = "projects/my-project/locations/us-central1/instances/old-cache"
324

325
# Delete the instance
326
operation = client.delete_instance(name=instance_name)
327

328
print(f"Deleting instance: {operation.name}")
329

330
# Wait for deletion to complete
331
operation.result(timeout=1800)
332
print("Instance deleted successfully")
333
```
334

335
### Monitor Operations
336

337
```python
338
from google.cloud.redis import CloudRedisClient
339

340
client = CloudRedisClient()
341

342
# List recent operations
343
parent = "projects/my-project/locations/us-central1"
344
operations = client.list_operations(name=parent)
345

346
for operation in operations:
347
    print(f"Operation: {operation.name}")
348
    print(f"Done: {operation.done}")
349
    if operation.done:
350
        if operation.error:
351
            print(f"Error: {operation.error}")
352
        else:
353
            print("Success!")
354
    print("---")
355

356
# Get specific operation status
357
operation_name = "projects/my-project/locations/us-central1/operations/operation-123"
358
operation = client.get_operation(name=operation_name)
359
print(f"Operation {operation.name} done: {operation.done}")
360
```
361

362
### Working with Locations
363

364
```python
365
from google.cloud.redis import CloudRedisClient
366

367
client = CloudRedisClient()
368

369
# List available locations
370
parent = "projects/my-project"
371
locations = client.list_locations(name=parent)
372

373
print("Available locations:")
374
for location in locations:
375
    print(f"Location: {location.name}")
376
    print(f"Display Name: {location.display_name}")
377
    for label_key, label_value in location.labels.items():
378
        print(f"  {label_key}: {label_value}")
379
    print("---")
380

381
# Get specific location details
382
location_name = "projects/my-project/locations/us-central1"
383
location = client.get_location(name=location_name)
384
print(f"Location: {location.display_name}")
385
print(f"Labels: {dict(location.labels)}")
386
```