implement first pass at cached image data source (#3)

implements envbuilder_cached_image data source

Author: johnstcn

.github/workflows/test.yml

@@ -65,11 +65,12 @@ jobs:
       matrix:
         # list whatever Terraform versions here you would like to support
         terraform:
-          - '1.0.*'
-          - '1.1.*'
-          - '1.2.*'
-          - '1.3.*'
-          - '1.4.*'
+          # TODO: test with more terraform versions. For now, testing with latest.
+          # - "1.5.*"
+          # - "1.6.*"
+          # - "1.7.*"
+          # - "1.8.*"
+          - "1.9.*"
     steps:
       - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
       - uses: actions/setup-go@cdcb36043654635271a94b9a6d1392de5bb323a7 # v5.0.1
@@ -81,6 +82,7 @@ jobs:
           terraform_version: ${{ matrix.terraform }}
           terraform_wrapper: false
       - run: go mod download
+      - run: make test-registry
       - env:
           TF_ACC: "1"
         run: go test -v -cover ./internal/provider/

.gitignore

@@ -34,4 +34,5 @@ website/vendor
 # Keep windows files with windows line endings
 *.winfile eol=crlf
 
-terraform-provider-envbuilder
+terraform-provider-envbuilder
+.registry-cache/

GNUmakefile

@@ -17,3 +17,34 @@ build: terraform-provider-envbuilder
 
 terraform-provider-envbuilder: internal/provider/*.go main.go
 	CGO_ENABLED=0 go build .
+
+.PHONY: update-envbuilder-version
+update-envbuilder-version:
+	go get github.com/coder/envbuilder@main
+	go mod tidy
+
+# Starts a local Docker registry on port 5000 with a local disk cache.
+.PHONY: test-registry
+test-registry: test-registry-container test-images-pull test-images-push
+
+.PHONY: test-registry-container
+test-registry-container: .registry-cache
+	if ! curl -fsSL http://localhost:5000/v2/_catalog > /dev/null 2>&1; then \
+		docker rm -f tfprov-envbuilder-registry && \
+		docker run -d -p 5000:5000 --name envbuilder-registry --volume $(PWD)/.registry-cache:/var/lib/registry registry:2; \
+	fi
+
+# Pulls images referenced in integration tests and pushes them to the local cache.
+.PHONY: test-images-push
+test-images-push: .registry-cache/docker/registry/v2/repositories/test-ubuntu
+
+.PHONY: test-images-pull
+test-images-pull:
+	docker pull ubuntu:latest
+	docker tag ubuntu:latest localhost:5000/test-ubuntu:latest
+
+.registry-cache:
+	mkdir -p .registry-cache && chmod -R ag+w .registry-cache
+
+.registry-cache/docker/registry/v2/repositories/test-ubuntu:
+	docker push localhost:5000/test-ubuntu:latest

docs/data-sources/cached_image.md

@@ -3,12 +3,12 @@
 page_title: "envbuilder_cached_image Data Source - envbuilder"
 subcategory: ""
 description: |-
-  The cached image data source can be used to retrieve a cached image produced by envbuilder.
+  The cached image data source can be used to retrieve a cached image produced by envbuilder. Reading from this data source will clone the specified Git repository, read a Devcontainer specification or Dockerfile, and check for its presence in the provided cache repo.
 ---
 
 # envbuilder_cached_image (Data Source)
 
-The cached image data source can be used to retrieve a cached image produced by envbuilder.
+The cached image data source can be used to retrieve a cached image produced by envbuilder. Reading from this data source will clone the specified Git repository, read a Devcontainer specification or Dockerfile, and check for its presence in the provided cache repo.
 
 ## Example Usage
 
@@ -33,20 +33,36 @@ resource "docker_container" "container" {
 
 ### Required
 
-- `builder_image` (String) The builder image URL to use if the cache does not exist.
-- `cache_repo` (String) The name of the container registry to fetch the cache image from.
-- `git_url` (String) The URL of a Git repository containing a Devcontainer or Docker image to clone.
+- `builder_image` (String) The envbuilder image to use if the cached version is not found.
+- `cache_repo` (String) (Envbuilder option) The name of the container registry to fetch the cache image from.
+- `git_url` (String) (Envbuilder option) The URL of a Git repository containing a Devcontainer or Docker image to clone.
 
 ### Optional
 
-- `cache_ttl_days` (Number) The number of days to use cached layers before expiring them. Defaults to 7 days.
-- `extra_env` (Map of String) Extra environment variables to set for the container. This may include evbuilder options.
-- `git_password` (String, Sensitive) The password to use for Git authentication. This is optional.
-- `git_username` (String) The username to use for Git authentication. This is optional.
+- `base_image_cache_dir` (String) (Envbuilder option) The path to a directory where the base image can be found. This should be a read-only directory solely mounted for the purpose of caching the base image.
+- `build_context_path` (String) (Envbuilder option) Can be specified when a DockerfilePath is specified outside the base WorkspaceFolder. This path MUST be relative to the WorkspaceFolder path into which the repo is cloned.
+- `cache_ttl_days` (Number) (Envbuilder option) The number of days to use cached layers before expiring them. Defaults to 7 days.
+- `devcontainer_dir` (String) (Envbuilder option) The path to the folder containing the devcontainer.json file that will be used to build the workspace and can either be an absolute path or a path relative to the workspace folder. If not provided, defaults to `.devcontainer`.
+- `devcontainer_json_path` (String) (Envbuilder option) The path to a devcontainer.json file that is either an absolute path or a path relative to DevcontainerDir. This can be used in cases where one wants to substitute an edited devcontainer.json file for the one that exists in the repo.
+- `docker_config_base64` (String) (Envbuilder option) The base64 encoded Docker config file that will be used to pull images from private container registries.
+- `dockerfile_path` (String) (Envbuilder option) The relative path to the Dockerfile that will be used to build the workspace. This is an alternative to using a devcontainer that some might find simpler.
+- `exit_on_build_failure` (Boolean) (Envbuilder option) Terminates upon a build failure. This is handy when preferring the FALLBACK_IMAGE in cases where no devcontainer.json or image is provided. However, it ensures that the container stops if the build process encounters an error.
+- `extra_env` (Map of String) Extra environment variables to set for the container. This may include envbuilder options.
+- `fallback_image` (String) (Envbuilder option) Specifies an alternative image to use when neither an image is declared in the devcontainer.json file nor a Dockerfile is present. If there's a build failure (from a faulty Dockerfile) or a misconfiguration, this image will be the substitute. Set ExitOnBuildFailure to true to halt the container if the build faces an issue.
+- `git_clone_depth` (Number) (Envbuilder option) The depth to use when cloning the Git repository.
+- `git_clone_single_branch` (Boolean) (Envbuilder option) Clone only a single branch of the Git repository.
+- `git_http_proxy_url` (String) (Envbuilder option) The URL for the HTTP proxy. This is optional.
+- `git_password` (String, Sensitive) (Envbuilder option) The password to use for Git authentication. This is optional.
+- `git_ssh_private_key_path` (String) (Envbuilder option) Path to an SSH private key to be used for Git authentication.
+- `git_username` (String) (Envbuilder option) The username to use for Git authentication. This is optional.
+- `ignore_paths` (List of String) (Envbuilder option) The comma separated list of paths to ignore when building the workspace.
+- `insecure` (Boolean) (Envbuilder option) Bypass TLS verification when cloning and pulling from container registries.
+- `ssl_cert_base64` (String) (Envbuilder option) The content of an SSL cert file. This is useful for self-signed certificates.
+- `verbose` (Boolean) (Envbuilder option) Enable verbose output.
 
 ### Read-Only
 
 - `env` (List of String) Computed envbuilder configuration to be set for the container.
 - `exists` (Boolean) Whether the cached image was exists or not for the given config.
-- `id` (String) Cached image identifier
-- `image` (String) Outputs the cached image URL if it exists, otherwise the builder image URL is output instead.
+- `id` (String) Cached image identifier. This will generally be the image's SHA256 digest.
+- `image` (String) Outputs the cached image repo@digest if it exists, and builder image otherwise.