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

Fix references to buildx.Image

Browse Source
This commit is contained in:
Bryce Lampe
2024-03-29 11:22:08 -07:00
parent 6efd4b045b
commit da2fecf013
20 changed files with 979 additions and 981 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
provider/internal/embed/image-migration.md
View File

@@ -1,11 +1,11 @@
## Migrating v3 and v4 Image resources
The `buildx.Image` resource provides a superset of functionality over the `Image` resources available in versions 3 and 4 of the Pulumi Docker provider.
Existing `Image` resources can be converted to `build.Image` resources with minor modifications.
The `dockerbuild.Image` resource provides a superset of functionality over the `Image` resources available in versions 3 and 4 of the Pulumi Docker provider.
Existing `Image` resources can be converted to `dockerbuild.Image` resources with minor modifications.
### Behavioral differences
There are several key behavioral differences to keep in mind when transitioning images to the new `buildx.Image` resource.
There are several key behavioral differences to keep in mind when transitioning images to the new `dockerbuild.Image` resource.
#### Previews
@@ -16,8 +16,8 @@ Version `4.x` changed build-on-preview behavior to be opt-in.
By default, `v4.x` `Image` resources do _not_ build during previews, but this behavior can be toggled with the `buildOnPreview` option.
Some users felt this made previews in CI less helpful because they no longer detected bad images by default.
The default behavior of the `buildx.Image` resource has been changed to strike a better balance between CI use cases and manual updates.
By default, Pulumi will now only build `buildx.Image` resources during previews when it detects a CI environment like GitHub Actions.
The default behavior of the `dockerbuild.Image` resource has been changed to strike a better balance between CI use cases and manual updates.
By default, Pulumi will now only build `dockerbuild.Image` resources during previews when it detects a CI environment like GitHub Actions.
Previews run in non-CI environments will not build images.
This behavior is still configurable with `buildOnPreview`.
@@ -26,7 +26,7 @@ This behavior is still configurable with `buildOnPreview`.
Versions `3.x` and `4.x` of the Pulumi Docker provider attempt to push images to remote registries by default.
They expose a `skipPush: true` option to disable pushing.
The `buildx.Image` resource matches the Docker CLI's behavior and does not push images anywhere by default.
The `dockerbuild.Image` resource matches the Docker CLI's behavior and does not push images anywhere by default.
To push images to a registry you can include `push: true` (equivalent to Docker's `--push` flag) or configure an `export` of type `registry` (equivalent to Docker's `--output type=registry`).
Like Docker, if an image is configured without exports you will see a warning with instructions for how to enable pushing, but the build will still proceed normally.
@@ -37,7 +37,7 @@ Version `3.x` of the Pulumi Docker provider supports secrets by way of the `extr
Version `4.x` of the Pulumi Docker provider does not support secrets.
The `buildx.Image` resource supports secrets but does not require those secrets to exist on-disk or in environment variables.
The `dockerbuild.Image` resource supports secrets but does not require those secrets to exist on-disk or in environment variables.
Instead, they should be passed directly as values.
(Please be sure to familiarize yourself with Pulumi's [native secret handling](https://www.pulumi.com/docs/concepts/secrets/).)
Pulumi also provides [ESC](https://www.pulumi.com/product/esc/) to make it easier to share secrets across stacks and environments.
@@ -52,7 +52,7 @@ Version `4.x` exposes a similar parameter `cacheFrom: { images: [...] }` which p
Both versions 3 and 4 require specific environment variables to be set and deviate from Docker's native caching behavior.
This can result in inefficient builds due to unnecessary image pulls, repeated file transfers, etc.
The `buildx.Image` resource delegates all caching behavior to Docker.
The `dockerbuild.Image` resource delegates all caching behavior to Docker.
`cacheFrom` and `cacheTo` options (equivalent to Docker's `--cache-to` and `--cache-from`) are exposed and provide additional cache targets, such as local disk, S3 storage, etc.
#### Outputs
@@ -60,7 +60,7 @@ The `buildx.Image` resource delegates all caching behavior to Docker.
Versions `3.x` and `4.x` of the provider exposed a `repoDigest` output which was a fully qualified tag with digest.
In `4.x` this could also be a single sha256 hash if the image wasn't pushed.
Unlike earlier providers the `buildx.Image` resource can push multiple tags.
Unlike earlier providers the `dockerbuild.Image` resource can push multiple tags.
As a convenience, it exposes a `ref` output consisting of a tag with digest as long as the image was pushed.
If multiple tags were pushed this uses one at random.
@@ -73,7 +73,7 @@ Versions 3 and 4 of Pulumi Docker provider do not delete tags when the `Image` r
The `buidx.Image` will query your registries during `refresh` to ensure the expected tags exist.
If any are missing a subsequent `update` will push them.
When a `buildx.Image` is deleted, it will _attempt_ to also delete any pushed tags.
When a `dockerbuild.Image` is deleted, it will _attempt_ to also delete any pushed tags.
Deletion of remote tags is not guaranteed because not all registries support the manifest `DELETE` API (`docker.io` in particular).
Manifests are _not_ deleted in the same way during updates -- to do so safely would require a full build to determine whether a Pulumi operation should be an update or update-replace.
@@ -81,11 +81,11 @@ Use the [`retainOnDelete: true`](https://www.pulumi.com/docs/concepts/options/re
### Example migration
Examples of "fully-featured" `v3` and `v4` `Image` resources are shown below, along with an example `buildx.Image` resource showing how they would look after migration.
Examples of "fully-featured" `v3` and `v4` `Image` resources are shown below, along with an example `dockerbuild.Image` resource showing how they would look after migration.
The `v3` resource leverages `buildx` via a `DOCKER_BUILDKIT` environment variable and CLI flags passed in with `extraOption`.
After migration, the environment variable is no longer needed and CLI flags are now properties on the `buildx.Image`.
In almost all cases, properties of `buildx.Image` are named after the Docker CLI flag they correspond to.
After migration, the environment variable is no longer needed and CLI flags are now properties on the `dockerbuild.Image`.
In almost all cases, properties of `dockerbuild.Image` are named after the Docker CLI flag they correspond to.
The `v4` resource is less functional than its `v3` counterpart because it lacks the flexibility of `extraOptions`.
It it is shown with parameters similar to the `v3` example for completeness.
@@ -136,8 +136,8 @@ const v3 = new docker.Image("v3-image", {
},
});
// v3 Image after migrating to buildx.Image
const v3Migrated = new docker.buildx.Image("v3-to-buildx", {
// v3 Image after migrating to dockerbuild.Image
const v3Migrated = new dockerbuild.Image("v3-to-buildx", {
tags: ["myregistry.com/user/repo:latest", "local-tag"],
push: true,
dockerfile: {
@@ -195,8 +195,8 @@ const v4 = new docker.Image("v4-image", {
},
});
// v4 Image after migrating to buildx.Image
const v4Migrated = new docker.buildx.Image("v4-to-buildx", {
// v4 Image after migrating to dockerbuild.Image
const v4Migrated = new dockerbuild.Image("v4-to-buildx", {
tags: ["myregistry.com/user/repo:latest"],
push: true,
dockerfile: {