provisioning

package
v1.28.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 23, 2026 License: MIT Imports: 36 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// InfraProviderCustom is the infra.provider telemetry value recorded for a provider that is
	// not one of the built-in kinds (for example an extension-registered provider). The raw name
	// is never emitted because it may embed user-chosen project or organization identifiers.
	InfraProviderCustom = "custom"
)

Variables

View Source 
var (
	// ErrDeploymentInterruptedLeaveRunning is returned when the user chose to
	// stop azd but allow the in-flight Azure deployment to continue running.
	ErrDeploymentInterruptedLeaveRunning = errors.New(
		"azd was interrupted; the Azure deployment is still running")

	// ErrDeploymentCanceledByUser is returned when the user requested
	// cancellation and Azure confirmed the deployment reached the Canceled
	// terminal state.
	ErrDeploymentCanceledByUser = errors.New(
		"deployment was canceled by user request")

	// ErrDeploymentCancelTimeout is returned when azd asked Azure to cancel the
	// deployment but the deployment had not reached a terminal state before
	// the local wait budget expired. The cancellation is still in progress on
	// Azure.
	ErrDeploymentCancelTimeout = errors.New(
		"deployment cancel request was submitted but did not complete before timeout")

	// ErrDeploymentCancelTooLate is returned when azd attempted to cancel the
	// deployment but Azure had already moved it to a terminal state
	// (Succeeded or Failed) before the cancel request could take effect.
	ErrDeploymentCancelTooLate = errors.New(
		"deployment finished before the cancel request could take effect")

	// ErrDeploymentCancelFailed is returned when the ARM Cancel request itself
	// failed (network, permissions, etc.). The returned error includes the
	// underlying cause so the caller can inspect it with errors.Is or
	// errors.As.
	ErrDeploymentCancelFailed = errors.New(
		"deployment cancel request failed")
)

Cancellation sentinels surfaced by providers when the user interrupts a running deployment with Ctrl+C. These are sentinel errors so the action / error middleware can produce a friendly, non-zero exit (with the portal URL and a clear message) instead of treating the case as an unexpected failure.

View Source 
var AzdOperationsFeatureKey = alpha.MustFeatureKey("azd.operations")
View Source 
var ErrAzdOperationsNotEnabled = fmt.Errorf(
	"azd operations (alpha feature) is required but disabled. You can enable azd operations by running: %s",
	output.WithGrayFormat("%s", alpha.GetEnableCommand(AzdOperationsFeatureKey)))
View Source 
var ErrBindMountOperationDisabled = fmt.Errorf(
	"%sYour project has bind mounts.\n  - %w\n%s\n",
	output.WithWarningFormat("*Note: "),
	ErrAzdOperationsNotEnabled,
	output.WithWarningFormat("Ignoring bind mounts."),
)
View Source 
var ErrProvisionValidationCanceled = errors.New("provisioning canceled during validation")

ErrProvisionValidationCanceled signals that the provider-agnostic provision validation was canceled (an error-severity finding, or the user declining to continue past warnings). The provision/up command layer passes it through wrapProvisionError, which emits the "Provisioning was canceled." message and translates it into the standard [internal.ErrAbortedByUser] outcome.

Functions

func EnsureSubscription 

func EnsureSubscription(
	ctx context.Context,
	envManager environment.Manager,
	env *environment.Environment,
	prompter prompt.Prompter,
) error

func EnsureSubscriptionAndLocation 

func EnsureSubscriptionAndLocation(
	ctx context.Context,
	envManager environment.Manager,
	env *environment.Environment,
	prompter prompt.Prompter,
	options EnsureSubscriptionAndLocationOptions,
) error

EnsureSubscriptionAndLocation ensures that that that subscription (AZURE_SUBSCRIPTION_ID) and location (AZURE_LOCATION) variables are set in the environment, prompting the user for the values if they do not exist. locationFilter, when non-nil, filters the locations being displayed.

func InfraProviderTelemetryValue added in v1.28.1 

func InfraProviderTelemetryValue(kind ProviderKind) string

InfraProviderTelemetryValue maps a provider kind to a value that is safe to emit raw. Built-in kinds are returned verbatim; any other (custom / extension-registered) provider is bucketed to InfraProviderCustom so a user-chosen provider name is never sent as telemetry.

func NewEnvRefreshResultFromState 

func NewEnvRefreshResultFromState(state *State) contracts.EnvRefreshResult

NewEnvRefreshResultFromState creates a EnvRefreshResult from a provisioning state object, applying the required translations.

func OutputParametersFromArmOutputs 

func OutputParametersFromArmOutputs(
	templateOutputs azure.ArmTemplateOutputs,
	azureOutputParams map[string]azapi.AzCliDeploymentOutput) map[string]OutputParameter

OutputParametersFromArmOutputs converts the outputs from an ARM deployment to a map of provisioning.OutputParameter.

The casing of the output parameter names will match the casing in the provided templateOutputs. If an output is present in azureOutputParams but not in templateOutputs, the output name will be upper-cased to work around inconsistent casing behavior in Azure (e.g. `azurE_RESOURCE_GROUP`).

Secured outputs are skipped and not included in the result.

func UpdateEnvironment 

func UpdateEnvironment(
	ctx context.Context,
	outputs map[string]OutputParameter,
	env *environment.Environment,
	envManager environment.Manager,
) error

Types

type ActionOptions 

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

func NewActionOptions 

func NewActionOptions(formatter output.Formatter, interactive bool) ActionOptions

func (*ActionOptions) Formatter 

func (options *ActionOptions) Formatter() output.Formatter

Gets the specified output format

func (*ActionOptions) IsInteractive 

func (options *ActionOptions) IsInteractive() bool

Gets a value determining whether the console is interactive Console is only considered interactive when the interactive flag has been set and an output format has not been defined.

type ChangeType 

type ChangeType string

ChangeType defines a type for the valid changes for an Azure resource. 

const (
	ChangeTypeCreate      ChangeType = "Create"
	ChangeTypeDelete      ChangeType = "Delete"
	ChangeTypeDeploy      ChangeType = "Deploy"
	ChangeTypeIgnore      ChangeType = "Ignore"
	ChangeTypeModify      ChangeType = "Modify"
	ChangeTypeNoChange    ChangeType = "NoChange"
	ChangeTypeUnsupported ChangeType = "Unsupported"
)

type CurrentPrincipalIdProvider 

type CurrentPrincipalIdProvider interface {
	// CurrentPrincipalId returns the object id of the current logged in principal, or an error if it can not be
	// determined.
	CurrentPrincipalId(ctx context.Context) (string, error)
	CurrentPrincipalType(ctx context.Context) (PrincipalType, error)
}

func NewPrincipalIdProvider 

func NewPrincipalIdProvider(
	env *environment.Environment,
	userProfileService *azapi.UserProfileService,
	subResolver account.SubscriptionResolver,
	authManager *auth.Manager,
) CurrentPrincipalIdProvider

type DefaultProviderResolver 

type DefaultProviderResolver func() (ProviderKind, error)

type DeployPreviewResult 

type DeployPreviewResult struct {
	Preview *DeploymentPreview
}

DeployPreviewResult defines one deployment in preview mode, displaying what changes would it be performed, without applying the changes.

type DeployResult 

type DeployResult struct {
	Deployment    *Deployment
	SkippedReason SkippedReasonType
}

type Deployment 

type Deployment struct {
	Parameters map[string]InputParameter
	Outputs    map[string]OutputParameter
}

type DeploymentPreview 

type DeploymentPreview struct {
	Status     string
	Properties *DeploymentPreviewProperties
}

DeploymentPreview defines the general structure for a deployment preview regardless of the deployment provider.

type DeploymentPreviewChange 

type DeploymentPreviewChange struct {
	ChangeType        ChangeType
	ResourceId        Resource
	ResourceType      string
	Name              string
	UnsupportedReason string
	Before            any
	After             any
	Delta             []DeploymentPreviewPropertyChange
}

DeploymentPreviewChange represents a change to one Azure resource.

type DeploymentPreviewProperties 

type DeploymentPreviewProperties struct {
	Changes []*DeploymentPreviewChange
}

DeploymentPreviewProperties holds the changes for the deployment preview.

type DeploymentPreviewPropertyChange 

type DeploymentPreviewPropertyChange struct {
	ChangeType PropertyChangeType
	Path       string
	Before     any
	After      any
	Children   []DeploymentPreviewPropertyChange
}

DeploymentPreviewPropertyChange includes the details and properties from a resource change.

type DestroyOptions 

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

Infrastructure destroy options

func NewDestroyOptions 

func NewDestroyOptions(force bool, purge bool) DestroyOptions

func (*DestroyOptions) Force 

func (o *DestroyOptions) Force() bool

func (*DestroyOptions) Purge 

func (o *DestroyOptions) Purge() bool

type DestroyResult 

type DestroyResult struct {
	// InvalidatedEnvKeys is a list of keys that should be removed from the environment after the destroy is complete.
	InvalidatedEnvKeys []string
	// SkippedDeletion is true when the provider intentionally did not delete any resources (for example, when
	// running with --no-prompt in a CI/CD environment without --force, where only a destroy preview is shown).
	SkippedDeletion bool
}

type EnsureSubscriptionAndLocationOptions 

type EnsureSubscriptionAndLocationOptions struct {
	// LocationFilterPredicate is a function to filter the locations being displayed if prompting the user for the location.
	LocationFiler prompt.LocationFilterPredicate
	// SelectDefaultLocation is the default location that azd mark as selected when prompting the user for the location.
	SelectDefaultLocation *string
}

type HooksConfig added in v1.23.14 

type HooksConfig = ext.HooksConfig

HooksConfig aliases ext.HooksConfig for compatibility with existing provisioning package references.

type InputParameter 

type InputParameter struct {
	Type         string
	DefaultValue any
	Value        any
}

func (*InputParameter) HasDefaultValue 

func (p *InputParameter) HasDefaultValue() bool

func (*InputParameter) HasValue 

func (p *InputParameter) HasValue() bool

type Manager 

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

Manages the orchestration of infrastructure provisioning

func NewManager 

func NewManager(
	serviceLocator ioc.ServiceLocator,
	defaultProvider DefaultProviderResolver,
	envManager environment.Manager,
	env *environment.Environment,
	console input.Console,
	alphaFeatureManager *alpha.FeatureManager,
	fileShareService storage.FileShareService,
	cloud *cloud.Cloud,
) *Manager

Creates a new instance of the Provisioning Manager

func (*Manager) Deploy 

func (m *Manager) Deploy(ctx context.Context) (*DeployResult, error)

Deploys the Azure infrastructure for the specified project

func (*Manager) Destroy 

func (m *Manager) Destroy(ctx context.Context, options DestroyOptions) (*DestroyResult, error)

Destroys the Azure infrastructure for the specified project

func (*Manager) Initialize 

func (m *Manager) Initialize(ctx context.Context, projectPath string, options Options) error

func (*Manager) Parameters 

func (m *Manager) Parameters(ctx context.Context) ([]Parameter, error)

Parameters gets the list of parameters and its value which will be used to provision the infrastructure.

func (*Manager) PlannedOutputs added in v1.23.14 

func (m *Manager) PlannedOutputs(ctx context.Context) ([]PlannedOutput, error)

PlannedOutputs returns the list of outputs in the current plan.

func (*Manager) Preview 

func (m *Manager) Preview(ctx context.Context) (*DeployPreviewResult, error)

Preview generates the list of changes to be applied as part of the provisioning.

func (*Manager) RecordInfraProviderUsage added in v1.28.1 

func (m *Manager) RecordInfraProviderUsage(ctx context.Context, layers []Options)

RecordInfraProviderUsage records the resolved IaC provider(s) for a provisioning command (provision / up / down) as the infra.provider attribute directly on the current command span in ctx. The attribute is a sorted, de-duplicated string slice of the distinct providers the command's layers resolve to: built-in kinds are recorded verbatim (for example "bicep", "terraform", "arm"), while non-built-in (extension) providers are bucketed to InfraProviderCustom ("custom") so raw user-chosen names are never emitted. A single-provider project records a one-element slice (for example ["bicep"]); a multi-layer project that mixes providers records each distinct value (for example ["bicep", "terraform"]) rather than a lossy "mixed" marker, preserving which providers were combined while staying low-cardinality. Layers that leave the provider unspecified resolve through the manager's default provider. It is a no-op when no provider can be resolved.

The value is attached directly to the span in ctx (not the process-global usage bag) so it stays scoped to that single command span and does not leak onto sibling in-process child commands (for example a custom `workflows.up` running `provision` then `deploy`). Callers must invoke this once per command, before provider work begins, so the attribute is present on success, failure, and preview spans alike. The value is computed deterministically from configuration (rather than racing concurrent per-layer resolution).

func (*Manager) RunProvisionValidation added in v1.27.1 

func (m *Manager) RunProvisionValidation(ctx context.Context, preview bool) (err error)

RunProvisionValidation dispatches the provider-agnostic "provision" validation checks registered by extensions. It is invoked once per `azd provision` / `azd up`, before the layer graph runs, rather than inside Manager.Deploy/Manager.Preview — in multi-layer provisioning each layer has its own Manager whose Deploy runs concurrently, so dispatching here keeps the checks (and any warning confirmation prompt) firing exactly once with the single, env-scoped context. Unlike the Bicep-only "arm-provision" dispatch, this runs for every provider (Bicep, Terraform, and extension-provided providers such as microsoft.foundry and demo).

Findings render through the uniform provision validation report. The return value is a single error the command layer passes to wrapProvisionError:

  • ErrProvisionValidationCanceled: an error-severity finding, or the user declining to continue past warnings. wrapProvisionError translates this into the standard [internal.ErrAbortedByUser] outcome (exit code 0).
  • any other error: the confirmation prompt itself failed to run.
  • nil: validation passed, was skipped, or its warnings were accepted.

Dispatch/timeout failures are non-fatal: they are logged and treated as a skip (nil), so a blocked or unreachable extension never blocks provisioning.

The preview flag only affects the confirmation prompt wording.

func (*Manager) State 

func (m *Manager) State(ctx context.Context, options *StateOptions) (*StateResult, error)

Gets the latest deployment details for the specified scope

type Mode 

type Mode string
const (
	// Default mode for deploying or previewing the deployment.
	ModeDeploy Mode = ""
	// Mode for destroying the deployment.
	ModeDestroy Mode = "destroy"
)

type Options 

type Options struct {
	Provider         ProviderKind   `yaml:"provider,omitempty"`
	Path             string         `yaml:"path,omitempty"`
	Module           string         `yaml:"module,omitempty"`
	Name             string         `yaml:"name,omitempty"`
	Hooks            HooksConfig    `yaml:"hooks,omitempty"`
	DeploymentStacks map[string]any `yaml:"deploymentStacks,omitempty"`
	// Config holds provider-specific configuration options
	Config map[string]any `yaml:"config,omitempty"`
	// DependsOn lists the names of other layers this layer must wait for
	// before being provisioned. Use this to declare hook-mediated edges
	// (for example, when a postprovision hook in another layer writes an
	// env var that this layer's bicepparam reads at provision time)
	// that the static analyzer cannot infer from .bicep / .bicepparam /
	// .parameters.json contents alone. Only valid on layer entries under
	// the `infra.layers` array.
	DependsOn []string `yaml:"dependsOn,omitempty" json:"dependsOn,omitempty"`
	// Provisioning options for each individually defined layer.
	Layers []Options `yaml:"layers,omitempty"`

	// IgnoreDeploymentState when true, skips the deployment state check.
	IgnoreDeploymentState bool `yaml:"-"`
	// The mode in which the deployment is being run.
	Mode Mode `yaml:"-"`
	// Environment variables that should be considered as resolved when prompting for parameters.
	//
	// This is used when planning multiple layers, and would be set to plan-time outputs
	// from previous layers.
	VirtualEnv map[string]string `yaml:"-"`
}

Options for a provisioning provider.

func (Options) AbsolutePath added in v1.23.14 

func (o Options) AbsolutePath(projectPath string) string

AbsolutePath returns the layer path resolved against the project path when needed.

func (*Options) GetLayer 

func (o *Options) GetLayer(name string) (Options, error)

GetLayer returns the provisioning layer with the provided name. When Options.Layers is not defined, an empty name returns the single layer defined.

func (*Options) GetLayers 

func (o *Options) GetLayers() []Options

GetLayers return the provisioning layers defined. When Options.Layers is not defined, it returns the single layer defined.

The ordering is stable; and reflects the order defined in azure.yaml.

func (Options) GetWithDefaults 

func (o Options) GetWithDefaults(other ...Options) (Options, error)

GetWithDefaults merges the provided infra options with the default provisioning options

func (*Options) Validate 

func (o *Options) Validate() error

Validate validates the current loaded config for correctness.

This should be called immediately right after Unmarshal() before any defaulting is performed.

type OutputParameter 

type OutputParameter struct {
	Type  ParameterType
	Value any
}

type Parameter 

type Parameter struct {
	Name          string
	Secret        bool
	Value         any
	EnvVarMapping []string
	// true when the parameter value was set by the user from the command line (prompt)
	LocalPrompt        bool
	UsingEnvVarMapping bool
}

type ParameterType 

type ParameterType string
const (
	ParameterTypeString  ParameterType = "string"
	ParameterTypeNumber  ParameterType = "number"
	ParameterTypeBoolean ParameterType = "bool"
	ParameterTypeObject  ParameterType = "object"
	ParameterTypeArray   ParameterType = "array"
)

func ParameterTypeFromArmType 

func ParameterTypeFromArmType(armType string) ParameterType

ParameterTypeFromArmType maps an ARM parameter type to a provisioning.ParameterType.

Panics if the provided armType is not recognized.

type PlannedOutput added in v1.23.14 

type PlannedOutput struct {
	// The name of the planned output
	Name string
}

PlannedOutput represents a plan-time output. It does not contain the actual output value.

type PrincipalType 

type PrincipalType string
const (
	UserType             PrincipalType = "User"
	ServicePrincipalType PrincipalType = "ServicePrincipal"
)

type PropertyChangeType 

type PropertyChangeType string

PropertyChangeType defines a type for the valid properties of a change. 

const (
	PropertyChangeTypeArray    PropertyChangeType = "Array"
	PropertyChangeTypeCreate   PropertyChangeType = "Create"
	PropertyChangeTypeDelete   PropertyChangeType = "Delete"
	PropertyChangeTypeModify   PropertyChangeType = "Modify"
	PropertyChangeTypeNoEffect PropertyChangeType = "NoEffect"
)

type Provider 

type Provider interface {
	Name() string
	Initialize(ctx context.Context, projectPath string, options Options) error
	State(ctx context.Context, options *StateOptions) (*StateResult, error)
	Deploy(ctx context.Context) (*DeployResult, error)
	Preview(ctx context.Context) (*DeployPreviewResult, error)
	Destroy(ctx context.Context, options DestroyOptions) (*DestroyResult, error)
	EnsureEnv(ctx context.Context) error
	Parameters(ctx context.Context) ([]Parameter, error)
	PlannedOutputs(ctx context.Context) ([]PlannedOutput, error)
}

type ProviderKind 

type ProviderKind string
const (
	NotSpecified ProviderKind = ""
	Bicep        ProviderKind = "bicep"
	Arm          ProviderKind = "arm"
	Terraform    ProviderKind = "terraform"
	Pulumi       ProviderKind = "pulumi"
	Test         ProviderKind = "test"
)

func ParseProvider 

func ParseProvider(kind ProviderKind) (ProviderKind, error)

ParseProvider returns the specified IaC provider unchanged. Defaulting for NotSpecified is handled later during provider creation.

type Resource 

type Resource struct {
	Id string
}

type SkippedReasonType 

type SkippedReasonType string
const (
	DeploymentStateSkipped             SkippedReasonType = "deployment state"
	ProvisionValidationCanceledSkipped SkippedReasonType = "provision validation canceled"
)

type State 

type State struct {
	// Outputs from the most recent deployment.
	Outputs map[string]OutputParameter
	// The resources that make up the application.
	Resources []Resource
}

State represents the "current state" of the infrastructure, which is the result of the most recent deployment. For ARM this corresponds to information from the most recent deployment object. For Terraform, it's information from the state file.

func (*State) MergeInto 

func (s *State) MergeInto(other State)

MergeInto merges other on top of s, i.e. if a key exists in both s and other, the value from other will be used.

type StateOptions 

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

func NewStateOptions 

func NewStateOptions(hint string) *StateOptions

func (*StateOptions) Hint 

func (o *StateOptions) Hint() string

type StateResult 

type StateResult struct {
	State *State
}

type ValidationCheckDispatcher added in v1.26.0 

type ValidationCheckDispatcher interface {
	// DispatchChecks invokes all extension-registered checks matching the
	// given checkType and returns the aggregated results along with the
	// list of rule IDs that were invoked (for telemetry).
	DispatchChecks(
		ctx context.Context,
		checkType string,
		contextData map[string][]byte,
	) (results []*azdext.ValidationCheckResult, invokedRuleIDs []string, err error)
}

ValidationCheckDispatcher dispatches validation checks to extension-provided check implementations. This interface decouples provisioning providers from the gRPC server implementation.

Source Files

View all Source files

Directories

Path Synopsis
Package test contains an test implementation of provider.Provider.
 Package test contains an test implementation of provider.Provider.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.