armcore

README

Azure Resource Manager Core Client Module for Go

The armcore module provides functions and types for Go SDK ARM client modules. These modules follow the Azure SDK Design Guidelines for Go.

Getting started

This project uses Go modules for versioning and dependency management.

Typically, you will not need to explicitly install armcore as it will be installed as an ARM client module dependency. To add the latest version to your go.mod file, execute the following command.

go get -u github.com/Azure/azure-sdk-for-go/sdk/armcore

General documentation and examples can be found on pkg.go.dev.

Contributing

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 https://cla.microsoft.com.

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 repos 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 opencode@microsoft.com with any additional questions or comments.

Documentation

Overview

Package armcore provides connections and utilities for Go SDK ARM client modules.

All Azure Resource Manager clients require a Connection, which is simply a combination of the desired ARM endpoint and a pipeline for handling HTTP requests and responses.

To access the Azure public cloud, use the NewDefaultConnection() constructor with the required token credential. Module azidentity provides several methods for obtaining token credentials.

cred, _ := azidentity.NewDefaultAzureCredential(nil)
con := armcore.NewDefaultConnection(cred, nil)

When accessing clouds other than the Azure public cloud, use the NewConnection() constructor with the required ARM endpoint and token credential. The most common case is connecting to an Azure sovereign cloud or Azure Stack instance.

NewDefaultConnection() and NewConnection() are configured with the same pipeline thus have the same pipeline configuration options. Use the NewConnectionWithPipeline() constructor to create a connection that uses a custom azcore.Pipeline. Note that any custom pipeline will require at minimum an authentication policy obtained from a token credential in order to authenticate with ARM. See the implementation of NewConnection() for how to obtain a credential's authentication policy.

Index

• Constants
• func NewRPRegistrationPolicy(endpoint string, cred azcore.Credential, o *RegistrationOptions) azcore.Policy
• type Connection
  • func NewConnection(endpoint string, cred azcore.TokenCredential, options *ConnectionOptions) *Connection
  • func NewDefaultConnection(cred azcore.TokenCredential, options *ConnectionOptions) *Connection
  • func (c *Connection) Endpoint() string
  • func (c *Connection) Pipeline() azcore.Pipeline
• type ConnectionOptions
• type ErrorUnmarshaller
• type LROPoller
  • func NewLROPoller(pollerID string, finalState string, resp *azcore.Response, pl azcore.Pipeline, ...) (*LROPoller, error)
  • func NewLROPollerFromResumeToken(pollerID string, token string, pl azcore.Pipeline, eu ErrorUnmarshaller) (*LROPoller, error)
  • func (l *LROPoller) Done() bool
  • func (l *LROPoller) FinalResponse(ctx context.Context, respType interface{}) (*http.Response, error)
  • func (l *LROPoller) Poll(ctx context.Context) (*http.Response, error)
  • func (l *LROPoller) PollUntilDone(ctx context.Context, freq time.Duration, respType interface{}) (*http.Response, error)
  • func (l *LROPoller) ResumeToken() (string, error)
• type Provider
• type ProviderResponse
• type RegistrationOptions

Constants

const (
	// AzureChina is the Azure Resource Manager China cloud endpoint.
	AzureChina = "https://management.chinacloudapi.cn/"
	// AzureGermany is the Azure Resource Manager Germany cloud endpoint.
	AzureGermany = "https://management.microsoftazure.de/"
	// AzureGovernment is the Azure Resource Manager US government cloud endpoint.
	AzureGovernment = "https://management.usgovcloudapi.net/"
	// AzurePublicCloud is the Azure Resource Manager public cloud endpoint.
	AzurePublicCloud = "https://management.azure.com/"
)

const (
	// UserAgent is the string to be used in the user agent string when making requests.
	UserAgent = "armcore/" + Version

	// Version is the semantic version (see http://semver.org) of this module.
	Version = "v0.8.1"
)

const (
	// LogRPRegistration entries contain information specific to the automatic registration of an RP.
	// Entries of this classification are written IFF the policy needs to take any action.
	LogRPRegistration azcore.LogClassification = "RPRegistration"
)

Functions

func NewRPRegistrationPolicy

func NewRPRegistrationPolicy(endpoint string, cred azcore.Credential, o *RegistrationOptions) azcore.Policy

NewRPRegistrationPolicy creates a policy object configured using the specified endpoint, credentials and options. The policy controls if an unregistered resource provider should automatically be registered. See https://aka.ms/rps-not-found for more information. Pass nil to accept the default options; this is the same as passing a zero-value options.

Types

type Connection

type Connection struct {
	// contains filtered or unexported fields
}

Connection is a connection to an Azure Resource Manager endpoint. It contains the base ARM endpoint and a pipeline for making requests.

func NewConnection

func NewConnection(endpoint string, cred azcore.TokenCredential, options *ConnectionOptions) *Connection

NewConnection creates an instance of the Connection type with the specified endpoint. Use this when connecting to clouds other than the Azure public cloud (stack/sovereign clouds). Pass nil to accept the default options; this is the same as passing a zero-value options.

func NewDefaultConnection

func NewDefaultConnection(cred azcore.TokenCredential, options *ConnectionOptions) *Connection

NewDefaultConnection creates an instance of the Connection type using the AzurePublicCloud. Pass nil to accept the default options; this is the same as passing a zero-value options.

func (*Connection) Endpoint

func (c *Connection) Endpoint() string

Endpoint returns the connection's ARM endpoint.

func (*Connection) Pipeline

func (c *Connection) Pipeline() azcore.Pipeline

Pipeline returns the connection's pipeline.

type ConnectionOptions

type ConnectionOptions struct {
	// AuxiliaryTenants contains a list of additional tenants to be used to authenticate
	// across multiple tenants.
	AuxiliaryTenants []string

	// HTTPClient sets the transport for making HTTP requests.
	HTTPClient azcore.Transport

	// Retry configures the built-in retry policy behavior.
	Retry azcore.RetryOptions

	// Telemetry configures the built-in telemetry policy behavior.
	Telemetry azcore.TelemetryOptions

	// Logging configures the built-in logging policy behavior.
	Logging azcore.LogOptions

	// DisableRPRegistration disables the auto-RP registration policy.
	// The default value is false.
	DisableRPRegistration bool

	// PerCallPolicies contains custom policies to inject into the pipeline.
	// Each policy is executed once per request.
	PerCallPolicies []azcore.Policy

	// PerRetryPolicies contains custom policies to inject into the pipeline.
	// Each policy is executed once per request, and for each retry request.
	PerRetryPolicies []azcore.Policy
}

ConnectionOptions contains configuration settings for the connection's pipeline. All zero-value fields will be initialized with their default values.

type ErrorUnmarshaller

type ErrorUnmarshaller func(*azcore.Response) error

ErrorUnmarshaller is the func to invoke when the endpoint returns an error response that requires unmarshalling.

type LROPoller

type LROPoller struct {
	Pipeline azcore.Pipeline
	// contains filtered or unexported fields
}

LROPoller encapsulates state and logic for polling on long-running operations. NOTE: this is only meant for internal use in generated code.

func NewLROPoller

func NewLROPoller(pollerID string, finalState string, resp *azcore.Response, pl azcore.Pipeline, eu ErrorUnmarshaller) (*LROPoller, error)

NewLROPoller creates an LROPoller based on the provided initial response. pollerID - a unique identifier for an LRO. it's usually the client.Method string. NOTE: this is only meant for internal use in generated code.

func NewLROPollerFromResumeToken

func NewLROPollerFromResumeToken(pollerID string, token string, pl azcore.Pipeline, eu ErrorUnmarshaller) (*LROPoller, error)

NewLROPollerFromResumeToken creates an LROPoller from a resume token string. pollerID - a unique identifier for an LRO. it's usually the client.Method string. NOTE: this is only meant for internal use in generated code.

func (*LROPoller) Done

func (l *LROPoller) Done() bool

Done returns true if the LRO has reached a terminal state.

func (*LROPoller) FinalResponse

func (l *LROPoller) FinalResponse(ctx context.Context, respType interface{}) (*http.Response, error)

FinalResponse will perform a final GET request and return the final HTTP response for the polling operation and unmarshall the content of the payload into the respType interface that is provided.

func (*LROPoller) Poll

func (l *LROPoller) Poll(ctx context.Context) (*http.Response, error)

Poll sends a polling request to the polling endpoint and returns the response or error.

func (*LROPoller) PollUntilDone

func (l *LROPoller) PollUntilDone(ctx context.Context, freq time.Duration, respType interface{}) (*http.Response, error)

PollUntilDone will handle the entire span of the polling operation until a terminal state is reached, then return the final HTTP response for the polling operation and unmarshal the content of the payload into the respType interface that is provided. freq - the time to wait between polling intervals if the endpoint doesn't send a Retry-After header.

A good starting value is 30 seconds.  Note that some resources might benefit from a different value.

func (*LROPoller) ResumeToken

func (l *LROPoller) ResumeToken() (string, error)

ResumeToken returns a token string that can be used to resume a poller that has not yet reached a terminal state.

type Provider

type Provider struct {
	// The provider ID.
	ID *string `json:"id,omitempty"`

	// The namespace of the resource provider.
	Namespace *string `json:"namespace,omitempty"`

	// The registration policy of the resource provider.
	RegistrationPolicy *string `json:"registrationPolicy,omitempty"`

	// The registration state of the resource provider.
	RegistrationState *string `json:"registrationState,omitempty"`
}

Provider - Resource provider information.

type ProviderResponse

type ProviderResponse struct {
	// Resource provider information.
	Provider *Provider

	// RawResponse contains the underlying HTTP response.
	RawResponse *http.Response
}

ProviderResponse is the response envelope for operations that return a Provider type.

type RegistrationOptions

type RegistrationOptions struct {
	// MaxAttempts is the total number of times to attempt automatic registration
	// in the event that an attempt fails.
	// The default value is 3.
	// Set to a value less than zero to disable the policy.
	MaxAttempts int

	// PollingDelay is the amount of time to sleep between polling intervals.
	// The default value is 15 seconds.
	// A value less than zero means no delay between polling intervals (not recommended).
	PollingDelay time.Duration

	// PollingDuration is the amount of time to wait before abandoning polling.
	// The default valule is 5 minutes.
	// NOTE: Setting this to a small value might cause the policy to prematurely fail.
	PollingDuration time.Duration

	// HTTPClient sets the transport for making HTTP requests.
	HTTPClient azcore.Transport

	// Retry configures the built-in retry policy behavior.
	Retry azcore.RetryOptions

	// Telemetry configures the built-in telemetry policy behavior.
	Telemetry azcore.TelemetryOptions

	// Logging configures the built-in logging policy behavior.
	Logging azcore.LogOptions
}

RegistrationOptions configures the registration policy's behavior. All zero-value fields will be initialized with their default values.