diff --git a/README.md b/README.md index 74ba62eeffd8..1bf1f582e4fa 100644 --- a/README.md +++ b/README.md @@ -3,42 +3,33 @@ [![godoc](https://godoc.org/github.com/Azure/azure-sdk-for-go?status.svg)](https://godoc.org/github.com/Azure/azure-sdk-for-go) [![Build Status](https://dev.azure.com/azure-sdk/public/_apis/build/status/go/Azure.azure-sdk-for-go?branchName=main)](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=640&branchName=main) -azure-sdk-for-go provides Go packages for managing and using Azure services. -It officially supports the last two major releases of Go. Older versions of -Go will be kept running in CI until they no longer work due to changes in any -of the SDK's external dependencies. The CHANGELOG will be updated when a -version of Go is removed from CI. +This repository is for active development of the Azure SDK for Go. For consumers of the SDK you can follow the links below to visit the documentation you are interested in +* [Overview of Azure SDK for Go](https://docs.microsoft.com/azure/developer/go/) +* [SDK Reference](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go) +* [Code Samples for Azure Go SDK](https://github.com/azure-samples/azure-sdk-for-go-samples) +* [Azure REST API Docs](https://docs.microsoft.com/rest/api/) +* [General Azure Docs](https://docs.microsoft.com/azure) -To be notified about updates and changes, subscribe to the [Azure update -feed](https://azure.microsoft.com/updates/). -Users may prefer to jump right in to our samples repo at -[github.com/Azure-Samples/azure-sdk-for-go-samples][samples_repo]. +## New Releases -Questions and feedback? Chat with us in the **[#Azure SDK -channel](https://gophers.slack.com/messages/CA7HK8EEP)** on the [Gophers -Slack](https://gophers.slack.com/). Sign up -[here](https://invite.slack.golangbridge.org) first if necessary. +A new set of management libraries for Go that follow the [Azure SDK Design Guidelines for Go](https://azure.github.io/azure-sdk/golang_introduction.html) are now available. These new libraries provide a number of core capabilities that are shared amongst all Azure SDKs, including the intuitive Azure Identity library, an HTTP Pipeline with custom policies, error-handling, distributed tracing, and much more. Those new libraries can be identified by locating them under the `/sdk` directory in the repo, and you can find the corresponding references [here](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk). +To get started, please follow the [quickstart guide here](https://aka.ms/azsdk/go/mgmt). To see the benefits of migrating to the new libraries, please visit this [migration guide](https://aka.ms/azsdk/go/mgmt/migration) that shows how to transition from older versions of libraries. -## Package Updates +You can find the most up to date list of all of the new packages [on this page](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk) as well as our [official releases page](https://azure.github.io/azure-sdk/releases/latest/go.html) -Most packages in the SDK are generated from [Azure API specs][azure_rest_specs] -using [Azure/autorest.go][] and [Azure/autorest][]. These generated packages -depend on the HTTP client implemented at [Azure/go-autorest][]. +## Previous Versions -[azure_rest_specs]: https://github.com/Azure/azure-rest-api-specs -[azure/autorest]: https://github.com/Azure/autorest -[azure/autorest.go]: https://github.com/Azure/autorest.go -[azure/go-autorest]: https://github.com/Azure/go-autorest +Previous Go SDK packages are located under [/services folder](https://github.com/Azure/azure-sdk-for-go/tree/master/services), and you can see the full list [on this page](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/services). They might not have the same feature set as the new releases but they do offer wider coverage of services. -The SDK codebase adheres to [semantic versioning](https://semver.org) and thus -avoids breaking changes other than at major (x.0.0) releases. Because Azure's -APIs are updated frequently, we release a **new major version at the end of -each month** with a full changelog. For more details and background see [SDK Update -Practices](https://github.com/Azure/azure-sdk-for-go/wiki/SDK-Update-Practices). -Packages that are still in public preview can be found under the `services/preview` directory. Please be aware that since these packages are in preview they are subject to change, including breaking changes, outside of a major semver bump. +## Getting Started + +For instructions and documentation on how to use our Azure SDK for Go, we have provided quick-start tutorials for both new and previous releases. + +* [Quickstart tutorial for new releases](https://aka.ms/azsdk/go/mgmt). Documentation is also available at each readme file of the individual module (Example: [Readme for Compute Module](https://github.com/Azure/azure-sdk-for-go/tree/master/sdk/compute/armcompute)) +* [Quickstart tutorial for previous versions](https://aka.ms/azsdk/go/mgmt/previous) ## Other Azure Go Packages @@ -54,516 +45,28 @@ If a package you need isn't available please open an issue and let us know. | Event Hubs | [github.com/Azure/azure-event-hubs-go](https://github.com/Azure/azure-event-hubs-go) | | Application Insights | [github.com/Microsoft/ApplicationInsights-go](https://github.com/Microsoft/ApplicationInsights-go) | -# Install and Use: - -## Install - -```sh -$ go get -u github.com/Azure/azure-sdk-for-go/... -``` - -and you should also make sure to include the minimum version of [`go-autorest`](https://github.com/Azure/go-autorest) that is specified in `Gopkg.toml` file. - - -If you need to install Go, follow [the official instructions](https://golang.org/dl/). - -## Use - -For many more scenarios and examples see -[Azure-Samples/azure-sdk-for-go-samples][samples_repo]. - -Apply the following general steps to use packages in this repo. For more on -authentication and the `Authorizer` interface see [the next -section](#authentication). - -1. Import a package from the [services][services_dir] directory. -2. Create and authenticate a client with a `New*Client` func, e.g. - `c := compute.NewVirtualMachinesClient(...)`. -3. Invoke API methods using the client, e.g. - `res, err := c.CreateOrUpdate(...)`. -4. Handle responses and errors. - -[services_dir]: https://github.com/Azure/azure-sdk-for-go/tree/main/services - -For example, to create a new virtual network (substitute your own values for -strings in angle brackets): - -```go -package main - -import ( - "context" - - "github.com/Azure/azure-sdk-for-go/services/network/mgmt/2017-09-01/network" - - "github.com/Azure/go-autorest/autorest/azure/auth" - "github.com/Azure/go-autorest/autorest/to" -) - -func main() { - // create a VirtualNetworks client - vnetClient := network.NewVirtualNetworksClient("") - - // create an authorizer from env vars or Azure Managed Service Idenity - authorizer, err := auth.NewAuthorizerFromEnvironment() - if err == nil { - vnetClient.Authorizer = authorizer - } - - // call the VirtualNetworks CreateOrUpdate API - vnetClient.CreateOrUpdate(context.Background(), - "", - "", - network.VirtualNetwork{ - Location: to.StringPtr(""), - VirtualNetworkPropertiesFormat: &network.VirtualNetworkPropertiesFormat{ - AddressSpace: &network.AddressSpace{ - AddressPrefixes: &[]string{"10.0.0.0/8"}, - }, - Subnets: &[]network.Subnet{ - { - Name: to.StringPtr(""), - SubnetPropertiesFormat: &network.SubnetPropertiesFormat{ - AddressPrefix: to.StringPtr("10.0.0.0/16"), - }, - }, - { - Name: to.StringPtr(""), - SubnetPropertiesFormat: &network.SubnetPropertiesFormat{ - AddressPrefix: to.StringPtr("10.1.0.0/16"), - }, - }, - }, - }, - }) -} -``` - -## Authentication - -Typical SDK operations must be authenticated and authorized. The _Authorizer_ -interface allows use of any auth style in requests, such as inserting an OAuth2 -Authorization header and bearer token received from Azure AD. - -The SDK itself provides a simple way to get an authorizer which first checks -for OAuth client credentials in environment variables and then falls back to -Azure's [Managed Service Identity](https://github.com/Azure/azure-sdk-for-go/) when available, e.g. when on an Azure -VM. The following snippet from [the previous section](#use) demonstrates -this helper. - -```go -import "github.com/Azure/go-autorest/autorest/azure/auth" - -// create a VirtualNetworks client -vnetClient := network.NewVirtualNetworksClient("") - -// create an authorizer from env vars or Azure Managed Service Idenity -authorizer, err := auth.NewAuthorizerFromEnvironment() -if err == nil { - vnetClient.Authorizer = authorizer -} - -// call the VirtualNetworks CreateOrUpdate API -vnetClient.CreateOrUpdate(context.Background(), -// ... -``` - -The following environment variables help determine authentication configuration: - -- `AZURE_ENVIRONMENT`: Specifies the Azure Environment to use. If not set, it - defaults to `AzurePublicCloud`. Not applicable to authentication with Managed - Service Identity (MSI). -- `AZURE_AD_RESOURCE`: Specifies the AAD resource ID to use. If not set, it - defaults to `ResourceManagerEndpoint` for operations with Azure Resource - Manager. You can also choose an alternate resource programmatically with - `auth.NewAuthorizerFromEnvironmentWithResource(resource string)`. - -### More Authentication Details - -The previous is the first and most recommended of several authentication -options offered by the SDK because it allows seamless use of both service -principals and [Azure Managed Service Identity][]. Other options are listed -below. - -> Note: If you need to create a new service principal, run `az ad sp create-for-rbac -n ""` in the -> [azure-cli](https://github.com/Azure/azure-cli). See [these -> docs](https://docs.microsoft.com/cli/azure/create-an-azure-service-principal-azure-cli?view=azure-cli-latest) -> for more info. Copy the new principal's ID, secret, and tenant ID for use in -> your app, or consider the `--sdk-auth` parameter for serialized output. - -[azure managed service identity]: https://docs.microsoft.com/azure/active-directory/msi-overview - -- The `auth.NewAuthorizerFromEnvironment()` described above creates an authorizer - from the first available of the following configuration: - - 1. **Client Credentials**: Azure AD Application ID and Secret. - - - `AZURE_TENANT_ID`: Specifies the Tenant to which to authenticate. - - `AZURE_CLIENT_ID`: Specifies the app client ID to use. - - `AZURE_CLIENT_SECRET`: Specifies the app secret to use. - - 2. **Client Certificate**: Azure AD Application ID and X.509 Certificate. - - - `AZURE_TENANT_ID`: Specifies the Tenant to which to authenticate. - - `AZURE_CLIENT_ID`: Specifies the app client ID to use. - - `AZURE_CERTIFICATE_PATH`: Specifies the certificate Path to use. - - `AZURE_CERTIFICATE_PASSWORD`: Specifies the certificate password to use. - - 3. **Resource Owner Password**: Azure AD User and Password. This grant type is *not - recommended*, use device login instead if you need interactive login. - - - `AZURE_TENANT_ID`: Specifies the Tenant to which to authenticate. - - `AZURE_CLIENT_ID`: Specifies the app client ID to use. - - `AZURE_USERNAME`: Specifies the username to use. - - `AZURE_PASSWORD`: Specifies the password to use. - - 4. **Azure Managed Service Identity**: Delegate credential management to the - platform. Requires that code is running in Azure, e.g. on a VM. All - configuration is handled by Azure. See [Azure Managed Service - Identity](https://docs.microsoft.com/azure/active-directory/msi-overview) - for more details. - -- The `auth.NewAuthorizerFromFile()` method creates an authorizer using - credentials from an auth file created by the [Azure CLI][]. Follow these - steps to utilize: - - 1. Create a service principal and output an auth file using `az ad sp create-for-rbac --sdk-auth > client_credentials.json`. - 2. Set environment variable `AZURE_AUTH_LOCATION` to the path of the saved - output file. - 3. Use the authorizer returned by `auth.NewAuthorizerFromFile()` in your - client as described above. - -- The `auth.NewAuthorizerFromCLI()` method creates an authorizer which - uses [Azure CLI][] to obtain its credentials. - - The default audience being requested is `https://management.azure.com` (Azure ARM API). - To specify your own audience, export `AZURE_AD_RESOURCE` as an evironment variable. - This is read by `auth.NewAuthorizerFromCLI()` and passed to Azure CLI to acquire the access token. - - For example, to request an access token for Azure Key Vault, export - ``` - AZURE_AD_RESOURCE="https://vault.azure.net" - ``` - -- `auth.NewAuthorizerFromCLIWithResource(AUDIENCE_URL_OR_APPLICATION_ID)` - this method is self contained and does - not require exporting environment variables. For example, to request an access token for Azure Key Vault: - ``` - auth.NewAuthorizerFromCLIWithResource("https://vault.azure.net") - ``` - - To use `NewAuthorizerFromCLI()` or `NewAuthorizerFromCLIWithResource()`, follow these steps: - - 1. Install [Azure CLI v2.0.12](https://docs.microsoft.com/cli/azure/install-azure-cli) or later. Upgrade earlier versions. - 2. Use `az login` to sign in to Azure. - - If you receive an error, use `az account get-access-token` to verify access. - - If Azure CLI is not installed to the default directory, you may receive an error - reporting that `az` cannot be found. - Use the `AzureCLIPath` environment variable to define the Azure CLI installation folder. - - If you are signed in to Azure CLI using multiple accounts or your account has - access to multiple subscriptions, you need to specify the specific subscription - to be used. To do so, use: - - ``` - az account set --subscription - ``` - - To verify the current account settings, use: - - ``` - az account list - ``` - -[azure cli]: https://github.com/Azure/azure-cli - -- Finally, you can use OAuth's [Device Flow][] by calling - `auth.NewDeviceFlowConfig()` and extracting the Authorizer as follows: - - ```go - config := auth.NewDeviceFlowConfig(clientID, tenantID) - a, err := config.Authorizer() - ``` - -[device flow]: https://oauth.net/2/device-flow/ - -# Versioning - -azure-sdk-for-go provides at least a basic Go binding for every Azure API. To -provide maximum flexibility to users, the SDK even includes previous versions of -Azure APIs which are still in use. This enables us to support users of the -most updated Azure datacenters, regional datacenters with earlier APIs, and -even on-premises installations of Azure Stack. - -**SDK versions** apply globally and are tracked by git -[tags](https://github.com/Azure/azure-sdk-for-go/tags). These are in x.y.z form -and generally adhere to [semantic versioning](https://semver.org) specifications. - -**Service API versions** are generally represented by a date string and are -tracked by offering separate packages for each version. For example, to choose the -latest API versions for Compute and Network, use the following imports: - -```go -import ( - "github.com/Azure/azure-sdk-for-go/services/compute/mgmt/2017-12-01/compute" - "github.com/Azure/azure-sdk-for-go/services/network/mgmt/2017-09-01/network" -) -``` - -Occasionally service-side changes require major changes to existing versions. -These cases are noted in the changelog, and for this reason `Service API versions` -cannot be used alone to ensure backwards compatibility. - -All available services and versions are listed under the `services/` path in -this repo and in [GoDoc][services_godoc]. Run `find ./services -type d -mindepth 3` to list all available service packages. - -[services_godoc]: https://godoc.org/github.com/Azure/azure-sdk-for-go/services - -### Profiles - -Azure **API profiles** specify subsets of Azure APIs and versions. Profiles can provide: - -- **stability** for your application by locking to specific API versions; and/or -- **compatibility** for your application with Azure Stack and regional Azure datacenters. - -In the Go SDK, profiles are available under the `profiles/` path and their -component API versions are aliases to the true service package under -`services/`. You can use them as follows: - -```go -import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/compute/mgmt/compute" -import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/network/mgmt/network" -import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/storage/mgmt/storage" -``` - -The following profiles are available for hybrid Azure and Azure Stack environments. -- 2017-03-09 -- 2018-03-01 - -In addition to versioned profiles, we also provide two special profiles -`latest` and `preview`. The `latest` profile contains the latest API version -of each service, excluding any preview versions and/or content. The `preview` -profile is similar to the `latest` profile but includes preview API versions. - -The `latest` and `preview` profiles can help you stay up to date with API -updates as you build applications. Since they are by definition not stable, -however, they **should not** be used in production apps. Instead, choose the -latest specific API version (or an older one if necessary) from the `services/` -path. - -As an example, to automatically use the most recent Compute APIs, use one of -the following imports: - -```go -import "github.com/Azure/azure-sdk-for-go/profiles/latest/compute/mgmt/compute" -import "github.com/Azure/azure-sdk-for-go/profiles/preview/compute/mgmt/compute" -``` - -### Avoiding Breaking Changes - -To avoid breaking changes, when specifying imports you should specify a `Service API Version` or `Profile`, as well as lock (using [dep](https://github.com/golang/dep) and soon with [Go Modules](https://github.com/golang/go/wiki/Modules)) to a specific SDK version. - -For example, in your source code imports, use a `Service API Version` (`2017-12-01`): - -```go -import "github.com/Azure/azure-sdk-for-go/services/compute/mgmt/2017-12-01/compute" -``` - -or `Profile` version (`2017-03-09`): - -```go -import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/compute/mgmt/compute" -``` - -## Inspecting and Debugging - -### Built-in Basic Request/Response Logging - -Starting with `go-autorest v10.15.0` you can enable basic logging of requests and responses through setting environment variables. -Setting `AZURE_GO_SDK_LOG_LEVEL` to `INFO` will log request/response without their bodies. To include the bodies set the log level to `DEBUG`. - -By default the logger writes to stderr, however it can also write to stdout or a file -if specified in `AZURE_GO_SDK_LOG_FILE`. Note that if the specified file already exists it will be truncated. - -**IMPORTANT:** by default the logger will redact the Authorization and Ocp-Apim-Subscription-Key -headers. Any other secrets will _not_ be redacted. - -### Writing Custom Request/Response Inspectors - -All clients implement some handy hooks to help inspect the underlying requests being made to Azure. - -- `RequestInspector`: View and manipulate the go `http.Request` before it's sent -- `ResponseInspector`: View the `http.Response` received - -Here is an example of how these can be used with `net/http/httputil` to see requests and responses. - -```go -vnetClient := network.NewVirtualNetworksClient("") -vnetClient.RequestInspector = LogRequest() -vnetClient.ResponseInspector = LogResponse() - -// ... - -func LogRequest() autorest.PrepareDecorator { - return func(p autorest.Preparer) autorest.Preparer { - return autorest.PreparerFunc(func(r *http.Request) (*http.Request, error) { - r, err := p.Prepare(r) - if err != nil { - log.Println(err) - } - dump, _ := httputil.DumpRequestOut(r, true) - log.Println(string(dump)) - return r, err - }) - } -} - -func LogResponse() autorest.RespondDecorator { - return func(p autorest.Responder) autorest.Responder { - return autorest.ResponderFunc(func(r *http.Response) error { - err := p.Respond(r) - if err != nil { - log.Println(err) - } - dump, _ := httputil.DumpResponse(r, true) - log.Println(string(dump)) - return err - }) - } -} -``` - -## Tracing and Metrics - -All packages and the runtime are instrumented using [OpenCensus](https://opencensus.io/). - -### Enable - -By default, no tracing provider will be compiled into your program, and the legacy approach of setting `AZURE_SDK_TRACING_ENABLED` environment variable will no longer take effect. - -To enable tracing, you must now add the following include to your source file. - -``` go -import _ "github.com/Azure/go-autorest/tracing/opencensus" -``` - -To hook up a tracer simply call `tracing.Register()` passing in a type that satisfies the `tracing.Tracer` interface. - -**Note**: In future major releases of the SDK, tracing may become enabled by default. - -### Usage - -Once enabled, all SDK calls will emit traces and metrics and the traces will correlate the SDK calls with the raw http calls made to Azure API's. To consume those traces, if are not doing it yet, you need to register an exporter of your choice such as [Azure App Insights](https://docs.microsoft.com/azure/application-insights/opencensus-local-forwarder) or [Zipkin](https://opencensus.io/quickstart/go/tracing/#exporting-traces). - -To correlate the SDK calls between them and with the rest of your code, pass in a context that has a span initiated using the [opencensus-go library](https://github.com/census-instrumentation/opencensus-go) using the `trace.Startspan(ctx context.Context, name string, o ...StartOption)` function. Here is an example: - -```go -func doAzureCalls() { - // The resulting context will be initialized with a root span as the context passed to - // trace.StartSpan() has no existing span. - ctx, span := trace.StartSpan(context.Background(), "doAzureCalls", trace.WithSampler(trace.AlwaysSample())) - defer span.End() - - // The traces from the SDK calls will be correlated under the span inside the context that is passed in. - zone, _ := zonesClient.CreateOrUpdate(ctx, rg, zoneName, dns.Zone{Location: to.StringPtr("global")}, "", "") - zone, _ = zonesClient.Get(ctx, rg, *zone.Name) - for i := 0; i < rrCount; i++ { - rr, _ := recordsClient.CreateOrUpdate(ctx, rg, zoneName, fmt.Sprintf("rr%d", i), dns.CNAME, rdSet{ - RecordSetProperties: &dns.RecordSetProperties{ - TTL: to.Int64Ptr(3600), - CnameRecord: &dns.CnameRecord{ - Cname: to.StringPtr("vladdbCname"), - }, - }, - }, - "", - "", - ) - } -} -``` - -## Request Retry Policy - -The SDK provides a baked in retry policy for failed requests with default values that can be configured. -Each [client](https://godoc.org/github.com/Azure/go-autorest/autorest#Client) object contains the follow fields. -- `RetryAttempts` - the number of times to retry a failed request -- `RetryDuration` - the duration to wait between retries - -For async operations the follow values are also used. -- `PollingDelay` - the duration to wait between polling requests -- `PollingDuration` - the total time to poll an async request before timing out - -Please see the [documentation](https://godoc.org/github.com/Azure/go-autorest/autorest#pkg-constants) for the default values used. - -Changing one or more values will affect all subsequet API calls. - -The default policy is to call `autorest.DoRetryForStatusCodes()` from an API's `Sender` method. Example: -```go -func (client OperationsClient) ListSender(req *http.Request) (*http.Response, error) { - sd := autorest.GetSendDecorators(req.Context(), autorest.DoRetryForStatusCodes(client.RetryAttempts, client.RetryDuration, autorest.StatusCodesForRetry...)) - return autorest.SendWithSender(client, req, sd...) -} -``` - -Details on how `autorest.DoRetryforStatusCodes()` works can be found in the [documentation](https://godoc.org/github.com/Azure/go-autorest/autorest#DoRetryForStatusCodes). - -The slice of `SendDecorators` used in a `Sender` method can be customized per API call by smuggling them in the context. Here's an example. - -```go -ctx := context.Background() -autorest.WithSendDecorators(ctx, []autorest.SendDecorator{ - autorest.DoRetryForStatusCodesWithCap(client.RetryAttempts, - client.RetryDuration, time.Duration(0), - autorest.StatusCodesForRetry...)}) -client.List(ctx) -``` - -This will replace the default slice of `SendDecorators` with the provided slice. - -The `PollingDelay` and `PollingDuration` values are used exclusively by [WaitForCompletionRef()](https://godoc.org/github.com/Azure/go-autorest/autorest/azure#Future.WaitForCompletionRef) when blocking on an async call until it completes. - -# Resources +Packages that are still in public preview can be found under the `services/preview` directory. Please be aware that since these packages are in preview they are subject to change, including breaking changes, outside of a major semver bump. -- SDK docs are at [godoc.org](https://godoc.org/github.com/Azure/azure-sdk-for-go/). -- SDK samples are at [Azure-Samples/azure-sdk-for-go-samples](https://github.com/Azure-Samples/azure-sdk-for-go-samples). -- SDK notifications are published via the [Azure update feed](https://azure.microsoft.com/updates/). -- Azure API docs are at [docs.microsoft.com/rest/api](https://docs.microsoft.com/rest/api/). -- General Azure docs are at [docs.microsoft.com/azure](https://docs.microsoft.com/azure). +## Samples +[Samples_repo]: https://github.com/Azure-Samples/azure-sdk-for-go-samples ## Reporting security issues and security bugs Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) . You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the [Security TechCenter](https://www.microsoft.com/msrc/faqs-report-an-issue). -## License - -``` - The MIT License (MIT) +## Need help? - Copyright (c) 2021 Microsoft +* File an issue via [Github Issues](https://github.com/Azure/azure-sdk-for-go/issues) +* Check [previous questions](https://stackoverflow.com/questions/tagged/azure+go) or ask new ones on StackOverflow using `azure` and `go` tags. - Permission is hereby granted, free of charge, to any person obtaining a copy - of this software and associated documentation files (the "Software"), to deal - in the Software without restriction, including without limitation the rights - to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: +## Community - The above copyright notice and this permission notice shall be included in all - copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE. -``` +* Chat with us in the **[#Azure SDK +channel](https://gophers.slack.com/messages/CA7HK8EEP)** on the [Gophers +Slack](https://gophers.slack.com/). Sign up +[here](https://invite.slack.golangbridge.org) first if necessary. ## Contribute See [CONTRIBUTING.md](https://github.com/Azure/azure-sdk-for-go/blob/main/CONTRIBUTING.md). -[samples_repo]: https://github.com/Azure-Samples/azure-sdk-for-go-samples diff --git a/documentation/new-version-quickstart.md b/documentation/new-version-quickstart.md new file mode 100644 index 000000000000..e7e94d4cfdd7 --- /dev/null +++ b/documentation/new-version-quickstart.md @@ -0,0 +1,366 @@ + +Getting Started - New Azure Go SDK +============================================================= + +We are excited to announce that a new set of management libraries are +now production-ready. Those packages share a number of new features +such as Azure Identity support, HTTP pipeline, error-handling.,etc, and +they also follow the new Azure SDK guidelines which create easy-to-use +APIs that are idiomatic, compatible, and dependable. + +You can find the full list of those new libraries +[here](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk) + +In this basic quickstart guide, we will walk you through how to +authenticate to Azure and start interacting with Azure resources. There are several possible approaches to +authentication. This document illustrates the most common scenario. + +Migration from older versions of Azure management libraries for Go +------------------------------------------------------------------ + +If you are an existing user of the older version of Azure management library for Go (packages that are located under [`/services`](https://github.com/Azure/azure-sdk-for-go/tree/main/services)), and you are looking for a migration guide to upgrade to the latest version of the SDK, please refer to [this migration guide](https://aka.ms/azsdk/go/mgmt/migration) for detailed instructions. + +Prerequisites +------------- + +You will need the following values to authenticate to Azure + +- **Subscription ID** +- **Client ID** +- **Client Secret** +- **Tenant ID** + +These values can be obtained from the portal, here's the instructions: + +### Get Subscription ID + +1. Login into your Azure account +2. Select Subscriptions in the left sidebar +3. Select whichever subscription is needed +4. Click on Overview +5. Copy the Subscription ID + +### Get Client ID / Client Secret / Tenant ID + +For information on how to get Client ID, Client Secret, and Tenant ID, +please refer to [this document](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal) + +### Setting Environment Variables + +After you obtained the values, you need to set the following values as +your environment variables + +- `AZURE_CLIENT_ID` +- `AZURE_CLIENT_SECRET` +- `AZURE_TENANT_ID` +- `AZURE_SUBSCRIPTION_ID` + +To set the following environment variables on your development system: + +Windows (Note: Administrator access is required) + +1. Open the Control Panel +2. Click System Security, then System +3. Click Advanced system settings on the left +4. Inside the System Properties window, click the `Environment Variables…` button. +5. Click on the property you would like to change, then click the `Edit…` button. If the property name is not listed, then click the `New…` button. + +Linux-based OS : + + export AZURE_CLIENT_ID="__CLIENT_ID__" + export AZURE_CLIENT_SECRET="__CLIENT_SECRET__" + export AZURE_TENANT_ID="__TENANT_ID__" + export AZURE_SUBSCRIPTION_ID="__SUBSCRIPTION_ID__" + +Install the package +------------------- + +This project uses Go modules for versioning and dependency management. + +As an example, to install the Azure Compute module, you would run : + +```sh +go get github.com/Azure/azure-sdk-for-go/sdk/compute/armcompute +``` +We also recommend installing other packages for authentication and core functionalities : + +```sh +go get github.com/Azure/azure-sdk-for-go/sdk/armcore +go get github.com/Azure/azure-sdk-for-go/sdk/azcore +go get github.com/Azure/azure-sdk-for-go/sdk/azidentity +go get github.com/Azure/azure-sdk-for-go/sdk/to +``` + +Authentication +-------------- + +Once the environment is setup, all you need to do is to create an authenticated client. Before creating a client, you will first need to authenticate to Azure. In specific, you will need to provide a credential for authenticating with the Azure service. The `azidentity` module provides facilities for various ways of authenticating with Azure including client/secret, certificate, managed identity, and more. + +Our default option is to use **DefaultAzureCredential** which will make use of the environment variables we have set and take care of the authentication flow for us. + +```go +cred, err := azidentity.NewDefaultAzureCredential(nil) +``` + +For more details on how authentication works in `azidentity`, please see the documentation for `azidentity` at [pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity). + + +Connecting to Azure +------------------- + +Once you have a credential, create a connection to the desired ARM endpoint. The `armcore` module provides facilities for connecting with ARM endpoints including public and sovereign clouds as well as Azure Stack. + +```go +con := armcore.NewDefaultConnection(cred, nil) +``` + +For more information on ARM connections, please see the documentation for `armcore` at [pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/armcore](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/armcore). + +Creating a Resource Management Client +------------------------------------- + +Once you have a connection to ARM, you will need to decide what service to use and create a client to connect to that service. In this section, we will use `Compute` as our target service. The Compute modules consist of one or more clients. A client groups a set of related APIs, providing access to its functionality within the specified subscription. You will need to create one or more clients to access the APIs you require using your `armcore.Connection`. + +To show an example, we will create a client to manage Virtual Machines. The code to achieve this task would be: + +```go +client := armcompute.NewVirtualMachinesClient(con, "") +``` +You can use the same pattern to connect with other Azure services that you are using. For example, in order to manage Virtual Network resources, you would install the Network package and create a `VirtualNetwork` Client: + +```go +client := armnetwork.NewVirtualNetworksClient(acon, "") +``` + +Interacting with Azure Resources +-------------------------------- + +Now that we are authenticated and have created our sub-resource clients, we can use our client to make API calls. For resource management scenarios, most of our cases are centered around creating / updating / reading / deleting Azure resources. Those scenarios correspond to what we call "operations" in Azure. Once you are sure of which operations you want to call, you can then implement the operation call using the management client we just created in previous section. + +To write the concrete code for the API call, you might need to look up the information of request parameters, types, and response body for a certain opertaion. We recommend using the following site for SDK reference: + +- [Official Go docs for new Azure Go SDK packages](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk) - This web-site contains the complete SDK references for each released package as well as embedded code snippets for some operation + +To see the reference for a certain package, you can either click into each package on the web-site, or directly add the SDK path to the end of URL. For example, to see the reference for Azure Compute package, you can use [https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/compute/armcompute](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/compute/armcompute). Certain development tool or IDE has features that allow you to directly look up API definitions as well. + +Let's illustrate the SDK usage by a few quick examples. In the following sample. we are going to create a resource group using the SDK. To achieve this scenario, we can take the follow steps + +- **Step 1** : Decide which client we want to use, in our case, we know that it's related to Resource Group so our choice is the [ResourceGroupsClient](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/resources/armresources#ResourceGroupsClient) +- **Step 2** : Find out which operation is responsible for creating a resource group. By locating the client in previous step, we are able to see all the functions under `ResourceGroupsClient`, and we can see [the `CreateOrUpdate` function](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/resources/armresources#ResourceGroupsClient.CreateOrUpdate) is what need. +- **Step 3** : Using the information about this operation, we can then fill in the required parameters, and implement it using the Go SDK. If we need extra information on what those parameters mean, we can also use the [Azure service documentation](https://docs.microsoft.com/azure/?product=featured) on Microsoft Docs + +Let's show our what final code looks like + +Example: Creating a Resource Group +--------------------------------- + +***Import the packages*** +```go +import { + "github.com/Azure/azure-sdk-for-go/sdk/armcore" + "github.com/Azure/azure-sdk-for-go/sdk/resources/armresources" + "github.com/Azure/azure-sdk-for-go/sdk/azidentity" + "github.com/Azure/azure-sdk-for-go/sdk/to" +} +``` + +***Define some global variables*** +```go +var ( + ctx = context.Background() + subscriptionId = os.Getenv("AZURE_SUBSCRIPTION_ID") + location = "westus2" + resourceGroupName = "resourceGroupName" +) +``` + +***Write a function to create a resource group*** +```go +func createResourceGroup(ctx context.Context, connection *armcore.Connection) (armresources.ResourceGroupResponse, error) { + rgClient := armresources.NewResourceGroupsClient(connection, subscriptionId) + + param := armresources.ResourceGroup{ + Location: to.StringPtr(location), + } + + return rgClient.CreateOrUpdate(context.Backgroud(), resourceGroupName, param, nil) +} +``` + +***Invoking the `createResourceGroup` function in main*** +```go +func main() { + cred, err := azidentity.NewDefaultAzureCredential(nil) + if err != nil { + log.Fatalf("authentication failure: %+v", err) + } + conn := armcore.NewDefaultConnection(cred, &armcore.ConnectionOptions{ + Logging: azcore.LogOptions{ + IncludeBody: true, + }, + }) + + resourceGroup, err := createResourceGroup(ctx, conn) + if err != nil { + log.Fatalf("cannot create resource group: %+v", err) + } + log.Printf("Resource Group %s created", *resourceGroup.ID) +} +``` + +Let's demonstrate management client's usage by showing additional samples + +Example: Managing Resource Groups +--------------------------------- + +***Update a resource group*** + +```go +func updateResourceGroup(ctx context.Context, connection *armcore.Connection) (armresources.ResourceGroupResponse, error) { + rgClient := armresources.NewResourceGroupsClient(connection, subscriptionId) + + update := armresources.ResourceGroupPatchable{ + Tags: map[string]*string{ + "new": to.StringPtr("tag"), + }, + } + return rgClient.Update(ctx, resourceGroupName, update, nil) +} +``` + +***List all resource groups*** + +```go +func listResourceGroups(ctx context.Context, connection *armcore.Connection) ([]*armresources.ResourceGroup, error) { + rgClient := armresources.NewResourceGroupsClient(connection, subscriptionId) + + pager := rgClient.List(nil) + + var resourceGroups []*armresources.ResourceGroup + for pager.NextPage(ctx) { + resp := pager.PageResponse() + if resp.ResourceGroupListResult != nil { + resourceGroups = append(resourceGroups, resp.ResourceGroupListResult.Value...) + } + } + return resourceGroups, pager.Err() +} +``` + +***Delete a resource group*** + +```go +func deleteResourceGroup(ctx context.Context, connection *armcore.Connection) error { + rgClient := armresources.NewResourceGroupsClient(connection, subscriptionId) + + poller, err := rgClient.BeginDelete(ctx, resourceGroupName, nil) + if err != nil { + return err + } + if _, err := poller.PollUntilDone(ctx, interval); err != nil { + return err + } + return nil +} +``` + +***Invoking the update, list and delete of resource group in the main function*** +```go +func main() { + cred, err := azidentity.NewDefaultAzureCredential(nil) + if err != nil { + log.Fatalf("authentication failure: %+v", err) + } + conn := armcore.NewDefaultConnection(cred, &armcore.ConnectionOptions{ + Logging: azcore.LogOptions{ + IncludeBody: true, + }, + }) + + + resourceGroup, err := createResourceGroup(ctx, conn) + if err != nil { + log.Fatalf("cannot create resource group: %+v", err) + } + log.Printf("Resource Group %s created", *resourceGroup.ID) + + updatedRG, err := updateResourceGroup(ctx, conn) + if err != nil { + log.Fatalf("cannot update resource group: %+v", err) + } + log.Printf("Resource Group %s updated", *updatedRG.ID) + + rgList, err := listResourceGroups(ctx, conn) + if err != nil { + log.Fatalf("cannot list resource group: %+v", err) + } + log.Printf("We totally have %d resource groups", len(rgList)) + + if err := deleteResourceGroup(ctx, conn); err != nil { + log.Fatalf("cannot delete resource group: %+v", err) + } + log.Printf("Resource Group deleted") +}) +``` + +Example: Managing Virtual Machines +--------------------------------- +In addition to resource groups, we will also use Virtual Machine as an example and show how to manage how to create a Virtual Machine which involves three Azure services (Resource Group, Network and Compute) + +Due to the complexity of this scenario, please [click here](https://aka.ms/azsdk/go/mgmt/samples) for the complete sample. + +Long Running Operations +----------------------- +In the samples above, you might notice that some operations has a ``Begin`` prefix (for example, ``BeginDelete``). This indicates the operation is a Long-Running Operation (In short, LRO). For resource managment libraries, this kind of operation is quite common since certain resource operations may take a while to finish. When you need to use those LROs, you will need to use a poller and keep polling for the result until it is done. To illustrate this pattern, here is an example + +```go +poller, err := client.BeginCreate(context.Background(), "resource_identifier", "additonal_parameter") +if err != nil { + // handle error... +} +resp, err = poller.PollUntilDone(context.Background(), 5*time.Second) +if err != nil { + // handle error... +} +fmt.Printf("LRO done") +// dealing with `resp` +``` +Note that you will need to pass a polling interval to ```PollUntilDone``` and tell the poller how often it should try to get the status. This number is usually small but it's best to consult the [Azure service documentation](https://docs.microsoft.com/azure/?product=featured) on best practices and recommdend intervals for your specific use cases. + +For more advanced usage of LRO and design guidelines of LRO, please visit [this documentation here](https://azure.github.io/azure-sdk/golang_introduction.html#methods-invoking-long-running-operations) + +## Code Samples + +More code samples for using the management library for Go SDK can be found in the following locations +- [Go SDK Code Samples](https://aka.ms/azsdk/go/mgmt/samples) +- Example files under each package. For example, examples for Network packages can be [found here](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/network/armnetwork/example_networkinterfaces_test.go) + +Need help? +---------- + +- File an issue via [Github + Issues](https://github.com/Azure/azure-sdk-for-go/issues) +- Check [previous + questions](https://stackoverflow.com/questions/tagged/azure+go) + or ask new ones on StackOverflow using azure and Go tags. + +Contributing +------------ + +For details on contributing to this repository, see the contributing +guide. + +This project welcomes contributions and suggestions. Most contributions +require you to agree to a Contributor License Agreement (CLA) declaring +that you have the right to, and actually do, grant us the rights to use +your contribution. For details, visit . + +When you submit a pull request, a CLA-bot will automatically determine +whether you need to provide a CLA and decorate the PR appropriately +(e.g., label, comment). Simply follow the instructions provided by the +bot. You will only need to do this once across all repositories using +our CLA. + +This project has adopted the Microsoft Open Source Code of Conduct. For +more information see the Code of Conduct FAQ or contact + with any additional questions or comments. diff --git a/documentation/previous-versions-quickstart.md b/documentation/previous-versions-quickstart.md new file mode 100644 index 000000000000..107712ccf326 --- /dev/null +++ b/documentation/previous-versions-quickstart.md @@ -0,0 +1,531 @@ +# Azure SDK for Go - Previous Versions + +This guide is for developers who are using the old versions of Azure Go SDK. Those SDKs are located under +[services folder](https://github.com/Azure/azure-sdk-for-go/tree/master/services). + +## Package Updates + +Most packages in the SDK are generated from [Azure API specs][azure_rest_specs] +using [Azure/autorest.go][] and [Azure/autorest][]. These generated packages +depend on the HTTP client implemented at [Azure/go-autorest][]. + +[azure_rest_specs]: https://github.com/Azure/azure-rest-api-specs +[azure/autorest]: https://github.com/Azure/autorest +[azure/autorest.go]: https://github.com/Azure/autorest.go +[azure/go-autorest]: https://github.com/Azure/go-autorest + +The SDK codebase adheres to [semantic versioning](https://semver.org) and thus +avoids breaking changes other than at major (x.0.0) releases. Because Azure's +APIs are updated frequently, we release a **new major version at the end of +each month** with a full changelog. For more details and background see [SDK Update +Practices](https://github.com/Azure/azure-sdk-for-go/wiki/SDK-Update-Practices). + +To more reliably manage dependencies like the Azure SDK in your applications we +recommend [golang/dep](https://github.com/golang/dep). + +Packages that are still in public preview can be found under the ./services/preview +directory. Please be aware that since these packages are in preview they are subject +to change, including breaking changes outside of a major semver bump. + +# Install and Use: + +## Install + +```sh +$ go get -u github.com/Azure/azure-sdk-for-go/... +``` + +and you should also make sure to include the minimum version of [`go-autorest`](https://github.com/Azure/go-autorest) that is specified in `Gopkg.toml` file. + +Or if you use dep, within your repo run: + +```sh +$ dep ensure -add github.com/Azure/azure-sdk-for-go +``` + +If you need to install Go, follow [the official instructions](https://golang.org/dl/). + +## Use + +For many more scenarios and examples see +[Azure-Samples/azure-sdk-for-go-samples][samples_repo]. + +Apply the following general steps to use packages in this repo. For more on +authentication and the `Authorizer` interface see [the next +section](#authentication). + +1. Import a package from the [services][services_dir] directory. +2. Create and authenticate a client with a `New*Client` func, e.g. + `c := compute.NewVirtualMachinesClient(...)`. +3. Invoke API methods using the client, e.g. + `res, err := c.CreateOrUpdate(...)`. +4. Handle responses and errors. + +[services_dir]: https://github.com/Azure/azure-sdk-for-go/tree/master/services + +For example, to create a new virtual network (substitute your own values for +strings in angle brackets): + +```go +package main + +import ( + "context" + + "github.com/Azure/azure-sdk-for-go/services/network/mgmt/2017-09-01/network" + + "github.com/Azure/go-autorest/autorest/azure/auth" + "github.com/Azure/go-autorest/autorest/to" +) + +func main() { + // create a VirtualNetworks client + vnetClient := network.NewVirtualNetworksClient("") + + // create an authorizer from env vars or Azure Managed Service Idenity + authorizer, err := auth.NewAuthorizerFromEnvironment() + if err == nil { + vnetClient.Authorizer = authorizer + } + + // call the VirtualNetworks CreateOrUpdate API + vnetClient.CreateOrUpdate(context.Background(), + "", + "", + network.VirtualNetwork{ + Location: to.StringPtr(""), + VirtualNetworkPropertiesFormat: &network.VirtualNetworkPropertiesFormat{ + AddressSpace: &network.AddressSpace{ + AddressPrefixes: &[]string{"10.0.0.0/8"}, + }, + Subnets: &[]network.Subnet{ + { + Name: to.StringPtr(""), + SubnetPropertiesFormat: &network.SubnetPropertiesFormat{ + AddressPrefix: to.StringPtr("10.0.0.0/16"), + }, + }, + { + Name: to.StringPtr(""), + SubnetPropertiesFormat: &network.SubnetPropertiesFormat{ + AddressPrefix: to.StringPtr("10.1.0.0/16"), + }, + }, + }, + }, + }) +} +``` + +## Authentication + +Typical SDK operations must be authenticated and authorized. The _Authorizer_ +interface allows use of any auth style in requests, such as inserting an OAuth2 +Authorization header and bearer token received from Azure AD. + +The SDK itself provides a simple way to get an authorizer which first checks +for OAuth client credentials in environment variables and then falls back to +Azure's [Managed Service Identity](https://github.com/Azure/azure-sdk-for-go/) when available, e.g. when on an Azure +VM. The following snippet from [the previous section](#use) demonstrates +this helper. + +```go +import "github.com/Azure/go-autorest/autorest/azure/auth" + +// create a VirtualNetworks client +vnetClient := network.NewVirtualNetworksClient("") + +// create an authorizer from env vars or Azure Managed Service Idenity +authorizer, err := auth.NewAuthorizerFromEnvironment() +if err == nil { + vnetClient.Authorizer = authorizer +} + +// call the VirtualNetworks CreateOrUpdate API +vnetClient.CreateOrUpdate(context.Background(), +// ... +``` + +The following environment variables help determine authentication configuration: + +- `AZURE_ENVIRONMENT`: Specifies the Azure Environment to use. If not set, it + defaults to `AzurePublicCloud`. Not applicable to authentication with Managed + Service Identity (MSI). +- `AZURE_AD_RESOURCE`: Specifies the AAD resource ID to use. If not set, it + defaults to `ResourceManagerEndpoint` for operations with Azure Resource + Manager. You can also choose an alternate resource programmatically with + `auth.NewAuthorizerFromEnvironmentWithResource(resource string)`. + +### More Authentication Details + +The previous is the first and most recommended of several authentication +options offered by the SDK because it allows seamless use of both service +principals and [Azure Managed Service Identity][]. Other options are listed +below. + +> Note: If you need to create a new service principal, run `az ad sp create-for-rbac -n ""` in the +> [azure-cli](https://github.com/Azure/azure-cli). See [these +> docs](https://docs.microsoft.com/cli/azure/create-an-azure-service-principal-azure-cli?view=azure-cli-latest) +> for more info. Copy the new principal's ID, secret, and tenant ID for use in +> your app, or consider the `--sdk-auth` parameter for serialized output. + +[azure managed service identity]: https://docs.microsoft.com/azure/active-directory/msi-overview + +- The `auth.NewAuthorizerFromEnvironment()` described above creates an authorizer + from the first available of the following configuration: + + 1. **Client Credentials**: Azure AD Application ID and Secret. + + - `AZURE_TENANT_ID`: Specifies the Tenant to which to authenticate. + - `AZURE_CLIENT_ID`: Specifies the app client ID to use. + - `AZURE_CLIENT_SECRET`: Specifies the app secret to use. + + 2. **Client Certificate**: Azure AD Application ID and X.509 Certificate. + + - `AZURE_TENANT_ID`: Specifies the Tenant to which to authenticate. + - `AZURE_CLIENT_ID`: Specifies the app client ID to use. + - `AZURE_CERTIFICATE_PATH`: Specifies the certificate Path to use. + - `AZURE_CERTIFICATE_PASSWORD`: Specifies the certificate password to use. + + 3. **Resource Owner Password**: Azure AD User and Password. This grant type is *not + recommended*, use device login instead if you need interactive login. + + - `AZURE_TENANT_ID`: Specifies the Tenant to which to authenticate. + - `AZURE_CLIENT_ID`: Specifies the app client ID to use. + - `AZURE_USERNAME`: Specifies the username to use. + - `AZURE_PASSWORD`: Specifies the password to use. + + 4. **Azure Managed Service Identity**: Delegate credential management to the + platform. Requires that code is running in Azure, e.g. on a VM. All + configuration is handled by Azure. See [Azure Managed Service + Identity](https://docs.microsoft.com/azure/active-directory/msi-overview) + for more details. + +- The `auth.NewAuthorizerFromFile()` method creates an authorizer using + credentials from an auth file created by the [Azure CLI][]. Follow these + steps to utilize: + + 1. Create a service principal and output an auth file using `az ad sp create-for-rbac --sdk-auth > client_credentials.json`. + 2. Set environment variable `AZURE_AUTH_LOCATION` to the path of the saved + output file. + 3. Use the authorizer returned by `auth.NewAuthorizerFromFile()` in your + client as described above. + +- The `auth.NewAuthorizerFromCLI()` method creates an authorizer which + uses [Azure CLI][] to obtain its credentials. + + The default audience being requested is `https://management.azure.com` (Azure ARM API). + To specify your own audience, export `AZURE_AD_RESOURCE` as an evironment variable. + This is read by `auth.NewAuthorizerFromCLI()` and passed to Azure CLI to acquire the access token. + + For example, to request an access token for Azure Key Vault, export + ``` + AZURE_AD_RESOURCE="https://vault.azure.net" + ``` + +- `auth.NewAuthorizerFromCLIWithResource(AUDIENCE_URL_OR_APPLICATION_ID)` - this method is self contained and does + not require exporting environment variables. For example, to request an access token for Azure Key Vault: + ``` + auth.NewAuthorizerFromCLIWithResource("https://vault.azure.net") + ``` + + To use `NewAuthorizerFromCLI()` or `NewAuthorizerFromCLIWithResource()`, follow these steps: + + 1. Install [Azure CLI v2.0.12](https://docs.microsoft.com/cli/azure/install-azure-cli) or later. Upgrade earlier versions. + 2. Use `az login` to sign in to Azure. + + If you receive an error, use `az account get-access-token` to verify access. + + If Azure CLI is not installed to the default directory, you may receive an error + reporting that `az` cannot be found. + Use the `AzureCLIPath` environment variable to define the Azure CLI installation folder. + + If you are signed in to Azure CLI using multiple accounts or your account has + access to multiple subscriptions, you need to specify the specific subscription + to be used. To do so, use: + + ``` + az account set --subscription + ``` + + To verify the current account settings, use: + + ``` + az account list + ``` + +[azure cli]: https://github.com/Azure/azure-cli + +- Finally, you can use OAuth's [Device Flow][] by calling + `auth.NewDeviceFlowConfig()` and extracting the Authorizer as follows: + + ```go + config := auth.NewDeviceFlowConfig(clientID, tenantID) + a, err := config.Authorizer() + ``` + +[device flow]: https://oauth.net/2/device-flow/ + +# Versioning + +azure-sdk-for-go provides at least a basic Go binding for every Azure API. To +provide maximum flexibility to users, the SDK even includes previous versions of +Azure APIs which are still in use. This enables us to support users of the +most updated Azure datacenters, regional datacenters with earlier APIs, and +even on-premises installations of Azure Stack. + +**SDK versions** apply globally and are tracked by git +[tags](https://github.com/Azure/azure-sdk-for-go/tags). These are in x.y.z form +and generally adhere to [semantic versioning](https://semver.org) specifications. + +**Service API versions** are generally represented by a date string and are +tracked by offering separate packages for each version. For example, to choose the +latest API versions for Compute and Network, use the following imports: + +```go +import ( + "github.com/Azure/azure-sdk-for-go/services/compute/mgmt/2017-12-01/compute" + "github.com/Azure/azure-sdk-for-go/services/network/mgmt/2017-09-01/network" +) +``` + +Occasionally service-side changes require major changes to existing versions. +These cases are noted in the changelog, and for this reason `Service API versions` +cannot be used alone to ensure backwards compatibility. + +All available services and versions are listed under the `services/` path in +this repo and in [GoDoc][services_godoc]. Run `find ./services -type d -mindepth 3` to list all available service packages. + +[services_godoc]: https://godoc.org/github.com/Azure/azure-sdk-for-go/services + +### Profiles + +Azure **API profiles** specify subsets of Azure APIs and versions. Profiles can provide: + +- **stability** for your application by locking to specific API versions; and/or +- **compatibility** for your application with Azure Stack and regional Azure datacenters. + +In the Go SDK, profiles are available under the `profiles/` path and their +component API versions are aliases to the true service package under +`services/`. You can use them as follows: + +```go +import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/compute/mgmt/compute" +import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/network/mgmt/network" +import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/storage/mgmt/storage" +``` + +The following profiles are available for hybrid Azure and Azure Stack environments. +- 2017-03-09 +- 2018-03-01 + +In addition to versioned profiles, we also provide two special profiles +`latest` and `preview`. The `latest` profile contains the latest API version +of each service, excluding any preview versions and/or content. The `preview` +profile is similar to the `latest` profile but includes preview API versions. + +The `latest` and `preview` profiles can help you stay up to date with API +updates as you build applications. Since they are by definition not stable, +however, they **should not** be used in production apps. Instead, choose the +latest specific API version (or an older one if necessary) from the `services/` +path. + +As an example, to automatically use the most recent Compute APIs, use one of +the following imports: + +```go +import "github.com/Azure/azure-sdk-for-go/profiles/latest/compute/mgmt/compute" +import "github.com/Azure/azure-sdk-for-go/profiles/preview/compute/mgmt/compute" +``` + +### Avoiding Breaking Changes + +To avoid breaking changes, when specifying imports you should specify a `Service API Version` or `Profile`, as well as lock (using [dep](https://github.com/golang/dep) and soon with [Go Modules](https://github.com/golang/go/wiki/Modules)) to a specific SDK version. + +For example, in your source code imports, use a `Service API Version` (`2017-12-01`): + +```go +import "github.com/Azure/azure-sdk-for-go/services/compute/mgmt/2017-12-01/compute" +``` + +or `Profile` version (`2017-03-09`): + +```go +import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/compute/mgmt/compute" +``` + +As well as, for dep, a `Gopkg.toml` file with: + +```toml +[[constraint]] + name = "github.com/Azure/azure-sdk-for-go" + version = "21.0.0" +``` + +Combined, these techniques will ensure that breaking changes should not occur. If you are extra sensitive to changes, adding an additional [version pin](https://golang.github.io/dep/docs/Gopkg.toml.html#version-rules) in your SDK Version should satisfy your needs: + +```toml +[[constraint]] + name = "github.com/Azure/azure-sdk-for-go" + version = "=21.3.0" +``` + +## Inspecting and Debugging + +### Built-in Basic Request/Response Logging + +Starting with `go-autorest v10.15.0` you can enable basic logging of requests and responses through setting environment variables. +Setting `AZURE_GO_SDK_LOG_LEVEL` to `INFO` will log request/response without their bodies. To include the bodies set the log level to `DEBUG`. + +By default the logger writes to stderr, however it can also write to stdout or a file +if specified in `AZURE_GO_SDK_LOG_FILE`. Note that if the specified file already exists it will be truncated. + +**IMPORTANT:** by default the logger will redact the Authorization and Ocp-Apim-Subscription-Key +headers. Any other secrets will _not_ be redacted. + +### Writing Custom Request/Response Inspectors + +All clients implement some handy hooks to help inspect the underlying requests being made to Azure. + +- `RequestInspector`: View and manipulate the go `http.Request` before it's sent +- `ResponseInspector`: View the `http.Response` received + +Here is an example of how these can be used with `net/http/httputil` to see requests and responses. + +```go +vnetClient := network.NewVirtualNetworksClient("") +vnetClient.RequestInspector = LogRequest() +vnetClient.ResponseInspector = LogResponse() + +// ... + +func LogRequest() autorest.PrepareDecorator { + return func(p autorest.Preparer) autorest.Preparer { + return autorest.PreparerFunc(func(r *http.Request) (*http.Request, error) { + r, err := p.Prepare(r) + if err != nil { + log.Println(err) + } + dump, _ := httputil.DumpRequestOut(r, true) + log.Println(string(dump)) + return r, err + }) + } +} + +func LogResponse() autorest.RespondDecorator { + return func(p autorest.Responder) autorest.Responder { + return autorest.ResponderFunc(func(r *http.Response) error { + err := p.Respond(r) + if err != nil { + log.Println(err) + } + dump, _ := httputil.DumpResponse(r, true) + log.Println(string(dump)) + return err + }) + } +} +``` + +## Tracing and Metrics + +All packages and the runtime are instrumented using [OpenCensus](https://opencensus.io/). + +### Enable + +By default, no tracing provider will be compiled into your program, and the legacy approach of setting `AZURE_SDK_TRACING_ENABLED` environment variable will no longer take effect. + +To enable tracing, you must now add the following include to your source file. + +``` go +import _ "github.com/Azure/go-autorest/tracing/opencensus" +``` + +To hook up a tracer simply call `tracing.Register()` passing in a type that satisfies the `tracing.Tracer` interface. + +**Note**: In future major releases of the SDK, tracing may become enabled by default. + +### Usage + +Once enabled, all SDK calls will emit traces and metrics and the traces will correlate the SDK calls with the raw http calls made to Azure API's. To consume those traces, if are not doing it yet, you need to register an exporter of your choice such as [Azure App Insights](https://docs.microsoft.com/azure/application-insights/opencensus-local-forwarder) or [Zipkin](https://opencensus.io/quickstart/go/tracing/#exporting-traces). + +To correlate the SDK calls between them and with the rest of your code, pass in a context that has a span initiated using the [opencensus-go library](https://github.com/census-instrumentation/opencensus-go) using the `trace.Startspan(ctx context.Context, name string, o ...StartOption)` function. Here is an example: + +```go +func doAzureCalls() { + // The resulting context will be initialized with a root span as the context passed to + // trace.StartSpan() has no existing span. + ctx, span := trace.StartSpan(context.Background(), "doAzureCalls", trace.WithSampler(trace.AlwaysSample())) + defer span.End() + + // The traces from the SDK calls will be correlated under the span inside the context that is passed in. + zone, _ := zonesClient.CreateOrUpdate(ctx, rg, zoneName, dns.Zone{Location: to.StringPtr("global")}, "", "") + zone, _ = zonesClient.Get(ctx, rg, *zone.Name) + for i := 0; i < rrCount; i++ { + rr, _ := recordsClient.CreateOrUpdate(ctx, rg, zoneName, fmt.Sprintf("rr%d", i), dns.CNAME, rdSet{ + RecordSetProperties: &dns.RecordSetProperties{ + TTL: to.Int64Ptr(3600), + CnameRecord: &dns.CnameRecord{ + Cname: to.StringPtr("vladdbCname"), + }, + }, + }, + "", + "", + ) + } +} +``` + +## Request Retry Policy + +The SDK provides a baked in retry policy for failed requests with default values that can be configured. +Each [client](https://godoc.org/github.com/Azure/go-autorest/autorest#Client) object contains the follow fields. +- `RetryAttempts` - the number of times to retry a failed request +- `RetryDuration` - the duration to wait between retries + +For async operations the follow values are also used. +- `PollingDelay` - the duration to wait between polling requests +- `PollingDuration` - the total time to poll an async request before timing out + +Please see the [documentation](https://godoc.org/github.com/Azure/go-autorest/autorest#pkg-constants) for the default values used. + +Changing one or more values will affect all subsequet API calls. + +The default policy is to call `autorest.DoRetryForStatusCodes()` from an API's `Sender` method. Example: +```go +func (client OperationsClient) ListSender(req *http.Request) (*http.Response, error) { + sd := autorest.GetSendDecorators(req.Context(), autorest.DoRetryForStatusCodes(client.RetryAttempts, client.RetryDuration, autorest.StatusCodesForRetry...)) + return autorest.SendWithSender(client, req, sd...) +} +``` + +Details on how `autorest.DoRetryforStatusCodes()` works can be found in the [documentation](https://godoc.org/github.com/Azure/go-autorest/autorest#DoRetryForStatusCodes). + +The slice of `SendDecorators` used in a `Sender` method can be customized per API call by smuggling them in the context. Here's an example. + +```go +ctx := context.Background() +autorest.WithSendDecorators(ctx, []autorest.SendDecorator{ + autorest.DoRetryForStatusCodesWithCap(client.RetryAttempts, + client.RetryDuration, time.Duration(0), + autorest.StatusCodesForRetry...)}) +client.List(ctx) +``` + +This will replace the default slice of `SendDecorators` with the provided slice. + +The `PollingDelay` and `PollingDuration` values are used exclusively by [WaitForCompletionRef()](https://godoc.org/github.com/Azure/go-autorest/autorest/azure#Future.WaitForCompletionRef) when blocking on an async call until it completes. + +# Resources + +- SDK docs are at [godoc.org](https://godoc.org/github.com/Azure/azure-sdk-for-go/). +- SDK samples are at [Azure-Samples/azure-sdk-for-go-samples](https://github.com/Azure-Samples/azure-sdk-for-go-samples). +- SDK notifications are published via the [Azure update feed](https://azure.microsoft.com/updates/). +- Azure API docs are at [docs.microsoft.com/rest/api](https://docs.microsoft.com/rest/api/). +- General Azure docs are at [docs.microsoft.com/azure](https://docs.microsoft.com/azure). + +## Reporting security issues and security bugs + +Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) . You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the [Security TechCenter](https://www.microsoft.com/msrc/faqs-report-an-issue).