feat(plugins/docker): add docker-ref plugin

.changelog/3912.txt

@@ -0,0 +1,3 @@
+```release-note:improvement
+plugins/docker: Add new `docker-ref` for a build noop for referencing a Docker Image
+```

builtin/docker/ref/builder.go

@@ -0,0 +1,109 @@
+package dockerref
+
+import (
+ "github.com/hashicorp/go-argmapper"
+ "github.com/hashicorp/waypoint-plugin-sdk/docs"
+ "github.com/hashicorp/waypoint-plugin-sdk/terminal"
+ wpdocker "github.com/hashicorp/waypoint/builtin/docker"
+ empty "google.golang.org/protobuf/types/known/emptypb"
+)
+
+// Builder uses `docker build` to build a Docker iamge.
+type Builder struct {
+ config BuilderConfig
+}
+
+// BuildFunc implements component.Builder
+func (b *Builder) BuildFunc() interface{} {
+ return b.Build
+}
+
+// BuildODRFunc implements component.BuilderODR
+func (b *Builder) BuildODRFunc() interface{} {
+ return b.Build
+}
+
+// BuilderConfig is the configuration structure for the registry.
+type BuilderConfig struct {
+ // Image to pull
+ Image string `hcl:"image,attr"`
+ Tag string `hcl:"tag,attr"`
+}
+
+func (b *Builder) Documentation() (*docs.Documentation, error) {
+ doc, err := docs.New(docs.FromConfig(&BuilderConfig{}), docs.FromFunc(b.BuildFunc()))
+ if err != nil {
+ return nil, err
+ }
+
+ doc.Description(`
+Use an existing, pre-built Docker image without modifying it.
+`)
+
+ doc.Example(`
+build {
+ use "docker-ref" {
+ image = "gcr.io/my-project/my-image"
+ tag = "abcd1234"
+ }
+}
+`)
+
+ doc.Input("component.Source")
+ doc.Output("docker.Image")
+
+ doc.SetField(
+ "image",
+ "The image to pull.",
+ docs.Summary(
+ "This should NOT include the tag (the value following the ':' in a Docker image).",
+ "Use `tag` to define the image tag.",
+ ),
+ )
+
+ doc.SetField(
+ "tag",
+ "The tag of the image to pull.",
+ )
+
+ return doc, nil
+}
+
+// Config implements Configurable
+func (b *Builder) Config() (interface{}, error) {
+ return &b.config, nil
+}
+
+// We use the struct form of arguments so that we can access named
+// values (such as "HasRegistry").
+type buildArgs struct {
+ argmapper.Struct
+
+ UI terminal.UI
+}
+
+func (b *Builder) Build(args buildArgs) (*wpdocker.Image, error) {
+ // Pull all the args out to top-level values. This is mostly done
+ // cause the struct was added later, but also because these are very common.
+ ui := args.UI
+ sg := ui.StepGroup()
+ defer sg.Wait()
+ step := sg.Add("")
+ defer func() {
+ if step != nil {
+ step.Abort()
+ }
+ }()
+
+ result := &wpdocker.Image{
+ Image: b.config.Image,
+ Tag: b.config.Tag,
+ Location: &wpdocker.Image_Docker{Docker: &empty.Empty{}},
+ }
+
+ step.Update("Using Docker image in remote registry: %s", result.Name())
+ step.Done()
+
+ result.Location = &wpdocker.Image_Registry{Registry: &wpdocker.Image_RegistryLocation{}}
+ return result, nil
+}

builtin/docker/ref/main.go

@@ -0,0 +1,10 @@
+package dockerref
+
+import (
+ "github.com/hashicorp/waypoint-plugin-sdk"
+)
+
+// Options are the SDK options to use for instantiation.
+var Options = []sdk.Option{
+ sdk.WithComponents(&Builder{}),
+}

embedJson/gen/builder-docker-ref.json

@@ -0,0 +1,82 @@
+{
+ "description": "\nUse an existing, pre-built Docker image without modifying it.\n",
+ "example": "build {\n use \"docker-ref\" {\n image = \"gcr.io/my-project/my-image\"\n tag = \"abcd1234\"\n }\n}",
+ "input": "component.Source",
+ "mappers": null,
+ "name": "docker-ref",
+ "optionalFields": null,
+ "output": "docker.Image",
+ "outputAttrs": [
+ {
+ "Field": "architecture",
+ "Type": "string",
+ "Synopsis": "",
+ "Summary": "",
+ "Optional": false,
+ "Default": "",
+ "EnvVar": "",
+ "Category": false,
+ "SubFields": null
+ },
+ {
+ "Field": "image",
+ "Type": "string",
+ "Synopsis": "",
+ "Summary": "",
+ "Optional": false,
+ "Default": "",
+ "EnvVar": "",
+ "Category": false,
+ "SubFields": null
+ },
+ {
+ "Field": "location",
+ "Type": "docker.isImage_Location",
+ "Synopsis": "",
+ "Summary": "",
+ "Optional": false,
+ "Default": "",
+ "EnvVar": "",
+ "Category": false,
+ "SubFields": null
+ },
+ {
+ "Field": "tag",
+ "Type": "string",
+ "Synopsis": "",
+ "Summary": "",
+ "Optional": false,
+ "Default": "",
+ "EnvVar": "",
+ "Category": false,
+ "SubFields": null
+ }
+ ],
+ "outputAttrsHelp": "Output attributes can be used in your `waypoint.hcl` as [variables](/docs/waypoint-hcl/variables) via [`artifact`](/docs/waypoint-hcl/variables/artifact) or [`deploy`](/docs/waypoint-hcl/variables/deploy).",
+ "requiredFields": [
+ {
+ "Field": "image",
+ "Type": "string",
+ "Synopsis": "The image to pull.",
+ "Summary": "This should NOT include the tag (the value following the ':' in a Docker image). Use `tag` to define the image tag.",
+ "Optional": false,
+ "Default": "",
+ "EnvVar": "",
+ "Category": false,
+ "SubFields": null
+ },
+ {
+ "Field": "tag",
+ "Type": "string",
+ "Synopsis": "The tag of the image to pull.",
+ "Summary": "",
+ "Optional": false,
+ "Default": "",
+ "EnvVar": "",
+ "Category": false,
+ "SubFields": null
+ }
+ ],
+ "type": "builder",
+ "use": "the [`use` stanza](/docs/waypoint-hcl/use) for this plugin."
+}

embedJson/gen/configsourcer-docker-ref.json

@@ -0,0 +1,8 @@
+{
+ "mappers": null,
+ "name": "docker-ref",
+ "optionalFields": null,
+ "requiredFields": null,
+ "type": "configsourcer",
+ "use": "`dynamic` for sourcing [configuration values](/docs/app-config/dynamic) or [input variable values](/docs/waypoint-hcl/variables/dynamic)."
+}

embedJson/gen/platform-docker-ref.json

@@ -0,0 +1,8 @@
+{
+ "mappers": null,
+ "name": "docker-ref",
+ "optionalFields": null,
+ "requiredFields": null,
+ "type": "platform",
+ "use": "the [`use` stanza](/docs/waypoint-hcl/use) for this plugin."
+}

embedJson/gen/registry-docker-ref.json

@@ -0,0 +1,8 @@
+{
+ "mappers": null,
+ "name": "docker-ref",
+ "optionalFields": null,
+ "requiredFields": null,
+ "type": "registry",
+ "use": "the [`use` stanza](/docs/waypoint-hcl/use) for this plugin."
+}

embedJson/gen/releasemanager-docker-ref.json

@@ -0,0 +1,8 @@
+{
+ "mappers": null,
+ "name": "docker-ref",
+ "optionalFields": null,
+ "requiredFields": null,
+ "type": "releasemanager",
+ "use": "the [`use` stanza](/docs/waypoint-hcl/use) for this plugin."
+}

embedJson/gen/task-docker-ref.json

@@ -0,0 +1,8 @@
+{
+ "mappers": null,
+ "name": "docker-ref",
+ "optionalFields": null,
+ "requiredFields": null,
+ "type": "task",
+ "use": "the [`use` stanza](/docs/waypoint-hcl/use) for this plugin."
+}

internal/plugin/plugin.go

@@ -3,6 +3,7 @@ package plugin
 import (
  sdk "github.com/hashicorp/waypoint-plugin-sdk"
  "github.com/hashicorp/waypoint-plugin-sdk/component"
+ dockerref "github.com/hashicorp/waypoint/builtin/docker/ref"
  "github.com/hashicorp/waypoint/builtin/nomad/canary"
  "github.com/hashicorp/waypoint/internal/factory"
 
@@ -40,6 +41,7 @@ var (
  "pack": pack.Options,
  "docker": docker.Options,
  "docker-pull": dockerpull.Options,
+ "docker-ref": dockerref.Options,
  "exec": exec.Options,
  "google-cloud-run": cloudrun.Options,
  "azure-container-instance": aci.Options,

website/content/partials/components/builder-docker-ref.mdx

@@ -0,0 +1,61 @@
+## docker-ref (builder)
+
+Use an existing, pre-built Docker image without modifying it.
+
+### Interface
+
+- Input: **component.Source**
+- Output: **docker.Image**
+
+### Examples
+
+```hcl
+build {
+ use "docker-ref" {
+ image = "gcr.io/my-project/my-image"
+ tag = "abcd1234"
+ }
+}
+```
+
+### Required Parameters
+
+These parameters are used in the [`use` stanza](/docs/waypoint-hcl/use) for this plugin.
+
+#### image
+
+The image to pull.
+
+This should NOT include the tag (the value following the ':' in a Docker image). Use `tag` to define the image tag.
+
+- Type: **string**
+
+#### tag
+
+The tag of the image to pull.
+
+- Type: **string**
+
+### Optional Parameters
+
+This plugin has no optional parameters.
+
+### Output Attributes
+
+Output attributes can be used in your `waypoint.hcl` as [variables](/docs/waypoint-hcl/variables) via [`artifact`](/docs/waypoint-hcl/variables/artifact) or [`deploy`](/docs/waypoint-hcl/variables/deploy).
+
+#### architecture
+
+- Type: **string**
+
+#### image
+
+- Type: **string**
+
+#### location
+
+- Type: **docker.isImage_Location**
+
+#### tag
+
+- Type: **string**

website/content/partials/components/configsourcer-docker-ref.mdx

@@ -0,0 +1,9 @@
+## docker-ref (configsourcer)
+
+### Required Parameters
+
+This plugin has no required parameters.
+
+### Optional Parameters
+
+This plugin has no optional parameters.

website/content/partials/components/platform-docker-ref.mdx

@@ -0,0 +1,11 @@
+## docker-ref (platform)
+
+### Interface
+
+### Required Parameters
+
+This plugin has no required parameters.
+
+### Optional Parameters
+
+This plugin has no optional parameters.

website/content/partials/components/registry-docker-ref.mdx

@@ -0,0 +1,11 @@
+## docker-ref (registry)
+
+### Interface
+
+### Required Parameters
+
+This plugin has no required parameters.
+
+### Optional Parameters
+
+This plugin has no optional parameters.

website/content/partials/components/releasemanager-docker-ref.mdx

@@ -0,0 +1,11 @@
+## docker-ref (releasemanager)
+
+### Interface
+
+### Required Parameters
+
+This plugin has no required parameters.
+
+### Optional Parameters
+
+This plugin has no optional parameters.

website/content/partials/components/task-docker-ref.mdx

@@ -0,0 +1,11 @@
+## docker-ref (task)
+
+### Interface
+
+### Required Parameters
+
+This plugin has no required parameters.
+
+### Optional Parameters
+
+This plugin has no optional parameters.

website/content/plugins/docker.mdx

@@ -13,6 +13,8 @@ Learn](https://learn.hashicorp.com/collections/waypoint/get-started-docker).
 
 @include "components/builder-docker-pull.mdx"
 
+@include "components/builder-docker-ref.mdx"
+
 @include "components/registry-docker.mdx"
 
 @include "components/platform-docker.mdx"