github.com/ferranbt/nomad@v0.9.3-0.20190607002617-85c449b7667c/website/source/docs/internals/plugins/base.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Base Plugin"
     4  sidebar_current: "docs-internals-plugins-base"
     5  description: |-
     6    Learn about how to author a Nomad plugin.
     7  ---
     8  
     9  # Base Plugin
    10  
    11  The base plugin is a special plugin type implemented by all plugins. It allows
    12  for common plugin operations such as defining a configuration schema and
    13  version information.
    14  
    15  ## Plugin API
    16  
    17  #### `PluginInfo() (*PluginInfoResponse, error)`
    18  
    19  A `PluginInfoResponse` contains meta data about the plugin.
    20  
    21  ```go
    22  PluginInfoResponse{
    23      // Type is the plugin type which is implemented
    24      Type: PluginTypeDriver,
    25      // Plugin API versions supported by the plugin
    26      PluginApiVersions: []string{drivers.ApiVersion010},
    27      // Version of the plugin
    28      PluginVersion: "0.1.0",
    29      // Name of the plugin
    30      Name: "foodriver",
    31  }
    32  ```
    33  
    34  #### `ConfigSchema() (*hclspec.Spec, error)`
    35  
    36  The `ConfigSchema` function allows a plugin to tell Nomad the schema for its
    37  configuration. This configuration is given in a [plugin block][pluginblock] of
    38  the client configuration. The schema is defined with the [hclspec][hclspec]
    39  package.
    40  
    41  #### `SetConfig(config *Config) error`
    42  
    43  The `SetConfig` function is called when starting the plugin for the first
    44  time. The `Config` given has two different configuration fields. The first
    45  `PluginConfig`, is an encoded configuration from the `plugin` block of the
    46  client config. The second, `AgentConfig`, is the Nomad agent's configuration
    47  which is given to all plugins.
    48  
    49  ## HCL Specifications
    50  
    51  `*hclspec.Spec` is a struct that defines the schema to validate an HCL entity
    52  against. The full documentation of the different hcl attribute types can be
    53  found on the [hclspec godoc][hclspec].
    54  
    55  For a basic example, lets look at the driver configuration for the raw_exec
    56  driver:
    57  
    58  ```hcl
    59  job "example" {
    60  ...
    61        driver = "raw_exec"
    62        config {
    63          command = "/bin/sleep"
    64          args = ["100"] 
    65        }
    66  }
    67  ```
    68  
    69  The `config` block is what is validated against the `hclspec.Spec`. It has two
    70  keys, command which takes a string attribute and args which takes an array
    71  attribute. The corresponding `*hclspec.Spec` would be:
    72  
    73  ```go
    74      spec :=  hclspec.NewObject(map[string]*hclspec.Spec{
    75  		"command": hclspec.NewAttr("command", "string", true),
    76  		"args":    hclspec.NewAttr("args", "list(string)", false),
    77  	})
    78  ```
    79  
    80  
    81  [hclspec]: https://godoc.org/github.com/hashicorp/nomad/plugins/shared/hclspec
    82  [pluginblock]: /docs/configuration/plugin.html