github.com/hashicorp/packer@v1.14.3/website/content/docs/plugins/creation/custom-datasources.mdx (about)

     1  ---
     2  description: >
     3    Data sources fetch data to use in the Packer configuration. Learn how to define custom data sources so that Packer can use external data in builds.
     4  page_title: Custom Data Sources - Extending
     5  ---
     6  
     7  # Custom Data Sources
     8  
     9  Packer data sources let Packer fetch data to use within the configuration, including information defined outside of Packer. For example, the [amazon-ami data source](/packer/plugins/datasources/amazon/ami), outputs the data from an Amazon AMI.
    10  
    11  Data Source plugins implement the `packersdk.Datasource` interface and are registered within a plugin Set
    12  with `set.RegisterDatasource(...)` function and served using the `set.Run()`.
    13  
    14  ~> **Warning:** This is an advanced topic that requires strong knowledge of Packer and Packer plugins.
    15  
    16  ## Before You Begin
    17  
    18  We recommend reviewing the following resources before you begin development:
    19  
    20  - [Developing Plugins - Overview](/packer/docs/plugins/creation)
    21  - The [Go](https://go.dev/) language. You must write custom plugins in Go, so this guide assumes you are familiar with the language.
    22  
    23  ## The Interface
    24  
    25  The interface that must be implemented for a datasource is the
    26  `packersdk.Datasource` interface. It is reproduced below for reference. The
    27  actual interface in the source code contains some basic documentation as well
    28  explaining what each method should do.
    29  
    30  ```go
    31  type Datasource interface {
    32      ConfigSpec() hcldec.ObjectSpec
    33      OutputSpec() hcldec.ObjectSpec
    34      Configure(...interface{}) error
    35      Execute() (cty.Value, error)
    36  }
    37  ```
    38  
    39  ### The "ConfigSpec" Method
    40  
    41  This method returns a hcldec.ObjectSpec, which is a spec necessary for using
    42  HCL2 templates with Packer. For information on how to use and implement this
    43  function, check our
    44  [object spec docs](/packer/guides/hcl/component-object-spec)
    45  
    46  ### The "OutputSpec" Method
    47  
    48  This method returns a [hcldec.ObjectSpec](/packer/guides/hcl/component-object-spec) of the data source output.
    49  The object spec can be generated using the command [`packer-sdc mapstructure-to-hcl2`](https://github.com/hashicorp/packer-plugin-sdk/tree/main/cmd/packer-sdc)
    50  just like the configuration spec for the `ConfigSpec` method.
    51  
    52  This method is used in `packer validate` command. Packer will use the spec to assign
    53  unknown values to the data source, instead of executing it and fetching real values.
    54  
    55  ### The "Configure" Method
    56  
    57  The `Configure` method is called prior to any runs with the configuration that was given in the template.
    58  This is passed in as an array of `interface{}` types, but is generally `map[string]interface{}`. The Configure
    59  method is responsible for translating this configuration into an internal structure, validating it,
    60  and returning any errors.
    61  
    62  For multiple parameters, they should be merged together into the final
    63  configuration, with later parameters overwriting any previous configuration.
    64  The exact semantics of the merge are left to the builder author.
    65  
    66  For decoding the `interface{}` into a meaningful structure, the
    67  [mapstructure](https://github.com/mitchellh/mapstructure) library is
    68  recommended. Mapstructure will take an `interface{}` and decode it into an
    69  arbitrarily complex struct. If there are any errors, it generates very human
    70  friendly errors that can be returned directly from the Configure method.
    71  
    72  While it is not actively enforced, **no side effects** should occur from
    73  running the `Configure` method. Specifically, don't create files, don't launch
    74  virtual machines, etc. Configure's purpose is solely to configure the data source and
    75  validate the configuration.
    76  
    77  The `Configure` method is called very early in the build process so that errors
    78  may be displayed to the user before anything actually happens.
    79  
    80  ### The "Execute" Method
    81  
    82  This method returns an HCL cty.Value and an error. Packer will run the Execute method on `packer build` command
    83  so that the data source output will be available prior to evaluating build and locals blocks. Is expected that the
    84  Execute command will fetch the data and return it as a cty.Value.
    85  
    86  To get the equivalent cty.Value from an output config, we suggest using our
    87  [packer-plugin-sdk hcl2helper functions](https://github.com/hashicorp/packer-plugin-sdk/blob/v0.0.7/hcl2helper/values.go).
    88  
    89  ## Scaffolding template
    90  
    91  To make your experience easier when developing your new data source plugin, we provide you a
    92  [Packer plugin scaffolding](https://github.com/hashicorp/packer-plugin-scaffolding)
    93  to use as a template to your plugin repository. The template is structure with the basics and contain the necessary
    94  configuration to start creating your own plugin.