RemoteImage class

<!-- Bug: Type and Name are switched --> Manages the lifecycle of a docker image in your docker host. It can be used to build a new docker image or to pull an existing one from a registry. This resource will not pull new layers of the image automatically unless used in conjunction with docker.RegistryImage data source to update the pullTriggers field.

Example Usage

Basic

Finds and downloads the latest ubuntu:precise image but does not check for further updates of the image

import * as pulumi from "@pulumi/pulumi";
import * as docker from "@pulumi/docker";

const ubuntu = new docker.RemoteImage("ubuntu", {name: "ubuntu:precise"});

import pulumi
import pulumi_docker as docker

ubuntu = docker.RemoteImage("ubuntu", name="ubuntu:precise")

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Docker = Pulumi.Docker;

return await Deployment.RunAsync(() =>
{
    var ubuntu = new Docker.RemoteImage("ubuntu", new()
    {
        Name = "ubuntu:precise",
    });

});

package main

import (
	"github.com/pulumi/pulumi-docker/sdk/v5/go/docker"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := docker.NewRemoteImage(ctx, "ubuntu", &docker.RemoteImageArgs{
			Name: pulumi.String("ubuntu:precise"),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

pulumi {
  required_providers {
    docker = {
      source = "pulumi/docker"
    }
  }
}

resource "docker_remoteimage" "ubuntu" {
  name = "ubuntu:precise"
}

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.docker.RemoteImage;
import com.pulumi.docker.RemoteImageArgs;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var ubuntu = new RemoteImage("ubuntu", RemoteImageArgs.builder()
            .name("ubuntu:precise")
            .build());

    }
}

resources:
  ubuntu:
    type: docker:RemoteImage
    properties:
      name: ubuntu:precise

Dynamic updates

To be able to update an image dynamically when the sha256 sum changes, you need to use it in combination with docker.RegistryImage as follows:

import * as pulumi from "@pulumi/pulumi";
import * as docker from "@pulumi/docker";

const ubuntu = docker.getRegistryImage({
    name: "ubuntu:precise",
});
const ubuntuRemoteImage = new docker.RemoteImage("ubuntu", {
    name: ubuntu.then(ubuntu => ubuntu.name),
    pullTriggers: [ubuntu.then(ubuntu => ubuntu.sha256Digest)],
});

import pulumi
import pulumi_docker as docker

ubuntu = docker.get_registry_image(name="ubuntu:precise")
ubuntu_remote_image = docker.RemoteImage("ubuntu",
    name=ubuntu.name,
    pull_triggers=[ubuntu.sha256_digest])

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Docker = Pulumi.Docker;

return await Deployment.RunAsync(() =>
{
    var ubuntu = Docker.GetRegistryImage.Invoke(new()
    {
        Name = "ubuntu:precise",
    });

    var ubuntuRemoteImage = new Docker.RemoteImage("ubuntu", new()
    {
        Name = ubuntu.Apply(getRegistryImageResult => getRegistryImageResult.Name),
        PullTriggers = new[]
        {
            ubuntu.Apply(getRegistryImageResult => getRegistryImageResult.Sha256Digest),
        },
    });

});

package main

import (
	"github.com/pulumi/pulumi-docker/sdk/v5/go/docker"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		ubuntu, err := docker.GetRegistryImage(ctx, &docker.LookupRegistryImageArgs{
			Name: "ubuntu:precise",
		}, nil)
		if err != nil {
			return err
		}
		_, err = docker.NewRemoteImage(ctx, "ubuntu", &docker.RemoteImageArgs{
			Name: pulumi.String(ubuntu.Name),
			PullTriggers: pulumi.StringArray{
				pulumi.String(ubuntu.Sha256Digest),
			},
		})
		if err != nil {
			return err
		}
		return nil
	})
}

pulumi {
  required_providers {
    docker = {
      source = "pulumi/docker"
    }
  }
}

data "docker_getregistryimage" "ubuntu" {
  name = "ubuntu:precise"
}

resource "docker_remoteimage" "ubuntu" {
  name          = data.docker_getregistryimage.ubuntu.name
  pull_triggers = [data.docker_getregistryimage.ubuntu.sha256_digest]
}

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.docker.DockerFunctions;
import com.pulumi.docker.inputs.GetRegistryImageArgs;
import com.pulumi.docker.RemoteImage;
import com.pulumi.docker.RemoteImageArgs;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        final var ubuntu = DockerFunctions.getRegistryImage(GetRegistryImageArgs.builder()
            .name("ubuntu:precise")
            .build());

        var ubuntuRemoteImage = new RemoteImage("ubuntuRemoteImage", RemoteImageArgs.builder()
            .name(ubuntu.name())
            .pullTriggers(ubuntu.sha256Digest())
            .build());

    }
}

resources:
  ubuntuRemoteImage:
    type: docker:RemoteImage
    name: ubuntu
    properties:
      name: ${ubuntu.name}
      pullTriggers:
        - ${ubuntu.sha256Digest}
variables:
  ubuntu:
    fn::invoke:
      function: docker:getRegistryImage
      arguments:
        name: ubuntu:precise

Build

You can also use the resource to build an image. If you want to use a buildx builder with all of its features, please read the section below.

> Note: The default timeout for the building is 20 minutes. If you need to increase this, you can use operation timeouts.

In this case the image "zoo" and "zoo:develop" are built. The context path is resolved on the machine running Terraform (relative paths are relative to the current working directory, i.e. path.cwd). If dockerfile is not an absolute path, it is resolved relative to context. There is no need to copy the files to remote hosts before creating the resource.

import * as pulumi from "@pulumi/pulumi";
import * as docker from "@pulumi/docker";

const zoo = new docker.RemoteImage("zoo", {
    name: "zoo",
    build: {
        context: ".",
        tags: ["zoo:develop"],
        buildArgs: {
            foo: "zoo",
        },
        label: {
            author: "zoo",
        },
    },
});

import pulumi
import pulumi_docker as docker

zoo = docker.RemoteImage("zoo",
    name="zoo",
    build={
        "context": ".",
        "tags": ["zoo:develop"],
        "build_args": {
            "foo": "zoo",
        },
        "label": {
            "author": "zoo",
        },
    })

using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Docker = Pulumi.Docker;

return await Deployment.RunAsync(() =>
{
    var zoo = new Docker.RemoteImage("zoo", new()
    {
        Name = "zoo",
        Build = new Docker.Inputs.RemoteImageBuildArgs
        {
            Context = ".",
            Tags = new[]
            {
                "zoo:develop",
            },
            BuildArgs =
            {
                { "foo", "zoo" },
            },
            Label =
            {
                { "author", "zoo" },
            },
        },
    });

});

package main

import (
	"github.com/pulumi/pulumi-docker/sdk/v5/go/docker"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := docker.NewRemoteImage(ctx, "zoo", &docker.RemoteImageArgs{
			Name: pulumi.String("zoo"),
			Build: &docker.RemoteImageBuildArgs{
				Context: pulumi.String("."),
				Tags: pulumi.StringArray{
					pulumi.String("zoo:develop"),
				},
				BuildArgs: pulumi.StringMap{
					"foo": pulumi.String("zoo"),
				},
				Label: pulumi.StringMap{
					"author": pulumi.String("zoo"),
				},
			},
		})
		if err != nil {
			return err
		}
		return nil
	})
}

pulumi {
  required_providers {
    docker = {
      source = "pulumi/docker"
    }
  }
}

resource "docker_remoteimage" "zoo" {
  name = "zoo"
  build = {
    context = "."
    tags    = ["zoo:develop"]
    build_args = {
      "foo" = "zoo"
    }
    label = {
      "author" = "zoo"
    }
  }
}

package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.docker.RemoteImage;
import com.pulumi.docker.RemoteImageArgs;
import com.pulumi.docker.inputs.RemoteImageBuildArgs;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var zoo = new RemoteImage("zoo", RemoteImageArgs.builder()
            .name("zoo")
            .build(RemoteImageBuildArgs.builder()
                .context(".")
                .tags("zoo:develop")
                .buildArgs(Map.of("foo", "zoo"))
                .label(Map.of("author", "zoo"))
                .build())
            .build());

    }
}

resources:
  zoo:
    type: docker:RemoteImage
    properties:
      name: zoo
      build:
        context: .
        tags:
          - zoo:develop
        buildArgs:
          foo: zoo
        label:
          author: zoo

You can use the triggers argument to specify when the image should be rebuild. This is for example helpful when you want to rebuild the docker image whenever the source code changes.