9 "github.com/hashicorp/go-multierror"
10 "github.com/hashicorp/terraform/config"
11 "github.com/hashicorp/terraform/terraform"
14 // Provisioner represents a resource provisioner in Terraform and properly
15 // implements all of the ResourceProvisioner API.
17 // This higher level structure makes it much easier to implement a new or
18 // custom provisioner for Terraform.
20 // The function callbacks for this structure are all passed a context object.
21 // This context object has a number of pre-defined values that can be accessed
22 // via the global functions defined in context.go.
23 type Provisioner struct {
24 // ConnSchema is the schema for the connection settings for this
27 // The keys of this map are the configuration keys, and the value is
28 // the schema describing the value of the configuration.
30 // NOTE: The value of connection keys can only be strings for now.
31 ConnSchema map[string]*Schema
33 // Schema is the schema for the usage of this provisioner.
35 // The keys of this map are the configuration keys, and the value is
36 // the schema describing the value of the configuration.
37 Schema map[string]*Schema
39 // ApplyFunc is the function for executing the provisioner. This is required.
40 // It is given a context. See the Provisioner struct docs for more
42 ApplyFunc func(ctx context.Context) error
44 // ValidateFunc is a function for extended validation. This is optional
45 // and should be used when individual field validation is not enough.
46 ValidateFunc func(*terraform.ResourceConfig) ([]string, []error)
48 stopCtx context.Context
49 stopCtxCancel context.CancelFunc
53 // Keys that can be used to access data in the context parameters for
56 connDataInvalid = contextKey("data invalid")
58 // This returns a *ResourceData for the connection information.
59 // Guaranteed to never be nil.
60 ProvConnDataKey = contextKey("provider conn data")
62 // This returns a *ResourceData for the config information.
63 // Guaranteed to never be nil.
64 ProvConfigDataKey = contextKey("provider config data")
66 // This returns a terraform.UIOutput. Guaranteed to never be nil.
67 ProvOutputKey = contextKey("provider output")
69 // This returns the raw InstanceState passed to Apply. Guaranteed to
70 // be set, but may be nil.
71 ProvRawStateKey = contextKey("provider raw state")
74 // InternalValidate should be called to validate the structure
75 // of the provisioner.
77 // This should be called in a unit test to verify before release that this
78 // structure is properly configured for use.
79 func (p *Provisioner) InternalValidate() error {
81 return errors.New("provisioner is nil")
84 var validationErrors error
86 sm := schemaMap(p.ConnSchema)
87 if err := sm.InternalValidate(sm); err != nil {
88 validationErrors = multierror.Append(validationErrors, err)
93 sm := schemaMap(p.Schema)
94 if err := sm.InternalValidate(sm); err != nil {
95 validationErrors = multierror.Append(validationErrors, err)
99 if p.ApplyFunc == nil {
100 validationErrors = multierror.Append(validationErrors, fmt.Errorf(
101 "ApplyFunc must not be nil"))
104 return validationErrors
107 // StopContext returns a context that checks whether a provisioner is stopped.
108 func (p *Provisioner) StopContext() context.Context {
109 p.stopOnce.Do(p.stopInit)
113 func (p *Provisioner) stopInit() {
114 p.stopCtx, p.stopCtxCancel = context.WithCancel(context.Background())
117 // Stop implementation of terraform.ResourceProvisioner interface.
118 func (p *Provisioner) Stop() error {
119 p.stopOnce.Do(p.stopInit)
124 // Apply implementation of terraform.ResourceProvisioner interface.
125 func (p *Provisioner) Apply(
126 o terraform.UIOutput,
127 s *terraform.InstanceState,
128 c *terraform.ResourceConfig) error {
129 var connData, configData *ResourceData
132 // We first need to turn the connection information into a
133 // terraform.ResourceConfig so that we can use that type to more
134 // easily build a ResourceData structure. We do this by simply treating
135 // the conn info as configuration input.
136 raw := make(map[string]interface{})
138 for k, v := range s.Ephemeral.ConnInfo {
143 c, err := config.NewRawConfig(raw)
148 sm := schemaMap(p.ConnSchema)
149 diff, err := sm.Diff(nil, terraform.NewResourceConfig(c))
153 connData, err = sm.Data(nil, diff)
160 // Build the configuration data. Doing this requires making a "diff"
161 // even though that's never used. We use that just to get the correct types.
162 configMap := schemaMap(p.Schema)
163 diff, err := configMap.Diff(nil, c)
167 configData, err = configMap.Data(nil, diff)
173 // Build the context and call the function
174 ctx := p.StopContext()
175 ctx = context.WithValue(ctx, ProvConnDataKey, connData)
176 ctx = context.WithValue(ctx, ProvConfigDataKey, configData)
177 ctx = context.WithValue(ctx, ProvOutputKey, o)
178 ctx = context.WithValue(ctx, ProvRawStateKey, s)
179 return p.ApplyFunc(ctx)
182 // Validate implements the terraform.ResourceProvisioner interface.
183 func (p *Provisioner) Validate(c *terraform.ResourceConfig) (ws []string, es []error) {
184 if err := p.InternalValidate(); err != nil {
185 return nil, []error{fmt.Errorf(
186 "Internal validation of the provisioner failed! This is always a bug\n"+
187 "with the provisioner itself, and not a user issue. Please report\n"+
188 "this bug:\n\n%s", err)}
192 w, e := schemaMap(p.Schema).Validate(c)
193 ws = append(ws, w...)
194 es = append(es, e...)
197 if p.ValidateFunc != nil {
198 w, e := p.ValidateFunc(c)
199 ws = append(ws, w...)
200 es = append(es, e...)