From be65b84d7715008be6652323d541920d45929e06 Mon Sep 17 00:00:00 2001
From: Borodin Gregory <grihabor@gmail.com>
Date: Tue, 4 Mar 2025 09:08:10 +0100
Subject: [PATCH] Add docker image section

---
 docs/docs/kubernetes/index.mdx | 59 +++++++++++++++++++++++++++++++---
 1 file changed, 54 insertions(+), 5 deletions(-)

diff --git a/docs/docs/kubernetes/index.mdx b/docs/docs/kubernetes/index.mdx
index f737ff673ab..ba17ea38225 100644
--- a/docs/docs/kubernetes/index.mdx
+++ b/docs/docs/kubernetes/index.mdx
@@ -114,10 +114,10 @@ default context.
 
 ## Simple templates
 
-To use docker images you most likely will need some templating. This is because
-your docker image tags will be probably versioned. The simplest way to
-introduce templating is to use `python_format_string` target that will generate
-`k8s_sources` based on values you provide in the BUILD file.
+At some point, you may need to inject variables from a BUILD file into
+Kubernetes resources — also known as templating. The simplest way to achieve
+this is by using the `python_format_string` target, which generates
+`k8s_sources` by substituting the values you specify in the BUILD file.
 
 First, add the codegen backend:
 
@@ -131,7 +131,8 @@ backend_packages = [
 ]
 ```
 
-Then parametrize the yaml using python format string syntax:
+Then parametrize the yaml using python format string syntax, e.g. the
+namespace:
 
 ```yaml title="src/k8s/webpages.yaml
 ---
@@ -169,3 +170,51 @@ Now you can deploy the bundle:
 ```bash
 pants experimental-deploy src/k8s/:webpages
 ```
+
+This setup can now be used to deploy the same resource to multiple namespaces
+with [`parametrize`
+builtin](../using-pants/key-concepts/targets-and-build-files.mdx#parametrizing-targets):
+
+```python title="src/k8s/BUILD"
+python_format_string(
+    name="webpages-template",
+    source="webpages.yaml",
+    **parametrize("default", values={"namespace": "default"}),
+    **parametrize("web", values={"namespace": "web"}),
+)
+k8s_bundle(
+    name="webpages",
+    context="kind-kind",
+    **parametrize("default", sources=("src/k8s:webpages-template@parametrize=web",)),
+    **parametrize("web", sources=("src/k8s:webpages-template@parametrize=web",)),
+)
+```
+
+## Docker images
+
+To use docker images you most likely will need some templating. This is because
+your docker image tags will be probably versioned.
+
+You might want to use git to generate the version for your images, but you
+can't directly run git commands in a BUILD file. You can use a
+`.pants.bootstrap` file as a workaround:
+
+```python title=".pants.bootstrap"
+#!/bin/sh
+
+VERSION="${VERSION:-$(git describe --tags --dirty --match "[0-9\.]*" || echo 0.0.1)}"
+export VERSION
+```
+
+This script will run before every pants command, so you can now use the
+`VERSION` env var in the BUILD file:
+
+```python title="src/k8s/BUILD"
+docker_image(
+    name="nginx",
+    instructions=["FROM nginx"],
+    image_tags=[env("VERSION")],
+)
+# TODO
+```
+