From 3dbf3f5f41397f0e549e81445390eb02fe311405 Mon Sep 17 00:00:00 2001 From: Lucas Bajolet Date: Tue, 22 Oct 2024 10:43:08 -0400 Subject: [PATCH] docs: place HCL2 examples first for builder --- .web-docs/components/builder/docker/README.md | 240 +++++++++--------- docs/builders/docker.mdx | 240 +++++++++--------- 2 files changed, 240 insertions(+), 240 deletions(-) diff --git a/.web-docs/components/builder/docker/README.md b/.web-docs/components/builder/docker/README.md index 3aeee7c..0287ad6 100644 --- a/.web-docs/components/builder/docker/README.md +++ b/.web-docs/components/builder/docker/README.md @@ -24,6 +24,14 @@ documentation. Below is a fully functioning example. It doesn't do anything useful, since no provisioners are defined, but it will effectively repackage an image. +**HCL2** + +```hcl +source "docker" "example" { + image = "ubuntu" + export_path = "image.tar" +} + **JSON** ```json @@ -34,14 +42,6 @@ provisioners are defined, but it will effectively repackage an image. } ``` -**HCL2** - -```hcl -source "docker" "example" { - image = "ubuntu" - export_path = "image.tar" -} - build { sources = ["source.docker.example"] } @@ -53,16 +53,6 @@ Below is another example, the same as above but instead of exporting the running container, this one commits the container to an image. The image can then be more easily tagged, pushed, etc. -**JSON** - -```json -{ - "type": "docker", - "image": "ubuntu", - "export_path": "image.tar" -} -``` - **HCL2** ```hcl @@ -76,6 +66,16 @@ build { } ``` +**JSON** + +```json +{ + "type": "docker", + "image": "ubuntu", + "export_path": "image.tar" +} +``` + ## Basic Example: Changes to Metadata Below is an example using the changes argument of the builder. This feature @@ -87,6 +87,26 @@ Docker](https://docs.docker.com/engine/reference/commandline/commit/). Example uses of all of the options, assuming one is building an NGINX image from ubuntu as an simple example: +**HCL2** + +```hcl +source "docker" "example" { + image = "ubuntu" + commit = true + changes = [ + "USER www-data", + "WORKDIR /var/www", + "ENV HOSTNAME www.example.com", + "VOLUME /test1 /test2", + "EXPOSE 80 443", + "LABEL version=1.0", + "ONBUILD RUN date", + "CMD [\"nginx\", \"-g\", \"daemon off;\"]", + "ENTRYPOINT /var/www/start.sh" + ] +} +``` + **JSON** ```json @@ -108,26 +128,6 @@ from ubuntu as an simple example: } ``` -**HCL2** - -```hcl -source "docker" "example" { - image = "ubuntu" - commit = true - changes = [ - "USER www-data", - "WORKDIR /var/www", - "ENV HOSTNAME www.example.com", - "VOLUME /test1 /test2", - "EXPOSE 80 443", - "LABEL version=1.0", - "ONBUILD RUN date", - "CMD [\"nginx\", \"-g\", \"daemon off;\"]", - "ENTRYPOINT /var/www/start.sh" - ] -} -``` - Allowed metadata fields that can be changed are: - CMD @@ -395,6 +395,19 @@ definition (a collection of post-processors that are treated as as single pipeline, see [Post-Processors](/packer/docs/templates/legacy_json_templates/post-processors) for more information): +**HCL2** + +```hcl + post-processors { + post-processor "docker-tag" { + repository = "myrepo/myimage" + tags = ["0.7"] + } + post-processor "docker-push" {} + } +} +``` + **JSON** ```json @@ -414,12 +427,30 @@ information): } ``` +In the above example, the result of each builder is passed through the defined +sequence of post-processors starting first with the `docker-tag` post-processor +which tags the committed image with the supplied repository and tag +information. Once tagged, the resulting artifact is then passed on to the +`docker-push` post-processor which handles pushing the image to a container +repository. + +Going a step further, if you wanted to tag and push an image to multiple +container repositories, this could be accomplished by defining two, +nearly-identical sequence definitions, as demonstrated by the example below: + **HCL2** ```hcl post-processors { post-processor "docker-tag" { - repository = "myrepo/myimage" + repository = "myrepo/myimage1" + tags = ["0.7"] + } + post-processor "docker-push" {} + } + post-processors { + post-processor "docker-tag" { + repository = "myrepo/myimage2" tags = ["0.7"] } post-processor "docker-push" {} @@ -427,17 +458,6 @@ information): } ``` -In the above example, the result of each builder is passed through the defined -sequence of post-processors starting first with the `docker-tag` post-processor -which tags the committed image with the supplied repository and tag -information. Once tagged, the resulting artifact is then passed on to the -`docker-push` post-processor which handles pushing the image to a container -repository. - -Going a step further, if you wanted to tag and push an image to multiple -container repositories, this could be accomplished by defining two, -nearly-identical sequence definitions, as demonstrated by the example below: - **JSON** ```json @@ -463,26 +483,6 @@ nearly-identical sequence definitions, as demonstrated by the example below: } ``` -**HCL2** - -```hcl - post-processors { - post-processor "docker-tag" { - repository = "myrepo/myimage1" - tags = ["0.7"] - } - post-processor "docker-push" {} - } - post-processors { - post-processor "docker-tag" { - repository = "myrepo/myimage2" - tags = ["0.7"] - } - post-processor "docker-push" {} - } -} -``` - ## Docker For Windows @@ -498,6 +498,21 @@ containers, so you must either commit or discard them. The following is a fully functional template for building a Windows container. +**HCL2** + +```hcl +source "docker" "windows" { + image = "microsoft/windowsservercore:1709" + container_dir = "c:/app" + windows_container = true + commit = true +} + +build { + sources = ["source.docker.example"] +} +``` + **JSON** ```json @@ -514,27 +529,30 @@ container. } ``` +## Amazon EC2 Container Registry + +Packer can tag and push images for use in [Amazon EC2 Container +Registry](https://aws.amazon.com/ecr/). The post processors work as described +above and example configuration properties are shown below: + **HCL2** ```hcl -source "docker" "windows" { - image = "microsoft/windowsservercore:1709" - container_dir = "c:/app" - windows_container = true - commit = true -} +post-processors { + post-processor "docker-tag" { + repository = "12345.dkr.ecr.us-east-1.amazonaws.com/packer" + tags = ["0.7"] + } -build { - sources = ["source.docker.example"] + post-processor "docker-push" { + ecr_login = true + aws_access_key = "YOUR KEY HERE" + aws_secret_key = "YOUR SECRET KEY HERE" + login_server = "https://12345.dkr.ecr.us-east-1.amazonaws.com/" + } } ``` -## Amazon EC2 Container Registry - -Packer can tag and push images for use in [Amazon EC2 Container -Registry](https://aws.amazon.com/ecr/). The post processors work as described -above and example configuration properties are shown below: - **JSON** ```json @@ -558,30 +576,30 @@ above and example configuration properties are shown below: } ``` -**HCL2** - -```hcl -post-processors { - post-processor "docker-tag" { - repository = "12345.dkr.ecr.us-east-1.amazonaws.com/packer" - tags = ["0.7"] - } - - post-processor "docker-push" { - ecr_login = true - aws_access_key = "YOUR KEY HERE" - aws_secret_key = "YOUR SECRET KEY HERE" - login_server = "https://12345.dkr.ecr.us-east-1.amazonaws.com/" - } -} -``` - ## Amazon ECR Public Gallery Packer can tag and push images for use in [Amazon ECR Public Gallery](https://gallery.ecr.aws/). The post processors work as described above and example configuration properties are shown below: +**HCL2** + +```hcl + post-processors { + post-processor "docker-tag" { + repository = "public.ecr.aws/YOUR REGISTRY ALIAS HERE/YOUR REGISTRY NAME HERE" + tags = ["latest"] + } + + post-processor "docker-push" { + "ecr_login": true, + "aws_access_key": "YOUR KEY HERE", + "aws_secret_key": "YOUR SECRET KEY HERE", + login_server = "public.ecr.aws/YOUR REGISTRY ALIAS HERE" + } + } +``` + **JSON** ```json @@ -605,24 +623,6 @@ and example configuration properties are shown below: } ``` -**HCL2** - -```hcl - post-processors { - post-processor "docker-tag" { - repository = "public.ecr.aws/YOUR REGISTRY ALIAS HERE/YOUR REGISTRY NAME HERE" - tags = ["latest"] - } - - post-processor "docker-push" { - "ecr_login": true, - "aws_access_key": "YOUR KEY HERE", - "aws_secret_key": "YOUR SECRET KEY HERE", - login_server = "public.ecr.aws/YOUR REGISTRY ALIAS HERE" - } - } -``` - [Learn how to set Amazon AWS credentials.](/packer/integrations/hashicorp/amazon#specifying-amazon-credentials) ## Dockerfiles diff --git a/docs/builders/docker.mdx b/docs/builders/docker.mdx index b0cdf1d..3865e12 100644 --- a/docs/builders/docker.mdx +++ b/docs/builders/docker.mdx @@ -35,6 +35,14 @@ documentation. Below is a fully functioning example. It doesn't do anything useful, since no provisioners are defined, but it will effectively repackage an image. +**HCL2** + +```hcl +source "docker" "example" { + image = "ubuntu" + export_path = "image.tar" +} + **JSON** ```json @@ -45,14 +53,6 @@ provisioners are defined, but it will effectively repackage an image. } ``` -**HCL2** - -```hcl -source "docker" "example" { - image = "ubuntu" - export_path = "image.tar" -} - build { sources = ["source.docker.example"] } @@ -64,16 +64,6 @@ Below is another example, the same as above but instead of exporting the running container, this one commits the container to an image. The image can then be more easily tagged, pushed, etc. -**JSON** - -```json -{ - "type": "docker", - "image": "ubuntu", - "export_path": "image.tar" -} -``` - **HCL2** ```hcl @@ -87,6 +77,16 @@ build { } ``` +**JSON** + +```json +{ + "type": "docker", + "image": "ubuntu", + "export_path": "image.tar" +} +``` + ## Basic Example: Changes to Metadata Below is an example using the changes argument of the builder. This feature @@ -98,6 +98,26 @@ Docker](https://docs.docker.com/engine/reference/commandline/commit/). Example uses of all of the options, assuming one is building an NGINX image from ubuntu as an simple example: +**HCL2** + +```hcl +source "docker" "example" { + image = "ubuntu" + commit = true + changes = [ + "USER www-data", + "WORKDIR /var/www", + "ENV HOSTNAME www.example.com", + "VOLUME /test1 /test2", + "EXPOSE 80 443", + "LABEL version=1.0", + "ONBUILD RUN date", + "CMD [\"nginx\", \"-g\", \"daemon off;\"]", + "ENTRYPOINT /var/www/start.sh" + ] +} +``` + **JSON** ```json @@ -119,26 +139,6 @@ from ubuntu as an simple example: } ``` -**HCL2** - -```hcl -source "docker" "example" { - image = "ubuntu" - commit = true - changes = [ - "USER www-data", - "WORKDIR /var/www", - "ENV HOSTNAME www.example.com", - "VOLUME /test1 /test2", - "EXPOSE 80 443", - "LABEL version=1.0", - "ONBUILD RUN date", - "CMD [\"nginx\", \"-g\", \"daemon off;\"]", - "ENTRYPOINT /var/www/start.sh" - ] -} -``` - Allowed metadata fields that can be changed are: - CMD @@ -279,6 +279,19 @@ definition (a collection of post-processors that are treated as as single pipeline, see [Post-Processors](/packer/docs/templates/legacy_json_templates/post-processors) for more information): +**HCL2** + +```hcl + post-processors { + post-processor "docker-tag" { + repository = "myrepo/myimage" + tags = ["0.7"] + } + post-processor "docker-push" {} + } +} +``` + **JSON** ```json @@ -298,12 +311,30 @@ information): } ``` +In the above example, the result of each builder is passed through the defined +sequence of post-processors starting first with the `docker-tag` post-processor +which tags the committed image with the supplied repository and tag +information. Once tagged, the resulting artifact is then passed on to the +`docker-push` post-processor which handles pushing the image to a container +repository. + +Going a step further, if you wanted to tag and push an image to multiple +container repositories, this could be accomplished by defining two, +nearly-identical sequence definitions, as demonstrated by the example below: + **HCL2** ```hcl post-processors { post-processor "docker-tag" { - repository = "myrepo/myimage" + repository = "myrepo/myimage1" + tags = ["0.7"] + } + post-processor "docker-push" {} + } + post-processors { + post-processor "docker-tag" { + repository = "myrepo/myimage2" tags = ["0.7"] } post-processor "docker-push" {} @@ -311,17 +342,6 @@ information): } ``` -In the above example, the result of each builder is passed through the defined -sequence of post-processors starting first with the `docker-tag` post-processor -which tags the committed image with the supplied repository and tag -information. Once tagged, the resulting artifact is then passed on to the -`docker-push` post-processor which handles pushing the image to a container -repository. - -Going a step further, if you wanted to tag and push an image to multiple -container repositories, this could be accomplished by defining two, -nearly-identical sequence definitions, as demonstrated by the example below: - **JSON** ```json @@ -347,26 +367,6 @@ nearly-identical sequence definitions, as demonstrated by the example below: } ``` -**HCL2** - -```hcl - post-processors { - post-processor "docker-tag" { - repository = "myrepo/myimage1" - tags = ["0.7"] - } - post-processor "docker-push" {} - } - post-processors { - post-processor "docker-tag" { - repository = "myrepo/myimage2" - tags = ["0.7"] - } - post-processor "docker-push" {} - } -} -``` - ## Docker For Windows @@ -382,6 +382,21 @@ containers, so you must either commit or discard them. The following is a fully functional template for building a Windows container. +**HCL2** + +```hcl +source "docker" "windows" { + image = "microsoft/windowsservercore:1709" + container_dir = "c:/app" + windows_container = true + commit = true +} + +build { + sources = ["source.docker.example"] +} +``` + **JSON** ```json @@ -398,27 +413,30 @@ container. } ``` +## Amazon EC2 Container Registry + +Packer can tag and push images for use in [Amazon EC2 Container +Registry](https://aws.amazon.com/ecr/). The post processors work as described +above and example configuration properties are shown below: + **HCL2** ```hcl -source "docker" "windows" { - image = "microsoft/windowsservercore:1709" - container_dir = "c:/app" - windows_container = true - commit = true -} +post-processors { + post-processor "docker-tag" { + repository = "12345.dkr.ecr.us-east-1.amazonaws.com/packer" + tags = ["0.7"] + } -build { - sources = ["source.docker.example"] + post-processor "docker-push" { + ecr_login = true + aws_access_key = "YOUR KEY HERE" + aws_secret_key = "YOUR SECRET KEY HERE" + login_server = "https://12345.dkr.ecr.us-east-1.amazonaws.com/" + } } ``` -## Amazon EC2 Container Registry - -Packer can tag and push images for use in [Amazon EC2 Container -Registry](https://aws.amazon.com/ecr/). The post processors work as described -above and example configuration properties are shown below: - **JSON** ```json @@ -442,30 +460,30 @@ above and example configuration properties are shown below: } ``` -**HCL2** - -```hcl -post-processors { - post-processor "docker-tag" { - repository = "12345.dkr.ecr.us-east-1.amazonaws.com/packer" - tags = ["0.7"] - } - - post-processor "docker-push" { - ecr_login = true - aws_access_key = "YOUR KEY HERE" - aws_secret_key = "YOUR SECRET KEY HERE" - login_server = "https://12345.dkr.ecr.us-east-1.amazonaws.com/" - } -} -``` - ## Amazon ECR Public Gallery Packer can tag and push images for use in [Amazon ECR Public Gallery](https://gallery.ecr.aws/). The post processors work as described above and example configuration properties are shown below: +**HCL2** + +```hcl + post-processors { + post-processor "docker-tag" { + repository = "public.ecr.aws/YOUR REGISTRY ALIAS HERE/YOUR REGISTRY NAME HERE" + tags = ["latest"] + } + + post-processor "docker-push" { + "ecr_login": true, + "aws_access_key": "YOUR KEY HERE", + "aws_secret_key": "YOUR SECRET KEY HERE", + login_server = "public.ecr.aws/YOUR REGISTRY ALIAS HERE" + } + } +``` + **JSON** ```json @@ -489,24 +507,6 @@ and example configuration properties are shown below: } ``` -**HCL2** - -```hcl - post-processors { - post-processor "docker-tag" { - repository = "public.ecr.aws/YOUR REGISTRY ALIAS HERE/YOUR REGISTRY NAME HERE" - tags = ["latest"] - } - - post-processor "docker-push" { - "ecr_login": true, - "aws_access_key": "YOUR KEY HERE", - "aws_secret_key": "YOUR SECRET KEY HERE", - login_server = "public.ecr.aws/YOUR REGISTRY ALIAS HERE" - } - } -``` - [Learn how to set Amazon AWS credentials.](/packer/plugins/builders/amazon#specifying-amazon-credentials) ## Dockerfiles