sam_oneal/pulumi-docker-build
1
0
Fork 0
Code Actions Packages Releases Wiki Activity

Move _index.md and installation-configuration.md into the repo. (#622)

Browse Source 
Related to: https://github.com/pulumi/registry/pull/8814

Make this provider follow the Pulumi official convention of [using the
`_index.md` and
`installation-configuration.md`](https://www.pulumi.com/docs/iac/build-with-pulumi/publishing-packages/#write-documentation).
This commit is contained in:
Alberto Pose
2025-10-09 09:34:35 +01:00
committed by GitHub
parent c159079132
commit ff8995c434
2 changed files with 461 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

428
docs/_index.md Normal file
View File

@@ -0,0 +1,428 @@
---
title: Docker Build
meta_desc: Provides an overview of the Docker Build Provider for Pulumi.
layout: package
---
The Docker Build provider leverages [buildx and BuildKit](https://docs.docker.com/build/architecture/) to build modern Docker images with Pulumi.
Not to be confused with the earlier
[Docker](../docker) provider, which is still
appropriate for managing resources unrelated to building images.
| Provider | Use cases |
| ---------------- | ----------------------------------------------------------------------- |
| `@pulumi/docker-build` | Anything related to building images with `docker build`. |
| `@pulumi/docker` | Everything else -- including running containers and creating networks. |
## Example
If your Pulumi program has a directory called `app` alongside it, containing a
file named "Dockerfile" (which can be as simple as `FROM alpine` for the
purpose of example), then the code below shows how to build a multi-platform
image, publish it to a remote AWS ECR registry, and use an [inline
cache](https://docs.docker.com/build/cache/backends/inline/) to speed up
subsequent builds.
{{< chooser language "typescript,python,csharp,go,yaml,java" / >}}
{{% choosable language typescript %}}
```typescript
import * as aws from "@pulumi/aws";
import * as docker_build from "@pulumi/docker-build";
// Create an ECR repository for pushing.
const ecrRepository = new aws.ecr.Repository("ecr-repository", {});
// Grab auth credentials for ECR.
const authToken = aws.ecr.getAuthorizationTokenOutput({
registryId: ecrRepository.registryId,
});
// Build and push an image to ECR with inline caching.
const myImage = new docker_build.Image("my-image", {
// Tag our image with our ECR repository's address.
tags: [pulumi.interpolate`${ecrRepository.repositoryUrl}:latest`],
context: {
location: "./app",
},
// Use the pushed image as a cache source.
cacheFrom: [{
registry: {
ref: pulumi.interpolate`${ecrRepository.repositoryUrl}:latest`,
},
}],
// Include an inline cache with our pushed image.
cacheTo: [{
inline: {},
}],
// Build a multi-platform image manifest for ARM and AMD.
platforms: [
"linux/amd64",
"linux/arm64",
],
// Push the final result to ECR.
push: true,
// Provide our ECR credentials.
registries: [{
address: ecrRepository.repositoryUrl,
password: authToken.password,
username: authToken.userName,
}],
});
// Export a ref for the pushed images so we can deploy it.
export const ref = myImage.ref;
```
{{% /choosable %}}
{{% choosable language python %}}
```python
import pulumi
import pulumi_aws as aws
import pulumi_docker_build as docker_build
# Create an ECR repository for pushing.
ecr_repository = aws.ecr.Repository("ecr-repository")
# Grab auth credentials for ECR.
auth_token = aws.ecr.get_authorization_token_output(registry_id=ecr_repository.registry_id)
# Build and push an image to ECR with inline caching.
my_image = docker_build.Image("my-image",
# Tag our image with our ECR repository's address.
tags=[ecr_repository.repository_url.apply(lambda repository_url: f"{repository_url}:latest")],
context=docker_build.BuildContextArgs(
location="./app",
),
# Use the pushed image as a cache source.
cache_from=[docker_build.CacheFromArgs(
registry=docker_build.CacheFromRegistryArgs(
ref=ecr_repository.repository_url.apply(lambda repository_url: f"{repository_url}:latest"),
),
)],
# Include an inline cache with our pushed image.
cache_to=[docker_build.CacheToArgs(
inline=docker_build.CacheToInlineArgs(),
)],
# Build a multi-platform image manifest for ARM and AMD.
platforms=[
docker_build.Platform.LINUX_AMD64,
docker_build.Platform.LINUX_ARM64,
],
# Push the final result to ECR.
push=True,
# Provide our ECR credentials.
registries=[docker_build.RegistryArgs(
address=ecr_repository.repository_url,
password=auth_token.password,
username=auth_token.user_name,
)],
)
# Export a ref for the pushed images so we can deploy it.
pulumi.export("ref", my_image.ref)
```
{{% /choosable %}}
{{% choosable language csharp %}}
```csharp
using System.Collections.Generic;
using System.Linq;
using Pulumi;
using Aws = Pulumi.Aws;
using DockerBuild = Pulumi.DockerBuild;
return await Deployment.RunAsync(() =>
{
// Create an ECR repository for pushing.
var ecrRepository = new Aws.Ecr.Repository("ecr-repository");
// Grab auth credentials for ECR.
var authToken = Aws.Ecr.GetAuthorizationToken.Invoke(new()
{
RegistryId = ecrRepository.RegistryId,
});
// Build and push an image to ECR with inline caching.
var myImage = new DockerBuild.Image("my-image", new()
{
// Tag our image with our ECR repository's address.
Tags = new[]
{
ecrRepository.RepositoryUrl.Apply(repositoryUrl => $"{repositoryUrl}:latest"),
},
Context = new DockerBuild.Inputs.BuildContextArgs
{
Location = "./app",
},
// Use the pushed image as a cache source.
CacheFrom = new[]
{
new DockerBuild.Inputs.CacheFromArgs
{
Registry = new DockerBuild.Inputs.CacheFromRegistryArgs
{
Ref = ecrRepository.RepositoryUrl.Apply(repositoryUrl => $"{repositoryUrl}:latest"),
},
},
},
// Include an inline cache with our pushed image.
CacheTo = new[]
{
new DockerBuild.Inputs.CacheToArgs
{
Inline = null,
},
},
// Build a multi-platform image manifest for ARM and AMD.
Platforms = new[]
{
DockerBuild.Platform.Linux_amd64,
DockerBuild.Platform.Linux_arm64,
},
// Push the final result to ECR.
Push = true,
// Provide our ECR credentials.
Registries = new[]
{
new DockerBuild.Inputs.RegistryArgs
{
Address = ecrRepository.RepositoryUrl,
Password = authToken.Apply(getAuthorizationTokenResult => getAuthorizationTokenResult.Password),
Username = authToken.Apply(getAuthorizationTokenResult => getAuthorizationTokenResult.UserName),
},
},
});
// Export a ref for the pushed images so we can deploy it.
return new Dictionary<string, object?>
{
["ref"] = myImage.Ref,
};
});
```
{{% /choosable %}}
{{% choosable language go %}}
```go
package main
import (
"fmt"
"github.com/pulumi/pulumi-aws/sdk/v6/go/aws/ecr"
"github.com/pulumi/pulumi-docker-build/sdk/go/dockerbuild"
"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)
func main() {
pulumi.Run(func(ctx *pulumi.Context) error {
// Create an ECR repository for pushing.
ecrRepository, err := ecr.NewRepository(ctx, "ecr-repository", nil)
if err != nil {
return err
}
// Grab auth credentials for ECR.
authToken := ecr.GetAuthorizationTokenOutput(ctx, ecr.GetAuthorizationTokenOutputArgs{
RegistryId: ecrRepository.RegistryId,
}, nil)
// Build and push an image to ECR with inline caching.
myImage, err := dockerbuild.NewImage(ctx, "my-image", &dockerbuild.ImageArgs{
// Tag our image with our ECR repository's address.
Tags: pulumi.StringArray{
ecrRepository.RepositoryUrl.ApplyT(func(repositoryUrl string) (string, error) {
return fmt.Sprintf("%v:latest", repositoryUrl), nil
}).(pulumi.StringOutput),
},
Context: &dockerbuild.BuildContextArgs{
Location: pulumi.String("./app"),
},
// Use the pushed image as a cache source.
CacheFrom: dockerbuild.CacheFromArray{
&dockerbuild.CacheFromArgs{
Registry: &dockerbuild.CacheFromRegistryArgs{
Ref: ecrRepository.RepositoryUrl.ApplyT(func(repositoryUrl string) (string, error) {
return fmt.Sprintf("%v:latest", repositoryUrl), nil
}).(pulumi.StringOutput),
},
},
},
// Include an inline cache with our pushed image.
CacheTo: dockerbuild.CacheToArray{
&dockerbuild.CacheToArgs{
Inline: nil,
},
},
// Build a multi-platform image manifest for ARM and AMD.
Platforms: dockerbuild.PlatformArray{
dockerbuild.Platform_Linux_amd64,
dockerbuild.Platform_Linux_arm64,
},
// Push the final result to ECR.
Push: pulumi.Bool(true),
// Provide our ECR credentials.
Registries: dockerbuild.RegistryArray{
&dockerbuild.RegistryArgs{
Address: ecrRepository.RepositoryUrl,
Password: authToken.ApplyT(func(authToken ecr.GetAuthorizationTokenResult) (*string, error) {
return &authToken.Password, nil
}).(pulumi.StringPtrOutput),
Username: authToken.ApplyT(func(authToken ecr.GetAuthorizationTokenResult) (*string, error) {
return &authToken.UserName, nil
}).(pulumi.StringPtrOutput),
},
},
})
if err != nil {
return err
}
// Export a ref for the pushed images so we can deploy it.
ctx.Export("ref", myImage.Ref)
return nil
})
}
```
{{% /choosable %}}
{{% choosable language yaml %}}
```yaml
description: Push to AWS ECR with caching
name: ecr
outputs:
ref: ${my-image.ref}
resources:
# Create an ECR repository for pushing.
ecr-repository:
type: aws:ecr:Repository
# Build and push an image to ECR with inline caching.
my-image:
type: docker-build:Image
properties:
# Tag our image with our ECR repository's address.
tags:
- ${ecr-repository.repositoryUrl}:latest
context:
location: ./app
# Use the pushed image as a cache source.
cacheFrom:
- registry:
ref: ${ecr-repository.repositoryUrl}:latest
# Include an inline cache with our pushed image.
cacheTo:
- inline: {}
# Build a multi-platform image manifest for ARM and AMD.
platforms:
- linux/amd64
- linux/arm64
# Push the final result to ECR.
push: true
# Provide our ECR credentials.
registries:
- address: ${ecr-repository.repositoryUrl}
password: ${auth-token.password}
username: ${auth-token.userName}
runtime: yaml
variables:
auth-token:
# Grab auth credentials for ECR.
fn::aws:ecr:getAuthorizationToken:
registryId: ${ecr-repository.registryId}
```
{{% /choosable %}}
{{% choosable language java %}}
```java
package myapp;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.ecr.Repository;
import com.pulumi.aws.ecr.EcrFunctions;
import com.pulumi.aws.ecr.inputs.GetAuthorizationTokenArgs;
import com.pulumi.dockerbuild.Image;
import com.pulumi.dockerbuild.ImageArgs;
import com.pulumi.dockerbuild.inputs.CacheFromArgs;
import com.pulumi.dockerbuild.inputs.CacheFromRegistryArgs;
import com.pulumi.dockerbuild.inputs.CacheToArgs;
import com.pulumi.dockerbuild.inputs.CacheToInlineArgs;
import com.pulumi.dockerbuild.inputs.BuildContextArgs;
import com.pulumi.dockerbuild.inputs.RegistryArgs;
import java.util.List;
import java.util.ArrayList;
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) {
// Create an ECR repository for pushing.
var ecrRepository = new Repository("ecrRepository");
// Grab auth credentials for ECR.
final var authToken = EcrFunctions.getAuthorizationToken(GetAuthorizationTokenArgs.builder()
.registryId(ecrRepository.registryId())
.build());
// Build and push an image to ECR with inline caching.
var myImage = new Image("myImage", ImageArgs.builder()
// Tag our image with our ECR repository's address.
.tags(ecrRepository.repositoryUrl().applyValue(repositoryUrl -> String.format("%s:latest", repositoryUrl)))
.context(BuildContextArgs.builder()
.location("./app")
.build())
// Use the pushed image as a cache source.
.cacheFrom(CacheFromArgs.builder()
.registry(CacheFromRegistryArgs.builder()
.ref(ecrRepository.repositoryUrl().applyValue(repositoryUrl -> String.format("%s:latest", repositoryUrl)))
.build())
.build())
// Include an inline cache with our pushed image.
.cacheTo(CacheToArgs.builder()
.inline()
.build())
// Build a multi-platform image manifest for ARM and AMD.
.platforms(
"linux/amd64",
"linux/arm64")
// Push the final result to ECR.
.push(true)
// Provide our ECR credentials.
.registries(RegistryArgs.builder()
.address(ecrRepository.repositoryUrl())
.password(authToken.applyValue(getAuthorizationTokenResult -> getAuthorizationTokenResult).applyValue(authToken -> authToken.applyValue(getAuthorizationTokenResult -> getAuthorizationTokenResult.password())))
.username(authToken.applyValue(getAuthorizationTokenResult -> getAuthorizationTokenResult).applyValue(authToken -> authToken.applyValue(getAuthorizationTokenResult -> getAuthorizationTokenResult.userName())))
.build())
.build());
ctx.export("ref", myImage.ref());
}
}
```
{{% /choosable %}}
{{< /chooser >}}

33
docs/installation-configuration.md Normal file
View File

@@ -0,0 +1,33 @@
---
title: Docker-Build Installation & Configuration
meta_desc: Provides an overview on how to configure the Pulumi Docker-Build Provider.
layout: package
---
The Pulumi Docker-build provider builds modern Docker images with [buildx](https://docs.docker.com/reference/cli/docker/buildx/) and [BuildKit](https://docs.docker.com/build/buildkit/).
## Installation
The Docker-Build provider is available as a package in all Pulumi languages:
* JavaScript/TypeScript: [`@pulumi/docker-build`](https://www.npmjs.com/package/@pulumi/docker-build)
* Python: [`pulumi-docker-build`](https://pypi.org/project/pulumi-docker-build/)
* Go: [`github.com/pulumi/pulumi-docker-build/sdk/go/dockerbuild`](https://github.com/pulumi/pulumi-docker-build)
* .NET: [`Pulumi.DockerBuild`](https://www.nuget.org/packages/Pulumi.DockerBuild)
* Java: [`com.pulumi/docker-build`](https://central.sonatype.com/artifact/com.pulumi/docker-build)
## Configuring The Provider
### Host
The `DOCKER_HOST` environment variable can be used to specify a custom build daemon's location.
```bash
$ export DOCKER_HOST=tcp://127.0.0.1:2376/
```
This can also be specified in your stack's configuration:
```bash
$ pulumi config set docker-build:host tcp://127.0.0.1:2376/
```