feat: add support for using CLI container clients

[reedham-aws]

Which issue(s) does this change fix?

#3972, #8656, #3852

Why is this change necessary?

Currently, the docker-py SDK does not support BuildKit: docker/docker-py#2230. This means that in order for sam build to use BuildKit, we must use the Docker (or Finch) CLI.

How does it address the issue?

This change adds a BuildClient class that acts as a parent to either the SDKBuildClient or the CLIBuildClient. If a user passes a sam build argument of --use-buildkit, the CLIBuildClient is used with either docker buildx build or finch build ... (Finch uses buildkit by default).

What side effects does this change have?

For existing builds, there shouldn't be any. Using the CLI is entirely opt in, and the SDK build is doing the same thing as before with only a thin layer in between. There could be a difference between the SDK build and the CLI build for different applications (especially for things like cross platform builds, which buildkit is for). There also isn't any change to the detection of which build engine to use, so it shouldn't change where Docker/Finch is used.

Mandatory Checklist

PRs will only be reviewed after checklist is complete

• Review the generative AI contribution guidelines
• Add input/output type hints to new functions/methods
• Write design document if needed (Do I need to write a design document?)
• Write/update unit tests
• Write/update integration tests - To come in follow up PR on this branch
• make pr passes
• Write documentation

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[bnusunny]

If docker buildx version fails, it raises CalledProcessError before the returncode != 0 check is ever reached. This should use check=False or wrap in a try/except for CalledProcessError.

The Finch path has the same issue.

[reedham-aws]

I changed this to be check=False. I originally had let it fall through to the if result.returncode != 0, but then ruff didn't like the lack of explicit check. After that I forgot about the original intention 🙃.

[bnusunny]

This does not raise an exception. The caller function expects docker.errors.BuildError on build failure.

[reedham-aws]

Good callout. I changed this to raise the error instead of stream like this. What I did above was capture the stdout and save it in a list called build_log, then pass that as the build_log for the docker.errors.BuildError, which has the following definition:

class BuildError(DockerException):
    def __init__(self, reason, build_log):
        super().__init__(reason)
        self.msg = reason
        self.build_log = build_log

I think this should be fine, although I guess if the logs are long enough memory usage could balloon. Let me know if you think that is an issue.