diff --git a/docs/_index.md b/docs/_index.md new file mode 100644 index 0000000..66e11d1 --- /dev/null +++ b/docs/_index.md @@ -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 + { + ["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 >}} diff --git a/docs/installation-configuration.md b/docs/installation-configuration.md new file mode 100644 index 0000000..cd66298 --- /dev/null +++ b/docs/installation-configuration.md @@ -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/ +```