From 7e797b3679d7a25e8ef2a1867d1a1a07004c7ab5 Mon Sep 17 00:00:00 2001 From: vmelikyan Date: Wed, 21 Oct 2026 02:25:39 -0700 Subject: [PATCH] docs(schema): document builder cache mode --- documentation-metadata.json | 7 +++++ documentation-style-baseline.json | 10 +++---- public/llms.txt | 4 +-- src/pages/docs/schema/github.mdx | 43 +++++++++++++++++++++++++++++-- src/pages/docs/schema/helm.mdx | 7 +++-- 5 files changed, 60 insertions(+), 11 deletions(-) diff --git a/documentation-metadata.json b/documentation-metadata.json index 4d23161..e03fb28 100644 --- a/documentation-metadata.json +++ b/documentation-metadata.json @@ -123,6 +123,13 @@ "helm-charts": "6aff91c22411e641964774bcbb09e5265ac1250c" }, "notes": "Sites soft delete, restore, Recently deleted view, deleted-site retention setting, MCP hosted site write tools, and creator-or-admin Environment teardown merged and deployed. Live-verified: delete then restore through UI, CLI 0.6.0, and MCP; deleted public sites return 404; cleanup purges after retention." + }, + "2026-10-21-build-cache-mode-released": { + "verifiedOn": "2026-10-21", + "sources": { + "lifecycle": "bc9dc7dfb5511161e2bf744580815551ebf28561" + }, + "notes": "Lifecycle 0.2.3-alpha.45 (merge of docker.builder.cache.mode). Verified the schema enum (max, min, off, no other cache keys), BuildKit export and import flags per mode, Kaniko cache flags removed only for off, and no effect for the ci engine. Other claims on these pages carry over from 2026-07-24-comprehensive-audit." } } } diff --git a/documentation-style-baseline.json b/documentation-style-baseline.json index 9fa6abf..9e10319 100644 --- a/documentation-style-baseline.json +++ b/documentation-style-baseline.json @@ -1,6 +1,6 @@ { "schemaVersion": 3, - "updatedOn": "2026-10-12", + "updatedOn": "2026-10-21", "references": { "canonical": "ASD-STE100 Issue 9", "canonicalRules": [ @@ -351,14 +351,14 @@ "/docs/schema/github": { "file": "src/pages/docs/schema/github.mdx", "profile": "asd-ste100", - "reviewedOn": "2026-07-25", - "sha256": "6d90c58a426518bc34d557468d91c80088ad64a6784c16eb692bd91c292fd6f3" + "reviewedOn": "2026-10-21", + "sha256": "41da652e5fbfbbcd3fc9613ae40d38f45ee6eed658b5702453678a0c5983f26b" }, "/docs/schema/helm": { "file": "src/pages/docs/schema/helm.mdx", "profile": "asd-ste100", - "reviewedOn": "2026-07-25", - "sha256": "8e15742511246d8df0a91df004ccbd5b376fa9add9ec5bf1f8123cf0832e9a1d" + "reviewedOn": "2026-10-21", + "sha256": "5d91ca9765e848ccdc3a03909de73c418eba175ecbc7dba7fe01911f08920566" }, "/docs/schema/overview": { "file": "src/pages/docs/schema/overview.mdx", diff --git a/public/llms.txt b/public/llms.txt index 2019079..20cd0b4 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -58,9 +58,9 @@ This index is generated from the human documentation. Follow the linked page for - [Schema overview](https://uselifecycle.com/docs/schema/overview.md): Understand the lifecycle.yaml configuration file and its structure. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_ - [Environment configuration](https://uselifecycle.com/docs/schema/environment.md): Configure deployment behavior, Service groups, and automation for ephemeral Environments. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_ - [Webhook configuration](https://uselifecycle.com/docs/schema/webhooks.md): Configure webhooks that start automated actions after Environment events. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_ -- [GitHub Service](https://uselifecycle.com/docs/schema/github.md): Build and deploy Services from GitHub repositories with Docker. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_ +- [GitHub Service](https://uselifecycle.com/docs/schema/github.md): Build and deploy Services from GitHub repositories with Docker. _(audience: application-developer; last verified: 2026-10-21; baseline: 2026-10-21-build-cache-mode-released)_ - [Docker Service](https://uselifecycle.com/docs/schema/docker.md): Deploy pre-built Docker images for databases, caches, and other infrastructure components. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_ -- [Helm Service](https://uselifecycle.com/docs/schema/helm.md): Deploy Services with local, OCI, or public Helm charts. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_ +- [Helm Service](https://uselifecycle.com/docs/schema/helm.md): Deploy Services with local, OCI, or public Helm charts. _(audience: application-developer; last verified: 2026-10-21; baseline: 2026-10-21-build-cache-mode-released)_ - [Codefresh Service](https://uselifecycle.com/docs/schema/codefresh.md): Trigger external Codefresh pipelines for deployment and teardown. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_ - [Aurora Restore Service](https://uselifecycle.com/docs/schema/aurora-restore.md): Make an AWS Aurora point-in-time copy for an ephemeral Environment. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_ - [Configuration Service](https://uselifecycle.com/docs/schema/configuration.md): Deploy configuration-only Services for feature flags and shared configuration. _(audience: application-developer; last verified: 2026-08-01; baseline: 2026-08-01-configuration-schema-fix)_ diff --git a/src/pages/docs/schema/github.mdx b/src/pages/docs/schema/github.mdx index 2949a7f..1d2870c 100644 --- a/src/pages/docs/schema/github.mdx +++ b/src/pages/docs/schema/github.mdx @@ -3,8 +3,8 @@ title: GitHub Service description: Build and deploy Services from GitHub repositories with Docker. audience: - application-developer -lastVerified: "2026-07-24" -verificationBaseline: "2026-07-24-comprehensive-audit" +lastVerified: "2026-10-21" +verificationBaseline: "2026-10-21-build-cache-mode-released" contentProfile: asd-ste100 tags: - schema @@ -96,6 +96,8 @@ services: defaultTag: "main" builder: engine: "buildkit" # Options: buildkit, kaniko, ci + cache: # Optional - build cache behavior + mode: "max" # Options: max, min, off resources: # Optional - custom CPU/memory for the build job requests: cpu: "1" @@ -180,6 +182,7 @@ Configuration for the Docker build operation. | Field | Type | Description | | -------------------- | ----------------------- | ---------------------------------------------------- | | `engine` | string | Build engine: `buildkit`, `kaniko`, or `ci` | +| `cache.mode` | string | Build cache mode: `max`, `min`, or `off` | | `resources.requests` | object | Minimum CPU/memory guaranteed for the build job | | `resources.limits` | object | Maximum CPU/memory allowed for the build job | | `podAnnotations` | `Record` | Custom annotations applied to the build pod template | @@ -229,6 +232,42 @@ services: dockerfilePath: "Dockerfile" ``` +### docker.builder.cache + +The `cache.mode` field sets how BuildKit uses the build cache: + +- `max` - BuildKit exports the cache for all build steps. +- `min` - BuildKit exports the cache only for the layers of the final image. +- `off` - BuildKit does not export or import a cache. + +With `max` or `min`, BuildKit also imports the cache that it exported before. + +If you do not set `mode`, Lifecycle uses the installation default. This default +is `max` if an administrator did not change it. + +If the image is large, BuildKit can be slow when it exports the cache for all +build steps. If the next builds use only a small part of that cache, set `mode` +to `min`. If the cache does not make builds faster, set `mode` to `off`. + +For the `kaniko` engine, only `off` has an effect. With `off`, Kaniko does not +use a cache. The `ci` engine does not use `cache.mode`. + +```yaml filename="lifecycle.yaml" +services: + - name: "api" + github: + repository: "myorg/api" + branchName: "main" + docker: + defaultTag: "main" + builder: + engine: "buildkit" + cache: + mode: "min" # Options: max, min, off + app: + dockerfilePath: "Dockerfile" +``` + ### docker.app (required) Configuration for the main application container: diff --git a/src/pages/docs/schema/helm.mdx b/src/pages/docs/schema/helm.mdx index f0b9926..5d8b90f 100644 --- a/src/pages/docs/schema/helm.mdx +++ b/src/pages/docs/schema/helm.mdx @@ -3,8 +3,8 @@ title: Helm Service description: Deploy Services with local, OCI, or public Helm charts. audience: - application-developer -lastVerified: "2026-07-24" -verificationBaseline: "2026-07-24-comprehensive-audit" +lastVerified: "2026-10-21" +verificationBaseline: "2026-10-21-build-cache-mode-released" contentProfile: asd-ste100 tags: - schema @@ -245,10 +245,13 @@ The default Docker image tag, typically matching the branch name. Configuration for the Docker build operation. See [GitHub Service docker.builder](/docs/schema/github#dockerbuilder) for the full field list. That section includes the `resources` field and the `safe-to-evict` pod annotation. +For the cache modes, see [GitHub Service +docker.builder.cache](/docs/schema/github#dockerbuildercache). | Field | Type | Description | | -------------------- | ----------------------- | ---------------------------------------------------- | | `engine` | string | Build engine: `buildkit`, `kaniko`, or `ci` | +| `cache.mode` | string | Build cache mode: `max`, `min`, or `off` | | `resources.requests` | object | Minimum CPU/memory guaranteed for the build job | | `resources.limits` | object | Maximum CPU/memory allowed for the build job | | `podAnnotations` | `Record` | Custom annotations applied to the build pod template |