Skip to content

Commit 9dbd385

Browse files
rabirabi
committed
docs: Add procedure for configuring custom Heat resource plugins
Add documentation describing how to deploy custom Heat resource plugins using extraMounts to extend the orchestration service with custom resource types. Change-Id: I021341a509929b268c75f3afda8ab12af61625dd Signed-off-by: rabi <ramishra@redhat.com>
1 parent a38d13d commit 9dbd385

2 files changed

Lines changed: 171 additions & 0 deletions

File tree

‎docs/assemblies/prc_configuring-custom-heat-resource-plugins.adoc‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
[id="prc_configuring-custom-heat-resource-plugins_{context}"]
2+
= Configuring custom Heat resource plugins
3+
4+
[role="_abstract"]
5+
You can deploy custom Heat resource plugins to extend the orchestration service with custom resource types. This procedure uses the `extraMounts` feature to mount plugin files into the heat-engine pods. For information about writing Heat plugins, refer to the upstream Heat documentation.
6+
7+
.Prerequisites
8+
9+
* A deployed OpenStack control plane with Heat enabled.
10+
* Access to the OpenShift cluster with `oc` CLI.
11+
* Your custom Heat plugin Python file(s).
12+
13+
== Procedure
14+
15+
Create a `ConfigMap` containing your plugin files and mount it into the heat-engine pods using `extraMounts`.
16+
17+
. Create a `ConfigMap` containing your custom Heat plugin:
18+
+
19+
----
20+
apiVersion: v1
21+
kind: ConfigMap
22+
metadata:
23+
name: heat-custom-plugins
24+
namespace: openstack
25+
data:
26+
my_custom_resource.py: |
27+
<your_plugin_code>
28+
----
29+
+
30+
* Replace `<your_plugin_code>` with your custom Heat plugin Python code.
31+
32+
. Apply the `ConfigMap`:
33+
+
34+
----
35+
$ oc apply -f heat-custom-plugins-configmap.yaml
36+
----
37+
38+
. Patch the `OpenStackControlPlane` CR to add `extraMounts` to the Heat section:
39+
+
40+
----
41+
$ oc patch openstackcontrolplane <controlplane_name> -n openstack --type=merge -p '
42+
spec:
43+
heat:
44+
template:
45+
extraMounts:
46+
- name: custom-plugins
47+
extraVol:
48+
- extraVolType: heat-plugins
49+
volumes:
50+
- name: heat-custom-plugins
51+
configMap:
52+
name: heat-custom-plugins
53+
mounts:
54+
- name: heat-custom-plugins
55+
mountPath: /usr/lib/heat
56+
readOnly: true
57+
propagation:
58+
- HeatEngine
59+
'
60+
----
61+
+
62+
* Replace `<controlplane_name>` with your `OpenStackControlPlane` CR name.
63+
64+
. Wait for the heat-engine pods to restart:
65+
+
66+
----
67+
$ oc rollout status deployment/heat-engine -n openstack
68+
----
69+
70+
. Verify the plugin files are mounted in the heat-engine pod:
71+
+
72+
----
73+
$ oc exec deployment/heat-engine -n openstack -- ls -la /usr/lib/heat/
74+
----
75+
76+
. Verify the custom resource type is available:
77+
+
78+
----
79+
$ oc rsh -n openstack openstackclient openstack orchestration resource type list | grep <resource_type>
80+
----
81+
+
82+
* Replace `<resource_type>` with the resource type name defined in your plugin.
83+
84+
== Using a PersistentVolumeClaim for plugins larger than 1 MiB
85+
86+
If your plugin files exceed the 1 MiB `ConfigMap` size limit, use a `PersistentVolumeClaim` (PVC) instead.
87+
88+
.Procedure
89+
90+
. Create a `PersistentVolumeClaim`:
91+
+
92+
----
93+
apiVersion: v1
94+
kind: PersistentVolumeClaim
95+
metadata:
96+
name: heat-custom-plugins
97+
namespace: openstack
98+
spec:
99+
accessModes:
100+
- ReadWriteOnce
101+
resources:
102+
requests:
103+
storage: 1Gi
104+
----
105+
106+
. Apply the PVC:
107+
+
108+
----
109+
$ oc apply -f heat-custom-plugins-pvc.yaml
110+
----
111+
112+
. Copy your plugin files to the PVC using a temporary pod:
113+
+
114+
----
115+
$ oc run copy-plugins --image=registry.access.redhat.com/ubi9/ubi-minimal --restart=Never \
116+
--overrides='{"spec":{"containers":[{"name":"copy-plugins","image":"registry.access.redhat.com/ubi9/ubi-minimal","command":["sleep","3600"],"volumeMounts":[{"name":"plugins","mountPath":"/plugins"}]}],"volumes":[{"name":"plugins","persistentVolumeClaim":{"claimName":"heat-custom-plugins"}}]}}' \
117+
-n openstack
118+
$ oc wait --for=condition=Ready pod/copy-plugins -n openstack
119+
$ oc cp <local_plugin_path> openstack/copy-plugins:/plugins/
120+
$ oc delete pod copy-plugins -n openstack
121+
----
122+
+
123+
* Replace `<local_plugin_path>` with the path to your plugin file or folder.
124+
125+
. Patch the `OpenStackControlPlane` CR to add `extraMounts` to the Heat section:
126+
+
127+
----
128+
$ oc patch openstackcontrolplane <controlplane_name> -n openstack --type=merge -p '
129+
spec:
130+
heat:
131+
template:
132+
extraMounts:
133+
- name: custom-plugins
134+
extraVol:
135+
- extraVolType: heat-plugins
136+
volumes:
137+
- name: heat-custom-plugins
138+
persistentVolumeClaim:
139+
claimName: heat-custom-plugins
140+
mounts:
141+
- name: heat-custom-plugins
142+
mountPath: /usr/lib/heat
143+
readOnly: true
144+
propagation:
145+
- HeatEngine
146+
'
147+
----
148+
+
149+
* Replace `<controlplane_name>` with your `OpenStackControlPlane` CR name.
150+
151+
. Wait for the heat-engine pods to restart:
152+
+
153+
----
154+
$ oc rollout status deployment/heat-engine -n openstack
155+
----
156+
157+
. Verify the plugin files are mounted in the heat-engine pod:
158+
+
159+
----
160+
$ oc exec deployment/heat-engine -n openstack -- ls -la /usr/lib/heat/
161+
----
162+
163+
. Verify the custom resource type is available:
164+
+
165+
----
166+
$ oc rsh -n openstack openstackclient openstack orchestration resource type list | grep <resource_type>
167+
----
168+
+
169+
* Replace `<resource_type>` with the resource type name defined in your plugin.

‎docs/ctlplane.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,4 +134,6 @@ UnDeploy the controller to the cluster:
134134
make undeploy
135135
----
136136

137+
include::assemblies/prc_configuring-custom-heat-resource-plugins.adoc[leveloffset=+1]
138+
137139
include::assemblies/ctlplane_resources.adoc[leveloffset=-1]

0 commit comments

Comments
 (0)