Skip to content

Commit c771259

Browse files
medmesmedmes
committed
update the doc
1 parent 710f091 commit c771259

File tree

1 file changed

+148
-158
lines changed

1 file changed

+148
-158
lines changed

‎docs/contributor/14-creating-moduletemplate.md‎

Lines changed: 148 additions & 158 deletions
Original file line numberDiff line numberDiff line change
@@ -5,177 +5,167 @@ This guide describes how to create ModuleTemplate custom resources using [module
55
## Overview
66

77
ModuleTemplate creation involves two main steps:
8-
1. **Generate component descriptor and ModuleTemplate manifest** using modulectl
9-
2. **Push component descriptor to OCI registry** using OCM CLI
8+
9+
1. Generate a component descriptor and ModuleTemplate manifest using modulectl.
10+
2. Push the component descriptor to the OCI registry** using OCM CLI.
1011

1112
At runtime, Kyma Lifecycle Manager fetches component descriptors dynamically from the OCI registry based on the `ModuleReleaseMeta.Spec.OcmComponentName` and `ModuleTemplate.Spec.Version`.
1213

1314
## Prerequisites
1415

15-
- [modulectl](https://github.com/kyma-project/modulectl) installed (check the recommended version in the [versions.yaml](../../versions.yaml) file in the root of the repository)
16+
- [modulectl](https://github.com/kyma-project/modulectl) installed
1617
- [OCM CLI](https://github.com/open-component-model/ocm) installed
1718
- Access to an OCI registry (local or remote)
1819

19-
## 1. Configure OCM Registry Access
20-
21-
Create an OCM configuration file to define registry aliases and enable communication with your target registry.
22-
23-
### For Local Registries
24-
25-
If using a local registry (e.g., `localhost:5111`):
26-
27-
```yaml
28-
# ocm-config-local.yaml
29-
type: generic.config.ocm.software/v1
30-
configurations:
31-
- type: ocm.config.ocm.software
32-
aliases:
33-
localhost:5111:
34-
type: OCIRegistry
35-
baseUrl: http://localhost:5111
36-
- type: oci.config.ocm.software
37-
aliases:
38-
localhost:5111:
39-
type: OCIRegistry
40-
baseUrl: http://localhost:5111
41-
```
42-
43-
### For Private Registries with Authentication
44-
45-
```yaml
46-
# ocm-config-private.yaml
47-
type: generic.config.ocm.software/v1
48-
configurations:
49-
- type: ocm.config.ocm.software
50-
aliases:
51-
europe-docker.pkg.dev:
52-
type: OCIRegistry
53-
baseUrl: https://europe-docker.pkg.dev
54-
- type: credentials.config.ocm.software
55-
consumers:
56-
- identity:
57-
type: OCIRegistry
58-
hostname: europe-docker.pkg.dev
59-
credentials:
60-
- type: Credentials
61-
properties:
62-
username: _json_key
63-
password: |
64-
{
65-
"type": "service_account",
66-
...
67-
}
68-
```
69-
70-
## 2. Generate Component Constructor
71-
72-
Use `modulectl create` to generate the component constructor file without pushing to registry:
73-
74-
```bash
75-
modulectl create \
76-
--config-file module-config.yaml \
77-
--disable-ocm-registry-push \
78-
--output-constructor-file component-constructor.yaml
79-
```
80-
81-
**Key parameters:**
82-
- `--config-file`: Path to your module configuration (defines resources, images, etc.)
83-
- `--disable-ocm-registry-push`: Generate component constructor without pushing to registry
84-
- `--output-constructor-file`: Output file for the component constructor
85-
86-
This generates:
87-
- `component-constructor.yaml` - OCM component constructor file
88-
- `template.yaml` - The ModuleTemplate CR to apply to the cluster
89-
90-
## 3. Add Component Version to CTF Archive
91-
92-
Add the component version from the constructor file to a Common Transport Format (CTF) archive:
93-
94-
```bash
95-
ocm --config ocm-config-local.yaml add componentversions \
96-
--create \
97-
--file ./component-ctf \
98-
--skip-digest-generation \
99-
component-constructor.yaml
100-
```
101-
102-
**Parameters:**
103-
- `--config`: Path to OCM configuration file (for registry access)
104-
- `add componentversions`: Add component versions to the CTF archive
105-
- `--create`: Create the CTF archive directory if it doesn't exist
106-
- `--file`: Path where CTF archive will be created (directory)
107-
- `--skip-digest-generation`: Skip automatic digest generation (for faster processing)
108-
- Final argument: Path to the component constructor file
109-
110-
This creates a CTF archive in the `./component-ctf` directory containing the component descriptor and all referenced resources.
111-
112-
## 4. Transfer CTF to OCI Registry
113-
114-
Transfer the complete CTF archive to the OCI registry:
115-
116-
```bash
117-
ocm --config ocm-config-local.yaml transfer ctf \
118-
--overwrite \
119-
--no-update \
120-
./component-ctf \
121-
http://localhost:5111
122-
```
123-
124-
**Parameters:**
125-
- `--config`: Path to OCM configuration file
126-
- `transfer ctf`: Transfer command for CTF archives
127-
- `--overwrite`: Overwrite existing component versions in the registry
128-
- `--no-update`: Don't update component references during transfer
129-
- `./component-ctf`: Path to the source CTF archive directory
130-
- `http://localhost:5111`: Target OCI registry URL
131-
132-
This pushes the component descriptor and all resources from the CTF to the OCI registry.
133-
134-
## 5. Apply ModuleTemplate to Cluster
135-
136-
Apply the generated ModuleTemplate manifest:
137-
138-
```bash
139-
yq -i '.metadata.namespace="kcp-system"' template.yaml
140-
kubectl apply -f template.yaml
141-
```
142-
143-
## 6. Create ModuleReleaseMeta
144-
145-
Create a ModuleReleaseMeta CR to make the module available:
146-
147-
```yaml
148-
apiVersion: operator.kyma-project.io/v1beta2
149-
kind: ModuleReleaseMeta
150-
metadata:
151-
name: template-operator
152-
namespace: kcp-system
153-
spec:
154-
moduleName: template-operator
155-
ocmComponentName: kyma-project.io/module/template-operator
156-
channels:
157-
- channel: regular
158-
version: 1.0.4
159-
```
160-
161-
Apply it:
162-
163-
```bash
164-
kubectl apply -f module-release-meta.yaml
165-
```
20+
## Procedure
21+
22+
1. Create an OCM configuration file to define registry aliases and enable communication with your target registry.
23+
24+
a. For local registries, such as `localhost:5111`, use:
25+
26+
```yaml
27+
# ocm-config-local.yaml
28+
type: generic.config.ocm.software/v1
29+
configurations:
30+
- type: ocm.config.ocm.software
31+
aliases:
32+
localhost:5111:
33+
type: OCIRegistry
34+
baseUrl: http://localhost:5111
35+
- type: oci.config.ocm.software
36+
aliases:
37+
localhost:5111:
38+
type: OCIRegistry
39+
baseUrl: http://localhost:5111
40+
```
41+
42+
b. For private registries with authentication, use:
43+
44+
```yaml
45+
# ocm-config-private.yaml
46+
type: generic.config.ocm.software/v1
47+
configurations:
48+
- type: ocm.config.ocm.software
49+
aliases:
50+
europe-docker.pkg.dev:
51+
type: OCIRegistry
52+
baseUrl: https://europe-docker.pkg.dev
53+
- type: credentials.config.ocm.software
54+
consumers:
55+
- identity:
56+
type: OCIRegistry
57+
hostname: europe-docker.pkg.dev
58+
credentials:
59+
- type: Credentials
60+
properties:
61+
username: _json_key
62+
password: |
63+
{
64+
"type": "service_account",
65+
...
66+
}
67+
```
68+
69+
2. Use `modulectl create` to generate the component constructor file without pushing to the registry.
70+
71+
```bash
72+
modulectl create \
73+
--config-file module-config.yaml \
74+
--disable-ocm-registry-push \
75+
--output-constructor-file component-constructor.yaml
76+
```
77+
78+
**Key parameters:**
79+
- `--config-file`: The path to your module configuration (defines resources, images, etc.)
80+
- `--disable-ocm-registry-push`: Generates component constructor without pushing to registry
81+
- `--output-constructor-file`: The output file for the component constructor
82+
83+
The command generates:
84+
- `component-constructor.yaml`: The OCM component constructor file
85+
- `template.yaml`: The ModuleTemplate CR to apply to the cluster
86+
87+
3. Add the component version from the constructor file to a Common Transport Format (CTF) archive.
88+
89+
```bash
90+
ocm --config ocm-config-local.yaml add componentversions \
91+
--create \
92+
--file ./component-ctf \
93+
--skip-digest-generation \
94+
component-constructor.yaml
95+
```
96+
97+
**Key parameters:**
98+
- `--config`: The path to the OCM configuration file (for registry access)
99+
- `add componentversions`: Adds component versions to the CTF archive
100+
- `--create`: Creates the CTF archive directory if it doesn't exist
101+
- `--file`: The path where the CTF archive is created (directory)
102+
- `--skip-digest-generation`: Skips automatic digest generation (for faster processing)
103+
- `component-constructor.yaml`: The path to the component constructor file
104+
105+
The command creates a CTF archive in the `./component-ctf` directory containing the component descriptor and all referenced resources.
106+
107+
4. Transfer the complete CTF archive to the OCI registry.
108+
109+
```bash
110+
ocm --config ocm-config-local.yaml transfer ctf \
111+
--overwrite \
112+
--no-update \
113+
./component-ctf \
114+
http://localhost:5111
115+
```
116+
117+
**Key parameters:**
118+
- `--config`: The path to the OCM configuration file
119+
- `transfer ctf`: Transfers command for CTF archives
120+
- `--overwrite`: Overwrites the existing component versions in the registry
121+
- `--no-update`: Prevents updating component references during transfer
122+
- `./component-ctf`: The path to the source CTF archive directory
123+
- `http://localhost:5111`: The target OCI registry URL
124+
125+
The command pushes the component descriptor and all resources from the CTF to the OCI registry.
126+
127+
5. Apply the generated ModuleTemplate manifest in the cluster.
128+
129+
```bash
130+
yq -i '.metadata.namespace="kcp-system"' template.yaml
131+
kubectl apply -f template.yaml
132+
```
133+
134+
6. Create a ModuleReleaseMeta CR to make the module available.
135+
136+
```yaml
137+
apiVersion: operator.kyma-project.io/v1beta2
138+
kind: ModuleReleaseMeta
139+
metadata:
140+
name: template-operator
141+
namespace: kcp-system
142+
spec:
143+
moduleName: template-operator
144+
ocmComponentName: kyma-project.io/module/template-operator
145+
channels:
146+
- channel: regular
147+
version: 1.0.4
148+
```
149+
150+
To apply the CR, run:
151+
152+
```bash
153+
kubectl apply -f module-release-meta.yaml
154+
```
166155

167156
## Runtime Behavior
168157

169-
When a Kyma CR requests a module:
170-
1. Lifecycle Manager reads `ModuleReleaseMeta` to get the OCM component name and version
171-
2. Fetches the component descriptor from the OCI registry using these identifiers
172-
3. Parses the descriptor to extract image references and resources
173-
4. Deploys the module based on the descriptor content
158+
When a Kyma CR requests a module, Lifecycle Manager:
159+
1. Reads `ModuleReleaseMeta` to get the OCM component name and version.
160+
2. Fetches the component descriptor from the OCI registry using these identifiers.
161+
3. Parses the descriptor to extract image references and resources.
162+
4. Deploys the module based on the descriptor content.
174163

175-
> **Note:** The `spec.descriptor` field in ModuleTemplate is deprecated and not used at runtime. Component descriptors are always fetched from the OCI registry.
164+
> ### Note
165+
> The `spec.descriptor` field in ModuleTemplate is deprecated and not used at runtime. Component descriptors are always fetched from the OCI registry.
176166

177-
## See Also
167+
## Related Information
178168

179-
- [ModuleTemplate CR Reference](resources/03-moduletemplate.md)
169+
- [ModuleTemplate CR Reference](./resources/03-moduletemplate.md)
180170
- [modulectl Documentation](https://github.com/kyma-project/modulectl)
181171
- [OCM CLI Documentation](https://github.com/open-component-model/ocm)

0 commit comments

Comments
 (0)