HYPERFLEET-1216 - feat: migrate helmfile to OCI chart distribution #80
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,191 @@ | ||
| # Bumping Chart Versions | ||
|
|
||
| This guide explains how to update HyperFleet component chart versions for deployments. | ||
|
|
||
| ## Overview | ||
|
|
||
| HyperFleet component charts (API, Sentinel, Adapter) are published as OCI artifacts to Quay on every merge to main in their respective repos. This infrastructure repo consumes those charts from: | ||
|
|
||
| ``` | ||
| oci://quay.io/redhat-services-prod/hyperfleet-tenant/hyperfleet/ | ||
| ``` | ||
|
|
||
| ## Chart Version Variables | ||
|
|
||
| Three environment variables control which chart versions are deployed: | ||
|
|
||
| | Variable | Default | Component | | ||
| |----------|---------|-----------| | ||
| | `API_CHART_VERSION` | `` (empty) | hyperfleet-api-chart | | ||
| | `SENTINEL_CHART_VERSION` | `` (empty) | hyperfleet-sentinel-chart | | ||
| | `ADAPTER_CHART_VERSION` | `` (empty) | hyperfleet-adapter-chart | | ||
|
|
||
|
|
||
| These are defined in `helmfile/helmfile.yaml.gotmpl` and can be overridden via environment variables or `env.gcp`/`env.kind`. | ||
|
|
||
| **Default Behavior (empty/unset)**: By default, the version is empty, which tells Helm to pull the latest semantic version available in the OCI registry. This maintains the same "always up-to-date" behavior as the previous helm-git setup with `ref=main`. Helm automatically selects the highest SemVer tag. | ||
|
|
||
| **Pinning to a Specific Version**: For production deployments or when you need to test a specific chart version, set the variable to a SemVer version like `0.3.1`. | ||
| ## Listing Available Versions | ||
|
|
||
| ### Via Quay UI | ||
|
|
||
| Browse to: | ||
| - https://quay.io/repository/redhat-services-prod/hyperfleet-tenant/hyperfleet/hyperfleet-api-chart?tab=tags | ||
| - https://quay.io/repository/redhat-services-prod/hyperfleet-tenant/hyperfleet/hyperfleet-sentinel-chart?tab=tags | ||
| - https://quay.io/repository/redhat-services-prod/hyperfleet-tenant/hyperfleet/hyperfleet-adapter-chart?tab=tags | ||
|
|
||
| ### Via CLI | ||
|
|
||
| ```bash | ||
| # List all tags for a chart | ||
| skopeo list-tags docker://quay.io/redhat-services-prod/hyperfleet-tenant/hyperfleet/hyperfleet-api-chart | ||
|
|
||
| # List recent tags (last 10) | ||
| skopeo list-tags docker://quay.io/redhat-services-prod/hyperfleet-tenant/hyperfleet/hyperfleet-api-chart | jq -r '.Tags[]' | sort -V | tail -10 | ||
| ``` | ||
|
|
||
| ## Bumping Versions | ||
|
|
||
| ### Option 1: Override via CLI (temporary, one-time) | ||
|
|
||
| ```bash | ||
| # Upgrade all three charts to 0.3.2 | ||
| API_CHART_VERSION=0.3.2 \ | ||
| SENTINEL_CHART_VERSION=0.3.2 \ | ||
| ADAPTER_CHART_VERSION=0.3.2 \ | ||
| make install-hyperfleet | ||
| ``` | ||
|
|
||
| ### Option 2: Update env.gcp or env.kind (persistent for local dev) | ||
|
|
||
| Edit `env.gcp` or `env.kind`: | ||
|
|
||
| ```bash | ||
| # Add or update these lines | ||
| export API_CHART_VERSION=0.3.2 | ||
| export SENTINEL_CHART_VERSION=0.3.2 | ||
| export ADAPTER_CHART_VERSION=0.3.2 | ||
| ``` | ||
|
|
||
| Then deploy normally: | ||
|
|
||
| ```bash | ||
| make install-hyperfleet | ||
| ``` | ||
|
|
||
| ### Option 3: Update helmfile defaults (permanent, affects all users) | ||
|
|
||
| Edit `helmfile/helmfile.yaml.gotmpl`: | ||
|
|
||
| ```yaml | ||
| values: | ||
| - charts: | ||
| api: | ||
| version: {{ env "API_CHART_VERSION" | default "0.3.2" }} | ||
| sentinel: | ||
| version: {{ env "SENTINEL_CHART_VERSION" | default "0.3.2" }} | ||
| adapter: | ||
| version: {{ env "ADAPTER_CHART_VERSION" | default "0.3.2" }} | ||
| ``` | ||
|
|
||
| Commit and create a PR. After merge, all users get the new defaults. | ||
|
|
||
| ## Upgrade Strategy | ||
|
|
||
| ### Coordinated Release (recommended) | ||
|
|
||
| When all three component repos publish the same version: | ||
|
|
||
| ```bash | ||
| # Single version bump for all charts | ||
| export CHART_VERSION=0.3.2 | ||
| API_CHART_VERSION=$CHART_VERSION \ | ||
| SENTINEL_CHART_VERSION=$CHART_VERSION \ | ||
| ADAPTER_CHART_VERSION=$CHART_VERSION \ | ||
| make install-hyperfleet | ||
| ``` | ||
|
|
||
| ### Independent Versioning | ||
|
|
||
| When components have different versions (e.g., hotfix for API only): | ||
|
|
||
| ```bash | ||
| # Bump only API chart | ||
| API_CHART_VERSION=0.3.2 make install-api | ||
|
|
||
| # Or bump all with different versions | ||
| API_CHART_VERSION=0.3.2 \ | ||
| SENTINEL_CHART_VERSION=0.3.1 \ | ||
| ADAPTER_CHART_VERSION=0.3.1 \ | ||
| make install-hyperfleet | ||
| ``` | ||
|
|
||
| ## Verification | ||
|
|
||
| After deploying with new chart versions: | ||
|
|
||
| ```bash | ||
| # Check deployed chart versions | ||
| helm list -n hyperfleet | ||
|
|
||
| # Inspect a specific release | ||
| helm get values hyperfleet-api -n hyperfleet | ||
|
|
||
| # Verify chart metadata | ||
| helm get metadata hyperfleet-api -n hyperfleet | ||
| ``` | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| ### Chart version not found | ||
|
|
||
| ``` | ||
| Error: failed to download "hyperfleet-charts/hyperfleet-api-chart" at version "0.3.2" | ||
| ``` | ||
|
|
||
| **Cause:** The requested chart version doesn't exist on Quay. | ||
|
|
||
| **Fix:** Verify the version exists using `skopeo list-tags` or the Quay UI. Check that the component repo's pipeline successfully published the chart. | ||
|
Comment on lines
+139
to
+145
There was a problem hiding this comment. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win Replace the removed Git chart reference. Line [140] still uses Use the exact OCI reference selected after registry-path verification. As per path instructions, flag broken user-facing documentation. 🧰 Tools🪛 markdownlint-cli2 (0.23.2)[warning] 139-139: Fenced code blocks should have a language specified (MD040, fenced-code-language) 🤖 Prompt for AI AgentsSource: Path instructions |
||
|
|
||
| ### Permission denied pulling chart | ||
|
|
||
| ``` | ||
| Error: GET "https://quay.io/v2/...": response status code 401: unauthorized | ||
| ``` | ||
|
|
||
| **Cause:** Quay repository is private or you're not authenticated. | ||
|
|
||
| **Fix:** Charts should be public. If private, authenticate: | ||
|
|
||
| ```bash | ||
| helm registry login quay.io -u <username> | ||
| ``` | ||
|
|
||
| ### Helm says "improper constraint" | ||
|
|
||
| ``` | ||
| Error: improper constraint: 0.1.515_aff8821 | ||
| ``` | ||
|
|
||
| **Cause:** Invalid version format. Helm expects SemVer (0.3.1), not commit-suffixed tags (0.1.515_aff8821). | ||
|
|
||
| **Fix:** Use the SemVer tag (0.3.1), not build metadata tags. | ||
|
|
||
| ## Rollback | ||
|
|
||
| To rollback to a previous chart version: | ||
|
|
||
| ```bash | ||
| # Rollback API to 0.3.0 | ||
| API_CHART_VERSION=0.3.0 make install-api | ||
|
|
||
| # Or rollback via helm directly | ||
| helm rollback hyperfleet-api -n hyperfleet | ||
|
Comment on lines
+171
to
+180
There was a problem hiding this comment. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- target document ---'
sed -n '1,220p' docs/bump-chart-versions.md
printf '%s\n' '--- Helm declarations and rollback references ---'
rg -n -i 'helm|helmfile|helmVersion|rollback|API_CHART_VERSION' \
--glob '!vendor/**' --glob '!node_modules/**' . | head -n 240Repository: openshift-hyperfleet/hyperfleet-infra Length of output: 28297 🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- declared Helm/toolchain references ---'
rg -n -i 'helm|helm version|helmVersion|rollback' \
--glob '!vendor/**' --glob '!node_modules/**' . | head -n 240Repository: openshift-hyperfleet/architecture Length of output: 41107 🏁 Script executed (no clone): Length of output: 46788 🏁 Script executed: #!/bin/bash
set -eu
sed -n '165,185p' docs/bump-chart-versions.md
rg -n -i 'helm|helmVersion|rollback' \
--glob '!vendor/**' --glob '!node_modules/**' . | head -n 240Repository: openshift-hyperfleet/hyperfleet-infra Length of output: 22395 🏁 Script executed: #!/bin/bash
set -eu
rg -n -i 'helm|helm version|helmVersion|rollback' \
--glob '!vendor/**' --glob '!node_modules/**' . | head -n 240Repository: openshift-hyperfleet/architecture Length of output: 43833 🏁 Script executed (no clone): Length of output: 46752 🏁 Script executed: #!/bin/bash
set -eu
python3 - <<'PY'
from pathlib import Path
doc = Path("docs/bump-chart-versions.md").read_text()
makefile = Path("Makefile").read_text()
helmfile = Path("helmfile/helmfile.yaml.gotmpl").read_text()
assert "API_CHART_VERSION=0.3.0 make install-api" in doc
assert "helm rollback hyperfleet-api -n hyperfleet" in doc
assert "install-api:" in makefile
assert "helmfile apply -f helmfile/helmfile.yaml.gotmpl" in makefile
assert 'version: {{ env "API_CHART_VERSION"' in helmfile
print("install-api invokes helmfile apply and the API chart version is supplied through API_CHART_VERSION")
print("helm rollback is a separate direct Helm command")
PYRepository: openshift-hyperfleet/hyperfleet-infra Length of output: 322 Document chart-version rollback separately from release-revision rollback.
🤖 Prompt for AI AgentsSource: Path instructions |
||
| ``` | ||
|
|
||
| ## Related | ||
|
|
||
| - Chart publishing pipeline: See `.tekton/` in component repos (hyperfleet-api, hyperfleet-sentinel, hyperfleet-adapter) | ||
| - Chart source: `charts/` directory in each component repo | ||
| - Epic: HYPERFLEET-831 (Helm OCI Distribution) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use the active deployment namespace.
The commands hardcode
hyperfleet.helmfile/helmfile.yaml.gotmplrequiresNAMESPACE, andREADME.mddocuments other values such ashyperfleet-localand e2e namespaces. These commands can inspect or roll back the wrong release.Use
-n "$NAMESPACE"after sourcing the active environment file.As per path instructions, validate cross-file deployment contracts and prioritize operational correctness over formatting.
Also applies to: 175-180
🤖 Prompt for AI Agents
Source: Path instructions