Skip to content

Commit b5b2ca6

Browse files
morri-sonmorri-son
authored
Merge branch 'main' into create-new-security-docs
Signed-off-by: Gerald Morrison <67469729+morri-son@users.noreply.github.com>
2 parents 27c7c6f + ef663ee commit b5b2ca6

File tree

2 files changed

+170
-0
lines changed

2 files changed

+170
-0
lines changed

‎.github/config/wordlist.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -474,3 +474,5 @@ xdg
474474
subpaths
475475
iam
476476
ocirepository
477+
pullable
478+
descriptor's

‎content/docs/how-to/transfer-helm-charts.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
title: "Transfer Helm Charts with OCM"
3+
description: "Transfer component versions containing Helm chart resources between OCI registries using the OCM CLI."
4+
weight: 110
5+
toc: true
6+
---
7+
8+
## Goal
9+
10+
Transfer a component version that contains a Helm chart resource sourced from a **Helm repository** (type `helmChart` with `helm/v1` access)
11+
to an OCI registry. This guide does not cover charts that are already stored as OCI artifacts.
12+
13+
## Prerequisites
14+
15+
- [OCM CLI]({{< relref "docs/getting-started/ocm-cli-installation.md" >}}) installed
16+
- Write access to a target OCI registry with [credentials configured]({{< relref "docs/how-to/configure-multiple-credentials.md" >}})
17+
- A component version containing a Helm chart resource (stored in a CTF archive or OCI registry)
18+
19+
## Steps
20+
21+
{{< steps >}}
22+
23+
{{<callout context="note" title="Helm charts stored as ociImage" icon="outline/info-circle">}}
24+
If your existing component version contains a Helm chart stored as an `ociImage` resource rather than a `helmChart` with `helm/v1` access, you need to
25+
create a new component version using the `helmChart` type as shown below. This guide only covers the transfer of Helm charts sourced from Helm
26+
repositories.
27+
{{< /callout >}}
28+
29+
{{< step >}}
30+
31+
### Create a component version with a Helm chart resource
32+
33+
If you already have a component version containing a Helm chart with `helm/v1` access, skip to the next step.
34+
35+
Create a `constructor.yaml` that references a chart from a Helm repository:
36+
37+
```yaml
38+
components:
39+
- name: example.com/my-app
40+
version: 1.0.0
41+
provider:
42+
name: example.com
43+
resources:
44+
- name: my-chart
45+
version: 1.0.0
46+
type: helmChart
47+
access:
48+
type: helm/v1
49+
helmRepository: https://charts.example.com
50+
helmChart: my-chart-1.0.0.tgz
51+
```
52+
53+
Add the component version to a CTF archive:
54+
55+
```bash
56+
ocm add cv --repository ctf::<path/to/archive> \
57+
--constructor constructor.yaml \
58+
--skip-reference-digest-processing
59+
```
60+
61+
{{< /step >}}
62+
63+
{{<callout context="caution" title="Why --skip-reference-digest-processing?" icon="outline/alert-triangle">}}
64+
The `--skip-reference-digest-processing` flag is required because the `helm/v1` access type currently cannot be fully resolved during `add cv`.
65+
The chart is not downloaded at this stage, so digest calculation is not possible. The digests are computed later during transfer when the chart is
66+
actually fetched.
67+
Full Helm support is being tracked as a future feature in [ocm-project#911](https://github.com/open-component-model/ocm-project/issues/911).
68+
{{< /callout >}}
69+
70+
{{< step >}}
71+
72+
### Transfer the component version
73+
74+
Transfer the component version to the target registry. Use `--copy-resources` to include the Helm chart and `--upload-as ociArtifact` to store it as a
75+
standalone OCI artifact in the target registry.
76+
77+
> **Note:** The `--upload-as` flag is a temporary solution. It will be superseded by the upcoming transfer specification.
78+
> See [ocm-project#925](https://github.com/open-component-model/ocm-project/issues/925) for details.
79+
80+
```bash
81+
ocm transfer cv \
82+
--copy-resources \
83+
--upload-as ociArtifact \
84+
ctf::<path/to/archive>//<component-name>:<version> \
85+
<target-registry>
86+
```
87+
88+
During transfer, the Helm chart is always converted to an OCI artifact. With `--upload-as ociArtifact`,
89+
this artifact is uploaded as a separate image in the target registry.
90+
The component descriptor references it via an `imageReference` (e.g., `ghcr.io/my-org/charts/my-chart:1.0.0`),
91+
making it independently addressable and pullable with `helm pull`. For more details on how transfers and resource handling work,
92+
see [Transfer and Transport]({{< relref "docs/concepts/transfer-concept.md" >}}).
93+
94+
Alternatively, `--upload-as localBlob` embeds the chart directly in the component version's blob store.
95+
This keeps the chart coupled to the component version but means it is not independently addressable in the registry and cannot be pulled with the Helm
96+
CLI.
97+
98+
To find the `imageReference`, inspect the component descriptor:
99+
100+
```bash
101+
ocm get cv <target-registry>//<component-name>:<version> -o yaml
102+
```
103+
104+
In the output, look for the `resources[].access.imageReference` field:
105+
106+
```yaml
107+
resources:
108+
- name: my-chart
109+
type: helmChart
110+
access:
111+
type: ociArtifact/v1
112+
imageReference: ghcr.io/my-org/charts/my-chart:1.0.0
113+
```
114+
115+
Use the `imageReference` value with Helm's OCI support:
116+
117+
```bash
118+
helm pull oci://ghcr.io/my-org/charts/my-chart --version 1.0.0
119+
```
120+
121+
{{< /step >}}
122+
{{< step >}}
123+
124+
### Verify the transfer
125+
126+
Confirm the component version is available in the target registry:
127+
128+
```bash
129+
ocm get cv <target-registry>//<component-name>:<version>
130+
```
131+
132+
Download the chart resource to verify it was transferred correctly:
133+
134+
```bash
135+
ocm download resource \
136+
<target-registry>//<component-name>:<version> \
137+
--identity name=my-chart \
138+
--output ./downloaded
139+
```
140+
141+
{{< /step >}}
142+
{{< /steps >}}
143+
144+
## Transfer between registries
145+
146+
To transfer a Helm chart component version from one OCI registry to another, use the source registry reference directly:
147+
148+
```bash
149+
ocm transfer cv \
150+
--copy-resources \
151+
--upload-as ociArtifact \
152+
<source-registry>//<component-name>:<version> \
153+
<target-registry>
154+
```
155+
156+
## Tips
157+
158+
- **If provenance files (`.prov`) are present** in the Helm repository, they are automatically included in the transfer.
159+
- **If you need to transfer recursively**, add `--recursive` to include all transitively referenced component versions.
160+
- **For air-gapped environments**, first transfer to a CTF archive, move it across the boundary, then import into the target registry.
161+
See [Transfer Components Across an Air Gap]({{< relref "docs/how-to/air-gap-transfer.md" >}}).
162+
163+
## Related documentation
164+
165+
- [Transfer and Transport]({{< relref "docs/concepts/transfer-concept.md" >}}) -- Understand the transfer model and resource handling
166+
- [Transfer Components Across an Air Gap]({{< relref "docs/how-to/air-gap-transfer.md" >}}) -- Air-gapped transfer workflows
167+
- [Download Resources from Component Versions]({{< relref "docs/how-to/download-resources-from-component-versions.md" >}}) -- Download individual
168+
resources

0 commit comments

Comments
 (0)