Skip to content

Commit

Permalink
update readme (#599)
Browse files Browse the repository at this point in the history 
fix #597
fix #598
provide docs for recommended fix for #317
Improve documentation for xx_image rules to make more explicit that args such as env and symlinks will never be added to xx_image and container_image must be used in conjunction with xx_image for these use cases.
  • Loading branch information
@nlopezgi
nlopezgi authored Dec 4, 2018
1 parent 8d7fd07 commit ebb6ac7
Show file tree
Hide file tree
Showing 2 changed files with 128 additions and 9 deletions.
135 changes: 127 additions & 8 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,23 +77,39 @@ https://github.com/googlecloudplatform/distroless) language runtimes, but these
can be overridden via the `base="..."` attribute (e.g. with a `container_pull`
or `container_image` target).

Note also that these rules do not expose any docker related attributes. If you
need to add a custom `env` or `symlink` to a `lang_image`, you must use
`container_image` targets for this purpose. Specifically, you can use as base for your
`lang_image` target a `container_image` target that adds e.g., custom `env` or `symlink`.
Please see <a href=#go_image-custom-base>go_image (custom base)</a> for an example.

## Setup

Note: we're improving how `rules_docker` uses toolchains and will have a new release
soon. Instructions below are for the latest commit, if you want to use the
latest release (0.5.1) please use the README version at that release.
See <a href="toolchains/docker/readme.md">Docker Toolchains docs</a>
for details about ongoing toolchains work.

Add the following to your `WORKSPACE` file to add the external repositories:

```python
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
name = "io_bazel_rules_docker",
sha256 = "29d109605e0d6f9c892584f07275b8c9260803bf0c6fcb7de2623b2bedc910bd",
strip_prefix = "rules_docker-0.5.1",
urls = ["https://github.com/bazelbuild/rules_docker/archive/v0.5.1.tar.gz"],
sha256 = "{sha for latest commit, remove this attr and bazel will print it out as part of the build}",
strip_prefix = "rules_docker-{latest commit}",
urls = ["https://github.com/bazelbuild/rules_docker/archive/{latest commit}.tar.gz"],
)

# Call this to override the default docker toolchain configuration. This call
# should be placed BEFORE the call to "container_repositories" below to actually
# override the default toolchain configuration
# OPTIONAL: Include these lines to override the default docker toolchain
# configuration.
# This call should be placed BEFORE the call to "container_repositories"
# below to actually override the default toolchain configuration.
# Note this is only required if you actually want to call
# docker_toolchain_configure with a custom attr; please read the toolchains
# docs in /toolchains/docker/ before blindly adding this to your WORKSPACE.
load("@io_bazel_rules_docker//toolchains/docker:toolchain.bzl",
docker_toolchain_configure="toolchain_configure"
)
Expand All @@ -118,6 +134,15 @@ container_pull(
)
```

Note: Bazel does not deal well with diamond dependencies. If the repositories that
are imported by `container_repositories()` have already been imported (at a
different version) by other rules you called in your `WORKSPACE`, which are
placed above the call to `container_repositories()`, arbitrary errors might
ocurr. If you get errors related to external repositories, you will likely
not be able to use `container_repositories()` and will have to import
directly in your `WORKSPACE` all the required dependencies (see the most up
to date impl of `container_repositories()` for details).

## Using with Docker locally.

Suppose you have a `container_image` target `//my/image:helloworld`:
Expand All @@ -138,9 +163,9 @@ this behavior by passing the single flag: `bazel run :foo -- --norun`

Alternatively, you can build a `docker load` compatible bundle with:
`bazel build my/image:helloworld.tar`. This will produce the file:
`bazel-genfiles/my/image/helloworld.tar`, which you can load into
`bazel-bin/my/image/helloworld.tar`, which you can load into
your local Docker client by running:
`docker load -i bazel-genfiles/my/image/helloworld.tar`. Building
`docker load -i bazel-bin/my/image/helloworld.tar`. Building
this target can be expensive for large images.

These work with both `container_image`, `container_bundle`, and the
Expand Down Expand Up @@ -275,6 +300,16 @@ container_image(
)
```

Hint: if you want to put files in specific directories inside the image
use <a href="https://docs.bazel.build/versions/master/be/pkg.html">`pkg_tar` rule</a>
to create the desired directory structure and pass that to `container_image` via
`tars` attribute. Note you might need to set `strip_prefix = "."` or `strip_prefix = "{some directory}"`
in your rule for the files to not be flattened.
See <a href="https://github.com/bazelbuild/bazel/issues/2176">Bazel upstream issue 2176</a> and
<a href="https://github.com/bazelbuild/rules_docker/issues/317">rules_docker issue 317</a>
for more details.


### cc_image

To use `cc_image`, add the following to `WORKSPACE`:
Expand Down Expand Up @@ -320,6 +355,11 @@ cc_image(
)
```

If you need to modify somehow the container produced by
`cc_image` (e.g., `env`, `symlink`), see note above in
<a href=#overview-1>Language Rules Overview</a> about how to do this
and see <a href=#go_image-custom-base>go_image (custom base)</a> example below.

### py_image

To use `py_image`, add the following to `WORKSPACE`:
Expand All @@ -346,6 +386,11 @@ py_image(
)
```

If you need to modify somehow the container produced by
`py_image` (e.g., `env`, `symlink`), see note above in
<a href=#overview-1>Language Rules Overview</a> about how to do this
and see <a href=#go_image-custom-base>go_image (custom base)</a> example below.

### py_image (fine layering)

For Python and Java's `lang_image` rules, you can factor
Expand Down Expand Up @@ -418,6 +463,11 @@ py_image(
To use a Python 3 runtime instead of the default of Python 2, use `py3_image`,
instead of `py_image`. The other semantics are identical.

If you need to modify somehow the container produced by
`py3_image` (e.g., `env`, `symlink`), see note above in
<a href=#overview-1>Language Rules Overview</a> about how to do this
and see <a href=#go_image-custom-base>go_image (custom base)</a> example below.

### nodejs_image

**It is notable that unlike the other image rules, `nodejs_image` is not
Expand Down Expand Up @@ -459,6 +509,10 @@ load(
_nodejs_image_repos()
```

Note: See note about diamond dependencies in <a href=#setup>setup</a>
if you run into issues related to external repos after adding these
lines to your `WORKSPACE`.

Then in your `BUILD` file, simply rewrite `nodejs_binary` to `nodejs_image` with
the following import:
```python
Expand All @@ -474,6 +528,11 @@ nodejs_image(
)
```

If you need to modify somehow the container produced by
`nodejs_image` (e.g., `env`, `symlink`), see note above in
<a href=#overview-1>Language Rules Overview</a> about how to do this
and see <a href=#go_image-custom-base>go_image (custom base)</a> example below.

### go_image

To use `go_image`, add the following to `WORKSPACE`:
Expand All @@ -499,6 +558,10 @@ load(
_go_image_repos()
```

Note: See note about diamond dependencies in <a href=#setup>setup</a>
if you run into issues related to external repos after adding these
lines to your `WORKSPACE`.

Then in your `BUILD` file, simply rewrite `go_binary` to `go_image` with the
following import:
```python
Expand All @@ -513,9 +576,15 @@ go_image(
pure = "on",
)
```

Notice that it is important to explicitly specify `goarch`, `goos`, and `pure`
as the binary should be built for Linux since it will run on a Linux container.

If you need to modify somehow the container produced by
`go_image` (e.g., `env`, `symlink`), see note above in
<a href=#overview-1>Language Rules Overview</a> about how to do this and
see example below.

### go_image (custom base)

To use a custom base image, with any of the `lang_image`
Expand Down Expand Up @@ -600,6 +669,11 @@ java_image(
)
```

If you need to modify somehow the container produced by
`java_image` (e.g., `env`, `symlink`), see note above in
<a href=#overview-1>Language Rules Overview</a> about how to do this
and see <a href=#go_image-custom-base>go_image (custom base)</a> example.

### war_image

To use `war_image`, add the following to `WORKSPACE`:
Expand All @@ -613,6 +687,10 @@ load(
_java_image_repos()
```

Note: See note about diamond dependencies in <a href=#setup>setup</a>
if you run into issues related to external repos after adding these
lines to your `WORKSPACE`.

Then in your `BUILD` file, simply rewrite `java_war` to `war_image` with the
following import:
```python
Expand All @@ -629,6 +707,11 @@ war_image(
)
```

If you need to modify somehow the container produced by
`war_image` (e.g., `env`, `symlink`), see note above in
<a href=#overview-1>Language Rules Overview</a> about how to do this
and see <a href=#go_image-custom-base>go_image (custom base)</a> example.

### scala_image

To use `scala_image`, add the following to `WORKSPACE`:
Expand Down Expand Up @@ -658,6 +741,10 @@ load(
_scala_image_repos()
```

Note: See note about diamond dependencies in <a href=#setup>setup</a>
if you run into issues related to external repos after adding these
lines to your `WORKSPACE`.

Then in your `BUILD` file, simply rewrite `scala_binary` to `scala_image` with the
following import:
```python
Expand All @@ -670,6 +757,11 @@ scala_image(
)
```

If you need to modify somehow the container produced by
`scala_image` (e.g., `env`, `symlink`), see note above in
<a href=#overview-1>Language Rules Overview</a> about how to do this
and see <a href=#go_image-custom-base>go_image (custom base)</a> example.

### groovy_image

To use `groovy_image`, add the following to `WORKSPACE`:
Expand Down Expand Up @@ -699,6 +791,10 @@ load(
_groovy_image_repos()
```

Note: See note about diamond dependencies in <a href=#setup>setup</a>
if you run into issues related to external repos after adding these
lines to your `WORKSPACE`.

Then in your `BUILD` file, simply rewrite `groovy_binary` to `groovy_image` with the
following import:
```python
Expand All @@ -711,6 +807,11 @@ groovy_image(
)
```

If you need to modify somehow the container produced by
`groovy_image` (e.g., `env`, `symlink`), see note above in
<a href=#overview-1>Language Rules Overview</a> about how to do this
and see <a href=#go_image-custom-base>go_image (custom base)</a> example.

### rust_image

To use `rust_image`, add the following to `WORKSPACE`:
Expand Down Expand Up @@ -740,6 +841,10 @@ load(
_rust_image_repos()
```

Note: See note about diamond dependencies in <a href=#setup>setup</a>
if you run into issues related to external repos after adding these
lines to your `WORKSPACE`.

Then in your `BUILD` file, simply rewrite `rust_binary` to `rust_image` with the
following import:
```python
Expand All @@ -751,6 +856,11 @@ rust_image(
)
```

If you need to modify somehow the container produced by
`rust_image` (e.g., `env`, `symlink`), see note above in
<a href=#overview-1>Language Rules Overview</a> about how to do this
and see <a href=#go_image-custom-base>go_image (custom base)</a> example.

### d_image

To use `d_image`, add the following to `WORKSPACE`:
Expand Down Expand Up @@ -780,6 +890,10 @@ load(
_d_image_repos()
```

Note: See note about diamond dependencies in <a href=#setup>setup</a>
if you run into issues related to external repos after adding these
lines to your `WORKSPACE`.

Then in your `BUILD` file, simply rewrite `d_binary` to `d_image` with the
following import:
```python
Expand All @@ -791,6 +905,11 @@ d_image(
)
```

If you need to modify somehow the container produced by
`d_image` (e.g., `env`, `symlink`), see note above in
<a href=#overview-1>Language Rules Overview</a> about how to do this
and see <a href=#go_image-custom-base>go_image (custom base)</a> example.

> NOTE: all application image rules support the `args` string_list
> attribute. If specified, they will be appended directly after the
> container ENTRYPOINT binary name.
Expand Down
2 changes: 1 addition & 1 deletion container/container.bzl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,7 @@ py_library(
if "bazel_skylib" not in excludes:
http_archive(
name = "bazel_skylib",
#sha256 = "eb5c57e4c12e68c0c20bc774bfbc60a568e800d025557bc4ea022c6479acc867",
sha256 = "eb5c57e4c12e68c0c20bc774bfbc60a568e800d025557bc4ea022c6479acc867",
strip_prefix = "bazel-skylib-0.6.0",
urls = ["https://github.com/bazelbuild/bazel-skylib/archive/0.6.0.tar.gz"],
)
Expand Down

0 comments on commit ebb6ac7

Please # to comment.