From 859b8ffd808026bd3d0c645d28bf05b366439be8 Mon Sep 17 00:00:00 2001 From: Greg Magolan Date: Sun, 13 Oct 2024 11:49:06 -0700 Subject: [PATCH] chore: bump to stardoc 0.6.2 (#719) --- MODULE.bazel | 1 + WORKSPACE | 27 ++++++++++++++++++++----- docs/image.md | 49 +++++++++++++++++++++------------------------ docs/image_index.md | 1 - docs/load.md | 12 +++++------ docs/pull.md | 29 +++++++++++++-------------- docs/push.md | 19 ++++++++---------- internal_deps.bzl | 7 ++----- 8 files changed, 75 insertions(+), 70 deletions(-) diff --git a/MODULE.bazel b/MODULE.bazel index 37eba0dc..5b906517 100644 --- a/MODULE.bazel +++ b/MODULE.bazel @@ -35,3 +35,4 @@ bazel_dep(name = "rules_go", version = "0.46.0", dev_dependency = True, repo_nam bazel_dep(name = "gazelle", version = "0.35.0", dev_dependency = True, repo_name = "bazel_gazelle") bazel_dep(name = "bazel_skylib_gazelle_plugin", version = "1.4.1", dev_dependency = True) bazel_dep(name = "rules_multirun", version = "0.9.0", dev_dependency = True) +bazel_dep(name = "stardoc", version = "0.6.2", dev_dependency = True, repo_name = "io_bazel_stardoc") diff --git a/WORKSPACE b/WORKSPACE index 8708aa9d..abfbd520 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -7,11 +7,6 @@ load(":internal_deps.bzl", "rules_oci_internal_deps") rules_oci_internal_deps() -## Stardoc -load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories") - -stardoc_repositories() - ## Setup rules_oci load("//oci:dependencies.bzl", "rules_oci_dependencies") @@ -61,3 +56,25 @@ load(":fetch.bzl", "fetch_images", "fetch_test_repos") fetch_images() fetch_test_repos() + +############################################ +# Stardoc +load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories") + +stardoc_repositories() + +load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps") + +rules_jvm_external_deps() + +load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup") + +rules_jvm_external_setup() + +load("@io_bazel_stardoc//:deps.bzl", "stardoc_external_deps") + +stardoc_external_deps() + +load("@stardoc_maven//:defs.bzl", stardoc_pinned_maven_install = "pinned_maven_install") + +stardoc_pinned_maven_install() diff --git a/docs/image.md b/docs/image.md index 9b7a03c3..662d4960 100644 --- a/docs/image.md +++ b/docs/image.md @@ -1,13 +1,11 @@ - To load these rules, add this to the top of your `BUILD` file: ```starlark load("@rules_oci//oci:defs.bzl", ...) ``` - ## oci_image_rule @@ -64,28 +62,27 @@ oci_image( ) ``` - **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | -| annotations | A file containing a dictionary of annotations. Each line should be in the form name=value. | Label | optional | None | -| architecture | The CPU architecture which the binaries in this image are built to run on. eg: arm64, arm, amd64, s390x. See $GOARCH documentation for possible values: https://go.dev/doc/install/source#environment | String | optional | "" | -| base | Label to an oci_image target to use as the base. | Label | optional | None | -| cmd | A file containing a newline separated list to be used as the command & args of the container. These values act as defaults and may be replaced by any specified when creating a container. | Label | optional | None | -| entrypoint | A file containing a newline separated list to be used as the entrypoint to execute when the container starts. These values act as defaults and may be replaced by an entrypoint specified when creating a container. NOTE: Setting this attribute will reset the cmd attribute | Label | optional | None | -| env | A file containing the default values for the environment variables of the container. These values act as defaults and are merged with any specified when creating a container. Entries replace the base environment variables if any of the entries has conflicting keys. To merge entries with keys specified in the base, ${KEY} or $KEY syntax may be used. | Label | optional | None | -| exposed_ports | A file containing a comma separated list of exposed ports. (e.g. 2000/tcp, 3000/udp or 4000. No protocol defaults to tcp). | Label | optional | None | -| labels | A file containing a dictionary of labels. Each line should be in the form name=value. | Label | optional | None | -| os | The name of the operating system which the image is built to run on. eg: linux, windows. See $GOOS documentation for possible values: https://go.dev/doc/install/source#environment | String | optional | "" | -| resource_set | A predefined function used as the resource_set for actions.

Used with --experimental_action_resource_set to reserve more RAM/CPU, preventing Bazel overscheduling resource-intensive actions.

By default, Bazel allocates 1 CPU and 250M of RAM. https://github.com/bazelbuild/bazel/blob/058f943037e21710837eda9ca2f85b5f8538c8c5/src/main/java/com/google/devtools/build/lib/actions/AbstractAction.java#L77 | String | optional | "default" | -| tars | List of tar files to add to the image as layers. Do not sort this list; the order is preserved in the resulting image. Less-frequently changed files belong in lower layers to reduce the network bandwidth required to pull and push.

The authors recommend [dive](https://github.com/wagoodman/dive) to explore the layering of the resulting image. | List of labels | optional | [] | -| user | The username or UID which is a platform-specific structure that allows specific control over which user the process run as. This acts as a default value to use when the value is not specified when creating a container. For Linux based systems, all of the following are valid: user, uid, user:group, uid:gid, uid:group, user:gid. If group/gid is not specified, the default group and supplementary groups of the given user/uid in /etc/passwd from the container are applied. | String | optional | "" | -| variant | The variant of the specified CPU architecture. eg: v6, v7, v8. See: https://github.com/opencontainers/image-spec/blob/main/image-index.md#platform-variants for more. | String | optional | "" | -| volumes | A file containing a comma separated list of volumes. (e.g. /srv/data,/srv/other-data) | Label | optional | None | -| workdir | Sets the current working directory of the entrypoint process in the container. This value acts as a default and may be replaced by a working directory specified when creating a container. | String | optional | "" | +| annotations | A file containing a dictionary of annotations. Each line should be in the form `name=value`. | Label | optional | `None` | +| architecture | The CPU architecture which the binaries in this image are built to run on. eg: `arm64`, `arm`, `amd64`, `s390x`. See $GOARCH documentation for possible values: https://go.dev/doc/install/source#environment | String | optional | `""` | +| base | Label to an oci_image target to use as the base. | Label | optional | `None` | +| cmd | A file containing a newline separated list to be used as the `command & args` of the container. These values act as defaults and may be replaced by any specified when creating a container. | Label | optional | `None` | +| entrypoint | A file containing a newline separated list to be used as the `entrypoint` to execute when the container starts. These values act as defaults and may be replaced by an entrypoint specified when creating a container. NOTE: Setting this attribute will reset the `cmd` attribute | Label | optional | `None` | +| env | A file containing the default values for the environment variables of the container. These values act as defaults and are merged with any specified when creating a container. Entries replace the base environment variables if any of the entries has conflicting keys. To merge entries with keys specified in the base, `${KEY}` or `$KEY` syntax may be used. | Label | optional | `None` | +| exposed_ports | A file containing a comma separated list of exposed ports. (e.g. 2000/tcp, 3000/udp or 4000. No protocol defaults to tcp). | Label | optional | `None` | +| labels | A file containing a dictionary of labels. Each line should be in the form `name=value`. | Label | optional | `None` | +| os | The name of the operating system which the image is built to run on. eg: `linux`, `windows`. See $GOOS documentation for possible values: https://go.dev/doc/install/source#environment | String | optional | `""` | +| resource_set | A predefined function used as the resource_set for actions.

Used with --experimental_action_resource_set to reserve more RAM/CPU, preventing Bazel overscheduling resource-intensive actions.

By default, Bazel allocates 1 CPU and 250M of RAM. https://github.com/bazelbuild/bazel/blob/058f943037e21710837eda9ca2f85b5f8538c8c5/src/main/java/com/google/devtools/build/lib/actions/AbstractAction.java#L77 | String | optional | `"default"` | +| tars | List of tar files to add to the image as layers. Do not sort this list; the order is preserved in the resulting image. Less-frequently changed files belong in lower layers to reduce the network bandwidth required to pull and push.

The authors recommend [dive](https://github.com/wagoodman/dive) to explore the layering of the resulting image. | List of labels | optional | `[]` | +| user | The `username` or `UID` which is a platform-specific structure that allows specific control over which user the process run as. This acts as a default value to use when the value is not specified when creating a container. For Linux based systems, all of the following are valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. If `group/gid` is not specified, the default group and supplementary groups of the given `user/uid` in `/etc/passwd` from the container are applied. | String | optional | `""` | +| variant | The variant of the specified CPU architecture. eg: `v6`, `v7`, `v8`. See: https://github.com/opencontainers/image-spec/blob/main/image-index.md#platform-variants for more. | String | optional | `""` | +| volumes | A file containing a comma separated list of volumes. (e.g. /srv/data,/srv/other-data) | Label | optional | `None` | +| workdir | Sets the current working directory of the `entrypoint` process in the container. This value acts as a default and may be replaced by a working directory specified when creating a container. | String | optional | `""` | @@ -101,7 +98,7 @@ Macro wrapper around [oci_image_rule](#oci_image_rule). Allows labels and annotations to be provided as a dictionary, in addition to a text file. See https://github.com/opencontainers/image-spec/blob/main/annotations.md -Label/annotation/env can by configured using either dict(key->value) or a file that contains key=value pairs +Label/annotation/env can by configured using either dict(key->value) or a file that contains key=value pairs (one per line). The file can be preprocessed using (e.g. using `jq`) to supply external (potentially not deterministic) information when running with `--stamp` flag. See the example in [/examples/labels/BUILD.bazel](https://github.com/bazel-contrib/rules_oci/blob/main/examples/labels/BUILD.bazel). @@ -116,13 +113,13 @@ This is similar to the same-named target created by rules_docker's `container_im | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | name of resulting oci_image_rule | none | -| labels | Labels for the image config. See documentation above. | None | -| annotations | Annotations for the image config. See documentation above. | None | -| env | Environment variables provisioned by default to the running container. See documentation above. | None | -| cmd | Command & argument configured by default in the running container. See documentation above. | None | -| entrypoint | Entrypoint configured by default in the running container. See documentation above. | None | -| exposed_ports | Exposed ports in the running container. See documentation above. | None | -| volumes | Volumes for the container. See documentation above. | None | +| labels | Labels for the image config. See documentation above. | `None` | +| annotations | Annotations for the image config. See documentation above. | `None` | +| env | Environment variables provisioned by default to the running container. See documentation above. | `None` | +| cmd | Command & argument configured by default in the running container. See documentation above. | `None` | +| entrypoint | Entrypoint configured by default in the running container. See documentation above. | `None` | +| exposed_ports | Exposed ports in the running container. See documentation above. | `None` | +| volumes | Volumes for the container. See documentation above. | `None` | | kwargs | other named arguments to [oci_image_rule](#oci_image_rule) and [common rule attributes](https://bazel.build/reference/be/common-definitions#common-attributes). | none | diff --git a/docs/image_index.md b/docs/image_index.md index d4bc3dc9..df5c9c41 100644 --- a/docs/image_index.md +++ b/docs/image_index.md @@ -34,7 +34,6 @@ oci_image_index( ) ``` - **ATTRIBUTES** diff --git a/docs/load.md b/docs/load.md index 447978f9..6c2544bb 100644 --- a/docs/load.md +++ b/docs/load.md @@ -20,7 +20,6 @@ bazel run :load docker run --rm my-repository:latest ``` - ## oci_load @@ -59,9 +58,9 @@ filegroup( ### When using `format = "oci"` -When using format = oci, containerd image store needs to be enabled in order for the oci style tarballs to work. +When using format = oci, containerd image store needs to be enabled in order for the oci style tarballs to work. -On docker desktop this can be enabled by visiting `Settings (cog icon) -> Features in development -> Use containerd for pulling and storing images` +On docker desktop this can be enabled by visiting `Settings (cog icon) -> Features in development -> Use containerd for pulling and storing images` For more information, see https://docs.docker.com/desktop/containerd/ @@ -96,16 +95,15 @@ multirun( [rules_multirun]: https://github.com/keith/rules_multirun - **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | -| format | Format of image to generate. Options are: docker, oci. Currently, when the input image is an image_index, only oci is supported, and when the input image is an image, only docker is supported. Conversions between formats may be supported in the future. | String | optional | "docker" | -| image | Label of a directory containing an OCI layout, typically oci_image | Label | required | | -| loader | Alternative target for a container cli tool that will be used to load the image into the local engine when using bazel run on this target.

By default, we look for docker or podman on the PATH, and run the load command.

See the _run_template attribute for the script that calls this loader tool. | Label | optional | None | +| format | Format of image to generate. Options are: docker, oci. Currently, when the input image is an image_index, only oci is supported, and when the input image is an image, only docker is supported. Conversions between formats may be supported in the future. | String | optional | `"docker"` | +| image | Label of a directory containing an OCI layout, typically `oci_image` | Label | required | | +| loader | Alternative target for a container cli tool that will be used to load the image into the local engine when using `bazel run` on this target.

By default, we look for `docker` or `podman` on the PATH, and run the `load` command.

See the _run_template attribute for the script that calls this loader tool. | Label | optional | `None` | | repo_tags | a file containing repo_tags, one per line. | Label | required | | diff --git a/docs/pull.md b/docs/pull.md index 4c8a80df..7b513d4a 100644 --- a/docs/pull.md +++ b/docs/pull.md @@ -81,7 +81,7 @@ oci_image( ## Configuration Docker specifies a standard location where registry credentials are stored: -<https://docs.docker.com/engine/reference/commandline/cli/#configuration-files> + We search for this file in several locations, following the logic at https://github.com/google/go-containerregistry/tree/main/pkg/authn#tldr-for-consumers-of-this-package. @@ -115,7 +115,7 @@ common --credential_helper=public.ecr.aws=%workspace%/tools/auth.sh tools/auth.sh ```bash input=$(cat) -uri=$(jq -r ".uri" <<< $input) +uri=$(jq -r ".uri" <<< $input) host="$(echo $uri | awk -F[/:] '{print $4}')" curl -fsSL https://$host/token | jq '{headers:{"Authorization": [("Bearer " + .token)]}}' ``` @@ -127,7 +127,6 @@ For more information about the credential helpers checkout the [documentation](h See the [examples/credential_helper](/examples/credential_helper/auth.sh) directory for an example of how this work. - ## oci_pull @@ -143,8 +142,8 @@ To use the resulting image, you can use the `@wkspc` shorthand label, for exampl if `name = "distroless_base"`, then you can just use `base = "@distroless_base"` in rules like `oci_image`. -> This shorthand syntax is broken on the command-line prior to Bazel 6.2. -> See https://github.com/bazelbuild/bazel/issues/4385 +> This shorthand syntax is broken on the command-line prior to Bazel 6.2. +> See https://github.com/bazelbuild/bazel/issues/4385 **PARAMETERS** @@ -153,15 +152,15 @@ in rules like `oci_image`. | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | repository with this name is created | none | -| image | the remote image, such as gcr.io/bazel-public/bazel. A tag can be suffixed with a colon, like debian:latest, and a digest can be suffixed with an at-sign, like debian@sha256:e822570981e13a6ef1efcf31870726fbd62e72d9abfdcf405a9d8f566e8d7028.

Exactly one of image or {registry,repository} should be set. | None | -| repository | the image path beneath the registry, such as distroless/static. When set, registry must be set as well. | None | -| registry | the remote registry domain, such as gcr.io or docker.io. When set, repository must be set as well. | None | -| platforms | a list of the platforms the image supports. Mandatory for multi-architecture images. Optional for single-architecture images, which expect a one-element list. This creates a separate external repository for each platform, avoiding fetching layers, and an alias that validates the presence of an image matching the target platform's cpu. | None | -| digest | the digest string, starting with "sha256:", "sha512:", etc. If omitted, instructions for pinning are provided. | None | -| tag | a tag to choose an image from the registry. Exactly one of tag and digest must be set. Since tags are mutable, this is not reproducible, so a warning is printed. | None | -| reproducible | Set to False to silence the warning about reproducibility when using tag. | True | -| is_bzlmod | whether the oci_pull is being called from a module extension | False | -| config | Label to a .docker/config.json file. | None | -| bazel_tags | Bazel tags to be propagated to generated rules. | [] | +| image | the remote image, such as `gcr.io/bazel-public/bazel`. A tag can be suffixed with a colon, like `debian:latest`, and a digest can be suffixed with an at-sign, like `debian@sha256:e822570981e13a6ef1efcf31870726fbd62e72d9abfdcf405a9d8f566e8d7028`.

Exactly one of image or {registry,repository} should be set. | `None` | +| repository | the image path beneath the registry, such as `distroless/static`. When set, registry must be set as well. | `None` | +| registry | the remote registry domain, such as `gcr.io` or `docker.io`. When set, repository must be set as well. | `None` | +| platforms | a list of the platforms the image supports. Mandatory for multi-architecture images. Optional for single-architecture images, which expect a one-element list. This creates a separate external repository for each platform, avoiding fetching layers, and an alias that validates the presence of an image matching the target platform's cpu. | `None` | +| digest | the digest string, starting with "sha256:", "sha512:", etc. If omitted, instructions for pinning are provided. | `None` | +| tag | a tag to choose an image from the registry. Exactly one of `tag` and `digest` must be set. Since tags are mutable, this is not reproducible, so a warning is printed. | `None` | +| reproducible | Set to False to silence the warning about reproducibility when using `tag`. | `True` | +| is_bzlmod | whether the oci_pull is being called from a module extension | `False` | +| config | Label to a `.docker/config.json` file. | `None` | +| bazel_tags | Bazel tags to be propagated to generated rules. | `[]` | diff --git a/docs/push.md b/docs/push.md index 39c1c7d1..2f74101b 100644 --- a/docs/push.md +++ b/docs/push.md @@ -1,13 +1,11 @@ - To load these rules, add this to the top of your `BUILD` file: ```starlark load("@rules_oci//oci:defs.bzl", ...) ``` - ## oci_push_rule @@ -52,7 +50,7 @@ When running the pusher, you can pass flags to `bazel run`. 1. Override `repository` by passing the `-r|--repository` flag. -e.g. `bazel run //myimage:push -- --repository index.docker.io/<ORG>/image` +e.g. `bazel run //myimage:push -- --repository index.docker.io//image` 2. Supply tags in addition to `remote_tags` by passing the `-t|--tag` flag. @@ -69,7 +67,7 @@ oci_image(name = "image") oci_push( name = "push", image = ":image", - repository = "index.docker.io/<ORG>/image", + repository = "index.docker.io//image", remote_tags = ["latest"] ) ``` @@ -106,7 +104,7 @@ expand_template( oci_push( name = "push", image = ":app_image", - repository = "ghcr.io/<OWNER>/image", + repository = "ghcr.io//image", remote_tags = ":stamped", ) ``` @@ -120,7 +118,7 @@ For example: load("@rules_multirun//:defs.bzl", "command", "multirun") REPOS = { - "index": "index.docker.io/<ORG>/image", + "index": "index.docker.io//image", "ECR": "aws_account_id.dkr.ecr.us-west-2.amazonaws.com", } @@ -150,7 +148,6 @@ multirun( [rules_multirun]: https://github.com/keith/rules_multirun - **ATTRIBUTES** @@ -158,9 +155,9 @@ multirun( | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | image | Label to an oci_image or oci_image_index | Label | required | | -| remote_tags | a .txt file containing tags, one per line. These are passed to [crane tag]( https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_tag.md) | Label | optional | None | -| repository | Repository URL where the image will be signed at, e.g.: index.docker.io/<user>/image. Digests and tags are not allowed. | String | optional | "" | -| repository_file | The same as 'repository' but in a file. This allows pushing to different repositories based on stamping. | Label | optional | None | +| remote_tags | a .txt file containing tags, one per line. These are passed to [`crane tag`]( https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_tag.md) | Label | optional | `None` | +| repository | Repository URL where the image will be signed at, e.g.: `index.docker.io//image`. Digests and tags are not allowed. | String | optional | `""` | +| repository_file | The same as 'repository' but in a file. This allows pushing to different repositories based on stamping. | Label | optional | `None` | @@ -182,7 +179,7 @@ Allows the remote_tags attribute to be a list of strings in addition to a text f | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | name of resulting oci_push_rule | none | -| remote_tags | a list of tags to apply to the image after pushing, or a label of a file containing tags one-per-line. See [stamped_tags](https://github.com/bazel-contrib/rules_oci/blob/main/examples/push/stamp_tags.bzl) as one example of a way to produce such a file. | None | +| remote_tags | a list of tags to apply to the image after pushing, or a label of a file containing tags one-per-line. See [stamped_tags](https://github.com/bazel-contrib/rules_oci/blob/main/examples/push/stamp_tags.bzl) as one example of a way to produce such a file. | `None` | | kwargs | other named arguments to [oci_push_rule](#oci_push_rule) and [common rule attributes](https://bazel.build/reference/be/common-definitions#common-attributes). | none | diff --git a/internal_deps.bzl b/internal_deps.bzl index 97edf3e1..27516f28 100644 --- a/internal_deps.bzl +++ b/internal_deps.bzl @@ -52,11 +52,8 @@ def rules_oci_internal_deps(): http_archive( name = "io_bazel_stardoc", - sha256 = "dfbc364aaec143df5e6c52faf1f1166775a5b4408243f445f44b661cfdc3134f", - urls = [ - "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.6/stardoc-0.5.6.tar.gz", - "https://github.com/bazelbuild/stardoc/releases/download/0.5.6/stardoc-0.5.6.tar.gz", - ], + sha256 = "62bd2e60216b7a6fec3ac79341aa201e0956477e7c8f6ccc286f279ad1d96432", + urls = ["https://github.com/bazelbuild/stardoc/releases/download/0.6.2/stardoc-0.6.2.tar.gz"], ) http_archive(