Skip to content

Commit

Permalink
docs: use generated partials for builder docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@lbajolet-hashicorp
lbajolet-hashicorp committed Oct 22, 2024
1 parent be20d84 commit e4e754c
Show file tree
Hide file tree
Showing 2 changed files with 47 additions and 112 deletions.
57 changes: 44 additions & 13 deletions .web-docs/components/builder/docker/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,11 @@ standard [communicators](/packer/docs/templates/legacy_json_templates/communicat

You must specify (only) one of `commit`, `discard`, or `export_path`.

<!-- Code generated from the comments of the Config struct in builder/docker/config.go; DO NOT EDIT MANUALLY -->

- `commit` (bool) - If true, the container will be committed to an image rather than exported.
Default `false`. If `commit` is `false`, then either `discard` must be
set to `true` or an `export_path` must be provided.

- `discard` (bool) - Throw away the container when the build is complete. This is useful for
the [artifice
Expand All @@ -187,24 +191,20 @@ You must specify (only) one of `commit`, `discard`, or `export_path`.

- `image` (string) - The base image for the Docker container that will be started. This image
will be pulled from the Docker registry if it doesn't already exist.
Any value format that you can provide to `docker pull` is valid.
Example: `ubuntu` or `ubuntu:xenial`. If you only provide the repo, Docker
will pull the latest image, so setting `ubuntu` is the same as setting
`ubuntu:latest`. You can also set a distribution digest. For example,
ubuntu@sha256:a0d9e826ab87bd665cfc640598a871b748b4b70a01a4f3d174d4fb02adad07a9

- `message` (string) - Set a message for the commit.

### Optional:

- `aws_access_key` (string) - The AWS access key used to communicate with
AWS. [Learn how to set this.](/packer/integrations/hashicorp/amazon#specifying-amazon-credentials)
<!-- End of code generated from the comments of the Config struct in builder/docker/config.go; -->

- `aws_secret_key` (string) - The AWS secret key used to communicate with
AWS. [Learn how to set this.](/packer/integrations/hashicorp/amazon#specifying-amazon-credentials)

- `aws_token` (string) - The AWS access token to use. This is different from
the access key and secret key. If you're not sure what this is, then you
probably don't need it. This will also be read from the AWS_SESSION_TOKEN
environmental variable.
### Optional:

- `aws_profile` (string) - The AWS shared credentials profile used to
communicate with AWS. [Learn how to set this.](/packer/integrations/hashicorp/amazon#specifying-amazon-credentials)
<!-- Code generated from the comments of the Config struct in builder/docker/config.go; DO NOT EDIT MANUALLY -->

- `author` (string) - Set the author (e-mail) of a commit.

Expand Down Expand Up @@ -234,6 +234,13 @@ You must specify (only) one of `commit`, `discard`, or `export_path`.
- `privileged` (bool) - If true, run the docker container with the `--privileged` flag. This
defaults to false if not set.

- `runtime` (string) - Set the container runtime. A runtime different from the one installed
by default with Docker (`runc`) must be installed and configured.
The possible values are (non-exhaustive list):
`runsc` for [gVisor](https://gvisor.dev/),
`kata-runtime` for [Kata Containers](https://katacontainers.io/),
`sysbox-runc` for [Nestybox](https://www.nestybox.com/).

- `pull` (bool) - If true, the configured image will be pulled using `docker pull` prior
to use. Otherwise, it is assumed the image already exists and can be
used. This defaults to true if not set.
Expand Down Expand Up @@ -264,7 +271,7 @@ You must specify (only) one of `commit`, `discard`, or `export_path`.
running on a windows host. This is necessary for building Windows
containers, because our normal docker bindings do not work for them.

- `platform` (string) - Set platform if server is multi-platform capable.
- `platform` (string) - Set platform if server is multi-platform capable

- `login` (bool) - This is used to login to dockerhub to pull a private base container. For
pushing to dockerhub, see the docker post-processors
Expand All @@ -281,6 +288,30 @@ You must specify (only) one of `commit`, `discard`, or `export_path`.
login, login_username, and login_password will be ignored. For more
information see the section on ECR.

<!-- End of code generated from the comments of the Config struct in builder/docker/config.go; -->


<!-- Code generated from the comments of the AwsAccessConfig struct in builder/docker/ecr_login.go; DO NOT EDIT MANUALLY -->

- `aws_access_key` (string) - The AWS access key used to communicate with AWS.

- `aws_secret_key` (string) - The AWS secret key used to communicate with AWS.

- `aws_token` (string) - The AWS access token to use. This is different from
the access key and secret key. If you're not sure what this is, then you
probably don't need it. This will also be read from the AWS_SESSION_TOKEN
environmental variable.

- `aws_profile` (string) - The AWS shared credentials profile used to communicate with AWS.

- `aws_force_use_public_ecr` (bool) - The flag to identify whether to push docker image to Public _or_ Private
ECR. If the user sets this to `true` from the config, we will forcefully
try to push to Public ECR otherwise set this from code based on the
given LoginServer value.

<!-- End of code generated from the comments of the AwsAccessConfig struct in builder/docker/ecr_login.go; -->


## Build Shared Information Variables

This build shares generated data with provisioners and post-processors via [template engines](/packer/docs/templates/legacy_json_templates/engine)
Expand Down
102 changes: 3 additions & 99 deletions docs/builders/docker.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -188,109 +188,13 @@ standard [communicators](/packer/docs/templates/legacy_json_templates/communicat

You must specify (only) one of `commit`, `discard`, or `export_path`.

- `commit` (bool) - If true, the container will be committed to an image rather than exported.

- `discard` (bool) - Throw away the container when the build is complete. This is useful for
the [artifice
post-processor](/packer/docs/post-processors/artifice).

- `export_path` (string) - The path where the final container will be exported as a tar file.

- `image` (string) - The base image for the Docker container that will be started. This image
will be pulled from the Docker registry if it doesn't already exist.

- `message` (string) - Set a message for the commit.
@include 'builder/docker/Config-required.mdx'

### Optional:

- `aws_access_key` (string) - The AWS access key used to communicate with
AWS. [Learn how to set this.](/packer/plugins/builders/amazon#specifying-amazon-credentials)

- `aws_secret_key` (string) - The AWS secret key used to communicate with
AWS. [Learn how to set this.](/packer/plugins/builders/amazon#specifying-amazon-credentials)

- `aws_token` (string) - The AWS access token to use. This is different from
the access key and secret key. If you're not sure what this is, then you
probably don't need it. This will also be read from the AWS_SESSION_TOKEN
environmental variable.

- `aws_profile` (string) - The AWS shared credentials profile used to
communicate with AWS. [Learn how to set this.](/packer/plugins/builders/amazon#specifying-amazon-credentials)

- `author` (string) - Set the author (e-mail) of a commit.

- `changes` ([]string) - Dockerfile instructions to add to the commit. Example of instructions
are CMD, ENTRYPOINT, ENV, and EXPOSE. Example: [ "USER ubuntu", "WORKDIR
/app", "EXPOSE 8080" ]

- `container_dir` (string) - The directory inside container to mount temp directory from host server
for work [file provisioner](/packer/docs/provisioners/file). This defaults
to c:/packer-files on windows and /packer-files on other systems.

- `device` ([]string) - An array of devices which will be accessible in container when it's run
without `--privileged` flag.

- `cap_add` ([]string) - An array of additional [Linux
capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)
to grant to the container.

- `cap_drop` ([]string) - An array of [Linux
capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)
to drop from the container.

- `exec_user` (string) - Username (UID) to run remote commands with. You can also set the group
name/ID if you want: (UID or UID:GID). You may need this if you get
permission errors trying to run the shell or other provisioners.

- `privileged` (bool) - If true, run the docker container with the `--privileged` flag. This
defaults to false if not set.

- `pull` (bool) - If true, the configured image will be pulled using `docker pull` prior
to use. Otherwise, it is assumed the image already exists and can be
used. This defaults to true if not set.

- `run_command` ([]string) - An array of arguments to pass to docker run in order to run the
container. By default this is set to `["-d", "-i", "-t",
"--entrypoint=/bin/sh", "--", "{{.Image}}"]` if you are using a linux
container, and `["-d", "-i", "-t", "--entrypoint=powershell", "--",
"{{.Image}}"]` if you are running a windows container. `{{.Image}}` is a
template variable that corresponds to the image template option. Passing
the entrypoint option this way will make it the default entrypoint of
the resulting image, so running docker run -it --rm will start the
docker image from the /bin/sh shell interpreter; you could run a script
or another shell by running docker run -it --rm -c /bin/bash. If your
docker image embeds a binary intended to be run often, you should
consider changing the default entrypoint to point to it.

- `tmpfs` ([]string) - An array of additional tmpfs volumes to mount into this container.

- `volumes` (map[string]string) - A mapping of additional volumes to mount into this container. The key of
the object is the host path, the value is the container path.

- `fix_upload_owner` (bool) - If true, files uploaded to the container will be owned by the user the
container is running as. If false, the owner will depend on the version
of docker installed in the system. Defaults to true.

- `windows_container` (bool) - If "true", tells Packer that you are building a Windows container
running on a windows host. This is necessary for building Windows
containers, because our normal docker bindings do not work for them.

- `platform` (string) - Set platform if server is multi-platform capable.

- `login` (bool) - This is used to login to dockerhub to pull a private base container. For
pushing to dockerhub, see the docker post-processors

- `login_password` (string) - The password to use to authenticate to login.

- `login_server` (string) - The server address to login to.

- `login_username` (string) - The username to use to authenticate to login.
@include 'builder/docker/Config-not-required.mdx'

- `ecr_login` (bool) - Defaults to false. If true, the builder will login in order to pull the
image from Amazon EC2 Container Registry (ECR). The builder only logs in
for the duration of the pull. If true login_server is required and
login, login_username, and login_password will be ignored. For more
information see the section on ECR.
@include 'builder/docker/AwsAccessConfig-not-required.mdx'

## Build Shared Information Variables

Expand Down

0 comments on commit e4e754c

Please sign in to comment.