From feef516987604d6efcbf8be861924a16c56b246c Mon Sep 17 00:00:00 2001 From: ltagliaferri Date: Mon, 23 Oct 2023 19:44:07 -0400 Subject: [PATCH 1/3] apko update Signed-off-by: ltagliaferri --- content/open-source/apko/bazel-rules.md | 250 ++++++++++++++++++++++++ content/open-source/apko/faq.md | 4 +- 2 files changed, 252 insertions(+), 2 deletions(-) create mode 100644 content/open-source/apko/bazel-rules.md diff --git a/content/open-source/apko/bazel-rules.md b/content/open-source/apko/bazel-rules.md new file mode 100644 index 0000000000..30e404ee38 --- /dev/null +++ b/content/open-source/apko/bazel-rules.md @@ -0,0 +1,250 @@ +--- +title: "Bazel Rules for apko" +linktitle: "Bazel Rules" +type: "article" +lead: "Minimalist OCI image builder based on APK" +description: "Quickstart to get apko up and running" +date: 2023-10-23T08:49:31+00:00 +lastmod: 2023-10-23T16:49:31+00:00 +draft: false +tags: ["apko", "Procedural",] +images: [] +menu: + docs: + parent: "apko" +weight: 900 +toc: true +--- + +`rules_apko` is an open source plugin for Bazel that makes it possible to build secure, minimal Wolfi-based container images using the popular Bazel build system. This wraps the [apko](https://github.com/chainguard-dev/apko) tool for use under Bazel. + +## Prerequisites + +First, be sure you have Bazel installed, you can follow the [Bazel installation guide](https://bazel.build/install) for more details. + +Next, `rules_apko` requires a one-time setup to configure Bazel to be able to make partial fetches. + +Paste the following into your root `BUILD` file. + +```py +load("@rules_apko//apko:defs.bzl", "apko_bazelrc") + +apko_bazelrc() +``` + +> **Note**: By default, `apko_bazelrc` will generate `.bazelrc` to accomodate for fetching from `dl-cdn.alpinelinux.org` and `packages.wolfi.dev`. this can be configured by passing the `repositories` attribute to `apko_bazelrc()` call. + +Then, run the following command. + +```sh +bazel run @@//:apko_bazelrc && chmod +x .apko/range.sh +``` + +Finally, paste this into your preferred \`.bazelrc\` file, + +```sh +# Required for rules_apko to make range requests +try-import %workspace%/.apko/.bazelrc +``` + +Review additional [initial setup documentation](https://github.com/chainguard-dev/rules_apko/blob/main/docs/initial-setup.md) updates in the `rules_apko` [repo](https://github.com/chainguard-dev/rules_apko). + +## Installation + +To install v1.0.0, you can follow one of the options below. For other releases, follow the instructions in the release notes from the release you wish to use: [https://github.com/chainguard-dev/rules_apko/releases](https://github.com/chainguard-dev/rules_apko/releases). + +### Using Bzlmod with Bazel 6 + +1. Enable with `common --enable_bzlmod` in `.bazelrc`. +1. Add to your `MODULE.bazel` file: + +```starlark +bazel_dep(name = "rules_apko", version = "1.0.0-rc1") +``` + +## Using WORKSPACE + +Paste this snippet into your file: + +```starlark +load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") +http_archive( + name = "rules_apko", + sha256 = "5c91a2322bec84a0005dd8178495775938b581053812e70d21b030bef3625623", + strip_prefix = "rules_apko-1.0.0-rc1", + url = "https://github.com/chainguard-dev/rules_apko/releases/download/v1.0.0-rc1/rules_apko-v1.0.0-rc1.tar.gz", +) + +###################### +# rules_apko setup # +###################### +# Fetches the rules_apko dependencies. +# If you want to have a different version of some dependency, +# you should fetch it *before* calling this. +# Alternatively, you can skip calling this function, so long as you've +# already fetched all the dependencies. +load("@rules_apko//apko:repositories.bzl", "apko_register_toolchains", "rules_apko_dependencies") + +rules_apko_dependencies() + +apko_register_toolchains(name = "apko") + +load("@rules_apko//apko:translate_lock.bzl", "translate_apko_lock") + +translate_apko_lock( + name = "example_lock", + lock = "@//:apko.lock.json", +) + +load("@example_lock//:repositories.bzl", "apko_repositories") + +apko_repositories() +``` +## Rules + +Public API re-exports + +## apko_image + +
+apko_image(name, architecture, args, config, contents, output, tag)
+
+ +Build OCI images from APK packages directly without Dockerfile. + +This rule creates Alpine images using the `apko.yaml` configuration file and relies on cache contents generated by [translate_lock](https://github.com/chainguard-dev/rules_apko/blob/main/docs/translate_lock.md) to be fast. + +```starlark +apko_image( + name = "example", + config = "apko.yaml", + contents = "@example_lock//:contents", + tag = "example:latest", +) +``` + +The label `@example_lock//:contents` is generated by the `translate_lock` extension, which consumes an 'apko.lock.json' file. For more details, refer to the [apko cache documentation](#fetching-and-caching-contents). + +An example demonstrating usage with [rules_oci](https://github.com/bazel-contrib/rules_oci): + +```starlark +apko_image( + name = "alpine_base", + config = "apko.yaml", + contents = "@alpine_base_lock//:contents", + tag = "alpine_base:latest", +) + +oci_image( + name = "app", + base = ":alpine_base" +) +``` + +For more examples checkout the [examples](https://github.com/chainguard-dev/rules_apko/tree/main/examples) directory. + +### Attributes + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| architecture | the CPU architecture which this image should be built to run on. See https://github.com/chainguard-dev/apko/blob/main/docs/apko_file.md#archs-top-level-element | String | optional | "" | +| args | additional arguments to provide when running the apko build command. | List of strings | optional | [] | +| config | Label to the apko.yaml file. | Label | required | | +| contents | Label to the contents repository generated by translate_lock. See [apko-cache](./apko-cache.md) documentation. | Label | required | | +| output | - | String | optional | "oci" | +| tag | tag to apply to the resulting docker tarball. only applicable when output is docker | String | required | | + +### apko_bazelrc + +
+apko_bazelrc(name, repositories, kwargs)
+
+ +Helper macro for generating `.bazelrc` and `range.sh` files to allow for partial package fetches. + +Review [Prerequisites](#prerequisites) documentation for more information. + +### Parameters + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| name | name of the target | "apko_bazelrc" | +| repositories | list of repositories to generate .bazelrc for | ["dl-cdn.alpinelinux.org", "packages.wolfi.dev"] | +| kwargs | passed to expanding targets. only well known attributes such as tags testonly ought to be present. | none | + +## Fetching and Caching Contents + +To ensure efficient operation, the `apko_image` rule must maintain a cache of remote contents that it fetches from repositories. While outside of Bazel, `apko` manages its own cache, under Bazel, the cache must be maintained by Bazel to ensure correctness and speed. Therefore, Bazel needs to know what needs to be fetched and from where to cache these HTTP requests and provide them to `apko` as required. + +The `apko.lock.json` file contains all the necessary information about how to perform the HTTP fetches required by `apko` to build the container image. + +### Generating the Lock File + +> **Note:** Documentation for lockfile generation [will be added to the repository docs](https://github.com/chainguard-dev/rules_apko/blob/main/docs/apko-cache.md) once the `apko resolve` command is available. + +### Using `translate_lock` + +Having just the `apko.lock.json` file alone is insufficient; all the information needs to be converted into `apk_` repository calls to make them accessible to Bazel. The `translate_lock` tool accomplishes this by taking the `apko.lock.json` file and dynamically generating the required Bazel repositories. + +`translate_lock` will create a new bazel repository named after itself. This repository will also have a target named contents, which you can pass to `apko_image`: + +```starlark +apko_image( + name = "lock", + config = "apko.yaml", + # name of the repository is the same translate_lock! + contents = "@examples_lock//:contents", + tag = "lock:latest", +) +``` + +#### Usage with `bzlmod` + +```starlark +apk = use_extension("//apko:extensions.bzl", "apko") + +apk.translate_lock( + name = "examples_lock", + lock = "//path/to/lock:apko.lock.json", +) +use_repo(apk, "examples_lock") +``` + +#### Usage with Workspace + +```starlark +load("@rules_apko//apko:translate_lock.bzl", "translate_apko_lock") + +translate_apko_lock( + name = "example_lock", + lock = "//path/to/lock:apko.lock.json", +) + +load("@example_lock//:repositories.bzl", "apko_repositories") + +apko_repositories() +``` + +## Repository rules for translating apko.lock.json + +`translate_apko_lock` + +
+translate_apko_lock(name, lock, repo_mapping, target_name)
+
+ +## Repository rule to generate starlark code from an `apko.lock.json` file. + +Review [the section above](http://localhost:1313/open-source/apko/bazel-rules/#fetching-and-caching-contents) for more information. + + +### Attributes + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this repository. | Name | required | | +| lock | label to the apko.lock.json file. | Label | required | | +| repo_mapping | A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.<p>For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target). | Dictionary: String -> String | required | | +| target_name | internal. do not use! | String | optional | "" | diff --git a/content/open-source/apko/faq.md b/content/open-source/apko/faq.md index 52513516bb..d1655fd6be 100644 --- a/content/open-source/apko/faq.md +++ b/content/open-source/apko/faq.md @@ -4,14 +4,14 @@ type: "article" lead: "Frequently asked questions about apko" description: "Frequently asked questions about apko" date: 2022-10-10T11:07:52+02:00 -lastmod: 2022-10-10T11:07:52+02:00 +lastmod: 2023-10-23T11:07:52+02:00 draft: false tags: ["apko", "FAQ",] images: [] menu: docs: parent: "apko" -weight: 900 +weight: 50 toc: true --- From 3c5af3f36118fe376305da397245c94e5add31cd Mon Sep 17 00:00:00 2001 From: ltagliaferri Date: Mon, 23 Oct 2023 20:17:49 -0400 Subject: [PATCH 2/3] Update content/open-source/apko/bazel-rules.md --- content/open-source/apko/bazel-rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/open-source/apko/bazel-rules.md b/content/open-source/apko/bazel-rules.md index 30e404ee38..56cbfb7bcb 100644 --- a/content/open-source/apko/bazel-rules.md +++ b/content/open-source/apko/bazel-rules.md @@ -2,7 +2,7 @@ title: "Bazel Rules for apko" linktitle: "Bazel Rules" type: "article" -lead: "Minimalist OCI image builder based on APK" +lead: "Build secure, minimal Wolfi-based container images using Bazel" description: "Quickstart to get apko up and running" date: 2023-10-23T08:49:31+00:00 lastmod: 2023-10-23T16:49:31+00:00 From d472f6c2ad9b634f0f3af6823d513111d6da1fa8 Mon Sep 17 00:00:00 2001 From: ltagliaferri Date: Mon, 23 Oct 2023 20:17:54 -0400 Subject: [PATCH 3/3] Update content/open-source/apko/bazel-rules.md --- content/open-source/apko/bazel-rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/open-source/apko/bazel-rules.md b/content/open-source/apko/bazel-rules.md index 56cbfb7bcb..099e01a1d5 100644 --- a/content/open-source/apko/bazel-rules.md +++ b/content/open-source/apko/bazel-rules.md @@ -3,7 +3,7 @@ title: "Bazel Rules for apko" linktitle: "Bazel Rules" type: "article" lead: "Build secure, minimal Wolfi-based container images using Bazel" -description: "Quickstart to get apko up and running" +description: "Build secure, minimal Wolfi-based container images using Bazel" date: 2023-10-23T08:49:31+00:00 lastmod: 2023-10-23T16:49:31+00:00 draft: false