Join us at the Cloud Engineering Summit on October 20th for a free day of learning. Save your spot.

RemoteImage

Pulls a Docker image to a given Docker host from a Docker Registry. This resource will not pull new layers of the image automatically unless used in conjunction with docker.RegistryImage data source to update the pull_triggers field.

Schema

Required

  • name (String) The name of the Docker image, including any tags or SHA256 repo digests.

Optional

  • build (Block Set, Max: 1) Configuration to build an image. Please see docker build command reference too. (see below for nested schema)
  • force_remove (Boolean) If true, then the image is removed forcibly when the resource is destroyed.
  • id (String) The ID of this resource.
  • keep_locally (Boolean) If true, then the Docker image won’t be deleted on destroy operation. If this is false, it will delete the image from the docker local storage on destroy operation.
  • pull_trigger (String, Deprecated) A value which cause an image pull when changed
  • pull_triggers (Set of String) List of values which cause an image pull when changed. This is used to store the image digest from the registry when using the docker_registry_image.

Read-Only

  • latest (String, Deprecated) The ID of the image in the form of sha256:<hash> image digest. Do not confuse it with the default latest tag.
  • output (String, Deprecated)
  • repo_digest (String) The image sha256 digest in the form of repo[:tag]@sha256:<hash>.

Nested Schema for build

Required:

  • path (String) Context path

Optional:

  • build_arg (Map of String) Set build-time variables
  • dockerfile (String) Name of the Dockerfile. Defaults to Dockerfile.
  • force_remove (Boolean) Always remove intermediate containers
  • label (Map of String) Set metadata for an image
  • no_cache (Boolean) Do not use cache when building the image
  • remove (Boolean) Remove intermediate containers after a successful build. Defaults to true.
  • tag (List of String) Name and optionally a tag in the ‘name:tag’ format
  • target (String) Set the target build stage to build

Example Usage

Basic

using Pulumi;
using Docker = Pulumi.Docker;

class MyStack : Stack
{
    public MyStack()
    {
        var ubuntu = new Docker.RemoteImage("ubuntu", new Docker.RemoteImageArgs
        {
            Name = "ubuntu:precise",
        });
    }

}
package main

import (
	"github.com/pulumi/pulumi-docker/sdk/v3/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
	})
}
import pulumi
import pulumi_docker as docker

ubuntu = docker.RemoteImage("ubuntu", name="ubuntu:precise")
import * as pulumi from "@pulumi/pulumi";
import * as docker from "@pulumi/docker";

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

Dynamic updates

using Pulumi;
using Docker = Pulumi.Docker;

class MyStack : Stack
{
    public MyStack()
    {
        var ubuntuRegistryImage = Output.Create(Docker.GetRegistryImage.InvokeAsync(new Docker.GetRegistryImageArgs
        {
            Name = "ubuntu:precise",
        }));
        var ubuntuRemoteImage = new Docker.RemoteImage("ubuntuRemoteImage", new Docker.RemoteImageArgs
        {
            Name = ubuntuRegistryImage.Apply(ubuntuRegistryImage => ubuntuRegistryImage.Name),
            PullTriggers = 
            {
                ubuntuRegistryImage.Apply(ubuntuRegistryImage => ubuntuRegistryImage.Sha256Digest),
            },
        });
    }

}
package main

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

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

ubuntu_registry_image = docker.get_registry_image(name="ubuntu:precise")
ubuntu_remote_image = docker.RemoteImage("ubuntuRemoteImage",
    name=ubuntu_registry_image.name,
    pull_triggers=[ubuntu_registry_image.sha256_digest])
import * as pulumi from "@pulumi/pulumi";
import * as docker from "@pulumi/docker";

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

Build

using Pulumi;
using Docker = Pulumi.Docker;

class MyStack : Stack
{
    public MyStack()
    {
        var zoo = new Docker.RemoteImage("zoo", new Docker.RemoteImageArgs
        {
            Name = "zoo",
            Build = new Docker.Inputs.RemoteImageBuildArgs
            {
                Path = ".",
                Tags = 
                {
                    "zoo:develop",
                },
                BuildArg = 
                {
                    { "foo", "zoo" },
                },
                Label = 
                {
                    { "author", "zoo" },
                },
            },
        });
    }

}
package main

import (
	"github.com/pulumi/pulumi-docker/sdk/v3/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{
				Path: pulumi.String("."),
				Tags: pulumi.StringArray{
					pulumi.String("zoo:develop"),
				},
				BuildArg: pulumi.StringMap{
					"foo": pulumi.String("zoo"),
				},
				Label: pulumi.StringMap{
					"author": pulumi.String("zoo"),
				},
			},
		})
		if err != nil {
			return err
		}
		return nil
	})
}
import pulumi
import pulumi_docker as docker

zoo = docker.RemoteImage("zoo",
    name="zoo",
    build=docker.RemoteImageBuildArgs(
        path=".",
        tags=["zoo:develop"],
        build_arg={
            "foo": "zoo",
        },
        label={
            "author": "zoo",
        },
    ))
import * as pulumi from "@pulumi/pulumi";
import * as docker from "@pulumi/docker";

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

Create a RemoteImage Resource

new RemoteImage(name: string, args: RemoteImageArgs, opts?: CustomResourceOptions);
@overload
def RemoteImage(resource_name: str,
                opts: Optional[ResourceOptions] = None,
                build: Optional[RemoteImageBuildArgs] = None,
                force_remove: Optional[bool] = None,
                keep_locally: Optional[bool] = None,
                name: Optional[str] = None,
                pull_trigger: Optional[str] = None,
                pull_triggers: Optional[Sequence[str]] = None)
@overload
def RemoteImage(resource_name: str,
                args: RemoteImageArgs,
                opts: Optional[ResourceOptions] = None)
func NewRemoteImage(ctx *Context, name string, args RemoteImageArgs, opts ...ResourceOption) (*RemoteImage, error)
public RemoteImage(string name, RemoteImageArgs args, CustomResourceOptions? opts = null)
name string
The unique name of the resource.
args RemoteImageArgs
The arguments to resource properties.
opts CustomResourceOptions
Bag of options to control resource's behavior.
resource_name str
The unique name of the resource.
args RemoteImageArgs
The arguments to resource properties.
opts ResourceOptions
Bag of options to control resource's behavior.
ctx Context
Context object for the current deployment.
name string
The unique name of the resource.
args RemoteImageArgs
The arguments to resource properties.
opts ResourceOption
Bag of options to control resource's behavior.
name string
The unique name of the resource.
args RemoteImageArgs
The arguments to resource properties.
opts CustomResourceOptions
Bag of options to control resource's behavior.

RemoteImage Resource Properties

To learn more about resource properties and how to use them, see Inputs and Outputs in the Architecture and Concepts docs.

Inputs

The RemoteImage resource accepts the following input properties:

Name string
The name of the Docker image, including any tags or SHA256 repo digests.
Build RemoteImageBuildArgs
Configuration to build an image. Please see docker build command reference too.
ForceRemove bool
If true, then the image is removed forcibly when the resource is destroyed.
KeepLocally bool
If true, then the Docker image won’t be deleted on destroy operation. If this is false, it will delete the image from the docker local storage on destroy operation.
PullTrigger string
A value which cause an image pull when changed

Deprecated: Use field pull_triggers instead

PullTriggers List<string>
List of values which cause an image pull when changed. This is used to store the image digest from the registry when using the docker_registry_image.
Name string
The name of the Docker image, including any tags or SHA256 repo digests.
Build RemoteImageBuildArgs
Configuration to build an image. Please see docker build command reference too.
ForceRemove bool
If true, then the image is removed forcibly when the resource is destroyed.
KeepLocally bool
If true, then the Docker image won’t be deleted on destroy operation. If this is false, it will delete the image from the docker local storage on destroy operation.
PullTrigger string
A value which cause an image pull when changed

Deprecated: Use field pull_triggers instead

PullTriggers []string
List of values which cause an image pull when changed. This is used to store the image digest from the registry when using the docker_registry_image.
name string
The name of the Docker image, including any tags or SHA256 repo digests.
build RemoteImageBuildArgs
Configuration to build an image. Please see docker build command reference too.
forceRemove boolean
If true, then the image is removed forcibly when the resource is destroyed.
keepLocally boolean
If true, then the Docker image won’t be deleted on destroy operation. If this is false, it will delete the image from the docker local storage on destroy operation.
pullTrigger string
A value which cause an image pull when changed

Deprecated: Use field pull_triggers instead

pullTriggers string[]
List of values which cause an image pull when changed. This is used to store the image digest from the registry when using the docker_registry_image.
name str
The name of the Docker image, including any tags or SHA256 repo digests.
build RemoteImageBuildArgs
Configuration to build an image. Please see docker build command reference too.
force_remove bool
If true, then the image is removed forcibly when the resource is destroyed.
keep_locally bool
If true, then the Docker image won’t be deleted on destroy operation. If this is false, it will delete the image from the docker local storage on destroy operation.
pull_trigger str
A value which cause an image pull when changed

Deprecated: Use field pull_triggers instead

pull_triggers Sequence[str]
List of values which cause an image pull when changed. This is used to store the image digest from the registry when using the docker_registry_image.

Outputs

All input properties are implicitly available as output properties. Additionally, the RemoteImage resource produces the following output properties:

Id string
The provider-assigned unique ID for this managed resource.
Latest string
The ID of the image in the form of sha256:<hash> image digest. Do not confuse it with the default latest tag.

Deprecated: Use repo_digest instead

Output string

Deprecated: Is unused and will be removed.

RepoDigest string
The image sha256 digest in the form of repo[:tag]@sha256:<hash>.
Id string
The provider-assigned unique ID for this managed resource.
Latest string
The ID of the image in the form of sha256:<hash> image digest. Do not confuse it with the default latest tag.

Deprecated: Use repo_digest instead

Output string

Deprecated: Is unused and will be removed.

RepoDigest string
The image sha256 digest in the form of repo[:tag]@sha256:<hash>.
id string
The provider-assigned unique ID for this managed resource.
latest string
The ID of the image in the form of sha256:<hash> image digest. Do not confuse it with the default latest tag.

Deprecated: Use repo_digest instead

output string

Deprecated: Is unused and will be removed.

repoDigest string
The image sha256 digest in the form of repo[:tag]@sha256:<hash>.
id str
The provider-assigned unique ID for this managed resource.
latest str
The ID of the image in the form of sha256:<hash> image digest. Do not confuse it with the default latest tag.

Deprecated: Use repo_digest instead

output str

Deprecated: Is unused and will be removed.

repo_digest str
The image sha256 digest in the form of repo[:tag]@sha256:<hash>.

Look up an Existing RemoteImage Resource

Get an existing RemoteImage resource’s state with the given name, ID, and optional extra properties used to qualify the lookup.

public static get(name: string, id: Input<ID>, state?: RemoteImageState, opts?: CustomResourceOptions): RemoteImage
@staticmethod
def get(resource_name: str,
        id: str,
        opts: Optional[ResourceOptions] = None,
        build: Optional[RemoteImageBuildArgs] = None,
        force_remove: Optional[bool] = None,
        keep_locally: Optional[bool] = None,
        latest: Optional[str] = None,
        name: Optional[str] = None,
        output: Optional[str] = None,
        pull_trigger: Optional[str] = None,
        pull_triggers: Optional[Sequence[str]] = None,
        repo_digest: Optional[str] = None) -> RemoteImage
func GetRemoteImage(ctx *Context, name string, id IDInput, state *RemoteImageState, opts ...ResourceOption) (*RemoteImage, error)
public static RemoteImage Get(string name, Input<string> id, RemoteImageState? state, CustomResourceOptions? opts = null)
name
The unique name of the resulting resource.
id
The unique provider ID of the resource to lookup.
state
Any extra arguments used during the lookup.
opts
A bag of options that control this resource's behavior.
resource_name
The unique name of the resulting resource.
id
The unique provider ID of the resource to lookup.
name
The unique name of the resulting resource.
id
The unique provider ID of the resource to lookup.
state
Any extra arguments used during the lookup.
opts
A bag of options that control this resource's behavior.
name
The unique name of the resulting resource.
id
The unique provider ID of the resource to lookup.
state
Any extra arguments used during the lookup.
opts
A bag of options that control this resource's behavior.

The following state arguments are supported:

Build RemoteImageBuildArgs
Configuration to build an image. Please see docker build command reference too.
ForceRemove bool
If true, then the image is removed forcibly when the resource is destroyed.
KeepLocally bool
If true, then the Docker image won’t be deleted on destroy operation. If this is false, it will delete the image from the docker local storage on destroy operation.
Latest string
The ID of the image in the form of sha256:<hash> image digest. Do not confuse it with the default latest tag.

Deprecated: Use repo_digest instead

Name string
The name of the Docker image, including any tags or SHA256 repo digests.
Output string

Deprecated: Is unused and will be removed.

PullTrigger string
A value which cause an image pull when changed

Deprecated: Use field pull_triggers instead

PullTriggers List<string>
List of values which cause an image pull when changed. This is used to store the image digest from the registry when using the docker_registry_image.
RepoDigest string
The image sha256 digest in the form of repo[:tag]@sha256:<hash>.
Build RemoteImageBuildArgs
Configuration to build an image. Please see docker build command reference too.
ForceRemove bool
If true, then the image is removed forcibly when the resource is destroyed.
KeepLocally bool
If true, then the Docker image won’t be deleted on destroy operation. If this is false, it will delete the image from the docker local storage on destroy operation.
Latest string
The ID of the image in the form of sha256:<hash> image digest. Do not confuse it with the default latest tag.

Deprecated: Use repo_digest instead

Name string
The name of the Docker image, including any tags or SHA256 repo digests.
Output string

Deprecated: Is unused and will be removed.

PullTrigger string
A value which cause an image pull when changed

Deprecated: Use field pull_triggers instead

PullTriggers []string
List of values which cause an image pull when changed. This is used to store the image digest from the registry when using the docker_registry_image.
RepoDigest string
The image sha256 digest in the form of repo[:tag]@sha256:<hash>.
build RemoteImageBuildArgs
Configuration to build an image. Please see docker build command reference too.
forceRemove boolean
If true, then the image is removed forcibly when the resource is destroyed.
keepLocally boolean
If true, then the Docker image won’t be deleted on destroy operation. If this is false, it will delete the image from the docker local storage on destroy operation.
latest string
The ID of the image in the form of sha256:<hash> image digest. Do not confuse it with the default latest tag.

Deprecated: Use repo_digest instead

name string
The name of the Docker image, including any tags or SHA256 repo digests.
output string

Deprecated: Is unused and will be removed.

pullTrigger string
A value which cause an image pull when changed

Deprecated: Use field pull_triggers instead

pullTriggers string[]
List of values which cause an image pull when changed. This is used to store the image digest from the registry when using the docker_registry_image.
repoDigest string
The image sha256 digest in the form of repo[:tag]@sha256:<hash>.
build RemoteImageBuildArgs
Configuration to build an image. Please see docker build command reference too.
force_remove bool
If true, then the image is removed forcibly when the resource is destroyed.
keep_locally bool
If true, then the Docker image won’t be deleted on destroy operation. If this is false, it will delete the image from the docker local storage on destroy operation.
latest str
The ID of the image in the form of sha256:<hash> image digest. Do not confuse it with the default latest tag.

Deprecated: Use repo_digest instead

name str
The name of the Docker image, including any tags or SHA256 repo digests.
output str

Deprecated: Is unused and will be removed.

pull_trigger str
A value which cause an image pull when changed

Deprecated: Use field pull_triggers instead

pull_triggers Sequence[str]
List of values which cause an image pull when changed. This is used to store the image digest from the registry when using the docker_registry_image.
repo_digest str
The image sha256 digest in the form of repo[:tag]@sha256:<hash>.

Supporting Types

RemoteImageBuild

Path string
BuildArg Dictionary<string, string>
Dockerfile string
ForceRemove bool
Label Dictionary<string, string>
NoCache bool
Remove bool
Tags List<string>
Target string
Path string
BuildArg map[string]string
Dockerfile string
ForceRemove bool
Label map[string]string
NoCache bool
Remove bool
Tags []string
Target string
path string
buildArg {[key: string]: string}
dockerfile string
forceRemove boolean
label {[key: string]: string}
noCache boolean
remove boolean
tags string[]
target string
path str
build_arg Mapping[str, str]
dockerfile str
force_remove bool
label Mapping[str, str]
no_cache bool
remove bool
tags Sequence[str]
target str

Package Details

Repository
https://github.com/pulumi/pulumi-docker
License
Apache-2.0
Notes
This Pulumi package is based on the docker Terraform Provider.