From c2b61602022080d9fc8f76772d4d0b81f978084e Mon Sep 17 00:00:00 2001 From: Aleix Penella Date: Wed, 27 Dec 2023 22:14:10 +0100 Subject: [PATCH] markdown linter --- README.md | 2 +- content/en/docs/_index.md | 12 +- .../en/docs/contribution-guidelines/_index.md | 10 ++ .../code-of-conduct.md | 10 +- content/en/docs/docs-v0.11/_index.md | 14 ++- .../contribution-guidelines/_index.md | 10 ++ .../code-of-conduct.md | 10 +- .../getting-started/concepts/_index.md | 62 ++++++---- .../getting-started/configuration/_index.md | 113 +++++++++++++----- .../docs-v0.11/getting-started/install.md | 8 +- .../docs-v0.11/getting-started/quickstart.md | 24 +++- .../builder/ansible-playbook/_index.md | 6 +- .../reference-guide/builder/docker/_index.md | 6 +- .../docs/getting-started/concepts/_index.md | 50 +++++--- .../getting-started/configuration/_index.md | 89 +++++++++++--- content/en/docs/getting-started/install.md | 8 +- content/en/docs/getting-started/quickstart.md | 20 +++- .../builder/ansible-playbook/_index.md | 4 +- .../reference-guide/builder/docker/_index.md | 2 +- 19 files changed, 331 insertions(+), 129 deletions(-) diff --git a/README.md b/README.md index 80588f5..3a9f102 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,6 @@ When a new site's release is ready to be deployed on your development environmen 1) Create a pull request to the `main` branch 2) Merge the pull request, and then the `Publish` action is triggered. -3) Once the `Publish` action is completed properly, the site is already available on https://gostevedore.github.io/ +3) Once the `Publish` action is completed properly, the site will be available at https://gostevedore.github.io/ > The `Publish` action pushes the code generated by `Hugo` to `gh-pages` repository's branch. diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index 2dd3c37..942c9e7 100755 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -1,4 +1,3 @@ - --- title: "Documentation" linkTitle: "Documentation" @@ -17,6 +16,7 @@ One of the key benefits of using Stevedore is that it provides a consistent way Overall, Stevedore is a useful tool for anyone who needs to build and manage large numbers of Docker images, and it can help to improve the experience of building and promoting Docker images at scale. ## Why stevedore? + Stevedore simplifies the building of Docker images in a standardized way, with the ability to define relationships between them. You can build images from multiple sources, including local files and git repositories, and generate automatic tags for semantic versioning. @@ -26,19 +26,25 @@ Stevedore also offers a credentials store for easy authentication to Docker regi ## Features ### Standardize + Build your Docker images in a standardized way. Create a Dockerfile and reuse it for as many use cases as needed ### Relatives build + Automate the building of related Docker images by defining their relationships and dependencies ### Credentials -Store credentials to log in to your Docker registry, AWS Elastic Container Registry or a Git server + +Store credentials to log in to your Docker registry, AWS Elastic Container Registry, or Git server ### Promote + Easily promote or copy Docker images from one registry to another using Stevedore's image promotion feature ### Semver awareness + Automatically generate tags for semantic version 2.0.0 when building Docker image ### Multiple build contexts -Build your images using multiple build context sources. Use local files, a git repository or merge several sources + +Build your images using multiple build context sources. Use local files, a git repository, or merge several sources diff --git a/content/en/docs/contribution-guidelines/_index.md b/content/en/docs/contribution-guidelines/_index.md index 4a0a65a..c38d5d5 100644 --- a/content/en/docs/contribution-guidelines/_index.md +++ b/content/en/docs/contribution-guidelines/_index.md @@ -5,9 +5,11 @@ description: How to contribute to Stevedore --- # Contributing to Stevedore + Thank you for your interest in contributing to Stevedore! All contributions are welcome, whether they are bug reports, feature requests, or code contributions. ## Getting Started + Before contributing to Stevedore, you should: 1. Fork the repository. @@ -16,13 +18,17 @@ Before contributing to Stevedore, you should: 4. Create a new branch for your changes. ## How to Contribute + ### Bug Reports + If you find a bug in Stevedore, please report it by creating a new issue on our GitHub repository. Please include as much information as possible, including a description of the bug, the steps to reproduce it, and any error messages you received. ### Feature Requests + If you have a feature request, please create a new issue on our GitHub repository. Please include a detailed description of the feature, as well as any relevant use cases or examples. ### Code Contributions + If you would like to contribute code to Stevedore, please follow these steps: 1. Create a new branch for your changes. @@ -32,6 +38,7 @@ If you would like to contribute code to Stevedore, please follow these steps: Please ensure that your code adheres to our coding standards, that all tests pass before submitting a pull request, and you update the project [README](https://github.com/gostevedore/stevedore/blob/main/README.md), the [documentation](https://github.com/gostevedore/gostevedore.github.io), and the [RELEASE_NOTES](https://github.com/gostevedore/stevedore/blob/main/RELEASE_NOTES.md). ## Coding Standards + When contributing code to Stevedore, please adhere to the following coding standards: - Use clear, descriptive variable and function names. @@ -40,10 +47,13 @@ When contributing code to Stevedore, please adhere to the following coding stand - Write tests for your code. ## Issue Management + We use GitHub to manage issues and feature requests. To report a bug or request a feature, please create a new issue on our GitHub repository. ## Documentation + Documentation is an important part of the Stevedore project, and we rely on contributions from our community to keep it up-to-date. If your contribution involves changes to the behaviour of the Stevedore project, please make sure to update the documentation accordingly. This could include updating the [README](https://github.com/gostevedore/stevedore/blob/main/README.md) file, adding or modifying usage examples, or creating new [documentation](https://github.com/gostevedore/gostevedore.github.io) pages as needed. We encourage all contributors to participate in improving the documentation, as it helps ensure that the project is accessible and useful to as many people as possible. ## Thank You + Thank you for your interest in contributing to Stevedore! All contributions are appreciated. \ No newline at end of file diff --git a/content/en/docs/contribution-guidelines/code-of-conduct.md b/content/en/docs/contribution-guidelines/code-of-conduct.md index 6f15db4..8b6d3de 100644 --- a/content/en/docs/contribution-guidelines/code-of-conduct.md +++ b/content/en/docs/contribution-guidelines/code-of-conduct.md @@ -6,22 +6,28 @@ description: Stevedore has a code of conduct that all contributors are expected # Stevedore Project Code of Conduct -The Stevedore project is committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or similar personal characteristic. +The Stevedore project is committed to providing a friendly, safe, and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or similar personal characteristics. We expect all contributors, users, and community members to follow this code of conduct. This includes all interactions within the Stevedore community, whether online, in person, or otherwise. ## Code of Conduct + ### Be respectful and inclusive + We encourage participation from everyone. Please be respectful and considerate towards others, and avoid any language, images, or actions that could be considered disrespectful, offensive, or exclusionary. ### Listen and be open to constructive feedback + Be open to constructive feedback and criticism from others. We all have room to learn, grow, and improve, and being open to feedback is an important part of that process. ### Don't harass or discriminate + Harassment or discrimination of any kind will not be tolerated. This includes but is not limited to derogatory comments or slurs, sexual harassment, and unwanted physical contact or attention. If you experience or witness any form of harassment or discrimination, please report it immediately. ### Don't engage in disruptive behaviour + Disruptive behaviour, such as spamming, trolling, or other malicious behaviour, will not be tolerated. We want to maintain a positive and productive environment for everyone. -## Acknowledgements +## Acknowledgments + This Code of Conduct is adapted from the Contributor Covenant, version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. \ No newline at end of file diff --git a/content/en/docs/docs-v0.11/_index.md b/content/en/docs/docs-v0.11/_index.md index 0fc4f7c..1aa2dd9 100755 --- a/content/en/docs/docs-v0.11/_index.md +++ b/content/en/docs/docs-v0.11/_index.md @@ -1,4 +1,3 @@ - --- title: "Documentation v0.11" linkTitle: "Documentation v0.11" @@ -10,11 +9,12 @@ description: > Stevedore is a tool for building Docker images at scale, and it is not intended to replace Dockerfile or Buildkit. Instead, Stevedore can be used in conjunction with these tools to help streamline the process of building and promoting multiple Docker images. -One of the key benefits of using Stevedore is that it provides a consistent and modular way to build Docker images, which can be helpful when dealing with large and complex projects that require multiple images. By using a set of "workers" to perform specific tasks during the build process, you can create a more efficient and automated process for building and promoting Docker images. +One of the key benefits of using Stevedore is that it provides a consistent way to build Docker images and its descendant images, which can be helpful when dealing with large and complex projects that require multiple images. You can also create a more efficient and automated process for building and promoting Docker images. Overall, Stevedore is a useful tool for anyone who needs to build and manage large numbers of Docker images, and it can help to improve the experience of building and promoting Docker images at scale. ## Why stevedore? + Stevedore simplifies the building of Docker images in a standardized way, with the ability to define relationships between them. You can build images from multiple sources, including local files and git repositories, and generate automatic tags for semantic versioning. @@ -24,19 +24,25 @@ Stevedore also offers a credentials store for easy authentication to Docker regi ## Features ### Standardize + Build your Docker images in a standardized way. Create a Dockerfile and reuse it for as many use cases as needed ### Relatives build + Automate the building of related Docker images by defining their relationships and dependencies ### Credentials -Store credentials to log in to your Docker registry, AWS Elastic Container Registry or a Git server + +Store credentials to log in to your Docker registry, AWS Elastic Container Registry, or Git server ### Promote + Easily promote or copy Docker images from one registry to another using Stevedore's image promotion feature ### Semver awareness + Automatically generate tags for semantic version 2.0.0 when building Docker image ### Multiple build contexts -Build your images using multiple build context sources. Use local files, a git repository or merge several sources + +Build your images using multiple build context sources. Use local files, a git repository, or merge several sources diff --git a/content/en/docs/docs-v0.11/contribution-guidelines/_index.md b/content/en/docs/docs-v0.11/contribution-guidelines/_index.md index 4a0a65a..c38d5d5 100644 --- a/content/en/docs/docs-v0.11/contribution-guidelines/_index.md +++ b/content/en/docs/docs-v0.11/contribution-guidelines/_index.md @@ -5,9 +5,11 @@ description: How to contribute to Stevedore --- # Contributing to Stevedore + Thank you for your interest in contributing to Stevedore! All contributions are welcome, whether they are bug reports, feature requests, or code contributions. ## Getting Started + Before contributing to Stevedore, you should: 1. Fork the repository. @@ -16,13 +18,17 @@ Before contributing to Stevedore, you should: 4. Create a new branch for your changes. ## How to Contribute + ### Bug Reports + If you find a bug in Stevedore, please report it by creating a new issue on our GitHub repository. Please include as much information as possible, including a description of the bug, the steps to reproduce it, and any error messages you received. ### Feature Requests + If you have a feature request, please create a new issue on our GitHub repository. Please include a detailed description of the feature, as well as any relevant use cases or examples. ### Code Contributions + If you would like to contribute code to Stevedore, please follow these steps: 1. Create a new branch for your changes. @@ -32,6 +38,7 @@ If you would like to contribute code to Stevedore, please follow these steps: Please ensure that your code adheres to our coding standards, that all tests pass before submitting a pull request, and you update the project [README](https://github.com/gostevedore/stevedore/blob/main/README.md), the [documentation](https://github.com/gostevedore/gostevedore.github.io), and the [RELEASE_NOTES](https://github.com/gostevedore/stevedore/blob/main/RELEASE_NOTES.md). ## Coding Standards + When contributing code to Stevedore, please adhere to the following coding standards: - Use clear, descriptive variable and function names. @@ -40,10 +47,13 @@ When contributing code to Stevedore, please adhere to the following coding stand - Write tests for your code. ## Issue Management + We use GitHub to manage issues and feature requests. To report a bug or request a feature, please create a new issue on our GitHub repository. ## Documentation + Documentation is an important part of the Stevedore project, and we rely on contributions from our community to keep it up-to-date. If your contribution involves changes to the behaviour of the Stevedore project, please make sure to update the documentation accordingly. This could include updating the [README](https://github.com/gostevedore/stevedore/blob/main/README.md) file, adding or modifying usage examples, or creating new [documentation](https://github.com/gostevedore/gostevedore.github.io) pages as needed. We encourage all contributors to participate in improving the documentation, as it helps ensure that the project is accessible and useful to as many people as possible. ## Thank You + Thank you for your interest in contributing to Stevedore! All contributions are appreciated. \ No newline at end of file diff --git a/content/en/docs/docs-v0.11/contribution-guidelines/code-of-conduct.md b/content/en/docs/docs-v0.11/contribution-guidelines/code-of-conduct.md index 6f15db4..8b6d3de 100644 --- a/content/en/docs/docs-v0.11/contribution-guidelines/code-of-conduct.md +++ b/content/en/docs/docs-v0.11/contribution-guidelines/code-of-conduct.md @@ -6,22 +6,28 @@ description: Stevedore has a code of conduct that all contributors are expected # Stevedore Project Code of Conduct -The Stevedore project is committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or similar personal characteristic. +The Stevedore project is committed to providing a friendly, safe, and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or similar personal characteristics. We expect all contributors, users, and community members to follow this code of conduct. This includes all interactions within the Stevedore community, whether online, in person, or otherwise. ## Code of Conduct + ### Be respectful and inclusive + We encourage participation from everyone. Please be respectful and considerate towards others, and avoid any language, images, or actions that could be considered disrespectful, offensive, or exclusionary. ### Listen and be open to constructive feedback + Be open to constructive feedback and criticism from others. We all have room to learn, grow, and improve, and being open to feedback is an important part of that process. ### Don't harass or discriminate + Harassment or discrimination of any kind will not be tolerated. This includes but is not limited to derogatory comments or slurs, sexual harassment, and unwanted physical contact or attention. If you experience or witness any form of harassment or discrimination, please report it immediately. ### Don't engage in disruptive behaviour + Disruptive behaviour, such as spamming, trolling, or other malicious behaviour, will not be tolerated. We want to maintain a positive and productive environment for everyone. -## Acknowledgements +## Acknowledgments + This Code of Conduct is adapted from the Contributor Covenant, version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. \ No newline at end of file diff --git a/content/en/docs/docs-v0.11/getting-started/concepts/_index.md b/content/en/docs/docs-v0.11/getting-started/concepts/_index.md index ae1512a..41882e5 100644 --- a/content/en/docs/docs-v0.11/getting-started/concepts/_index.md +++ b/content/en/docs/docs-v0.11/getting-started/concepts/_index.md @@ -8,16 +8,18 @@ description: > --- ### Build + The process to generate a Docker image. ### Builder -A Builder arranges a set of parameters to build a Docker image. Among those parameters, you can define the [driver]({{}}) to perform the build, the Docker build context or the Dockerfile location. -You can define a builder as a **global builder** or an **in-line builder**. +A Builder arranges a set of parameters to build a Docker image. Among those parameters, you can define the [driver]({{}}) to perform the build, the Docker build context or the Dockerfile location. + +You can define a builder as a **global builder** or an **in-line builder**. -Global builders are defined within a folder location specified in the [configuration]({{}}) and can be used by any image definition. +Global builders are defined within a folder location specified in the [configuration]({{}}) and can be used by any image definition. -On the snipped below there are defined two global builders: `code`, at *line 2* and `global-infr-builder`, at *line 7*. +On the snipped below there are defined two global builders: `code`, at _line 2_, and `global-infr-builder`, at _line 7_. {{< highlight Yaml "linenos=table" >}} builders: code: @@ -51,30 +53,35 @@ simple-go-helloworld: {{< /highlight >}} ### Credentials -Credentials allow users to securely store authentication information, such as access keys, tokens, passwords, and SSH keys. These credentials can be used to authenticate with Docker registries and Git servers, allowing users to push and pull images and code securely and with ease. Refer to the [reference guide]({{}}) to know more about the credentials details. + +Credentials allow users to securely store authentication information, such as access keys, tokens, passwords, and SSH keys. These credentials can be used to authenticate with Docker registries and Git servers, allowing users to push and pull images and code securely and with ease. Refer to the [reference guide]({{}}) to know more about the credentials details. ### Credentials store -The credential store in Stevedore allows users to securely store and retrieve credentials needed during the Docker images building process. Refer to the [reference guide]({{}}) to know more about the credentials store. + +The credential store in Stevedore allows users to securely store and retrieve credentials needed during the Docker images' building process. Refer to the [reference guide]({{}}) to know more about the credentials store. ### Driver + Stevedore relies on existing tools designed for building Docker images rather than implementing its mechanism. The driver plays a crucial role in this process by preparing the build parameters based on the image and builder definitions and triggering the request to build the image. -As of today, Stevedore supports the following drivers: -- **docker** driver that uses the Docker API. When a builder is defined to use the docker driver, it must provide at least the context, along with other parameters such as Dockerfiles location. For further information refer to [reference guide]({{}}). -- **ansible-playbook** driver builds Docker images by executing ansible playbooks. When a builder is defined to use an ansible-playbook driver, it must provide the playbook location as well as the Ansible inventory. For further information refer to [reference guide]({{}}). +As of today, Stevedore supports the following drivers: + +- **docker** driver that uses the Docker API. When a builder is defined to use the docker driver, it must provide at least the context, along with other parameters such as Dockerfile location. For further information refer to [reference guide]({{}}). +- **ansible-playbook** driver builds Docker images by executing ansible playbooks. When a builder is defined to use the ansible-playbook driver, it must provide the playbook location as well as the Ansible inventory. For further information refer to [reference guide]({{}}). ### Image -An image definition, which is also known as _image_ in Stevedore's context, defines the Docker image you want to build, how to build it and the relationship with its parents or children images. -An image must be defined within the [Images-tree]({{}}), and you can refer to it by its name and version. For further information refer to [reference guide]({{}}). +An image definition, which is also known as _image_ in Stevedore's context, defines the Docker image you want to build, how to build it, and the relationship with its parents or children images. + +An image must be defined within the [Images-tree]({{}}), and you can refer to it by its name and version. For further information refer to [reference guide]({{}}). {{< highlight Yaml "linenos=table" >}} my-image-base: "0.0.1": - registry: my-registry.my-domain.cat + registry: my-registry.my-domain.cat namespace: library tags: - - latest + - latest parents: busybox: - "1.36" @@ -88,15 +95,16 @@ my-image-base: {{< /highlight >}} ### Images-tree -The Images-tree is a data structure containing the definition of the images, as well as the relationship among them. -Reference guide provides more detailed information about the [images-tree]({{}}). + +The _images-tree_ is a data structure containing the definition of the images, as well as the relationship among them. +Reference guide provides more detailed information about the [images-tree]({{}}). On the snipped below you can see three images defined within the Images-tree: `my-image-base`, at line 2, `my-ms1`, at line 13, and `my-ms2`, at line 35. {{< highlight Yaml "linenos=table" >}} images: my-image-base: "stable": - registry: my-registry.example.com + registry: my-registry.example.com namespace: library tags: - latest @@ -107,13 +115,13 @@ images: path: my-image-base my-ms1: "0.0.1": - registry: my-registry.example.com + registry: my-registry.example.com namespace: library parents: my-image-base: - stable devel: - registry: my-registry.example.com + registry: my-registry.example.com namespace: library version: "{{ .Version }}-{{ .Parent.Name }}{{ .Parent.Version }}" parents: @@ -121,7 +129,7 @@ images: - stable - devel "*": - registry: my-registry.example.com + registry: my-registry.example.com namespace: library version: "{{ .Version }}" parents: @@ -129,14 +137,14 @@ images: - stable my-ms2: "0.1.5": - registry: my-registry.example.com + registry: my-registry.example.com namespace: library version: "{{ .Version }}-{{ .Parent.Name }}{{ .Parent.Version }}" parents: my-image-base: - stable "*": - registry: my-registry.example.com + registry: my-registry.example.com namespace: library version: "{{ .Version }}" parents: @@ -145,29 +153,33 @@ images: {{< /highlight >}} ### Promote + Promoting an image, in Stevedore's context, means pushing an image to the Docker registry or another namespace on the same Docker registry. ### Semver tag + When a tag is [semantic version 2.0.0](https://semver.org/) compliance is known as semver tag. ### Wildcard version + An image is identified by a name and version, and when you attempt to build an image using an undefined version, Stevedore uses the image definition with the wildcard version to build the Docker image. It means that the wildcard version provides a default definition that can be used to build an image whose version does not have an explicit image definition. -You can recognize when an image has defined a wildcard version definition because the value of the version is `*` (*start*). +You can recognize when an image has defined a wildcard version definition because the value of the version is `*` (_start_). The next snipped provides an image with a wildcard version definition, at line 5. The `{{ .Version }}` could be set as any value used to build the `my-app` image. {{< highlight Yaml "linenos=table" >}} my-app: "0.1.5": - registry: my-registry.example.com + registry: my-registry.example.com namespace: library "*": - registry: my-registry.example.com + registry: my-registry.example.com namespace: library version: "{{ .Version }}" {{< /highlight >}} ### Variables mapping + Variables mapping, also known as varmap or varmapping, is a builder's optional attribute that defines the name of those variables that are always generated by Stevedore and passed to the driver to perform the request to build an image. -Each driver defines its variables mapping. For further information refer to [variables mapping]({{}}) reference guide. +Each driver defines its variables mapping. For further information refer to [variables mapping]({{}}) reference guide. diff --git a/content/en/docs/docs-v0.11/getting-started/configuration/_index.md b/content/en/docs/docs-v0.11/getting-started/configuration/_index.md index c1753cd..66919be 100644 --- a/content/en/docs/docs-v0.11/getting-started/configuration/_index.md +++ b/content/en/docs/docs-v0.11/getting-started/configuration/_index.md @@ -8,15 +8,19 @@ description: > --- ## Stevedore configuration + Stevedore can load its configuration either from a local configuration file or environment variables. ### Configuration from environment variables + When you want to use environment variables to define a Stevedore configuration parameter, you must create an environment variable with the same name as the parameter, and prefix it with `STEVEDORE_`. The environment variables must be uppercased. -For example, to define the [images_path]({{}}) parameter as an environment variable, you must create the `STEVEDORE_TREE_PATH` variable. +For example, to define the [images_path]({{}}) parameter as an environment variable, you must create the `STEVEDORE_IMAGES_PATH` variable. ### Configuration from local configuration file -Stevedore looks for the user configuration on the listed files, and it does following order that appears in the list: + +Stevedore looks for the user configuration on the listed files, and it does the following order that appears in the list: + 1. ./stevedore.yaml 2. ~/.config/stevedore/stevedore.yaml 3. ~/stevedore.yaml @@ -24,189 +28,236 @@ Stevedore looks for the user configuration on the listed files, and it does foll However, you can load the configuration from a custom location using `--config` flag on stevedore CLI. Loading configuration from a custom location has precedence over any other configuration. ## Create the configuration file + Stevedore CLI provides the command `stevedore create configuration` to create the configuration file. However, you can also make it manually. The command `stevedore init`, is an alias from the create configuration subcommand that is also available to generate the configuration file. When you use the CLI to generate the configuration file, the outcome configuration is created at `./stevedore.yaml` but you can indicate your desired location by the `--config` flag. ### Stevedore credentials -Stevedore could store your Docker registry's credentials and use them on your behalf during the [building]({{}}) or [promoting]({{}}) processes. -The default folder to store the credentials is `~/.config/stevedore/credentials`. Nevertheless, you can define where to store the credentials by setting the [docker_registry_credentials_dir]({{}}) parameter. +Stevedore could store your Docker registry's credentials and use them on your behalf during the [building]({{}}) or [promoting]({{}}) processes. + +The default folder to store the credentials is `~/.config/stevedore/credentials`. Nevertheless, you can define where to store the credentials by setting the [docker_registry_credentials_dir]({{}}) parameter. In case you use the CLI to create Stevedore's configuration, you can also request to create Docker's registry credentials. Finally, with the CLI command `stevedore create credentials`, you can create as many credentials as you need. ## Configuration parameters -In the coming section are described all the Stevedore configuration parameters. + +The coming section describes all the Stevedore configuration parameters. ### **builder_path** + {{% pageinfo %}} -Desprecated configuration parameter, it will be removed on version 0.12.0. Please use [builders_path]({{}}) instead. +Desprecated configuration parameter, will be removed on version 0.12.0. Please use [builders_path]({{}}) instead. {{% /pageinfo %}} -It specifies the file that Stevedore uses to look for the definition of the [builders]({{}}). +It specifies the file that Stevedore uses to look for the definition of the [builders]({{}}). + - Environment variable: `STEVEDORE_BUILDER_PATH` - Default value: + ```yaml builder_path: stevedore.yaml ``` ### **builders_path** -It specifies the location path where Stevedore looks for the definition of the [builders]({{}}). + +It specifies the location path where Stevedore looks for the definition of the [builders]({{}}). This can be a file or directory. If you configure a directory, Stevedore loads the builders defined in each file within the directory. + - Environment variable: `STEVEDORE_BUILDERS_PATH` - Default value: + ```yaml builders_path: stevedore.yaml ``` ### **builders** -The [builders]({{}}) block contains the global builders definition. -The location of the builder definitions is specified in [builders_path]({{}}). Stevedore looks for the builder definitions in the file or directory specified by builders_path. For more details, please see the [reference guide]({{}}). +The [builders]({{}}) block contains the global builders definition. + +The location of the builder definitions is specified in [builders_path]({{}}). Stevedore looks for the builder definitions in the file or directory specified by builders_path. For more details, please see the [reference guide]({{}}). - Environment variable: `STEVEDORE_BUILDERS` ### **build_on_cascade** + {{% pageinfo %}} -Desprecated configuration parameter, it will be removed on version 0.12.0. To build an image on cascade, please use the `--cascade` flag in the [build]({{}}) command. +Desprecated configuration parameter, will be removed on version 0.12.0. To build an image on cascade, please use the `--cascade` flag in the [build]({{}}) command. {{% /pageinfo %}} On build command, indicates whether to start to build children's images once the image build finishes. + - Environment variable: `STEVEDORE_BUILD_ON_CASCADE` - Default value: -```yaml + +```yaml build_on_cascade: false ``` ### **concurrency** + This parameter sets the number of workers that Stevedore creates to build Docker images. Each worker corresponds to one image that can be built concurrently. + - Environment variable: `STEVEDORE_CONCURRENCY` - Default value: is the rounded integer value of the result of dividing the total number of CPUs by 4. For example, if the system has 16 CPUs, the default value would be 4. ### **credentials** -The credentials configuration block defines the credentials store used to authenticate with external Docker registries or a git server. -You can set the following parameters to for the credentials store: + +The credentials configuration block defines the credentials store used to authenticate with external Docker registries or a Git server. +You can set the following parameters for the credentials store: + #### encryption_key + The encryption_key parameter specifies the secret key used to encrypt and decrypt credentials. It is required to provide an encryption key when using `envvars` as the storage type for credentials. - Environment variable: `STEVEDORE_CREDENTIALS_ENCRYPTION_KEY` - Default value: null #### format + The format used to store the credentials. Currently supported formats are `JSON` and `YAML`. + - Environment variable: `STEVEDORE_CREDENTIALS_FORMAT` - Default value: "json" #### local_storage_path + When you use the local credentials store, it defines the local folder where to store the credentials on disk. + - Environment variable: `STEVEDORE_CREDENTIALS_LOCAL_STORAGE_PATH` - Default value: "credentials" #### storage_type + The storage_type parameter defines the type of storage backend to use for persisting the credentials. Currently supported types are `local` and `envvars`. - Environment variable: `STEVEDORE_CREDENTIALS_STORAGE_TYPE` - Default value: "local" ### **docker_registry_credentials_dir** + {{% pageinfo %}} -Desprecated configuration parameter, it will be removed on version 0.12.0. Refer to the [credentials]({{}}) configuration block to know more about how to define the credentials parameters. +Desprecated configuration parameter, will be removed on version 0.12.0. Refer to the [credentials]({{}}) configuration block to know more about how to define the credentials parameters. {{% /pageinfo %}} This option specifies the directory where Docker registry credentials are stored for persistence. + - Environment variable: `STEVEDORE_DOCKER_REGISTRY_CREDENTIALS_DIR` - Default value: -```yaml + +```yaml docker_registry_credentials_dir: ~/.config/stevedore/credentials ``` ### **images_path** -It is the configuration parameter that specifies the location where Stevedore searches for [images definition]({{}}). + +It is the configuration parameter that specifies the location where Stevedore searches for [images definition]({{}}). It can be set to either a file or directory. When the `images_path` configuration parameter is set to a directory, Stevedore loads the definitions from all files within that directory - Environment variable: `STEVEDORE_IMAGES_PATH` - Default value: + ```yaml images_path: stevedore.yaml ``` ### **images_tree** + {{% pageinfo %}} -Desprecated configuration parameter, it will be removed on version 0.12.0. Please use [images]({{}}) instead.. +Desprecated configuration parameter, will be removed on version 0.12.0. Please use [images]({{}}) instead.. {{% /pageinfo %}} -The `images_tree` block contains the [images-tree]({{}}), where are placed the [images definition]({{}}). +The `images_tree` block contains the [images-tree]({{}}), where are placed the [images definition]({{}}). -Stevedore looks for the images on the file set at [images_path]({{}}) and loads the images defined under the `images_tree` key. For further information see the [reference guide]({{}}). +Stevedore looks for the images on the file set at [images_path]({{}}) and loads the images defined under the `images_tree` key. For further information see the [reference guide]({{}}). - Environment variable: `STEVEDORE_IMAGES_TREE` ### **images** -The `images` block in the Stevedore configuration contains the image definitions. +The `images` block in the Stevedore configuration contains the image definitions. -Stevedore looks for these definitions in the file or directory set at [images_path]({{}}), and loads any images defined under the `images` key. For more information, please refer to the Stevedore [reference guide]({{}}). +Stevedore looks for these definitions in the file or directory set at [images_path]({{}}), and loads any images defined under the `images` key. For more information, please refer to the Stevedore [reference guide]({{}}). - Environment variable: `STEVEDORE_IMAGES` ### **log_path** + Is the configuration parameter that specifies the location of the log file. - Environment variable: `STEVEDORE_LOG_PATH` - Default value: -```yaml + +```yaml log_path: /dev/null ``` ### **num_workers** + {{% pageinfo %}} -Desprecated configuration parameter, it will be removed on version 0.12.0. Please use [concurrency]({{}}) instead. +Desprecated configuration parameter, will be removed on version 0.12.0. Please use [concurrency]({{}}) instead. {{% /pageinfo %}} -It defines the amount of workers to create to build images. That corresponds to the number of images that can be build concurrently. +It defines the amount of workers to create to build images. That corresponds to the number of images that can be built concurrently. + - Environment variable: `STEVEDORE_NUM_WORKERS` - Default value: is the rounded integer value of the result of dividing the total number of CPUs by 4. For example, if the system has 16 CPUs, the default value would be 4. ### **push_images** + The `push_images` configuration parameter specifies whether Stevedore should automatically push the built images to the registry after the build process is complete. - Environment variable: `STEVEDORE_PUSH_IMAGES` - Default value: -```yaml + +```yaml push_images: true ``` ### **semantic_version_tags_enabled** + When set to true, Stevedore generates additional tags based on the semantic version tree tags, if the main image tag is compliant with semantic version 2.0.0. + - Environment variable: `STEVEDORE_SEMANTIC_VERSION_TAGS_ENABLED` - Default value: + ```yaml semantic_version_tags_enabled: false ``` ### **semantic_version_tags_templates** - It is a list of templates that are used to generate additional tags when the [semantic_version_tags_enabled]({{}}) configuration parameter is enabled and the main image tag is semver 2.0.0 compliant. + + It is a list of templates that are used to generate additional tags when the [semantic_version_tags_enabled]({{}}) configuration parameter is enabled and the main image tag is semver 2.0.0 compliant. + - Environment variable: `STEVEDORE_SEMANTIC_VERSION_TAGS_TEMPLATES` - Default value: -```yaml + +```yaml semantic_version_tags_templates: - "{{ .Major }}.{{ .Minor }}.{{ .Patch }}" ``` ### **tree_path** + {{% pageinfo %}} -Desprecated configuration parameter, it will be removed on version 0.12.0. Please use [images_path]({{}}) instead. +Desprecated configuration parameter, will be removed on version 0.12.0. Please use [images_path]({{}}) instead. {{% /pageinfo %}} -Is the images tree location path. +Is the images' tree location path. + - Environment variable: `STEVEDORE_TREE_PATH` - Default value: + ```yaml tree_path: stevedore.yaml ``` + ## Configuration example + Here you have an example with all the parameters available + ```yaml builders_path: stevedore.yaml builders: @@ -235,4 +286,4 @@ push_images: true semantic_version_tags_enabled: true semantic_version_tags_templates: - "{{ .Major }}.{{ .Minor }}.{{ .Patch }}" -``` \ No newline at end of file +``` diff --git a/content/en/docs/docs-v0.11/getting-started/install.md b/content/en/docs/docs-v0.11/getting-started/install.md index d9071a1..e8d4987 100644 --- a/content/en/docs/docs-v0.11/getting-started/install.md +++ b/content/en/docs/docs-v0.11/getting-started/install.md @@ -8,7 +8,7 @@ description: > Learn about the different methods available to install Stevedore --- -Installing Stevedore is a straightforward process, and you have a few options to choose from. You can install using the provided installation script, which will take care of everything for you. Alternatively, you can download and install from a tarball or install from source if you prefer. This gives you more flexibility and control over the installation process. +Installing Stevedore is a straightforward process, and you have a few options to choose from. You can install using the provided installation script, which will take care of everything for you. Alternatively, you can download and install from a tarball or install from the source if you prefer. This gives you more flexibility and control over the installation process. ## Using the install script @@ -44,13 +44,13 @@ To install Stevedore using a tarball, simply download it directly from GitHub re - Go to the Stevedore Github releases page and download the latest tarball ```sh -curl -fsSLO https://github.com/gostevedore/stevedore/releases/download/v0.11.0/stevedore_v0.11.0_Linux-x86_64.tar.gz +curl -fsSLO https://github.com/gostevedore/stevedore/releases/download/v0.11.2/stevedore_v0.11.2_Linux-x86_64.tar.gz ``` - Extract the contents of the tarball to a directory of your choice ```sh -tar xzfv stevedore_v0.11.0_Linux-x86_64.tar.gz +tar xzfv stevedore_v0.11.2_Linux-x86_64.tar.gz ``` - Add the Stevedore executable to your system path or create a symlink @@ -61,7 +61,7 @@ ln -sf ${PWD}/stevedore /usr/local/bin/stevedore ## Install from source -If you prefer to install Stevedore from source, you can clone the GitHub repository and build it manually. Here are the steps to follow: +If you prefer to install Stevedore from the source, you can clone the GitHub repository and build it manually. Here are the steps to follow: - Clone the Stevedore repository using Git: diff --git a/content/en/docs/docs-v0.11/getting-started/quickstart.md b/content/en/docs/docs-v0.11/getting-started/quickstart.md index 5c34da6..e8a9075 100644 --- a/content/en/docs/docs-v0.11/getting-started/quickstart.md +++ b/content/en/docs/docs-v0.11/getting-started/quickstart.md @@ -11,6 +11,7 @@ description: > ## Installation To install Stevedore, use the script provided on the repository: + ```sh curl -fsSL https://raw.githubusercontent.com/gostevedore/stevedore/main/scripts/install.sh | sudo bash - ``` @@ -18,7 +19,8 @@ curl -fsSL https://raw.githubusercontent.com/gostevedore/stevedore/main/scripts/ Alternatively, you can visit the [installation guide]({{< ref "/docs/getting-started/install">}}) for other methods. ## Initial setup -- Create a folder structure to store image definitions and builder configurations before building Docker images. + +- Create a folder structure to store image definitions and builder configurations before building Docker images. ```sh / $ mkdir -p /docker/images /docker/builders @@ -27,10 +29,10 @@ Alternatively, you can visit the [installation guide]({{< ref "/docs/getting-sta - Initialize Stevedore. We create a configuration file for this guide, but it can be also defined on environment variables. + ```sh / $ cd /docker /docker $ stevedore initialize --builders-path builders --credentials-storage-type local --generate-credentials-encryption-key --images-path images --log-path-file /dev/null -2023-02-03 21:57:20 INFO Executing command 'stevedore [COMMAND] [OPTIONS] initialize' ``` After running this command, you can validate the configuration by using the _get configuration_ subcommand. @@ -55,12 +57,14 @@ After running this command, you can validate the configuration by using the _get - Create credentials to log into the Docker registry. Since you create a credential using a username and password, Stevedore prompts you to enter a password for the specified username. + ```sh /docker $ stevedore create credentials registry.stevedore.test --username admin Password: ``` - Validate that the credentials have been stored. + ```sh /docker $ stevedore get credentials ID TYPE CREDENTIALS @@ -68,12 +72,14 @@ registry.stevedore.test username-password username=admin ``` Stevedore's configuration encrypts the credentials content at rest by providing an encryption key. + ```sh /docker $ cat credentials/82e99d42ee1191bb42fbfb444920104d 2d067af765e8de39fd76b5cd1a430768a66464208bf8fe0c092bcb146a24feed377b916952494e6cea55187f397aee8c2d90a55ef9882cf85ee97ed5660700afa002767e028b4ea6bde274a524e7100f5729601f2d44caa08a1a102af7f79079723f35953133be56e31d0eaf44f52255a5c94512c74625dca3f00b77f9031d4f48f5cf38293f7a2a90f727c9a5eedf57e001ea8766a6d1e47d20354ad3ca6cf022ee70b97b3598e7377355a7b52f62fab8b6628b230c33cf0234ea1208c0d6ecef65e8e1206e7daf15acbbfb62d77650982c9f487129534b367a7fc2b519fd04538bffe87e57184adabc57e613be4b0e106480f9078c8c1c916b65de0039a3adc6cea70b962c0d93477e114e25a2a160db0218e9312d0df00d9b1044e0b4981982834094a36d8d9e4fd9ed766605c1a0b43ff11219d6e5bebb414e084102ce8cd57e86a658455de5fff927ba9be039be4afd393b7e8137cdefb268ed7c79ff37a60c1be3693372d7890b9f8f7c81fa559719ff83371e080efaee86b239e127a094136d056641a4a58245f71414b53dd96214149c6f54de055064163fa9dcb0a6b274d9269a49e1e4f76a9c0a89ec12d40c577ea1b5c1b3f9f8454f5473518c58e8c139a96335850a6415df7e2d41f5ab383f85d30281fd29493db0f0fb577aba35326cd5063b463a41161888514dbce09ccea5887494733256d74341e2623a5328c656/docker # ``` ## Build the Docker images for an application + In this section, we create an application that has multiple versions and needs to be built from multiple parents. - Prepare the application. @@ -81,6 +87,7 @@ In this section, we create an application that has multiple versions and needs t First, let's create the application directory and the Dockerfile. Note that we use the Dockerfile arguments `image_from_name` and `image_from_tag`, which are automatically generated by Stevedore to provide information about the parent image. Additionally, any arguments defined in the `vars` or `persistent_vars` attributes of the image definition can be used in the Dockerfile when building the image. + ```sh / $ mkdir -p /apps/my-app / $ cd /apps/my-app @@ -97,6 +104,7 @@ EOF - Define a builder. Next, we need to define the builder for our application. Take into account that to build all the versions in a standardized way we define a single builder, which uses the same Dockerfile. + ```sh / $ cd /docker/builders /docker/builders $ cat << EOF > apps.yaml @@ -110,6 +118,7 @@ EOF ``` To confirm that the builder is already available, use the following command: + ```sh / $ cd /docker /docker $ stevedore get builders @@ -120,6 +129,7 @@ my-apps docker - Define the foundational images, the parent images. Before creating the image definitions for our application, we define the base images that will serve as a starting point for building the Docker images. + ```sh / $ cd /docker/images /docker/images $ cat << EOF > foundational.yaml @@ -140,9 +150,10 @@ The `persistent_labels` attribute sets in key-value pairs the labels to add on a Stevedore uses Go's [text/template](https://pkg.go.dev/text/template) package to render the image definitions. {{% /pageinfo %}} -- Specify the images definitions for the application. +- Specify the image definitions for the application. In this step, we define two versions of the application `my-app` in the `applications.yaml` file, version `2.1.0` and `3.2.1`. + ```sh /docker/images $ cat << EOF > applications.yaml images: @@ -169,7 +180,8 @@ EOF The _name_ is set to `{{ .Name }}` which will be replaced by the actual name of the image. The _version_ is set to `{{ .Version }}-{{ .Parent.Name }}{{ .Parent.Version }}` which will be replaced by the actual version of the image and its parent name and version. The _builder_ is set to `my-app`, which is the _global-builder_ previously defined in the `/docker/builders/apps.yaml` file. The _parents_ are set to `busybox:1.35` for `2.1.0` version, `busybox:1.35` and `busybox:1.36` for the `3.2.1` version. -You can use the following comand to ensure that images are already defined. +You can use the following command to ensure that images are already defined. + ```sh / $ cd /docker /docker $ stevedore get images --tree @@ -183,6 +195,7 @@ You can use the following comand to ensure that images are already defined. - Build the Docker images. Create all the Docker images for our application at the same time, with just one command. + ```sh /docker $ stevedore build my-app registry.stevedore.test/my-app:3.2.1-busybox1.35 Step 1/7 : ARG image_from_name @@ -255,6 +268,7 @@ registry.stevedore.test/my-app:3.2.1-busybox1.35 Successfully tagged registry.st ``` Validate the recently created images. + ```sh /docker $ docker images REPOSITORY TAG IMAGE ID CREATED SIZE @@ -266,7 +280,9 @@ busybox 1.35 f68fa78323e7 6 weeks ago ``` ## Promote the images to a Docker registry + Now that we already have the images created, and since we did not set the push after the build flag, we promote the images to the Docker registry and push them to the `stable` namespace. + ```sh /docker $ stevedore promote registry.stevedore.test/my-app:3.2.1-busybox1.36 --promote-image-registry-namespace stable registry.stevedore.test/my-app:3.2.1-busybox1.36 ‣ The push refers to repository [registry.stevedore.test/stable/my-app] diff --git a/content/en/docs/docs-v0.11/reference-guide/builder/ansible-playbook/_index.md b/content/en/docs/docs-v0.11/reference-guide/builder/ansible-playbook/_index.md index 8281701..5acf3db 100644 --- a/content/en/docs/docs-v0.11/reference-guide/builder/ansible-playbook/_index.md +++ b/content/en/docs/docs-v0.11/reference-guide/builder/ansible-playbook/_index.md @@ -22,8 +22,8 @@ The `ansible-playbook` driver provides to ansible-playbook the variables-mapping |Key name|Description|Default
argument-name|Default
argument-value| |---|---|---|---| |**image_builder_label_key**|This is the argument-name to set the name of the intermediate container that is used to create the Docker image using the ansible-playbook driver|image_builder_label|The argument-value is set as the full qualified name of the image. | -|**image_fully_qualified_name**|This is the argument-name that you can use to set the fully-qualified image name of of the image that you are building.
Introduced in v0.11.1. | image_fully_qualified_name |This is the argument-name that provides you with fully-qualified image name. | -|**image_from_fully_qualified_name**|This is the argument-name that you can use to set the fully-qualified name of the base image that you want to use as a starting point for your Docker image.
Introduced in v0.11.1.| image_from_fully_qualified_name |This is the argument-name that provides you with fully-qualified parent image name. | +|**image_fully_qualified_name**|This is the argument-name that you can use to set the fully-qualified image name of of the image that you are building.
Introduced in v0.11.2. | image_fully_qualified_name |This is the argument-name that provides you with fully-qualified image name. | +|**image_from_fully_qualified_name**|This is the argument-name that you can use to set the fully-qualified name of the base image that you want to use as a starting point for your Docker image.
Introduced in v0.11.2.| image_from_fully_qualified_name |This is the argument-name that provides you with fully-qualified parent image name. | |**image_from_name_key**|This is the argument-name to set the name of the parent image from which the new image will be built using the ansible-playbook driver|image_from_name|The argument-value is set as the parent image's name within the [images-tree]({{}})| |**image_from_registry_host_key**|This is the argument-name to set the parent image's registry host when creating a Docker image using the ansible-playbook driver|image_from_registry_host|The argument-value is set as the parent image's registry host within the [images-tree]({{}})| |**image_from_registry_namespace_key**|This is the argument-name to set the parent image's namespace within the registry when creating a Docker image using the ansible-playbook driver|image_from_registry_namespace|The argument-value is set as the parent image's namespace within the [images-tree]({{}})| @@ -37,7 +37,7 @@ The `ansible-playbook` driver provides to ansible-playbook the variables-mapping ## Ansible-playbook driver example -The goal of the following example is to show you all the configuration options for a builder which uses the ansible-playbook driver. +The goal of the following example is to show you all the configuration options for a builder that uses the ansible-playbook driver. {{}} builder: diff --git a/content/en/docs/docs-v0.11/reference-guide/builder/docker/_index.md b/content/en/docs/docs-v0.11/reference-guide/builder/docker/_index.md index e3d9f8d..1f0e51e 100644 --- a/content/en/docs/docs-v0.11/reference-guide/builder/docker/_index.md +++ b/content/en/docs/docs-v0.11/reference-guide/builder/docker/_index.md @@ -76,7 +76,7 @@ For security concerns, the recommendation is to use the credentials store or the ##### Git context example -The goal of that example is to show you all the configuration options for the git context, including the various authentication mechanisms that can be used to access a Git repository. +The goal of that example is to show you all the configuration options for the Git context, including the various authentication mechanisms that can be used to access a Git repository. {{}} builder: @@ -103,7 +103,7 @@ Docker driver passes `variables mapping` to Docker API as build arguments and ea |Key name|Description|Default
argument-name|Default
argument-value| |---|---|---|---| -|**image_from_fully_qualified_name**|This is the argument-name that you can use to set the fully-qualified name of the base image that you want to use as a starting point for your Docker image.
Introduced in v0.11.1.| image_from_fully_qualified_name |This is the argument-name that provides you with fully-qualified parent image name. | +|**image_from_fully_qualified_name**|This is the argument-name that you can use to set the fully-qualified name of the base image that you want to use as a starting point for your Docker image.
Introduced in v0.11.2.| image_from_fully_qualified_name |This is the argument-name that provides you with fully-qualified parent image name. | |**image_from_name_key**|This is the argument-name that you can use to set the name of the base image that you want to use as a starting point for your Docker image. | image_from_name | The argument-value is set as the parent image’s name within the [images-tree]({{}}). | |**image_from_registry_host_key**|This is the argument-name that you can use to set the Docker registry host where the base image is located. | image_from_registry_host |The argument-value is set as the parent image’s registry host within the [images-tree]({{}}). | |**image_from_registry_namespace_key**|This is the argument-name that you can use to set the namespace of the Docker registry where the base image is located. | image_from_registry_namespace | The argument-value is set as the parent image’s namespace within the [images-tree]({{}}). | @@ -113,7 +113,7 @@ Docker driver passes `variables mapping` to Docker API as build arguments and ea The following example is provided for illustrative purposes only and should not be copied and pasted into your configuration. -The goal of the following example is to show you all the configuration options for a builder which uses the `docker` driver. +The goal of the following example is to show you all the configuration options for a builder that uses the `docker`` driver. {{}} builder: diff --git a/content/en/docs/getting-started/concepts/_index.md b/content/en/docs/getting-started/concepts/_index.md index 0e2c20a..41882e5 100644 --- a/content/en/docs/getting-started/concepts/_index.md +++ b/content/en/docs/getting-started/concepts/_index.md @@ -8,16 +8,18 @@ description: > --- ### Build + The process to generate a Docker image. ### Builder + A Builder arranges a set of parameters to build a Docker image. Among those parameters, you can define the [driver]({{}}) to perform the build, the Docker build context or the Dockerfile location. -You can define a builder as a **global builder** or an **in-line builder**. +You can define a builder as a **global builder** or an **in-line builder**. Global builders are defined within a folder location specified in the [configuration]({{}}) and can be used by any image definition. -On the snipped below there are defined two global builders: `code`, at *line 2* and `global-infr-builder`, at *line 7*. +On the snipped below there are defined two global builders: `code`, at _line 2_, and `global-infr-builder`, at _line 7_. {{< highlight Yaml "linenos=table" >}} builders: code: @@ -51,30 +53,35 @@ simple-go-helloworld: {{< /highlight >}} ### Credentials + Credentials allow users to securely store authentication information, such as access keys, tokens, passwords, and SSH keys. These credentials can be used to authenticate with Docker registries and Git servers, allowing users to push and pull images and code securely and with ease. Refer to the [reference guide]({{}}) to know more about the credentials details. ### Credentials store -The credential store in Stevedore allows users to securely store and retrieve credentials needed during the Docker images building process. Refer to the [reference guide]({{}}) to know more about the credentials store. + +The credential store in Stevedore allows users to securely store and retrieve credentials needed during the Docker images' building process. Refer to the [reference guide]({{}}) to know more about the credentials store. ### Driver + Stevedore relies on existing tools designed for building Docker images rather than implementing its mechanism. The driver plays a crucial role in this process by preparing the build parameters based on the image and builder definitions and triggering the request to build the image. -As of today, Stevedore supports the following drivers: -- **docker** driver that uses the Docker API. When a builder is defined to use the docker driver, it must provide at least the context, along with other parameters such as Dockerfiles location. For further information refer to [reference guide]({{}}). -- **ansible-playbook** driver builds Docker images by executing ansible playbooks. When a builder is defined to use an ansible-playbook driver, it must provide the playbook location as well as the Ansible inventory. For further information refer to [reference guide]({{}}). +As of today, Stevedore supports the following drivers: + +- **docker** driver that uses the Docker API. When a builder is defined to use the docker driver, it must provide at least the context, along with other parameters such as Dockerfile location. For further information refer to [reference guide]({{}}). +- **ansible-playbook** driver builds Docker images by executing ansible playbooks. When a builder is defined to use the ansible-playbook driver, it must provide the playbook location as well as the Ansible inventory. For further information refer to [reference guide]({{}}). ### Image -An image definition, which is also known as _image_ in Stevedore's context, defines the Docker image you want to build, how to build it and the relationship with its parents or children images. + +An image definition, which is also known as _image_ in Stevedore's context, defines the Docker image you want to build, how to build it, and the relationship with its parents or children images. An image must be defined within the [Images-tree]({{}}), and you can refer to it by its name and version. For further information refer to [reference guide]({{}}). {{< highlight Yaml "linenos=table" >}} my-image-base: "0.0.1": - registry: my-registry.my-domain.cat + registry: my-registry.my-domain.cat namespace: library tags: - - latest + - latest parents: busybox: - "1.36" @@ -88,7 +95,8 @@ my-image-base: {{< /highlight >}} ### Images-tree -The Images-tree is a data structure containing the definition of the images, as well as the relationship among them. + +The _images-tree_ is a data structure containing the definition of the images, as well as the relationship among them. Reference guide provides more detailed information about the [images-tree]({{}}). On the snipped below you can see three images defined within the Images-tree: `my-image-base`, at line 2, `my-ms1`, at line 13, and `my-ms2`, at line 35. @@ -96,7 +104,7 @@ On the snipped below you can see three images defined within the Images-tree: `m images: my-image-base: "stable": - registry: my-registry.example.com + registry: my-registry.example.com namespace: library tags: - latest @@ -107,13 +115,13 @@ images: path: my-image-base my-ms1: "0.0.1": - registry: my-registry.example.com + registry: my-registry.example.com namespace: library parents: my-image-base: - stable devel: - registry: my-registry.example.com + registry: my-registry.example.com namespace: library version: "{{ .Version }}-{{ .Parent.Name }}{{ .Parent.Version }}" parents: @@ -121,7 +129,7 @@ images: - stable - devel "*": - registry: my-registry.example.com + registry: my-registry.example.com namespace: library version: "{{ .Version }}" parents: @@ -129,14 +137,14 @@ images: - stable my-ms2: "0.1.5": - registry: my-registry.example.com + registry: my-registry.example.com namespace: library version: "{{ .Version }}-{{ .Parent.Name }}{{ .Parent.Version }}" parents: my-image-base: - stable "*": - registry: my-registry.example.com + registry: my-registry.example.com namespace: library version: "{{ .Version }}" parents: @@ -145,29 +153,33 @@ images: {{< /highlight >}} ### Promote + Promoting an image, in Stevedore's context, means pushing an image to the Docker registry or another namespace on the same Docker registry. ### Semver tag + When a tag is [semantic version 2.0.0](https://semver.org/) compliance is known as semver tag. ### Wildcard version + An image is identified by a name and version, and when you attempt to build an image using an undefined version, Stevedore uses the image definition with the wildcard version to build the Docker image. It means that the wildcard version provides a default definition that can be used to build an image whose version does not have an explicit image definition. -You can recognize when an image has defined a wildcard version definition because the value of the version is `*` (*start*). +You can recognize when an image has defined a wildcard version definition because the value of the version is `*` (_start_). The next snipped provides an image with a wildcard version definition, at line 5. The `{{ .Version }}` could be set as any value used to build the `my-app` image. {{< highlight Yaml "linenos=table" >}} my-app: "0.1.5": - registry: my-registry.example.com + registry: my-registry.example.com namespace: library "*": - registry: my-registry.example.com + registry: my-registry.example.com namespace: library version: "{{ .Version }}" {{< /highlight >}} ### Variables mapping + Variables mapping, also known as varmap or varmapping, is a builder's optional attribute that defines the name of those variables that are always generated by Stevedore and passed to the driver to perform the request to build an image. Each driver defines its variables mapping. For further information refer to [variables mapping]({{}}) reference guide. diff --git a/content/en/docs/getting-started/configuration/_index.md b/content/en/docs/getting-started/configuration/_index.md index d22ed3c..66919be 100644 --- a/content/en/docs/getting-started/configuration/_index.md +++ b/content/en/docs/getting-started/configuration/_index.md @@ -8,15 +8,19 @@ description: > --- ## Stevedore configuration + Stevedore can load its configuration either from a local configuration file or environment variables. ### Configuration from environment variables + When you want to use environment variables to define a Stevedore configuration parameter, you must create an environment variable with the same name as the parameter, and prefix it with `STEVEDORE_`. The environment variables must be uppercased. For example, to define the [images_path]({{}}) parameter as an environment variable, you must create the `STEVEDORE_IMAGES_PATH` variable. ### Configuration from local configuration file -Stevedore looks for the user configuration on the listed files, and it does following order that appears in the list: + +Stevedore looks for the user configuration on the listed files, and it does the following order that appears in the list: + 1. ./stevedore.yaml 2. ~/.config/stevedore/stevedore.yaml 3. ~/stevedore.yaml @@ -24,12 +28,14 @@ Stevedore looks for the user configuration on the listed files, and it does foll However, you can load the configuration from a custom location using `--config` flag on stevedore CLI. Loading configuration from a custom location has precedence over any other configuration. ## Create the configuration file + Stevedore CLI provides the command `stevedore create configuration` to create the configuration file. However, you can also make it manually. The command `stevedore init`, is an alias from the create configuration subcommand that is also available to generate the configuration file. When you use the CLI to generate the configuration file, the outcome configuration is created at `./stevedore.yaml` but you can indicate your desired location by the `--config` flag. ### Stevedore credentials + Stevedore could store your Docker registry's credentials and use them on your behalf during the [building]({{}}) or [promoting]({{}}) processes. The default folder to store the credentials is `~/.config/stevedore/credentials`. Nevertheless, you can define where to store the credentials by setting the [docker_registry_credentials_dir]({{}}) parameter. @@ -39,30 +45,38 @@ In case you use the CLI to create Stevedore's configuration, you can also reques Finally, with the CLI command `stevedore create credentials`, you can create as many credentials as you need. ## Configuration parameters -In the coming section are described all the Stevedore configuration parameters. + +The coming section describes all the Stevedore configuration parameters. ### **builder_path** + {{% pageinfo %}} -Desprecated configuration parameter, it will be removed on version 0.12.0. Please use [builders_path]({{}}) instead. +Desprecated configuration parameter, will be removed on version 0.12.0. Please use [builders_path]({{}}) instead. {{% /pageinfo %}} It specifies the file that Stevedore uses to look for the definition of the [builders]({{}}). + - Environment variable: `STEVEDORE_BUILDER_PATH` - Default value: + ```yaml builder_path: stevedore.yaml ``` ### **builders_path** + It specifies the location path where Stevedore looks for the definition of the [builders]({{}}). This can be a file or directory. If you configure a directory, Stevedore loads the builders defined in each file within the directory. + - Environment variable: `STEVEDORE_BUILDERS_PATH` - Default value: + ```yaml builders_path: stevedore.yaml ``` ### **builders** + The [builders]({{}}) block contains the global builders definition. The location of the builder definitions is specified in [builders_path]({{}}). Stevedore looks for the builder definitions in the file or directory specified by builders_path. For more details, please see the [reference guide]({{}}). @@ -70,71 +84,90 @@ The location of the builder definitions is specified in [builders_path]({{}}) command. +Desprecated configuration parameter, will be removed on version 0.12.0. To build an image on cascade, please use the `--cascade` flag in the [build]({{}}) command. {{% /pageinfo %}} On build command, indicates whether to start to build children's images once the image build finishes. + - Environment variable: `STEVEDORE_BUILD_ON_CASCADE` - Default value: -```yaml + +```yaml build_on_cascade: false ``` ### **concurrency** + This parameter sets the number of workers that Stevedore creates to build Docker images. Each worker corresponds to one image that can be built concurrently. + - Environment variable: `STEVEDORE_CONCURRENCY` - Default value: is the rounded integer value of the result of dividing the total number of CPUs by 4. For example, if the system has 16 CPUs, the default value would be 4. ### **credentials** -The credentials configuration block defines the credentials store used to authenticate with external Docker registries or a git server. -You can set the following parameters to for the credentials store: + +The credentials configuration block defines the credentials store used to authenticate with external Docker registries or a Git server. +You can set the following parameters for the credentials store: + #### encryption_key + The encryption_key parameter specifies the secret key used to encrypt and decrypt credentials. It is required to provide an encryption key when using `envvars` as the storage type for credentials. - Environment variable: `STEVEDORE_CREDENTIALS_ENCRYPTION_KEY` - Default value: null #### format + The format used to store the credentials. Currently supported formats are `JSON` and `YAML`. + - Environment variable: `STEVEDORE_CREDENTIALS_FORMAT` - Default value: "json" #### local_storage_path + When you use the local credentials store, it defines the local folder where to store the credentials on disk. + - Environment variable: `STEVEDORE_CREDENTIALS_LOCAL_STORAGE_PATH` - Default value: "credentials" #### storage_type + The storage_type parameter defines the type of storage backend to use for persisting the credentials. Currently supported types are `local` and `envvars`. - Environment variable: `STEVEDORE_CREDENTIALS_STORAGE_TYPE` - Default value: "local" ### **docker_registry_credentials_dir** + {{% pageinfo %}} -Desprecated configuration parameter, it will be removed on version 0.12.0. Refer to the [credentials]({{}}) configuration block to know more about how to define the credentials parameters. +Desprecated configuration parameter, will be removed on version 0.12.0. Refer to the [credentials]({{}}) configuration block to know more about how to define the credentials parameters. {{% /pageinfo %}} This option specifies the directory where Docker registry credentials are stored for persistence. + - Environment variable: `STEVEDORE_DOCKER_REGISTRY_CREDENTIALS_DIR` - Default value: -```yaml + +```yaml docker_registry_credentials_dir: ~/.config/stevedore/credentials ``` ### **images_path** + It is the configuration parameter that specifies the location where Stevedore searches for [images definition]({{}}). It can be set to either a file or directory. When the `images_path` configuration parameter is set to a directory, Stevedore loads the definitions from all files within that directory - Environment variable: `STEVEDORE_IMAGES_PATH` - Default value: + ```yaml images_path: stevedore.yaml ``` ### **images_tree** + {{% pageinfo %}} -Desprecated configuration parameter, it will be removed on version 0.12.0. Please use [images]({{}}) instead.. +Desprecated configuration parameter, will be removed on version 0.12.0. Please use [images]({{}}) instead.. {{% /pageinfo %}} The `images_tree` block contains the [images-tree]({{}}), where are placed the [images definition]({{}}). @@ -144,69 +177,87 @@ Stevedore looks for the images on the file set at [images_path]({{}}), and loads any images defined under the `images` key. For more information, please refer to the Stevedore [reference guide]({{}}). - Environment variable: `STEVEDORE_IMAGES` ### **log_path** + Is the configuration parameter that specifies the location of the log file. - Environment variable: `STEVEDORE_LOG_PATH` - Default value: -```yaml + +```yaml log_path: /dev/null ``` ### **num_workers** + {{% pageinfo %}} -Desprecated configuration parameter, it will be removed on version 0.12.0. Please use [concurrency]({{}}) instead. +Desprecated configuration parameter, will be removed on version 0.12.0. Please use [concurrency]({{}}) instead. {{% /pageinfo %}} -It defines the amount of workers to create to build images. That corresponds to the number of images that can be build concurrently. +It defines the amount of workers to create to build images. That corresponds to the number of images that can be built concurrently. + - Environment variable: `STEVEDORE_NUM_WORKERS` - Default value: is the rounded integer value of the result of dividing the total number of CPUs by 4. For example, if the system has 16 CPUs, the default value would be 4. ### **push_images** + The `push_images` configuration parameter specifies whether Stevedore should automatically push the built images to the registry after the build process is complete. - Environment variable: `STEVEDORE_PUSH_IMAGES` - Default value: -```yaml + +```yaml push_images: true ``` ### **semantic_version_tags_enabled** + When set to true, Stevedore generates additional tags based on the semantic version tree tags, if the main image tag is compliant with semantic version 2.0.0. + - Environment variable: `STEVEDORE_SEMANTIC_VERSION_TAGS_ENABLED` - Default value: + ```yaml semantic_version_tags_enabled: false ``` ### **semantic_version_tags_templates** + It is a list of templates that are used to generate additional tags when the [semantic_version_tags_enabled]({{}}) configuration parameter is enabled and the main image tag is semver 2.0.0 compliant. + - Environment variable: `STEVEDORE_SEMANTIC_VERSION_TAGS_TEMPLATES` - Default value: -```yaml + +```yaml semantic_version_tags_templates: - "{{ .Major }}.{{ .Minor }}.{{ .Patch }}" ``` ### **tree_path** + {{% pageinfo %}} -Desprecated configuration parameter, it will be removed on version 0.12.0. Please use [images_path]({{}}) instead. +Desprecated configuration parameter, will be removed on version 0.12.0. Please use [images_path]({{}}) instead. {{% /pageinfo %}} -Is the images tree location path. +Is the images' tree location path. + - Environment variable: `STEVEDORE_TREE_PATH` - Default value: + ```yaml tree_path: stevedore.yaml ``` + ## Configuration example + Here you have an example with all the parameters available + ```yaml builders_path: stevedore.yaml builders: @@ -235,4 +286,4 @@ push_images: true semantic_version_tags_enabled: true semantic_version_tags_templates: - "{{ .Major }}.{{ .Minor }}.{{ .Patch }}" -``` \ No newline at end of file +``` diff --git a/content/en/docs/getting-started/install.md b/content/en/docs/getting-started/install.md index d9071a1..e8d4987 100644 --- a/content/en/docs/getting-started/install.md +++ b/content/en/docs/getting-started/install.md @@ -8,7 +8,7 @@ description: > Learn about the different methods available to install Stevedore --- -Installing Stevedore is a straightforward process, and you have a few options to choose from. You can install using the provided installation script, which will take care of everything for you. Alternatively, you can download and install from a tarball or install from source if you prefer. This gives you more flexibility and control over the installation process. +Installing Stevedore is a straightforward process, and you have a few options to choose from. You can install using the provided installation script, which will take care of everything for you. Alternatively, you can download and install from a tarball or install from the source if you prefer. This gives you more flexibility and control over the installation process. ## Using the install script @@ -44,13 +44,13 @@ To install Stevedore using a tarball, simply download it directly from GitHub re - Go to the Stevedore Github releases page and download the latest tarball ```sh -curl -fsSLO https://github.com/gostevedore/stevedore/releases/download/v0.11.0/stevedore_v0.11.0_Linux-x86_64.tar.gz +curl -fsSLO https://github.com/gostevedore/stevedore/releases/download/v0.11.2/stevedore_v0.11.2_Linux-x86_64.tar.gz ``` - Extract the contents of the tarball to a directory of your choice ```sh -tar xzfv stevedore_v0.11.0_Linux-x86_64.tar.gz +tar xzfv stevedore_v0.11.2_Linux-x86_64.tar.gz ``` - Add the Stevedore executable to your system path or create a symlink @@ -61,7 +61,7 @@ ln -sf ${PWD}/stevedore /usr/local/bin/stevedore ## Install from source -If you prefer to install Stevedore from source, you can clone the GitHub repository and build it manually. Here are the steps to follow: +If you prefer to install Stevedore from the source, you can clone the GitHub repository and build it manually. Here are the steps to follow: - Clone the Stevedore repository using Git: diff --git a/content/en/docs/getting-started/quickstart.md b/content/en/docs/getting-started/quickstart.md index 69d9943..bd7e089 100644 --- a/content/en/docs/getting-started/quickstart.md +++ b/content/en/docs/getting-started/quickstart.md @@ -13,6 +13,7 @@ description: > ## Installation To install Stevedore, use the script provided on the repository: + ```sh curl -fsSL https://raw.githubusercontent.com/gostevedore/stevedore/main/scripts/install.sh | sudo bash - ``` @@ -20,6 +21,7 @@ curl -fsSL https://raw.githubusercontent.com/gostevedore/stevedore/main/scripts/ Alternatively, you can visit the [installation guide]({{< ref "/docs/getting-started/install">}}) for other methods. ## Initial setup + - Create a folder structure to store image definitions and builder configurations before building Docker images. ```sh @@ -29,10 +31,10 @@ Alternatively, you can visit the [installation guide]({{< ref "/docs/getting-sta - Initialize Stevedore. We create a configuration file for this guide, but it can be also defined on environment variables. + ```sh / $ cd /docker /docker $ stevedore initialize --builders-path builders --credentials-storage-type local --generate-credentials-encryption-key --images-path images --log-path-file /dev/null -2023-02-03 21:57:20 INFO Executing command 'stevedore [COMMAND] [OPTIONS] initialize' ``` After running this command, you can validate the configuration by using the _get configuration_ subcommand. @@ -57,12 +59,14 @@ After running this command, you can validate the configuration by using the _get - Create credentials to log into the Docker registry. Since you create a credential using a username and password, Stevedore prompts you to enter a password for the specified username. + ```sh /docker $ stevedore create credentials registry.stevedore.test --username admin Password: ``` - Validate that the credentials have been stored. + ```sh /docker $ stevedore get credentials ID TYPE CREDENTIALS @@ -70,12 +74,14 @@ registry.stevedore.test username-password username=admin ``` Stevedore's configuration encrypts the credentials content at rest by providing an encryption key. + ```sh /docker $ cat credentials/82e99d42ee1191bb42fbfb444920104d 2d067af765e8de39fd76b5cd1a430768a66464208bf8fe0c092bcb146a24feed377b916952494e6cea55187f397aee8c2d90a55ef9882cf85ee97ed5660700afa002767e028b4ea6bde274a524e7100f5729601f2d44caa08a1a102af7f79079723f35953133be56e31d0eaf44f52255a5c94512c74625dca3f00b77f9031d4f48f5cf38293f7a2a90f727c9a5eedf57e001ea8766a6d1e47d20354ad3ca6cf022ee70b97b3598e7377355a7b52f62fab8b6628b230c33cf0234ea1208c0d6ecef65e8e1206e7daf15acbbfb62d77650982c9f487129534b367a7fc2b519fd04538bffe87e57184adabc57e613be4b0e106480f9078c8c1c916b65de0039a3adc6cea70b962c0d93477e114e25a2a160db0218e9312d0df00d9b1044e0b4981982834094a36d8d9e4fd9ed766605c1a0b43ff11219d6e5bebb414e084102ce8cd57e86a658455de5fff927ba9be039be4afd393b7e8137cdefb268ed7c79ff37a60c1be3693372d7890b9f8f7c81fa559719ff83371e080efaee86b239e127a094136d056641a4a58245f71414b53dd96214149c6f54de055064163fa9dcb0a6b274d9269a49e1e4f76a9c0a89ec12d40c577ea1b5c1b3f9f8454f5473518c58e8c139a96335850a6415df7e2d41f5ab383f85d30281fd29493db0f0fb577aba35326cd5063b463a41161888514dbce09ccea5887494733256d74341e2623a5328c656/docker # ``` ## Build the Docker images for an application + In this section, we create an application that has multiple versions and needs to be built from multiple parents. - Prepare the application. @@ -83,6 +89,7 @@ In this section, we create an application that has multiple versions and needs t First, let's create the application directory and the Dockerfile. Note that we use the Dockerfile arguments `image_from_name` and `image_from_tag`, which are automatically generated by Stevedore to provide information about the parent image. Additionally, any arguments defined in the `vars` or `persistent_vars` attributes of the image definition can be used in the Dockerfile when building the image. + ```sh / $ mkdir -p /apps/my-app / $ cd /apps/my-app @@ -99,6 +106,7 @@ EOF - Define a builder. Next, we need to define the builder for our application. Take into account that to build all the versions in a standardized way we define a single builder, which uses the same Dockerfile. + ```sh / $ cd /docker/builders /docker/builders $ cat << EOF > apps.yaml @@ -112,6 +120,7 @@ EOF ``` To confirm that the builder is already available, use the following command: + ```sh / $ cd /docker /docker $ stevedore get builders @@ -122,6 +131,7 @@ my-apps docker - Define the foundational images, the parent images. Before creating the image definitions for our application, we define the base images that will serve as a starting point for building the Docker images. + ```sh / $ cd /docker/images /docker/images $ cat << EOF > foundational.yaml @@ -145,6 +155,7 @@ Stevedore uses Go's [text/template](https://pkg.go.dev/text/template) package to - Specify the images definitions for the application. In this step, we define two versions of the application `my-app` in the `applications.yaml` file, version `2.1.0` and `3.2.1`. + ```sh /docker/images $ cat << EOF > applications.yaml images: @@ -171,7 +182,8 @@ EOF The _name_ is set to `{{ .Name }}` which will be replaced by the actual name of the image. The _version_ is set to `{{ .Version }}-{{ .Parent.Name }}{{ .Parent.Version }}` which will be replaced by the actual version of the image and its parent name and version. The _builder_ is set to `my-app`, which is the _global-builder_ previously defined in the `/docker/builders/apps.yaml` file. The _parents_ are set to `busybox:1.35` for `2.1.0` version, `busybox:1.35` and `busybox:1.36` for the `3.2.1` version. -You can use the following comand to ensure that images are already defined. +You can use the following command to ensure that images are already defined. + ```sh / $ cd /docker /docker $ stevedore get images --tree @@ -185,6 +197,7 @@ You can use the following comand to ensure that images are already defined. - Build the Docker images. Create all the Docker images for our application at the same time, with just one command. + ```sh /docker $ stevedore build my-app registry.stevedore.test/my-app:3.2.1-busybox1.35 Step 1/7 : ARG image_from_name @@ -257,6 +270,7 @@ registry.stevedore.test/my-app:3.2.1-busybox1.35 Successfully tagged registry.st ``` Validate the recently created images. + ```sh /docker $ docker images REPOSITORY TAG IMAGE ID CREATED SIZE @@ -268,7 +282,9 @@ busybox 1.35 f68fa78323e7 6 weeks ago ``` ## Promote the images to a Docker registry + Now that we already have the images created, and since we did not set the push after the build flag, we promote the images to the Docker registry and push them to the `stable` namespace. + ```sh /docker $ stevedore promote registry.stevedore.test/my-app:3.2.1-busybox1.36 --promote-image-registry-namespace stable registry.stevedore.test/my-app:3.2.1-busybox1.36 ‣ The push refers to repository [registry.stevedore.test/stable/my-app] diff --git a/content/en/docs/reference-guide/builder/ansible-playbook/_index.md b/content/en/docs/reference-guide/builder/ansible-playbook/_index.md index 3ab263f..6417b57 100644 --- a/content/en/docs/reference-guide/builder/ansible-playbook/_index.md +++ b/content/en/docs/reference-guide/builder/ansible-playbook/_index.md @@ -22,8 +22,8 @@ The `ansible-playbook` driver provides to ansible-playbook the variables-mapping |Key name|Description|Default
argument-name|Default
argument-value| |---|---|---|---| |**image_builder_label_key**|This is the argument-name to set the name of the intermediate container that is used to create the Docker image using the ansible-playbook driver|image_builder_label|The argument-value is set as the full qualified name of the image| -|**image_fully_qualified_name**|This is the argument-name that you can use to set the fully-qualified image name of of the image that you are building.
Introduced in v0.11.1. | image_fully_qualified_name |This is the argument-name that provides you with fully-qualified image name. | -|**image_from_fully_qualified_name**|This is the argument-name that you can use to set the fully-qualified name of the base image that you want to use as a starting point for your Docker image.
Introduced in v0.11.1.| image_from_fully_qualified_name |This is the argument-name that provides you with fully-qualified parent image name. | +|**image_fully_qualified_name**|This is the argument-name that you can use to set the fully-qualified image name of of the image that you are building.
Introduced in v0.11.2. | image_fully_qualified_name |This is the argument-name that provides you with fully-qualified image name. | +|**image_from_fully_qualified_name**|This is the argument-name that you can use to set the fully-qualified name of the base image that you want to use as a starting point for your Docker image.
Introduced in v0.11.2.| image_from_fully_qualified_name |This is the argument-name that provides you with fully-qualified parent image name. | |**image_from_name_key**|This is the argument-name to set the name of the parent image from which the new image will be built using the ansible-playbook driver|image_from_name|The argument-value is set as the parent image's name within the [images-tree]({{}})| |**image_from_registry_host_key**|This is the argument-name to set the parent image's registry host when creating a Docker image using the ansible-playbook driver|image_from_registry_host|The argument-value is set as the parent image's registry host within the [images-tree]({{}})| |**image_from_registry_namespace_key**|This is the argument-name to set the parent image's namespace within the registry when creating a Docker image using the ansible-playbook driver|image_from_registry_namespace|The argument-value is set as the parent image's namespace within the [images-tree]({{}})| diff --git a/content/en/docs/reference-guide/builder/docker/_index.md b/content/en/docs/reference-guide/builder/docker/_index.md index e3d9f8d..ec0c2fd 100644 --- a/content/en/docs/reference-guide/builder/docker/_index.md +++ b/content/en/docs/reference-guide/builder/docker/_index.md @@ -103,7 +103,7 @@ Docker driver passes `variables mapping` to Docker API as build arguments and ea |Key name|Description|Default
argument-name|Default
argument-value| |---|---|---|---| -|**image_from_fully_qualified_name**|This is the argument-name that you can use to set the fully-qualified name of the base image that you want to use as a starting point for your Docker image.
Introduced in v0.11.1.| image_from_fully_qualified_name |This is the argument-name that provides you with fully-qualified parent image name. | +|**image_from_fully_qualified_name**|This is the argument-name that you can use to set the fully-qualified name of the base image that you want to use as a starting point for your Docker image.
Introduced in v0.11.2.| image_from_fully_qualified_name |This is the argument-name that provides you with fully-qualified parent image name. | |**image_from_name_key**|This is the argument-name that you can use to set the name of the base image that you want to use as a starting point for your Docker image. | image_from_name | The argument-value is set as the parent image’s name within the [images-tree]({{}}). | |**image_from_registry_host_key**|This is the argument-name that you can use to set the Docker registry host where the base image is located. | image_from_registry_host |The argument-value is set as the parent image’s registry host within the [images-tree]({{}}). | |**image_from_registry_namespace_key**|This is the argument-name that you can use to set the namespace of the Docker registry where the base image is located. | image_from_registry_namespace | The argument-value is set as the parent image’s namespace within the [images-tree]({{}}). |