This repository has been archived by the owner on Mar 31, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 491
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Put README content on authentication and goal into separate docs
Add docs on build phase configs
- Loading branch information
Showing
3 changed files
with
149 additions
and
126 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,102 @@ | ||
| # Authentication | ||
|
|
||
| ## Authentication and private Docker registry support | ||
|
|
||
| Since version 1.3.0, the plugin will automatically use any configuration in | ||
| your `~/.dockercfg` or `~/.docker/config.json` file when pulling, pushing, or | ||
| building images to private registries. | ||
|
|
||
| Additionally the plugin will enable support for Google Container Registry if it | ||
| is able to successfully load [Google's "Application Default Credentials"][ADC]. | ||
| The plugin will also load Google credentials from the file pointed to by the | ||
| environment variable `DOCKER_GOOGLE_CREDENTIALS` if it is defined. Since GCR | ||
| authentication requires retrieving short-lived access codes for the given | ||
| credentials, support for this registry is baked into the underlying | ||
| docker-client rather than having to first populate the docker config file | ||
| before running the plugin. | ||
|
|
||
| [ADC]: https://developers.google.com/identity/protocols/application-default-credentials | ||
|
|
||
| GCR users may need to initialize their Application Default Credentials via `gcloud`. | ||
| Depending on where the plugin will run, they may wish to use [their Google | ||
| identity][app-def-login] by running the following command | ||
|
|
||
| gcloud auth application-default login | ||
|
|
||
| or [create a service account][service-acct] instead. | ||
|
|
||
| [app-def-login]: https://cloud.google.com/sdk/gcloud/reference/auth/application-default/login | ||
| [service-acct]: https://cloud.google.com/docs/authentication/getting-started#creating_a_service_account | ||
|
|
||
| ## Authenticating with maven settings.xml | ||
|
|
||
| Since version 1.3.6, you can authenticate using your maven settings.xml instead | ||
| of docker configuration. Just add configuration similar to: | ||
|
|
||
| ```xml | ||
| <configuration> | ||
| <repository>docker-repo.example.com:8080/organization/image</repository> | ||
| <tag>latest</tag> | ||
| <useMavenSettingsForAuth>true</useMavenSettingsForAuth> | ||
| </configuration> | ||
| ``` | ||
|
|
||
| You can also use `-Ddockerfile.useMavenSettingsForAuth=true` on the command line. | ||
|
|
||
| Then, in your maven settings file, add configuration for the server: | ||
|
|
||
| ```xml | ||
| <servers> | ||
| <server> | ||
| <id>docker-repo.example.com:8080</id> | ||
| <username>me</username> | ||
| <password>mypassword</password> | ||
| </server> | ||
| </servers> | ||
| ``` | ||
|
|
||
| exactly as you would for any other server configuration. | ||
|
|
||
| Since version 1.4.3, using an encrypted password in the Maven settings file is supported. For more | ||
| information about encrypting server passwords in `settings.xml`, | ||
| [read the documentation here](https://maven.apache.org/guides/mini/guide-encryption.html). | ||
|
|
||
| ## Authenticating with maven pom.xml | ||
|
|
||
| Since version 1.3.XX, you can authenticate using config from the pom itself. | ||
| Just add configuration similar to: | ||
|
|
||
| ```xml | ||
| <plugin> | ||
| <groupId>com.spotify</groupId> | ||
| <artifactId>dockerfile-maven-plugin</artifactId> | ||
| <version>${version}</version> | ||
| <configuration> | ||
| <username>repoUserName</username> | ||
| <password>repoPassword</password> | ||
| <repository>${docker.image.prefix}/${project.artifactId}</repository> | ||
| <buildArgs> | ||
| <JAR_FILE>target/${project.build.finalName}.jar</JAR_FILE> | ||
| </buildArgs> | ||
| </configuration> | ||
| </plugin> | ||
| ``` | ||
| or simpler, | ||
| ```xml | ||
| <plugin> | ||
| <groupId>com.spotify</groupId> | ||
| <artifactId>dockerfile-maven-plugin</artifactId> | ||
| <version>${version}</version> | ||
| <configuration> | ||
| <repository>${docker.image.prefix}/${project.artifactId}</repository> | ||
| <buildArgs> | ||
| <JAR_FILE>target/${project.build.finalName}.jar</JAR_FILE> | ||
| </buildArgs> | ||
| </configuration> | ||
| </plugin> | ||
| ``` | ||
|
|
||
| with this command line call | ||
|
|
||
| mvn goal -Ddockerfile.username=... -Ddockerfile.password=... | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| # Usage | ||
|
|
||
| ## Maven Goals | ||
|
|
||
| Goals available for this plugin: | ||
|
|
||
| | Goal | Description | Default Phase | | ||
| | ---- | -------------- | ------------- | | ||
| | `dockerfile:build` | Builds a Docker image from a Dockerfile. | package | | ||
| | `dockerfile:tag` | Tags a Docker image. | package | | ||
| | `dockerfile:push` | Pushes a Docker image to a repository. | deploy | | ||
|
|
||
| ### Skip Docker Goals Bound to Maven Phases | ||
|
|
||
| You can pass options to maven to disable the docker goals. | ||
|
|
||
| | Maven Option | What Does it Do? | Default Value | | ||
| | ------------- | -------------------------- | ------------- | | ||
| | `dockerfile.skip` | Disables the entire dockerfile plugin; all goals become no-ops. | false | | ||
| | `dockerfile.build.skip` | Disables the build goal; it becomes a no-op. | false | | ||
| | `dockerfile.tag.skip` | Disables the tag goal; it becomes a no-op. | false | | ||
| | `dockerfile.push.skip` | Disables the push goal; it becomes a no-op. | false | | ||
|
|
||
| For example, to skip the entire dockerfile plugin: | ||
| ``` | ||
| mvn clean package -Ddockerfile.skip | ||
| ``` | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Build Phase | ||
|
|
||
| | Maven Option | What Does it Do? | Required | Default Value | | ||
| | ------------- | -------------------------- | -------- | ------------- | | ||
| | `dockerfile.contextDirectory` | Directory containing the Dockerfile to build. | yes | none | | ||
| | `dockerfile.repository` | The repository to name the built image | no | none | | ||
| | `dockerfile.tag` | The tag to apply when building the Dockerfile, which is appended to the repository. | no | latest | | ||
| | `dockerfile.build.pullNewerImage` | Updates base images automatically. | no | true | | ||
| | `dockerfile.build.noCache` | Do not use cache when building the image. | no | false | | ||
| | `dockerfile.buildArgs` | Custom build arguments. | no | none | |