Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support index manifest to push multi-arch container images #2087

Closed
wants to merge 5 commits into from
Closed
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Add docs for the new container_push_index rule
  • Loading branch information
PingWriter committed Jan 30, 2023
commit 19d30777c526fe9986e1a19b49324beb34537ce0
46 changes: 35 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,13 @@ Generated API documentation is in the docs folder, or you can browse it online a
* [container_load](/docs/container.md#container_load)
* [container_pull](/docs/container.md#container_pull) ([example](#container_pull))
* [container_push](/docs/container.md#container_push) ([example](#container_push))
* [container_push_index](/docs/container.md#container_push_index) ([example](#container_push_index))

These rules used to be `docker_build`, `docker_push`, etc. and the aliases for
these (mostly) legacy names still exist largely for backwards-compatibility. We
also have **early-stage** `oci_image`, `oci_push`, etc. aliases for folks that
enjoy the consistency of a consistent rule prefix. The only place the
format-specific names currently do any more than alias things is in `foo_push`,
where they also specify the appropriate format as which to publish the image.
these (mostly) legacy names still exist largely for backwards-compatibility.
The only place the format-specific names currently do any more than alias things
is in `foo_push`, where they also specify the appropriate format as which
to publish the image.

### Overview

Expand Down Expand Up @@ -283,9 +283,9 @@ to use `container_push` with custom docker authentication credentials.
## Varying image names

A common request from folks using
`container_push`, `container_bundle`, or `container_image` is to
be able to vary the tag that is pushed or embedded. There are two options
at present for doing this.
`container_push`, `container_push_index`, `container_bundle`,
or `container_image` is to be able to vary the tag that is pushed
or embedded. There are two options at present for doing this.

### Stamping

Expand Down Expand Up @@ -329,7 +329,6 @@ A common example is to provide the current git SHA, with

That flag is typically passed in the `.bazelrc` file, see for example [`.bazelrc` in kubernetes](https://github.com/kubernetes/kubernetes/blob/81ce94ae1d8f5d04058eeb214e9af498afe78ff2/build/root/.bazelrc#L6).


### Make variables

The second option is to employ `Makefile`-style variables:
Expand Down Expand Up @@ -1138,13 +1137,14 @@ container_push(
)
```

We also support the `docker_push` (from `docker/docker.bzl`) and `oci_push`
(from `oci/oci.bzl`) aliases, which bake in the `format = "..."` attribute.
We also support the `docker_push` (from `docker/docker.bzl`) aliases,
which bake in the `format = "Docker"` attribute.

See [here](#container_push-custom-client-configuration) for an example of how
to use container_push with custom docker authentication credentials.

### container_push (Custom client configuration)

If you wish to use container_push using custom docker authentication credentials,
in `WORKSPACE`:

Expand Down Expand Up @@ -1185,6 +1185,25 @@ container_push(
)
```

### container_push_index

This target pushes on `bazel run :push_foo_all`:

``` python
container_push_index(
name = "push_foo_all",
images = {
":foo_amd64": "linux/amd64",
":foo_arm64": "linux/arm64/v8",
":foo_ppc64le": "linux/ppc64le",
},
format = "OCI",
registry = "gcr.io",
repository = "my-project/my-image",
tag = "{STABLE_VERSION}",
)
```

### container_pull (DockerHub)

In `WORKSPACE`:
Expand Down Expand Up @@ -1342,6 +1361,11 @@ shared layers and letting them diverge could result in sub-optimal push and pull

**MOVED**: See [docs/container.md](/docs/container.md#container_push)

<a name="container_push_index"></a>
## container_push_index

**MOVED**: See [docs/container.md](/docs/container.md#container_push_index)

<a name="container_layer"></a>
## container_layer

Expand Down
7 changes: 6 additions & 1 deletion container/container.docs.bzl
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,11 @@ load("//container:import.bzl", _container_import = "container_import")
load("//container:layer.bzl", _container_layer = "container_layer_")
load("//container:load.bzl", _container_load = "container_load")
load("//container:pull.bzl", _container_pull = "container_pull")
load("//container:push.bzl", _container_push = "container_push_")
load(
"//container:push.bzl",
_container_push = "container_push_",
_container_push_index = "container_push_index_",
)

# Explicitly re-export the functions
container_bundle = _container_bundle
Expand All @@ -26,4 +30,5 @@ container_layer = _container_layer
container_import = _container_import
container_pull = _container_pull
container_push = _container_push
container_push_index = _container_push_index
container_load = _container_load
55 changes: 55 additions & 0 deletions docs/container.md
Original file line number Diff line number Diff line change
Expand Up @@ -250,6 +250,61 @@ container_push(<a href="#container_push-name">name</a>, <a href="#container_push
| <a id="container_push-windows_paths"></a>windows_paths | - | Boolean | required | |


<a id="#container_push_index"></a>

## container_push_index

<pre>
container_push_index(<a href="#container_push_index-name">name</a>, <a href="#container_push_index-extension">extension</a>, <a href="#container_push_index-extract_config">extract_config</a>, <a href="#container_push_index-format">format</a>, <a href="#container_push_index-images">images</a>, <a href="#container_push_index-incremental_load_template">incremental_load_template</a>,
<a href="#container_push_index-insecure_repository">insecure_repository</a>, <a href="#container_push_index-registry">registry</a>, <a href="#container_push_index-repository">repository</a>, <a href="#container_push_index-repository_file">repository_file</a>,
<a href="#container_push_index-skip_unchanged_digest">skip_unchanged_digest</a>, <a href="#container_push_index-stamp">stamp</a>, <a href="#container_push_index-tag">tag</a>, <a href="#container_push_index-tag_file">tag_file</a>, <a href="#container_push_index-tag_tpl">tag_tpl</a>, <a href="#container_push_index-windows_paths">windows_paths</a>)
</pre>

Push a docker image for multiple platforms.

This rule will push all given image manifests, and then the manifest list,
aka the _fat manifest_, with the definition of all image platforms.

An image platforms must follow the format: `[<os>/][<arch>][/<variant>]`.

Example of the `images` attribute value:

```json
{
":my_image_amd64": "linux/amd64",
":my_image_arm64": "linux/arm64/v8",
":my_image_ppc64le": "linux/ppc64le",
}
```

- if `<os>` is missing, `linux` will be used.
- if `<arch>` is missing, `amd64` will be used.
- `<variant>` cannot be specified without `<os>` and `<arch>`.


**ATTRIBUTES**


| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="container_push_index-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <a id="container_push_index-extension"></a>extension | The file extension for the push script. | String | optional | "" |
| <a id="container_push_index-extract_config"></a>extract_config | - | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //container/go/cmd/extract_config:extract_config |
| <a id="container_push_index-format"></a>format | The form to push: Docker or OCI, default to 'Docker'. | String | required | |
| <a id="container_push_index-images"></a>images | The list of all images to push.<br><br> The value of each entries is the platform of the container image. | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: Label -> String</a> | required | |
| <a id="container_push_index-incremental_load_template"></a>incremental_load_template | - | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //container:incremental_load_template |
| <a id="container_push_index-insecure_repository"></a>insecure_repository | Whether the repository is insecure or not (http vs https) | Boolean | optional | False |
| <a id="container_push_index-registry"></a>registry | The registry to which we are pushing. | String | required | |
| <a id="container_push_index-repository"></a>repository | The name of the image. | String | required | |
| <a id="container_push_index-repository_file"></a>repository_file | The label of the file with repository value. Overrides 'repository'. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="container_push_index-skip_unchanged_digest"></a>skip_unchanged_digest | Check if the container registry already contain the image's digest. If yes, skip the push for that image. Default to False. Note that there is no transactional guarantee between checking for digest existence and pushing the digest. This means that you should try to avoid running the same container_push targets in parallel. | Boolean | optional | False |
| <a id="container_push_index-stamp"></a>stamp | Whether to encode build information into the output. Possible values:<br><br> - <code>@io_bazel_rules_docker//stamp:always</code>: Always stamp the build information into the output, even in [--nostamp][stamp] builds. This setting should be avoided, since it potentially causes cache misses remote caching for any downstream actions that depend on it.<br><br> - <code>@io_bazel_rules_docker//stamp:never</code>: Always replace build information by constant values. This gives good build result caching.<br><br> - <code>@io_bazel_rules_docker//stamp:use_stamp_flag</code>: Embedding of build information is controlled by the [--[no]stamp][stamp] flag. Stamped binaries are not rebuilt unless their dependencies change.<br><br> [stamp]: https://docs.bazel.build/versions/main/user-manual.html#flag--stamp | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | @io_bazel_rules_docker//stamp:use_stamp_flag |
| <a id="container_push_index-tag"></a>tag | The tag of the image. | String | optional | "latest" |
| <a id="container_push_index-tag_file"></a>tag_file | The label of the file with tag value. Overrides 'tag'. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="container_push_index-tag_tpl"></a>tag_tpl | The script template to use. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required | |
| <a id="container_push_index-windows_paths"></a>windows_paths | - | Boolean | required | |


<a id="#container_image"></a>

## container_image
Expand Down