0
# Cache and Credentials
1

2
Cache rule management for upstream registry caching and credential set management for secure authentication to external registries. These features enable efficient content distribution through caching and secure access to upstream registries and external artifact sources.
3

4
## Capabilities
5

6
### Cache Rule Management
7

8
Create and manage cache rules that define how content from upstream registries is cached locally, improving performance and reducing bandwidth usage.
9

10
```python { .api }
11
def begin_create(resource_group_name: str, registry_name: str, cache_rule_name: str, cache_rule_create_parameters: CacheRule, **kwargs) -> LROPoller[CacheRule]:
12
    """
13
    Create a cache rule for a container registry.
14
    
15
    Parameters:
16
    - resource_group_name: str - Name of the resource group
17
    - registry_name: str - Name of the registry
18
    - cache_rule_name: str - Name of the cache rule
19
    - cache_rule_create_parameters: CacheRule - Cache rule configuration
20
    
21
    Returns:
22
    LROPoller[CacheRule] - Long-running operation poller for the cache rule
23
    """
24

25
def begin_delete(resource_group_name: str, registry_name: str, cache_rule_name: str, **kwargs) -> LROPoller[None]:
26
    """
27
    Delete a cache rule from a container registry.
28
    
29
    Parameters:
30
    - resource_group_name: str - Name of the resource group
31
    - registry_name: str - Name of the registry
32
    - cache_rule_name: str - Name of the cache rule to delete
33
    
34
    Returns:
35
    LROPoller[None] - Long-running operation poller
36
    """
37

38
def begin_update(resource_group_name: str, registry_name: str, cache_rule_name: str, cache_rule_update_parameters: CacheRuleUpdateParameters, **kwargs) -> LROPoller[CacheRule]:
39
    """
40
    Update a cache rule for a container registry.
41
    
42
    Parameters:
43
    - resource_group_name: str - Name of the resource group
44
    - registry_name: str - Name of the registry
45
    - cache_rule_name: str - Name of the cache rule to update
46
    - cache_rule_update_parameters: CacheRuleUpdateParameters - Update parameters
47
    
48
    Returns:
49
    LROPoller[CacheRule] - Long-running operation poller for the updated cache rule
50
    """
51

52
def get(resource_group_name: str, registry_name: str, cache_rule_name: str, **kwargs) -> CacheRule:
53
    """
54
    Get properties of a cache rule.
55
    
56
    Parameters:
57
    - resource_group_name: str - Name of the resource group
58
    - registry_name: str - Name of the registry
59
    - cache_rule_name: str - Name of the cache rule
60
    
61
    Returns:
62
    CacheRule - Cache rule resource with complete configuration
63
    """
64

65
def list(resource_group_name: str, registry_name: str, **kwargs) -> ItemPaged[CacheRule]:
66
    """
67
    List all cache rules for a container registry.
68
    
69
    Parameters:
70
    - resource_group_name: str - Name of the resource group
71
    - registry_name: str - Name of the registry
72
    
73
    Returns:
74
    ItemPaged[CacheRule] - Paginated list of all cache rules for the registry
75
    """
76
```
77

78
### Credential Set Management
79

80
Create and manage credential sets that provide secure authentication credentials for accessing external registries and upstream sources.
81

82
```python { .api }
83
def begin_create(resource_group_name: str, registry_name: str, credential_set_name: str, credential_set_create_parameters: CredentialSet, **kwargs) -> LROPoller[CredentialSet]:
84
    """
85
    Create a credential set for a container registry.
86
    
87
    Parameters:
88
    - resource_group_name: str - Name of the resource group
89
    - registry_name: str - Name of the registry
90
    - credential_set_name: str - Name of the credential set
91
    - credential_set_create_parameters: CredentialSet - Credential set configuration
92
    
93
    Returns:
94
    LROPoller[CredentialSet] - Long-running operation poller for the credential set
95
    """
96

97
def begin_delete(resource_group_name: str, registry_name: str, credential_set_name: str, **kwargs) -> LROPoller[None]:
98
    """
99
    Delete a credential set from a container registry.
100
    
101
    Parameters:
102
    - resource_group_name: str - Name of the resource group
103
    - registry_name: str - Name of the registry
104
    - credential_set_name: str - Name of the credential set to delete
105
    
106
    Returns:
107
    LROPoller[None] - Long-running operation poller
108
    """
109

110
def begin_update(resource_group_name: str, registry_name: str, credential_set_name: str, credential_set_update_parameters: CredentialSetUpdateParameters, **kwargs) -> LROPoller[CredentialSet]:
111
    """
112
    Update a credential set for a container registry.
113
    
114
    Parameters:
115
    - resource_group_name: str - Name of the resource group
116
    - registry_name: str - Name of the registry
117
    - credential_set_name: str - Name of the credential set to update
118
    - credential_set_update_parameters: CredentialSetUpdateParameters - Update parameters
119
    
120
    Returns:
121
    LROPoller[CredentialSet] - Long-running operation poller for the updated credential set
122
    """
123

124
def get(resource_group_name: str, registry_name: str, credential_set_name: str, **kwargs) -> CredentialSet:
125
    """
126
    Get properties of a credential set.
127
    
128
    Parameters:
129
    - resource_group_name: str - Name of the resource group
130
    - registry_name: str - Name of the registry
131
    - credential_set_name: str - Name of the credential set
132
    
133
    Returns:
134
    CredentialSet - Credential set resource with complete configuration
135
    """
136

137
def list(resource_group_name: str, registry_name: str, **kwargs) -> ItemPaged[CredentialSet]:
138
    """
139
    List all credential sets for a container registry.
140
    
141
    Parameters:
142
    - resource_group_name: str - Name of the resource group
143
    - registry_name: str - Name of the registry
144
    
145
    Returns:
146
    ItemPaged[CredentialSet] - Paginated list of all credential sets for the registry
147
    """
148
```
149

150
## Core Model Types
151

152
### CacheRule
153

154
```python { .api }
155
class CacheRule:
156
    """
157
    An object that represents a cache rule for a container registry.
158
    
159
    Attributes:
160
    - id: str - Resource ID
161
    - name: str - Resource name
162
    - type: str - Resource type
163
    - provisioning_state: ProvisioningState - Current provisioning state
164
    - source_repository: str - Source repository pattern to cache
165
    - target_repository: str - Target repository in the registry
166
    - credential_set_resource_id: str - Credential set for upstream authentication
167
    - creation_date: datetime - Creation timestamp
168
    """
169
```
170

171
### CacheRuleUpdateParameters
172

173
```python { .api }
174
class CacheRuleUpdateParameters:
175
    """
176
    Parameters for updating a cache rule.
177
    
178
    Attributes:
179
    - credential_set_resource_id: str - Credential set resource ID for authentication
180
    """
181
```
182

183
### CredentialSet
184

185
```python { .api }
186
class CredentialSet:
187
    """
188
    An object that represents a credential set for a container registry.
189
    
190
    Attributes:
191
    - id: str - Resource ID
192
    - name: str - Resource name
193
    - type: str - Resource type
194
    - identity: IdentityProperties - Managed identity configuration
195
    - provisioning_state: ProvisioningState - Current provisioning state
196
    - login_server: str - Login server URL for the credential set
197
    - auth_credentials: List[AuthCredential] - Authentication credentials
198
    - creation_date: datetime - Creation timestamp
199
    """
200
```
201

202
### CredentialSetUpdateParameters
203

204
```python { .api }
205
class CredentialSetUpdateParameters:
206
    """
207
    Parameters for updating a credential set.
208
    
209
    Attributes:
210
    - identity: IdentityProperties - Managed identity configuration
211
    - auth_credentials: List[AuthCredential] - Authentication credentials to update
212
    """
213
```
214

215
### AuthCredential
216

217
```python { .api }
218
class AuthCredential:
219
    """
220
    Authentication credential for external registry access.
221
    
222
    Attributes:
223
    - name: CredentialName - Credential name identifier
224
    - username_secret_identifier: str - Key vault secret identifier for username
225
    - password_secret_identifier: str - Key vault secret identifier for password
226
    - credential_health: CredentialHealth - Health status of the credential
227
    """
228
```
229

230
### CredentialHealth
231

232
```python { .api }
233
class CredentialHealth:
234
    """
235
    Health status of a credential.
236
    
237
    Attributes:
238
    - status: CredentialHealthStatus - Health status (Healthy, Unhealthy)
239
    - error_code: str - Error code if unhealthy
240
    - error_message: str - Detailed error message
241
    """
242
```
243

244
## Enums
245

246
### CredentialName
247

248
```python { .api }
249
class CredentialName(str, Enum):
250
    """Credential name identifiers."""
251
    CREDENTIAL1 = "Credential1"
252
```
253

254
### CredentialHealthStatus
255

256
```python { .api }
257
class CredentialHealthStatus(str, Enum):
258
    """Credential health status options."""
259
    HEALTHY = "Healthy"
260
    UNHEALTHY = "Unhealthy"
261
```
262

263
### ProvisioningState
264

265
```python { .api }
266
class ProvisioningState(str, Enum):
267
    """Provisioning state of a resource."""
268
    CREATING = "Creating"
269
    UPDATING = "Updating"
270
    DELETING = "Deleting"
271
    SUCCEEDED = "Succeeded"
272
    FAILED = "Failed"
273
    CANCELED = "Canceled"
274
```
275

276
## Usage Examples
277

278
### Create Cache Rule for Docker Hub
279

280
```python
281
from azure.mgmt.containerregistry import ContainerRegistryManagementClient
282
from azure.mgmt.containerregistry.models import CacheRule
283
from azure.identity import DefaultAzureCredential
284

285
client = ContainerRegistryManagementClient(
286
    DefaultAzureCredential(), 
287
    "subscription-id"
288
)
289

290
# Create cache rule for caching Docker Hub images
291
dockerhub_cache_rule = CacheRule(
292
    source_repository="docker.io/library/*",  # Cache official Docker Hub images
293
    target_repository="dockerhub-cache/*",    # Store in dockerhub-cache namespace
294
    credential_set_resource_id="/subscriptions/sub-id/resourceGroups/rg/providers/Microsoft.ContainerRegistry/registries/my-registry/credentialSets/dockerhub-creds"
295
)
296

297
cache_rule = client.cache_rules.begin_create(
298
    "my-resource-group",
299
    "my-registry",
300
    "dockerhub-cache",
301
    dockerhub_cache_rule
302
).result()
303

304
print(f"Created cache rule: {cache_rule.name}")
305
print(f"Source: {cache_rule.source_repository}")
306
print(f"Target: {cache_rule.target_repository}")
307
```
308

309
### Create Credential Set for Private Registry
310

311
```python
312
from azure.mgmt.containerregistry.models import (
313
    CredentialSet, AuthCredential, CredentialName, IdentityProperties, ResourceIdentityType
314
)
315

316
# Create credential set for accessing private registry
317
credential_set_params = CredentialSet(
318
    identity=IdentityProperties(
319
        type=ResourceIdentityType.SYSTEM_ASSIGNED
320
    ),
321
    login_server="private-registry.company.com",
322
    auth_credentials=[
323
        AuthCredential(
324
            name=CredentialName.CREDENTIAL1,
325
            username_secret_identifier="https://myvault.vault.azure.net/secrets/registry-username",
326
            password_secret_identifier="https://myvault.vault.azure.net/secrets/registry-password"
327
        )
328
    ]
329
)
330

331
credential_set = client.credential_sets.begin_create(
332
    "my-resource-group",
333
    "my-registry",
334
    "private-registry-creds",
335
    credential_set_params
336
).result()
337

338
print(f"Created credential set: {credential_set.name}")
339
print(f"Login server: {credential_set.login_server}")
340
```
341

342
### Set Up Comprehensive Caching Strategy
343

344
```python
345
# Create multiple cache rules for different upstream registries
346
cache_configurations = [
347
    {
348
        "name": "dockerhub-official",
349
        "source": "docker.io/library/*",
350
        "target": "cache/dockerhub/*",
351
        "credential_set": None  # Docker Hub public images
352
    },
353
    {
354
        "name": "mcr-dotnet",
355
        "source": "mcr.microsoft.com/dotnet/*",
356
        "target": "cache/mcr-dotnet/*", 
357
        "credential_set": None  # Microsoft Container Registry public
358
    },
359
    {
360
        "name": "quay-bitnami",
361
        "source": "quay.io/bitnami/*",
362
        "target": "cache/bitnami/*",
363
        "credential_set": "/subscriptions/sub-id/resourceGroups/rg/providers/Microsoft.ContainerRegistry/registries/my-registry/credentialSets/quay-creds"
364
    },
365
    {
366
        "name": "private-company",
367
        "source": "company-registry.local/*",
368
        "target": "cache/company/*",
369
        "credential_set": "/subscriptions/sub-id/resourceGroups/rg/providers/Microsoft.ContainerRegistry/registries/my-registry/credentialSets/company-creds"
370
    }
371
]
372

373
created_cache_rules = []
374

375
for config in cache_configurations:
376
    cache_rule_params = CacheRule(
377
        source_repository=config["source"],
378
        target_repository=config["target"],
379
        credential_set_resource_id=config["credential_set"]
380
    )
381
    
382
    cache_rule = client.cache_rules.begin_create(
383
        "my-resource-group",
384
        "my-registry",
385
        config["name"],
386
        cache_rule_params
387
    ).result()
388
    
389
    created_cache_rules.append(cache_rule)
390
    print(f"Created cache rule '{config['name']}': {config['source']} -> {config['target']}")
391

392
print(f"\nTotal cache rules created: {len(created_cache_rules)}")
393
```
394

395
### Monitor Credential Health
396

397
```python
398
# List all credential sets and check their health
399
credential_sets = client.credential_sets.list("my-resource-group", "my-registry")
400

401
print("Credential Set Health Report:")
402
print("-" * 50)
403
for cred_set in credential_sets:
404
    print(f"Credential Set: {cred_set.name}")
405
    print(f"  Login Server: {cred_set.login_server}")
406
    print(f"  Provisioning State: {cred_set.provisioning_state}")
407
    
408
    if cred_set.auth_credentials:
409
        for auth_cred in cred_set.auth_credentials:
410
            print(f"  Credential {auth_cred.name}:")
411
            if auth_cred.credential_health:
412
                print(f"    Health: {auth_cred.credential_health.status}")
413
                if auth_cred.credential_health.status == CredentialHealthStatus.UNHEALTHY:
414
                    print(f"    Error: {auth_cred.credential_health.error_message}")
415
            else:
416
                print(f"    Health: Not available")
417
    print()
418
```
419

420
### Update Credential Set with New Credentials
421

422
```python
423
from azure.mgmt.containerregistry.models import CredentialSetUpdateParameters
424

425
# Update credential set with new Key Vault secret identifiers
426
update_params = CredentialSetUpdateParameters(
427
    auth_credentials=[
428
        AuthCredential(
429
            name=CredentialName.CREDENTIAL1,
430
            username_secret_identifier="https://myvault.vault.azure.net/secrets/new-registry-username",
431
            password_secret_identifier="https://myvault.vault.azure.net/secrets/new-registry-password"
432
        )
433
    ]
434
)
435

436
updated_cred_set = client.credential_sets.begin_update(
437
    "my-resource-group",
438
    "my-registry",
439
    "private-registry-creds",
440
    update_params
441
).result()
442

443
print(f"Updated credential set: {updated_cred_set.name}")
444
print("New credential identifiers configured")
445
```
446

447
### Cache Performance Analysis
448

449
```python
450
def analyze_cache_performance(client, resource_group, registry_name):
451
    """
452
    Analyze cache rule performance and usage.
453
    """
454
    
455
    cache_rules = list(client.cache_rules.list(resource_group, registry_name))
456
    
457
    analysis = {
458
        "total_cache_rules": len(cache_rules),
459
        "active_rules": 0,
460
        "failed_rules": 0,
461
        "rules_by_source": {},
462
        "credential_usage": {}
463
    }
464
    
465
    for rule in cache_rules:
466
        # Count by provisioning state
467
        if rule.provisioning_state == ProvisioningState.SUCCEEDED:
468
            analysis["active_rules"] += 1
469
        elif rule.provisioning_state == ProvisioningState.FAILED:
470
            analysis["failed_rules"] += 1
471
        
472
        # Group by source domain
473
        source_domain = rule.source_repository.split('/')[0]
474
        if source_domain not in analysis["rules_by_source"]:
475
            analysis["rules_by_source"][source_domain] = []
476
        analysis["rules_by_source"][source_domain].append(rule.name)
477
        
478
        # Track credential set usage
479
        if rule.credential_set_resource_id:
480
            cred_set_name = rule.credential_set_resource_id.split('/')[-1]
481
            if cred_set_name not in analysis["credential_usage"]:
482
                analysis["credential_usage"][cred_set_name] = []
483
            analysis["credential_usage"][cred_set_name].append(rule.name)
484
    
485
    return analysis
486

487
# Analyze cache performance
488
performance = analyze_cache_performance(
489
    client,
490
    "my-resource-group", 
491
    "my-registry"
492
)
493

494
print("Cache Performance Analysis:")
495
print("=" * 40)
496
print(f"Total Cache Rules: {performance['total_cache_rules']}")
497
print(f"Active Rules: {performance['active_rules']}")
498
print(f"Failed Rules: {performance['failed_rules']}")
499

500
print("\nRules by Source Registry:")
501
for source, rules in performance["rules_by_source"].items():
502
    print(f"  {source}: {len(rules)} rules")
503

504
print("\nCredential Set Usage:")
505
for cred_set, rules in performance["credential_usage"].items():
506
    print(f"  {cred_set}: used by {len(rules)} rules")
507
```
508

509
### Automated Cache Rule Management
510

511
```python
512
def setup_cache_infrastructure(client, resource_group, registry_name, cache_config):
513
    """
514
    Set up comprehensive cache infrastructure with credential sets and cache rules.
515
    """
516
    
517
    created_resources = {
518
        "credential_sets": [],
519
        "cache_rules": []
520
    }
521
    
522
    # Create credential sets first
523
    for cred_config in cache_config.get("credential_sets", []):
524
        credential_set_params = CredentialSet(
525
            identity=IdentityProperties(type=ResourceIdentityType.SYSTEM_ASSIGNED),
526
            login_server=cred_config["login_server"],
527
            auth_credentials=[
528
                AuthCredential(
529
                    name=CredentialName.CREDENTIAL1,
530
                    username_secret_identifier=cred_config["username_secret"],
531
                    password_secret_identifier=cred_config["password_secret"]
532
                )
533
            ]
534
        )
535
        
536
        cred_set = client.credential_sets.begin_create(
537
            resource_group,
538
            registry_name,
539
            cred_config["name"],
540
            credential_set_params
541
        ).result()
542
        
543
        created_resources["credential_sets"].append(cred_set)
544
        print(f"Created credential set: {cred_set.name}")
545
    
546
    # Create cache rules
547
    for cache_config_rule in cache_config.get("cache_rules", []):
548
        # Build credential set resource ID if specified
549
        credential_set_id = None
550
        if cache_config_rule.get("credential_set"):
551
            credential_set_id = f"/subscriptions/{client._config.subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.ContainerRegistry/registries/{registry_name}/credentialSets/{cache_config_rule['credential_set']}"
552
        
553
        cache_rule_params = CacheRule(
554
            source_repository=cache_config_rule["source"],
555
            target_repository=cache_config_rule["target"],
556
            credential_set_resource_id=credential_set_id
557
        )
558
        
559
        cache_rule = client.cache_rules.begin_create(
560
            resource_group,
561
            registry_name,
562
            cache_config_rule["name"],
563
            cache_rule_params
564
        ).result()
565
        
566
        created_resources["cache_rules"].append(cache_rule)
567
        print(f"Created cache rule: {cache_rule.name}")
568
    
569
    return created_resources
570

571
# Example cache infrastructure configuration
572
cache_infrastructure_config = {
573
    "credential_sets": [
574
        {
575
            "name": "dockerhub-pro-creds",
576
            "login_server": "registry-1.docker.io",
577
            "username_secret": "https://myvault.vault.azure.net/secrets/dockerhub-username",
578
            "password_secret": "https://myvault.vault.azure.net/secrets/dockerhub-password"
579
        },
580
        {
581
            "name": "quay-creds",
582
            "login_server": "quay.io",
583
            "username_secret": "https://myvault.vault.azure.net/secrets/quay-username",
584
            "password_secret": "https://myvault.vault.azure.net/secrets/quay-password"
585
        }
586
    ],
587
    "cache_rules": [
588
        {
589
            "name": "dockerhub-official-cache",
590
            "source": "docker.io/library/*",
591
            "target": "cache/dockerhub-official/*",
592
            "credential_set": None
593
        },
594
        {
595
            "name": "dockerhub-pro-cache", 
596
            "source": "docker.io/company/*",
597
            "target": "cache/dockerhub-company/*",
598
            "credential_set": "dockerhub-pro-creds"
599
        },
600
        {
601
            "name": "quay-bitnami-cache",
602
            "source": "quay.io/bitnami/*",
603
            "target": "cache/bitnami/*",
604
            "credential_set": "quay-creds"
605
        }
606
    ]
607
}
608

609
# Set up the cache infrastructure
610
infrastructure = setup_cache_infrastructure(
611
    client,
612
    "my-resource-group",
613
    "my-registry",
614
    cache_infrastructure_config
615
)
616

617
print(f"\nCache infrastructure setup completed:")
618
print(f"  Credential sets: {len(infrastructure['credential_sets'])}")
619
print(f"  Cache rules: {len(infrastructure['cache_rules'])}")
620
```
621

622
### Clean Up Cache Resources
623

624
```python
625
# Clean up cache rules and credential sets
626
def cleanup_cache_resources(client, resource_group, registry_name):
627
    """
628
    Clean up all cache-related resources.
629
    """
630
    
631
    # Delete all cache rules first
632
    cache_rules = list(client.cache_rules.list(resource_group, registry_name))
633
    for rule in cache_rules:
634
        try:
635
            client.cache_rules.begin_delete(
636
                resource_group,
637
                registry_name,
638
                rule.name
639
            ).result()
640
            print(f"Deleted cache rule: {rule.name}")
641
        except Exception as e:
642
            print(f"Failed to delete cache rule {rule.name}: {e}")
643
    
644
    # Then delete credential sets
645
    credential_sets = list(client.credential_sets.list(resource_group, registry_name))
646
    for cred_set in credential_sets:
647
        try:
648
            client.credential_sets.begin_delete(
649
                resource_group,
650
                registry_name,
651
                cred_set.name
652
            ).result()
653
            print(f"Deleted credential set: {cred_set.name}")
654
        except Exception as e:
655
            print(f"Failed to delete credential set {cred_set.name}: {e}")
656

657
# Example cleanup
658
cleanup_cache_resources(client, "my-resource-group", "my-registry")
659
```