docs: image version management for deployments#433
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe documentation adds version-manifest configuration, container image selection and validation guidance, image persistence semantics, upgrade procedures, and MkDocs navigation for the new image-management page. ChangesContainer Image Management
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Up to standards ✅🟢 Issues
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/using/image-management.md (1)
38-40: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueSpecify a language for fenced code blocks.
To improve syntax highlighting and avoid linter warnings, consider specifying a language (like
text) for these code blocks.
docs/using/image-management.md#L38-L40: appendtextto the opening backticks.docs/using/image-management.md#L194-L196: appendtextto the opening backticks.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/using/image-management.md` around lines 38 - 40, Specify the text language on both fenced code blocks in docs/using/image-management.md at lines 38-40 and 194-196 by appending text to each opening fence.Source: Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/using/upgrade-db.md`:
- Around line 187-189: Replace the curly single quotes in the shell commands
with standard straight single quotes: update the URL at docs/using/upgrade-db.md
lines 187-189 and the header value and data payload at lines 215-221.
---
Nitpick comments:
In `@docs/using/image-management.md`:
- Around line 38-40: Specify the text language on both fenced code blocks in
docs/using/image-management.md at lines 38-40 and 194-196 by appending text to
each opening fence.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: db7363d6-ffc6-4c6b-ac10-9cf33627f171
📒 Files selected for processing (5)
docs/installation/configuration.mddocs/installation/installation.mddocs/using/image-management.mddocs/using/upgrade-db.mdmkdocs.yml
4dcf39f to
0364836
Compare
| === "curl" | ||
|
|
||
| ```sh | ||
| curl ‘http://host-3:3000/v1/databases/example?include=available_upgrades’ |
There was a problem hiding this comment.
Curly quotes in the upgrade-db.md curl examples The new examples use smart quotes instead of straight quotes, so if someone copies and pastes them into a shell they will fail. Example lines: curl 'http://host-3:3000/v1/databases/example?include=available_upgrades', the -H header, and the --data body all use curly quotes. Replace them with normal straight quotes like the image-management.md examples already do.
| | `etcd_server.client_port` | `PGEDGE_ETCD_SERVER__CLIENT_PORT` | int | `2379` | The port that the embedded Etcd server will listen on for client connections. | | | ||
| | `etcd_client.log_level` | `PGEDGE_ETCD_CLIENT__LOG_LEVEL` | string | `fatal` | The log level for Etcd client operations performed by this Control Plane server. | | | ||
| | `docker_swarm.image_repository_host` | `PGEDGE_DOCKER_SWARM__IMAGE_REPOSITORY_HOST` | string | `ghcr.io/pgedge` | The base URL of pgEdge Docker images. | | | ||
| | `docker_swarm.manifest_url` | `PGEDGE_DOCKER_SWARM__MANIFEST_URL` | string | pgEdge hosted manifest URL | Overrides the default version manifest URL. Set to an internal endpoint for air-gapped deployments or a staging URL for pre-release image testing. When set, the embedded binary manifest is still used as a last-resort fallback. | | |
There was a problem hiding this comment.
Can you verify if its correct?
There was a problem hiding this comment.
Actionable comments posted: 7
🧹 Nitpick comments (1)
docs/using/image-management.md (1)
102-110: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winClarify the air-gapped override requirement.
Custom image overrides always perform registry manifest validation on every host (Lines 205-226). State that this requires a registry reachable from each host; fully offline deployments with only pre-pulled images must use the manifest-based path instead.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/using/image-management.md` around lines 102 - 110, Update the air-gapped deployments guidance near the custom image override discussion to state that registry manifest validation requires a registry reachable from every host. Clarify that fully offline deployments using only pre-pulled images cannot use custom overrides and must use the manifest-based image path instead.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/installation/configuration.md`:
- Around line 50-51: Update the documentation for docker_swarm.manifest_url and
docker_swarm.manifest_path to explicitly state configuration precedence: CLI
flags override environment variables, which override config-file values. Clarify
that this order determines which manifest URL or path is used when sources
provide conflicting settings.
- Line 50: Update the manifest-resolution startup statement in image-management
documentation to match the behavior documented for docker_swarm.manifest_url:
the Control Plane does not fail for the default URL, but a custom URL can fail
startup when both the URL and disk cache are unavailable. Preserve the existing
default-URL behavior while explicitly documenting this custom-URL exception.
In `@docs/installation/installation.md`:
- Around line 259-261: Update the version-manifest bind mount in the Docker
Compose example to include the read-only option, ensuring the Control Plane
container cannot modify the host manifest while preserving the existing mount
paths.
- Around line 270-276: Update the manifest endpoint guidance around
PGEDGE_DOCKER_SWARM__MANIFEST_URL to require HTTPS or equivalent authentication
and integrity protection for custom manifest URLs. Replace the plain HTTP
example with a secure endpoint example and retain the existing internal-server
configuration context.
In `@docs/using/image-management.md`:
- Around line 38-40: Update the fenced examples in image-management.md,
including the shown image naming pattern and the additional fence referenced by
the comment, to specify the text language identifier. Preserve the example
contents unchanged.
In `@docs/using/upgrade-db.md`:
- Around line 229-231: Update the target image requirements in the upgrade
documentation to state that the image must be strictly newer than the database’s
current image, while retaining the existing stable-manifest and matching
Postgres/Spock major constraints.
- Around line 210-225: The upgrade endpoint documentation should describe the
response as an ApplyUpgradeResponse containing task and database objects, and
clarify that the task identifier is read from task.task_id rather than returned
as a bare task ID. Update the surrounding task-tracking guidance while
preserving the existing asynchronous workflow and request example.
---
Nitpick comments:
In `@docs/using/image-management.md`:
- Around line 102-110: Update the air-gapped deployments guidance near the
custom image override discussion to state that registry manifest validation
requires a registry reachable from every host. Clarify that fully offline
deployments using only pre-pulled images cannot use custom overrides and must
use the manifest-based image path instead.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 36d92014-e8f0-4120-8157-b01994fd8b95
📒 Files selected for processing (5)
docs/installation/configuration.mddocs/installation/installation.mddocs/using/image-management.mddocs/using/upgrade-db.mdmkdocs.yml
| | `docker_swarm.manifest_url` | `PGEDGE_DOCKER_SWARM__MANIFEST_URL` | string | pgEdge hosted manifest URL | Overrides the default version manifest URL. Set to an internal endpoint for air-gapped deployments or a staging URL for pre-release image testing. When set to a custom URL, the control plane falls back to the disk cache if the URL is unreachable, but does not fall back to the embedded manifest — an error is returned if both sources fail. | | | ||
| | `docker_swarm.manifest_path` | `PGEDGE_DOCKER_SWARM__MANIFEST_PATH` | string | | Path to a local version manifest file. When set, all remote URL fetching is skipped and the manifest is loaded exclusively from this file. Intended for air-gapped deployments where no outbound network access is available. See [Container Image Management](../using/image-management.md). | | |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Document configuration-source precedence for these settings.
The rows expose environment variables, while the page only states that configuration sources can be combined. Clarify that precedence is CLI flags > environment variables > config file so operators know which manifest URL/path wins when sources disagree.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/installation/configuration.md` around lines 50 - 51, Update the
documentation for docker_swarm.manifest_url and docker_swarm.manifest_path to
explicitly state configuration precedence: CLI flags override environment
variables, which override config-file values. Clarify that this order determines
which manifest URL or path is used when sources provide conflicting settings.
Source: Learnings
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/using/image-management.md (1)
274-280: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winClarify air-gapped support for image overrides.
manifest_pathonly skips remote manifest fetches;orchestrator_opts.swarm.imagestill requires a reachable registry for validation, so fully air-gapped deployments can only use manifest-selected images.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/using/image-management.md` around lines 274 - 280, Clarify the warning in the image-management documentation: explain that manifest_path only avoids remote manifest fetching, while orchestrator_opts.swarm.image still requires registry reachability for validation. State that fully air-gapped deployments must use images selected by the local manifest and pre-pull all referenced images on each host.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/using/image-management.md`:
- Around line 289-295: Update the image-resolution trigger list in the image
management documentation to include spock_version and every other database spec
field that influences image selection, alongside postgres_version and
orchestrator_opts.swarm.image. Ensure the documented behavior states that
changing any of these fields refreshes resolved_image.
- Around line 212-214: Update the image pinning example in the documentation to
use a complete valid 64-character SHA-256 digest, or replace the truncated value
with the explicit <sha256-digest> placeholder; do not leave the ellipsis in the
image reference.
- Around line 109-111: Update the upgrade discovery rule in the image-management
documentation to include candidates with a higher Spock version or build number,
not only a higher Postgres version. Keep the existing stable-manifest and
matching `(postgres_major, spock_major)` constraints, and align the wording with
the upgrade criteria documented in upgrade-db.md.
---
Outside diff comments:
In `@docs/using/image-management.md`:
- Around line 274-280: Clarify the warning in the image-management
documentation: explain that manifest_path only avoids remote manifest fetching,
while orchestrator_opts.swarm.image still requires registry reachability for
validation. State that fully air-gapped deployments must use images selected by
the local manifest and pre-pull all referenced images on each host.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: c52a395c-d6fe-4503-b159-b997fba35329
📒 Files selected for processing (4)
docs/installation/configuration.mddocs/installation/installation.mddocs/using/image-management.mddocs/using/upgrade-db.md
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/installation/installation.md
- docs/installation/configuration.md
7cabe88 to
dc7a682
Compare
6b7c3ee to
d8252ea
Compare
| | `etcd_client.log_level` | `PGEDGE_ETCD_CLIENT__LOG_LEVEL` | string | `fatal` | The log level for Etcd client operations performed by this Control Plane server. | | | ||
| | `docker_swarm.image_repository_host` | `PGEDGE_DOCKER_SWARM__IMAGE_REPOSITORY_HOST` | string | `ghcr.io/pgedge` | **(Docker Swarm only)** The base URL of pgEdge Docker images. | | | ||
| | `docker_swarm.image_repository_host` | `PGEDGE_DOCKER_SWARM__IMAGE_REPOSITORY_HOST` | string | `ghcr.io/pgedge` | The base URL of pgEdge Docker images. | | | ||
| | `docker_swarm.manifest_url` | `PGEDGE_DOCKER_SWARM__MANIFEST_URL` | string | pgEdge hosted manifest URL | Overrides the default version manifest URL. Set to an internal endpoint for air-gapped deployments or a staging URL for pre-release image testing. When set to a custom URL, the control plane falls back to the disk cache if the URL is unreachable, but does not fall back to the embedded manifest - an error is returned if both sources fail. | | |
There was a problem hiding this comment.
I think we usually capitalize Control Plane...
Control Plane was in lowercase; updated to match other uses.
susan-pgedge
left a comment
susan-pgedge
left a comment
There was a problem hiding this comment.
The only change I've made is converting one occurrence of control plane to Control Plane.
3 participants
Summary
This PR adds end-user and internal documentation explaining how the Control Plane manages container images, including the version manifest, custom image overrides, validation rules, available upgrades, and offline/air-gapped deployment configuration.
Changes
docs/using/image-management.md— full image lifecycle: manifest resolution order, checking available upgrades, per-database and per-node image overrides, digest-pinned images, validation rules with error examples, and image persistence behaviourdocs/installation/configuration.md— adddocker_swarm.manifest_urlanddocker_swarm.manifest_pathto the optional settings tabledocs/installation/installation.md— add "Version Manifest" section covering offline/air-gapped setup viamanifest_pathandmanifest_urldocs/using/upgrade-db.md— add "Image Upgrades" section with?include=available_upgradesandPOST /v1/databases/{id}/upgradeexamplesmkdocs.yml— register the new page in the nav under "Using Control Plane"internal-design-docs/control-plane/2026-07-15-testing-version-manifest.md— runbook for adding new manifest entries, local dev testing, publishing to downloads.pgedge.com, and a validation checklistTesting
Verification:
Checklist
PLAT-673