# DockerImage

A Docker image.

Obtainable from: DockerImage.fromBuild, DockerImage.fromBuildV2, DockerImage.fromRegistry

- Source: [`core/lib/bundling.ts`](https://github.com/aws/aws-cdk/blob/v2.278.0/packages/aws-cdk-lib/core/lib/bundling.ts#L351)

## Example

TypeScript:

```ts
const entry = '/path/to/function';
const image = DockerImage.fromBuild(entry);

new python.PythonFunction(this, 'function', {
  entry,
  runtime: Runtime.PYTHON_3_8,
  bundling: {
    buildArgs: { PIP_INDEX_URL: "https://your.index.url/simple/", PIP_EXTRA_INDEX_URL: "https://your.extra-index.url/simple/" },
  },
});
```

Python:

```python
entry = "/path/to/function"
image = DockerImage.from_build(entry)

python.PythonFunction(self, "function",
    entry=entry,
    runtime=Runtime.PYTHON_3_8,
    bundling=python.BundlingOptions(
        build_args={"PIP_INDEX_URL": "https://your.index.url/simple/", "PIP_EXTRA_INDEX_URL": "https://your.extra-index.url/simple/"}
    )
)
```

Java:

```java
String entry = "/path/to/function";
DockerImage image = DockerImage.fromBuild(entry);

PythonFunction.Builder.create(this, "function")
        .entry(entry)
        .runtime(Runtime.PYTHON_3_8)
        .bundling(BundlingOptions.builder()
                .buildArgs(Map.of("PIP_INDEX_URL", "https://your.index.url/simple/", "PIP_EXTRA_INDEX_URL", "https://your.extra-index.url/simple/"))
                .build())
        .build();
```

C# / .NET:

```csharp
// Install: dotnet add package Amazon.CDK.Lib
var entry = "/path/to/function";
var image = DockerImage.FromBuild(entry);

new PythonFunction(this, "function", new PythonFunctionProps {
    Entry = entry,
    Runtime = Runtime.PYTHON_3_8,
    Bundling = new BundlingOptions {
        BuildArgs = new Dictionary<string, string> { { "PIP_INDEX_URL", "https://your.index.url/simple/" }, { "PIP_EXTRA_INDEX_URL", "https://your.extra-index.url/simple/" } }
    }
});
```

Golang:

```go
// Install: go get github.com/aws/aws-cdk-go/awscdk/v2
entry := "/path/to/function"
image := awscdk.DockerImage_FromBuild(entry)

python.NewPythonFunction(this, jsii.String("function"), &PythonFunctionProps{
	Entry: jsii.String(Entry),
	Runtime: awscdk.Runtime_PYTHON_3_8(),
	Bundling: &BundlingOptions{
		BuildArgs: map[string]*string{
			"PIP_INDEX_URL": jsii.String("https://your.index.url/simple/"),
			"PIP_EXTRA_INDEX_URL": jsii.String("https://your.extra-index.url/simple/"),
		},
	},
})
```

## Initializer

TypeScript:

```ts
new DockerImage(image: string, _imageHash?: string)
```

Python:

```python
DockerImage(image: str, _image_hash: typing.Optional[str] = None)
```

Java:

```java
new DockerImage(String image, String _imageHash)
```

C# / .NET:

```csharp
new DockerImage(string image, string? _imageHash = null)
```

Golang:

```go
NewDockerImage(Image *string, _imageHash *string)
```

## Properties

- `image`: string — The Docker image.

## Methods

- `buildImage(): void` — Build the image, if it is built from a Docker file and hasn't been built yet.

  Does nothing for other images, such as images from a registry. Running the
  image or copying files out of it calls this automatically. Call it yourself
  before you pass `image` to your own `docker` commands.

- `cp(imagePath: string, outputPath?: string): string` — Copies a file or directory out of the Docker image to the local filesystem.

  If `outputPath` is omitted the destination path is a temporary directory.

  Builds the image first if it is built on demand and hasn't been built yet.

  **Parameters**

  - `imagePath` — the path in the Docker image.
  - `outputPath` — the destination path for the copy operation.

  **Returns:** the destination path

- `fromBuild(path: string, options?: DockerBuildOptions): DockerImage // chainable` (static) — Builds a Docker image.

  The image is built right away, even if it is never used.

  Use `DockerImage.fromBuildV2()` instead. It builds the same image under the
  same tag, but only when the image is first needed, so assets whose bundled
  output already exists, or that skip bundling, never pay for the build. If
  you need the image right away, call `buildImage()` on it.

  **Parameters**

  - `path` — The path to the directory containing the Docker file.
  - `options` — Docker build options.

- `fromBuildV2(path: string, options?: DockerBuildOptions): DockerImage // chainable` (static) — Reference a Docker image that is built from a Docker file when it is first needed.

  The image is built when `buildImage()` is called, when it first runs, or when
  files are first copied out of it. Asset bundling builds the image right
  before it runs the bundling container, so assets whose bundled output
  already exists, or that skip bundling, never build it.

  Until the image is built, `image` names a tag that may not exist in the
  local Docker daemon yet. Call `buildImage()` before you pass the tag to
  your own `docker` commands. Errors in the Docker file are reported when the
  image is built, for example while an asset is bundled, not when this
  method is called.

  The tag and the `docker build` command are computed from the Docker file
  directory and the build options when this method is called, so later
  changes to the options have no effect. Don't change the Docker file
  directory afterwards, because the image would no longer match its tag.

  Images with the same tag are only built or checked once until the next
  `App` is created, unless they use `buildContexts`. After that, the local
  Docker daemon is checked again.

  The image has the same tag and hash as one built with `DockerImage.fromBuild()`
  from the same arguments, so switching between the two doesn't change asset hashes.

  **Parameters**

  - `path` — The path to the directory containing the Docker file.
  - `options` — Docker build options.

- `fromRegistry(image: string): DockerImage // chainable` (static) — Reference an image on DockerHub or another online registry.

  **Parameters**

  - `image` — the image name.

- `run(options?: DockerRunOptions): void` — Runs a Docker image.

  Builds the image first if it is built on demand and hasn't been built yet.

- `toJSON(): string` — Provides a stable representation of this image for JSON serialization.

  **Returns:** The overridden image name if set or image hash name in that order
