Skip to content

Commit e56698f

Browse files
mccoypmccoyp
authored
Add secrets migration guide, fix sample/readme (Azure#15853)
1 parent f8e4255 commit e56698f

File tree

3 files changed

+221
-7
lines changed

3 files changed

+221
-7
lines changed

‎sdk/keyvault/azure-keyvault-certificates/migration_guide.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -126,12 +126,17 @@ If you would like to check the status of your certificate creation, you can call
126126
In `azure-keyvault` you could retrieve a certificate (as a `CertificateBundle`) by using `get_certificate` and specifying the desired vault endpoint, certificate name, and certificate version. You could retrieve the versions of a certificate with the `get_certificate_versions` method, which returned an iterator-like object.
127127

128128
```python
129-
certificate_versions = client.get_certificate_versions(
129+
from azure.keyvault import CertificateId
130+
131+
certificate_items = client.get_certificate_versions(
130132
vault_base_url="https://my-key-vault.vault.azure.net/",
131133
certificate_name="cert-name"
132134
)
133135

134-
for certificate_version in certificate_versions:
136+
for certificate_item in certificate_items:
137+
certificate_id = CertificateId(certificate_item.id)
138+
certificate_version = certificate_id.version
139+
135140
certificate = client.get_certificate(
136141
vault_base_url="https://my-key-vault.vault.azure.net/",
137142
certificate_name="cert-name",

‎sdk/keyvault/azure-keyvault-secrets/README.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Azure Key Vault Secret client library for Python
1+
# Azure Key Vault Secrets client library for Python
22
Azure Key Vault helps solve the following problems:
33

44
- Secrets management (this library) -
@@ -260,23 +260,26 @@ for secret_property in secret_properties:
260260
This library includes a complete async API supported on Python 3.5+. To use it, you must
261261
first install an async transport, such as [aiohttp](https://pypi.org/project/aiohttp/).
262262
See
263-
[azure-core documentation](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/README.md#transport)
263+
[azure-core documentation](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/CLIENT_LIBRARY_DEVELOPER.md#transport)
264264
for more information.
265265

266266
Async clients should be closed when they're no longer needed. Each async
267267
client is an async context manager and defines an async `close` method. For
268268
example:
269269

270270
```py
271-
from azure.keyvault.secrets import SecretClient
271+
from azure.identity.aio import DefaultAzureCredential
272+
from azure.keyvault.secrets.aio import SecretClient
273+
274+
credential = DefaultAzureCredential()
272275

273276
# call close when the client is no longer needed
274-
client = SecretClient()
277+
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
275278
...
276279
await client.close()
277280

278281
# alternatively, use the client as an async context manager
279-
client = SecretClient()
282+
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
280283
async with client:
281284
...
282285
```

‎sdk/keyvault/azure-keyvault-secrets/migration_guide.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# Guide for migrating to azure-keyvault-secrets from azure-keyvault
2+
3+
This guide is intended to assist in the migration to `azure-keyvault-secrets` from `azure-keyvault`. It will focus on side-by-side comparisons for similar operations between the two packages.
4+
5+
Familiarity with the `azure-keyvault` package is assumed. For those new to the Key Vault client library for Python, please refer to the [README for `azure-keyvault-secrets`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/keyvault/azure-keyvault-secrets/README.md) rather than this guide.
6+
7+
## Table of contents
8+
9+
* [Migration benefits](#migration-benefits)
10+
* [Important changes](#important-changes)
11+
- [Separate packages and clients](#separate-packages-and-clients)
12+
- [Client constructors](#client-constructors)
13+
- [Async operations](#async-operations)
14+
- [Set a secret](#set-a-secret)
15+
- [Retrieve a secret](#retrieve-a-secret)
16+
- [List properties of secrets](#list-properties-of-secrets)
17+
- [Delete a secret](#delete-a-secret)
18+
* [Additional samples](#additional-samples)
19+
20+
## Migration benefits
21+
22+
A natural question to ask when considering whether or not to adopt a new version or library is what the benefits of doing so would be. As Azure has matured and been embraced by a more diverse group of developers, we have been focused on learning the patterns and practices to best support developer productivity and to understand the gaps that the Python client libraries have.
23+
24+
There were several areas of consistent feedback expressed across the Azure client library ecosystem. One of the most important is that the client libraries for different Azure services have not had a consistent approach to organization, naming, and API structure. Additionally, many developers have felt that the learning curve was difficult, and the APIs did not offer a good, approachable, and consistent onboarding story for those learning Azure or exploring a specific Azure service.
25+
26+
To try and improve the development experience across Azure services, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/general_introduction.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [Python-specific guidelines](https://azure.github.io/azure-sdk/python_introduction.html) was also introduced to ensure that Python clients have a natural and idiomatic feel with respect to the Python ecosystem. Further details are available in the guidelines for those interested.
27+
28+
### Cross Service SDK improvements
29+
30+
The modern Key Vault client library also provides the ability to share in some of the cross-service improvements made to the Azure development experience, such as
31+
- using the new [`azure-identity`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/identity/azure-identity/README.md) library to share a single authentication approach between clients
32+
- a unified logging and diagnostics pipeline offering a common view of the activities across each of the client libraries
33+
34+
## Important changes
35+
36+
### Separate packages and clients
37+
38+
In the interest of simplifying the API `azure-keyvault` and `KeyVaultClient` were split into separate packages and clients:
39+
40+
- [`azure-keyvault-certificates`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/keyvault/azure-keyvault-certificates/README.md) contains `CertificateClient` for working with certificates.
41+
- [`azure-keyvault-keys`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/keyvault/azure-keyvault-keys/README.md) contains `KeyClient` for working with keys and `CryptographyClient` for performing cryptographic operations.
42+
- `azure-keyvault-secrets` contains `SecretClient` for working with secrets.
43+
44+
### Client constructors
45+
46+
Across all modern Azure client libraries, clients consistently take an endpoint or connection string along with token credentials. This differs from `KeyVaultClient`, which took an authentication delegate and could be used for multiple Key Vault endpoints.
47+
48+
#### Authenticating
49+
50+
Previously in `azure-keyvault` you could create a `KeyVaultClient` by using `ServicePrincipalCredentials` from `azure.common`:
51+
52+
```python
53+
from azure.common.credentials import ServicePrincipalCredentials
54+
from azure.keyvault import KeyVaultClient
55+
56+
credentials = ServicePrincipalCredentials(
57+
client_id="client id",
58+
secret="client secret",
59+
tenant="tenant id"
60+
)
61+
62+
client = KeyVaultClient(credentials)
63+
```
64+
65+
Now in `azure-keyvault-secrets` you can create a `SecretClient` using any credential from [`azure-identity`](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/identity/azure-identity/README.md). Below is an example using [`DefaultAzureCredential`](https://docs.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential?view=azure-python):
66+
67+
```python
68+
from azure.identity import DefaultAzureCredential
69+
from azure.keyvault.secrets import SecretClient
70+
71+
credential = DefaultAzureCredential()
72+
73+
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
74+
```
75+
76+
### Async operations
77+
78+
The modern `azure-keyvault-secrets` library includes a complete async API supported on Python 3.5+. To use it, you must first install an async transport, such as [aiohttp](https://pypi.org/project/aiohttp/). See [azure-core documentation](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/CLIENT_LIBRARY_DEVELOPER.md#transport) for more information.
79+
80+
Async operations are available on async clients, which should be closed when they're no longer needed. Each async client is an async context manager and defines an async `close` method. For example:
81+
82+
```python
83+
from azure.identity.aio import DefaultAzureCredential
84+
from azure.keyvault.secrets.aio import SecretClient
85+
86+
credential = DefaultAzureCredential()
87+
88+
# call close when the client is no longer needed
89+
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
90+
...
91+
await client.close()
92+
93+
# alternatively, use the client as an async context manager
94+
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
95+
async with client:
96+
...
97+
```
98+
99+
### Set a secret
100+
101+
In `azure-keyvault` you could set a secret by using `KeyVaultClient`'s `set_secret` method, which required a vault endpoint, secret name, and value. This method returned a `SecretBundle` containing the secret.
102+
103+
```python
104+
secret_bundle = client.set_secret(
105+
vault_base_url="https://my-key-vault.vault.azure.net/",
106+
secret_name="secret-name",
107+
value="secret-value"
108+
)
109+
secret_value = secret_bundle.value
110+
```
111+
112+
Now in `azure-keyvault-secrets` you can set a secret by using `set_secret` with a secret name and value. This returns the created secret (as a `KeyVaultSecret`).
113+
114+
```python
115+
secret = secret_client.set_secret(name="secret-name", value="secret-value")
116+
secret_value = secret.value
117+
```
118+
119+
### Retrieve a secret
120+
121+
In `azure-keyvault` you could retrieve a secret (in a `SecretBundle`) by using `get_secret` and specifying the desired vault endpoint, secret name, and secret version. You could retrieve the versions of a secret with the `get_secret_versions` method, which returned an iterator-like object.
122+
123+
```python
124+
from azure.keyvault import SecretId
125+
126+
secret_items = client.get_secret_versions(
127+
vault_base_url="https://my-key-vault.vault.azure.net/",
128+
secret_name="secret-name"
129+
)
130+
131+
for secret_item in secret_items:
132+
secret_id = SecretId(secret_item.id)
133+
secret_version = secret_id.version
134+
135+
secret_bundle = client.get_secret(
136+
vault_base_url="https://my-key-vault.vault.azure.net/",
137+
secret_name="secret-name",
138+
secret_version=secret_version
139+
)
140+
secret_value = secret_bundle.value
141+
```
142+
143+
Now in `azure-keyvault-secrets` you can retrieve the latest version of a secret (as a `KeyVaultSecret`) by using `get_secret` and providing a secret name.
144+
145+
```python
146+
secret = secret_client.get_secret(name="secret-name")
147+
148+
print(secret.name)
149+
print(secret.value)
150+
151+
# get the version of the secret
152+
secret_version = secret.properties.version
153+
```
154+
155+
### List properties of secrets
156+
157+
In `azure-keyvault` you could list the properties of secrets in a specified vault with the `get_secrets` method. This returned an iterator-like object containing `SecretItem` instances.
158+
159+
```python
160+
secrets = client.get_secrets(vault_base_url="https://my-key-vault.vault.azure.net/")
161+
162+
for secret in secrets:
163+
print(secret.attributes.content_type)
164+
```
165+
166+
Now in `azure-keyvault-secrets` you can list the properties of secrets in a vault with the `list_properties_of_secrets` method. This returns an iterator-like object containing `SecretProperties` instances.
167+
168+
```python
169+
secrets = secret_client.list_properties_of_secrets()
170+
171+
for secret in secrets:
172+
print(secret.name)
173+
print(secret.content_type)
174+
```
175+
176+
### Delete a secret
177+
178+
In `azure-keyvault` you could delete all versions of a secret with the `delete_secret` method. This returned information about the deleted secret (as a `DeletedSecretBundle`), but you could not poll the deletion operation to know when it completed. This would be valuable information if you intended to permanently delete the deleted secret with `purge_deleted_secret`.
179+
180+
```python
181+
deleted_secret = client.delete_secret(
182+
vault_base_url="https://my-key-vault.vault.azure.net/",
183+
secret_name="secret-name"
184+
)
185+
186+
# this purge would fail if deletion hadn't finished
187+
client.purge_deleted_secret(
188+
vault_base_url="https://my-key-vault.vault.azure.net/",
189+
secret_name="secret-name"
190+
)
191+
```
192+
193+
Now in `azure-keyvault-secrets` you can delete a secret with `begin_delete_secret`, which returns a long operation poller object that can be used to wait/check on the operation. Calling `result()` on the poller will return information about the deleted secret (as a `DeletedSecret`) without waiting for the operation to complete, but calling `wait()` will wait for the deletion to complete. Again, `purge_deleted_secret` will permanently delete your deleted secret and make it unrecoverable.
194+
195+
```python
196+
deleted_secret_poller = secret_client.begin_delete_secret(name="secret-name")
197+
deleted_secret = deleted_secret_poller.result()
198+
199+
deleted_secret_poller.wait()
200+
secret_client.purge_deleted_secret(name="secret-name")
201+
```
202+
203+
## Additional samples
204+
205+
* [Key Vault secrets samples for Python](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-secrets/samples)
206+
* [General Key Vault samples for Python](https://docs.microsoft.com/samples/browse/?products=azure-key-vault&languages=python)

0 commit comments

Comments
 (0)