-
Notifications
You must be signed in to change notification settings - Fork 836
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[keyvault] troubleshooting and migration guide (#23340)
- Loading branch information
1 parent
4299f74
commit 7902704
Showing
5 changed files
with
321 additions
and
18 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| # Troubleshoot Azure Key Vault Certificates Client Module Issues | ||
|
|
||
| See our [Azure Key Vault SDK Troubleshooting Guide](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/security/keyvault/TROUBLESHOOTING.md) | ||
| to troubleshoot issues common to Azure Key Vault client modules. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,95 @@ | ||
| # Guide to migrate from `keyvault` to `azcertificates` | ||
|
|
||
| This guide is intended to assist in the migration to the `azcertificates` module from the deprecated `keyvault` module. `azcertificates` allows users to create and manage [certificates][certificates] with Azure Key Vault. | ||
|
|
||
| ## General changes | ||
|
|
||
| In the past, Azure Key Vault operations were all contained in a single package. For Go, this was `github.com/Azure/azure-sdk-for-go/services/keyvault/<version>/keyvault`. | ||
|
|
||
| The new SDK divides the Key Vault API into separate modules for keys, secrets, and certificates. This guide focuses on migrating certificate operations to use the new `azcertificates` module. | ||
|
|
||
| There are other changes besides the module name. For example, some type and method names are different, and all new modules authenticate using our [azidentity] module. | ||
|
|
||
| ## Code example | ||
|
|
||
| The following code example shows the difference between the old and new modules when creating a certificate. The biggest differences are the client and authentication. In the `keyvault` module, users created a `keyvault.BaseClient` then added an `Authorizer` to the client to authenticate. In the `azcertificates` module, users create a credential using the [azidentity] module then use that credential to construct the client. | ||
|
|
||
| Another difference is that the Key Vault URL is now passed to the client once during construction, not every time a method is called. | ||
|
|
||
| ### `keyvault` create certificate | ||
| ```go | ||
| import ( | ||
| "context" | ||
| "fmt" | ||
|
|
||
| "github.com/Azure/azure-sdk-for-go/profiles/latest/keyvault/keyvault" | ||
| kvauth "github.com/Azure/azure-sdk-for-go/services/keyvault/auth" | ||
| ) | ||
|
|
||
| func main() { | ||
| vaultURL := "https://<TODO: your vault name>.vault.azure.net" | ||
| authorizer, err := kvauth.NewAuthorizerFromEnvironment() | ||
| if err != nil { | ||
| // TODO: handle error | ||
| } | ||
|
|
||
| basicClient := keyvault.New() | ||
| basicClient.Authorizer = authorizer | ||
|
|
||
| fmt.Println("\ncreating certificate in keyvault:") | ||
| issuerName := "self" | ||
| subject := "CN=DefaultPolicy" | ||
| createParams := keyvault.CertificateCreateParameters{ | ||
| CertificatePolicy: &keyvault.CertificatePolicy{ | ||
| IssuerParameters: &keyvault.IssuerParameters{Name: &issuerName}, | ||
| X509CertificateProperties: &keyvault.X509CertificateProperties{Subject: &subject}, | ||
| } | ||
| } | ||
| resp, err := basicClient.CreateCertificate(context.TODO(), vaultURL, "<cert name>", createParams) | ||
| if err != nil { | ||
| // TODO: handle error | ||
| } | ||
| fmt.Println("added/updated: " + *resp.ID) | ||
| } | ||
| ``` | ||
|
|
||
| ### `azcertificates` create certificate | ||
| ```go | ||
| import ( | ||
| "context" | ||
| "fmt" | ||
|
|
||
| "github.com/Azure/azure-sdk-for-go/sdk/azcore/to" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/azidentity" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azcertificates" | ||
| ) | ||
|
|
||
| func main() { | ||
| vaultURL := "https://<TODO: your vault name>.vault.azure.net" | ||
| cred, err := azidentity.NewDefaultAzureCredential(nil) | ||
| if err != nil { | ||
| // TODO: handle error | ||
| } | ||
|
|
||
| client, err := azcertificates.NewClient(vaultURL, cred, nil) | ||
| if err != nil { | ||
| // TODO: handle error | ||
| } | ||
|
|
||
| createParams := azcertificates.CreateCertificateParameters{ | ||
| CertificatePolicy: &azcertificates.CertificatePolicy{ | ||
| IssuerParameters: &azcertificates.IssuerParameters{Name: to.Ptr("self")}, | ||
| X509CertificateProperties: &azcertificates.X509CertificateProperties{Subject: to.Ptr("CN=DefaultPolicy")}, | ||
| }, | ||
| } | ||
| resp, err := client.CreateCertificate(context.TODO(), "<cert name>", createParams, nil) | ||
| if err != nil { | ||
| // TODO: handle error | ||
| } | ||
|
|
||
| fmt.Println("Created a certificate with ID:", *resp.ID) | ||
| } | ||
| ``` | ||
|
|
||
| [azidentity]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity | ||
| [certificates]: https://learn.microsoft.com/azure/key-vault/certificates/about-certificates |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,90 @@ | ||
| # Guide to migrate from `keyvault` to `azkeys` | ||
|
|
||
| This guide is intended to assist in the migration to the `azkeys` module from the deprecated `keyvault` module. `azkeys` allows users to create and manage [keys][keys] with Azure Key Vault. | ||
|
|
||
| ## General changes | ||
|
|
||
| In the past, Azure Key Vault operations were all contained in a single package. For Go, this was `github.com/Azure/azure-sdk-for-go/services/keyvault/<version>/keyvault`. | ||
|
|
||
| The new SDK divides the Key Vault API into separate modules for keys, secrets, and certificates. This guide focuses on migrating keys operations to use the new `azkeys` module. | ||
|
|
||
| There are other changes besides the module name. For example, some type and method names are different, and all new modules authenticate using our [azidentity] module. | ||
|
|
||
| ## Code examples | ||
|
|
||
| The following code example shows the difference between the old and new modules when creating a key. The biggest differences are the client and authentication. In the `keyvault` module, users created a `keyvault.BaseClient` then added an `Authorizer` to the client to authenticate. In the `azkeys` module, users create a credential using the [azidentity] module then use that credential to construct the client. | ||
|
|
||
| Another difference is that the Key Vault URL is now passed to the client once during construction, not every time a method is called. | ||
|
|
||
| ### `keyvault` create key | ||
| ```go | ||
| import ( | ||
| "context" | ||
| "fmt" | ||
|
|
||
| "github.com/Azure/azure-sdk-for-go/profiles/latest/keyvault/keyvault" | ||
| kvauth "github.com/Azure/azure-sdk-for-go/services/keyvault/auth" | ||
| ) | ||
|
|
||
| func main() { | ||
| vaultURL := "https://<TODO: your vault name>.vault.azure.net" | ||
| authorizer, err := kvauth.NewAuthorizerFromEnvironment() | ||
| if err != nil { | ||
| // TODO: handle error | ||
| } | ||
|
|
||
| basicClient := keyvault.New() | ||
| basicClient.Authorizer = authorizer | ||
|
|
||
| fmt.Println("\ncreating a key in keyvault:") | ||
| keyParams := keyvault.KeyCreateParameters{ | ||
| Curve: &keyvault.P256, | ||
| Kty: &keyvault.EC, | ||
| } | ||
| newBundle, err := basicClient.CreateKey(context.TODO(), vaultURL, "<key name>", keyParams) | ||
| if err != nil { | ||
| // TODO: handle error | ||
| } | ||
| fmt.Println("added/updated: " + *newBundle.JSONWebKey.Kid) | ||
| } | ||
| ``` | ||
|
|
||
| ### `azkeys` create key | ||
| ```go | ||
| package main | ||
|
|
||
| import ( | ||
| "context" | ||
| "fmt" | ||
|
|
||
| "github.com/Azure/azure-sdk-for-go/sdk/azcore/to" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/azidentity" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azkeys" | ||
| ) | ||
|
|
||
| func main() { | ||
| vaultURL := "https://<TODO: your vault name>.vault.azure.net" | ||
| cred, err := azidentity.NewDefaultAzureCredential(nil) | ||
| if err != nil { | ||
| // TODO: handle error | ||
| } | ||
|
|
||
| client, err := azkeys.NewClient(vaultURL, cred, nil) | ||
| if err != nil { | ||
| // TODO: handle error | ||
| } | ||
|
|
||
| keyParams := azkeys.CreateKeyParameters{ | ||
| Curve: to.Ptr(azkeys.CurveNameP256K), | ||
| Kty: to.Ptr(azkeys.KeyTypeEC), | ||
| } | ||
| resp, err := client.CreateKey(context.TODO(), "<key name>", keyParams, nil) | ||
| if err != nil { | ||
| // TODO: handle error | ||
| } | ||
| fmt.Println(*resp.Key.KID) | ||
| } | ||
| ``` | ||
|
|
||
| [azidentity]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity | ||
| [keys]: https://learn.microsoft.com/azure/key-vault/keys/about-keys |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| # Guide to migrate from `keyvault` to `azsecrets` | ||
|
|
||
| This guide is intended to assist in the migration to the `azsecrets` module from the deprecated `keyvault` module. `azsecrets` allows users to create and manage [secrets] with Azure Key Vault. | ||
|
|
||
| ## General changes | ||
|
|
||
| In the past, Azure Key Vault operations were all contained in a single package. For Go, this was `github.com/Azure/azure-sdk-for-go/services/keyvault/<version>/keyvault`. | ||
|
|
||
| The new SDK divides the Key Vault API into separate modules for keys, secrets, and certificates. This guide focuses on migrating secret operations to use the new `azsecrets` module. | ||
|
|
||
| There are other changes besides the module name. For example, some type and method names are different, and all new modules authenticate using our [azidentity] module. | ||
|
|
||
| ## Code examples | ||
|
|
||
| The following code example shows the difference between the old and new modules when creating a secret. The biggest differences are the client and authentication. In the `keyvault` module, users created a `keyvault.BaseClient` then added an `Authorizer` to the client to authenticate. In the `azsecrets` module, users create a credential using the [azidentity] module then use that credential to construct the client. | ||
|
|
||
| Another difference is that the Key Vault URL is now passed to the client once during construction, not every time a method is called. | ||
|
|
||
| ### `keyvault` create secret | ||
|
|
||
| ```go | ||
| import ( | ||
| "context" | ||
| "fmt" | ||
|
|
||
| "github.com/Azure/azure-sdk-for-go/profiles/latest/keyvault/keyvault" | ||
| kvauth "github.com/Azure/azure-sdk-for-go/services/keyvault/auth" | ||
| ) | ||
|
|
||
| func main() { | ||
| vaultURL := "https://<TODO: your vault name>.vault.azure.net" | ||
| secretName := "mySecret" | ||
| secretValue := "mySecretValue" | ||
|
|
||
| authorizer, err := kvauth.NewAuthorizerFromEnvironment() | ||
| if err != nil { | ||
| // TODO: handle error | ||
| } | ||
|
|
||
| basicClient := keyvault.New() | ||
| basicClient.Authorizer = authorizer | ||
|
|
||
| fmt.Println("\ncreating secret in keyvault:") | ||
| var secParams keyvault.SecretSetParameters | ||
| secParams.Value = &secretValue | ||
| newBundle, err := basicClient.SetSecret(context.Background(), vaultURL, secretName, secParams) | ||
| if err != nil { | ||
| // TODO: handle error | ||
| } | ||
| fmt.Println("added/updated: " + *newBundle.ID) | ||
| } | ||
| ``` | ||
|
|
||
| ### `azsecrets` create secret | ||
|
|
||
| ```go | ||
| package main | ||
|
|
||
| import ( | ||
| "context" | ||
| "fmt" | ||
|
|
||
| "github.com/Azure/azure-sdk-for-go/sdk/azidentity" | ||
| "github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets" | ||
| ) | ||
|
|
||
| func main() { | ||
| vaultURL := "https://<TODO: your vault name>.vault.azure.net" | ||
| secretName := "mySecret" | ||
| secretValue := "mySecretValue" | ||
|
|
||
| cred, err := azidentity.NewDefaultAzureCredential(nil) | ||
| if err != nil { | ||
| // TODO: handle error | ||
| } | ||
|
|
||
| client, err := azsecrets.NewClient(vaultURL, cred, nil) | ||
| if err != nil { | ||
| // TODO: handle error | ||
| } | ||
|
|
||
| resp, err := client.SetSecret(context.TODO(), secretName, azsecrets.SetSecretParameters{Value: &secretValue}, nil) | ||
| if err != nil { | ||
| // TODO: handle error | ||
| } | ||
|
|
||
| fmt.Printf("Set secret %s", resp.ID.Name()) | ||
| } | ||
| ``` | ||
|
|
||
| [azidentity]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity | ||
| [secrets]: https://learn.microsoft.com/azure/key-vault/secrets/about-secrets |