From ee690fd01faa57c04fd409f9d805de4b8a8e8c93 Mon Sep 17 00:00:00 2001 From: Siddhartha Singh Date: Tue, 19 May 2026 00:38:21 +0530 Subject: [PATCH 1/2] docs: add how-to guide for building vs supplying container images Add a dedicated how-to guide covering the two ways to resolve a container image at generation time: supplying a pre-built image with the --image flag, and building from local source with the --build flag for score-compose. Explains the 'image: .' placeholder, provides score-compose and score-k8s tabbed examples, and a guidance table for choosing between the approaches. Signed-off-by: Siddhartha Singh --- .../build-or-supply-a-container-image.md | 116 ++++++++++++++++++ .../build-supply-image-score-compose.md | 10 ++ .../included/build-supply-image-score-k8s.md | 10 ++ 3 files changed, 136 insertions(+) create mode 100644 content/en/docs/How to/build-or-supply-a-container-image.md create mode 100644 content/en/docs/How to/included/build-supply-image-score-compose.md create mode 100644 content/en/docs/How to/included/build-supply-image-score-k8s.md diff --git a/content/en/docs/How to/build-or-supply-a-container-image.md b/content/en/docs/How to/build-or-supply-a-container-image.md new file mode 100644 index 00000000..5ed8a98d --- /dev/null +++ b/content/en/docs/How to/build-or-supply-a-container-image.md @@ -0,0 +1,116 @@ +--- +title: "Build or supply a container image" +linkTitle: "Build or supply images" +weight: 6 +description: > + How to build a container image from local source or supply a pre-built + image with `score-compose` and `score-k8s`. +--- + +Every container in a Score workload needs a container image. To keep the +`score.yaml` file portable across environments, Score lets you leave the image +unresolved in the specification and choose how to resolve it when you run +`generate`. You have two options: + +- **Supply a pre-built image** that is already published to a registry. +- **Build an image from local source** as part of the `generate` step. + +This guide covers both options and explains when to use each. + +## The image placeholder + +Set the container `image` field to `.` to mark it as resolved at generation +time: + +```yaml +apiVersion: score.dev/v1b1 +metadata: + name: hello-world +containers: + hello-world: + image: . +``` + +The `.` placeholder keeps registry names and tags out of the specification. The +implementation resolves the placeholder when you run `generate`. A `generate` +command that leaves the placeholder unresolved fails with an error. + +A container that already points to a published image, such as +`image: nginx:1-alpine`, needs no further action. The implementation uses that +image without change. + +## Supply a pre-built image + +Use the `--image` flag when the image is already built and pushed to a +registry. Continuous integration pipelines are the most common case: an earlier +job builds and pushes the image, then the `generate` step references it by tag. + +The `--image` flag replaces the `.` placeholder for every container that uses +it. + +{{< tabs name="supply-image">}} +{{< tab name="score-compose" include="./included/build-supply-image-score-compose.md" />}} +{{< tab name="score-k8s" include="./included/build-supply-image-score-k8s.md" />}} +{{< /tabs >}} + +## Build an image from local source + +`score-compose` can build the container image from local source as part of the +generated Docker Compose file. Use the `--build` flag to point a container at a +build context. This option suits local development, where rebuilding the image +on each change is faster than pushing to a registry. + +The `--build` flag accepts two formats: + +- A short form that takes a directory: `--build=CONTAINER=./dir`. +- A JSON form that takes a build context and other options, such as image tags: + `--build=CONTAINER={"context":"./dir","tags":["my-image:local"]}`. + +The following example initializes a workspace, then builds the `hello-world` +container from the current directory and tags the resulting image: + +```bash +CONTAINER_NAME=hello-world +CONTAINER_IMAGE=${CONTAINER_NAME}:local + +score-compose init --no-sample +score-compose generate score.yaml \ + --build "${CONTAINER_NAME}={\"context\":\".\",\"tags\":[\"${CONTAINER_IMAGE}\"]}" +``` + +The generated `compose.yaml` contains a `build` block for the container instead +of a fixed `image` reference: + +```yaml +services: + hello-world-hello-world: + build: + context: . +``` + +Run `docker compose up` with the `--build` flag so Docker builds the image +before it starts the containers: + +```bash +docker compose up --build -d +``` + +`score-k8s` does not build images. Kubernetes runs pre-built images pulled from +a registry, so supply an image with `--image` when you target `score-k8s`. + +## When to build and when to supply + +| Scenario | Recommended approach | +| ----------------------------------------- | --------------------------------------- | +| Local development with `score-compose` | Build from source with `--build` | +| Quick iteration on application code | Build from source with `--build` | +| CI/CD pipeline | Supply a pre-built image with `--image` | +| Deployment with `score-k8s` | Supply a pre-built image with `--image` | +| The image is already published and stable | Reference it directly in `score.yaml` | + +## Related pages + +- [`score-compose` CLI reference](/docs/score-implementation/score-compose/cli/) +- [`score-k8s` CLI reference](/docs/score-implementation/score-k8s/cli/) +- [CI/CD pipelines with Score](/docs/how-to/score-cicd-pipelines/) +- [Specify configuration overrides](/docs/how-to/overrides/) diff --git a/content/en/docs/How to/included/build-supply-image-score-compose.md b/content/en/docs/How to/included/build-supply-image-score-compose.md new file mode 100644 index 00000000..1d908894 --- /dev/null +++ b/content/en/docs/How to/included/build-supply-image-score-compose.md @@ -0,0 +1,10 @@ +--- +title: "Supply a pre-built image with score-compose" +description: "Supply a pre-built image with score-compose" +headless: true +toc_hide: true +--- + +```bash +score-compose generate score.yaml --image my-registry/hello-world:1.0.0 +``` diff --git a/content/en/docs/How to/included/build-supply-image-score-k8s.md b/content/en/docs/How to/included/build-supply-image-score-k8s.md new file mode 100644 index 00000000..d17023b4 --- /dev/null +++ b/content/en/docs/How to/included/build-supply-image-score-k8s.md @@ -0,0 +1,10 @@ +--- +title: "Supply a pre-built image with score-k8s" +description: "Supply a pre-built image with score-k8s" +headless: true +toc_hide: true +--- + +```bash +score-k8s generate score.yaml --image my-registry/hello-world:1.0.0 +``` From 9fa61a0ad39f0c8cb59ae9c929622b6dfa2b404d Mon Sep 17 00:00:00 2001 From: Siddhartha Singh Date: Tue, 19 May 2026 12:41:00 +0530 Subject: [PATCH 2/2] docs: add container image section to the Overrides page Per maintainer feedback on score-spec/docs#110, move the building vs supplying container image guidance into a new dedicated section at the bottom of the existing Overrides page instead of a separate how-to guide. Covers the --image flag for score-compose and score-k8s, points to --override-property for per-workload images, and the score-compose --build flag with an example. Signed-off-by: Siddhartha Singh --- .../build-or-supply-a-container-image.md | 116 ------------------ content/en/docs/How to/overrides.md | 29 +++++ 2 files changed, 29 insertions(+), 116 deletions(-) delete mode 100644 content/en/docs/How to/build-or-supply-a-container-image.md diff --git a/content/en/docs/How to/build-or-supply-a-container-image.md b/content/en/docs/How to/build-or-supply-a-container-image.md deleted file mode 100644 index 5ed8a98d..00000000 --- a/content/en/docs/How to/build-or-supply-a-container-image.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: "Build or supply a container image" -linkTitle: "Build or supply images" -weight: 6 -description: > - How to build a container image from local source or supply a pre-built - image with `score-compose` and `score-k8s`. ---- - -Every container in a Score workload needs a container image. To keep the -`score.yaml` file portable across environments, Score lets you leave the image -unresolved in the specification and choose how to resolve it when you run -`generate`. You have two options: - -- **Supply a pre-built image** that is already published to a registry. -- **Build an image from local source** as part of the `generate` step. - -This guide covers both options and explains when to use each. - -## The image placeholder - -Set the container `image` field to `.` to mark it as resolved at generation -time: - -```yaml -apiVersion: score.dev/v1b1 -metadata: - name: hello-world -containers: - hello-world: - image: . -``` - -The `.` placeholder keeps registry names and tags out of the specification. The -implementation resolves the placeholder when you run `generate`. A `generate` -command that leaves the placeholder unresolved fails with an error. - -A container that already points to a published image, such as -`image: nginx:1-alpine`, needs no further action. The implementation uses that -image without change. - -## Supply a pre-built image - -Use the `--image` flag when the image is already built and pushed to a -registry. Continuous integration pipelines are the most common case: an earlier -job builds and pushes the image, then the `generate` step references it by tag. - -The `--image` flag replaces the `.` placeholder for every container that uses -it. - -{{< tabs name="supply-image">}} -{{< tab name="score-compose" include="./included/build-supply-image-score-compose.md" />}} -{{< tab name="score-k8s" include="./included/build-supply-image-score-k8s.md" />}} -{{< /tabs >}} - -## Build an image from local source - -`score-compose` can build the container image from local source as part of the -generated Docker Compose file. Use the `--build` flag to point a container at a -build context. This option suits local development, where rebuilding the image -on each change is faster than pushing to a registry. - -The `--build` flag accepts two formats: - -- A short form that takes a directory: `--build=CONTAINER=./dir`. -- A JSON form that takes a build context and other options, such as image tags: - `--build=CONTAINER={"context":"./dir","tags":["my-image:local"]}`. - -The following example initializes a workspace, then builds the `hello-world` -container from the current directory and tags the resulting image: - -```bash -CONTAINER_NAME=hello-world -CONTAINER_IMAGE=${CONTAINER_NAME}:local - -score-compose init --no-sample -score-compose generate score.yaml \ - --build "${CONTAINER_NAME}={\"context\":\".\",\"tags\":[\"${CONTAINER_IMAGE}\"]}" -``` - -The generated `compose.yaml` contains a `build` block for the container instead -of a fixed `image` reference: - -```yaml -services: - hello-world-hello-world: - build: - context: . -``` - -Run `docker compose up` with the `--build` flag so Docker builds the image -before it starts the containers: - -```bash -docker compose up --build -d -``` - -`score-k8s` does not build images. Kubernetes runs pre-built images pulled from -a registry, so supply an image with `--image` when you target `score-k8s`. - -## When to build and when to supply - -| Scenario | Recommended approach | -| ----------------------------------------- | --------------------------------------- | -| Local development with `score-compose` | Build from source with `--build` | -| Quick iteration on application code | Build from source with `--build` | -| CI/CD pipeline | Supply a pre-built image with `--image` | -| Deployment with `score-k8s` | Supply a pre-built image with `--image` | -| The image is already published and stable | Reference it directly in `score.yaml` | - -## Related pages - -- [`score-compose` CLI reference](/docs/score-implementation/score-compose/cli/) -- [`score-k8s` CLI reference](/docs/score-implementation/score-k8s/cli/) -- [CI/CD pipelines with Score](/docs/how-to/score-cicd-pipelines/) -- [Specify configuration overrides](/docs/how-to/overrides/) diff --git a/content/en/docs/How to/overrides.md b/content/en/docs/How to/overrides.md index fbf46510..e78a9837 100644 --- a/content/en/docs/How to/overrides.md +++ b/content/en/docs/How to/overrides.md @@ -77,3 +77,32 @@ Set the path of the property to an empty value to remove the property. {{< tab name="score-compose" include="./included/overrides-property-empty-score-compose.md" />}} {{< tab name="score-k8s" include="./included/overrides-property-empty-score-k8s.md" />}} {{< /tabs >}} + +## Build or supply a container image + +When you run `score-compose generate` or `score-k8s generate`, each workload needs a container image. You can supply a pre-built image, or, with `score-compose`, build one from local source. + +### How to supply a pre-built image + +The value provided to the `--image` flag overrides the `image` field of any workload that lacks an explicit image definition in its Score file. To handle different images for multiple workloads, use the `--override-property` flag shown in [How to override a property](#how-to-override-a-property). + +{{< tabs name="image-flag">}} +{{< tab name="score-compose" include="./included/build-supply-image-score-compose.md" />}} +{{< tab name="score-k8s" include="./included/build-supply-image-score-k8s.md" />}} +{{< /tabs >}} + +### How to build a container image + +Specific to `score-compose generate`, the `--build` flag specifies an optional build context to use for the given container. The format is either `--build=CONTAINER=./dir` or `--build=CONTAINER={"context":"./dir"}`. + +The following example builds the `hello-world` container from the current directory: + +```bash +score-compose generate score.yaml --build 'hello-world={"context":"."}' +``` + +Run `docker compose up` with the `--build` flag so Docker builds the image before it starts the containers: + +```bash +docker compose up --build -d +```