Skip to content

Commit 00feef1

Browse files
aj-emerichaj-emerich
committed
docs(kvm): update descriptions
1 parent b0ee0fa commit 00feef1

File tree

6 files changed

+158
-40
lines changed

6 files changed

+158
-40
lines changed

‎src/main/java/io/kestra/plugin/kvm/CreateVm.java‎

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -77,19 +77,31 @@
7777
)
7878
}
7979
)
80-
@Schema(title = "Create VM")
80+
@Schema(
81+
title = "Create or update KVM domain",
82+
description = "Defines a libvirt domain from rendered XML, creating it if it doesn't exist and keeping configuration in sync. Can optionally boot the VM when startAfterCreate is true (default false); requires access to the target libvirt URI."
83+
)
8184
public class CreateVm extends AbstractKvmTask implements RunnableTask<CreateVm.Output> {
8285

83-
@Schema(title = "VM Name")
86+
@Schema(
87+
title = "Domain name",
88+
description = "VM name used for lookup and definition; should match the <name> element in the XML."
89+
)
8490
@NotNull
8591
private Property<String> name;
8692

87-
@Schema(title = "XML Definition")
93+
@Schema(
94+
title = "Domain XML",
95+
description = "Full libvirt domain XML template rendered with flow variables before being sent to defineXML."
96+
)
8897
@NotNull
8998
private Property<String> xmlDefinition;
9099

91100
@Builder.Default
92-
@Schema(title = "Start after create")
101+
@Schema(
102+
title = "Start after define",
103+
description = "If true, boots the VM after definition when it isn't already running. Default false."
104+
)
93105
private Property<Boolean> startAfterCreate = Property.ofValue(false);
94106

95107
@Override
@@ -127,13 +139,22 @@ public Output run(RunContext runContext) throws Exception {
127139
@Builder
128140
@Getter
129141
public static class Output implements io.kestra.core.models.tasks.Output {
130-
@Schema(title = "VM Name")
142+
@Schema(
143+
title = "VM Name",
144+
description = "Defined domain name."
145+
)
131146
private String name;
132147

133-
@Schema(title = "VM UUID")
148+
@Schema(
149+
title = "VM UUID",
150+
description = "Persistent libvirt UUID of the domain."
151+
)
134152
private String uuid;
135153

136-
@Schema(title = "VM State")
154+
@Schema(
155+
title = "VM State",
156+
description = "Libvirt domain state after definition and optional start."
157+
)
137158
private String state;
138159
}
139160
}

‎src/main/java/io/kestra/plugin/kvm/DeleteVm.java‎

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -48,18 +48,30 @@
4848
)
4949
}
5050
)
51-
@Schema(title = "Delete VM")
51+
@Schema(
52+
title = "Delete or undefine KVM domain",
53+
description = "Looks up a libvirt domain by name, stops it if running, and undefines it. Can also delete attached storage volumes parsed from the domain XML when deleteStorage is true (default false). Fails when the domain is missing unless failIfNotFound is set to false (default true)."
54+
)
5255
public class DeleteVm extends AbstractKvmTask implements RunnableTask<DeleteVm.Output> {
53-
@Schema(title = "VM Name")
56+
@Schema(
57+
title = "Domain name",
58+
description = "Name of the libvirt domain to delete."
59+
)
5460
@NotNull
5561
private Property<String> name;
5662

5763
@Builder.Default
58-
@Schema(title = "Delete Storage")
64+
@Schema(
65+
title = "Delete storage volumes",
66+
description = "If true, deletes volumes referenced in the domain XML by pool/name before undefine. Default false."
67+
)
5968
private Property<Boolean> deleteStorage = Property.ofValue(false);
6069

6170
@Builder.Default
62-
@Schema(title = "Fail if VM not found")
71+
@Schema(
72+
title = "Fail if missing",
73+
description = "If true, throws when the domain does not exist; if false, logs a warning and continues. Default true."
74+
)
6375
private Property<Boolean> failIfNotFound = Property.ofValue(true);
6476

6577
@Override
@@ -138,10 +150,16 @@ private List<String> findAndDeleteVolumes(Domain domain, Connect conn, RunContex
138150
@Builder
139151
@Getter
140152
public static class Output implements io.kestra.core.models.tasks.Output {
141-
@Schema(title = "Result of the delete operation")
153+
@Schema(
154+
title = "Delete succeeded",
155+
description = "True when the domain was found and undefined; false when skipped."
156+
)
142157
private boolean success;
143158

144-
@Schema(title = "List of deleted volumes")
159+
@Schema(
160+
title = "Deleted volumes",
161+
description = "Volume identifiers removed when deleteStorage is true."
162+
)
145163
private List<String> deletedVolumes;
146164
}
147165
}

‎src/main/java/io/kestra/plugin/kvm/StartVm.java‎

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -44,18 +44,30 @@
4444
)
4545
}
4646
)
47-
@Schema(title = "Start VM")
47+
@Schema(
48+
title = "Start a KVM domain",
49+
description = "Boots a libvirt domain if it isn't already running. Can optionally wait until the domain reaches RUNNING state using exponential retry up to timeToWait (default PT60S). Requires access to the target libvirt URI."
50+
)
4851
public class StartVm extends AbstractKvmTask implements RunnableTask<StartVm.Output> {
49-
@Schema(title = "VM Name")
52+
@Schema(
53+
title = "Domain name",
54+
description = "Name of the libvirt domain to start."
55+
)
5056
@NotNull
5157
private Property<String> name;
5258

5359
@Builder.Default
54-
@Schema(title = "Wait for Running state")
60+
@Schema(
61+
title = "Wait for RUNNING",
62+
description = "If true, polls domain state until RUNNING or timeout. Default false."
63+
)
5564
private Property<Boolean> waitForRunning = Property.ofValue(false);
5665

5766
@Builder.Default
58-
@Schema(title = "Time to wait")
67+
@Schema(
68+
title = "Max wait duration",
69+
description = "Maximum time to wait for RUNNING when waitForRunning is true. Default PT60S."
70+
)
5971
private Property<Duration> timeToWait = Property.ofValue(Duration.ofSeconds(60));
6072

6173
@Override
@@ -142,10 +154,16 @@ public Output run(RunContext runContext) throws Exception {
142154
@Builder
143155
@Getter
144156
public static class Output implements io.kestra.core.models.tasks.Output {
145-
@Schema(title = "VM Name")
157+
@Schema(
158+
title = "VM Name",
159+
description = "Started domain name."
160+
)
146161
private String name;
147162

148-
@Schema(title = "VM State")
163+
@Schema(
164+
title = "VM State",
165+
description = "Libvirt domain state after the start attempt."
166+
)
149167
private String state;
150168
}
151169
}

‎src/main/java/io/kestra/plugin/kvm/StopVm.java‎

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -43,22 +43,37 @@
4343
)
4444
}
4545
)
46-
@Schema(title = "Stop VM")
46+
@Schema(
47+
title = "Stop or shutdown KVM domain",
48+
description = "Sends a shutdown or hard power-off (force) to a libvirt domain. Can optionally wait until the domain reaches SHUTOFF using exponential retry up to timeToWait (default PT60S). Requires access to the target libvirt URI."
49+
)
4750
public class StopVm extends AbstractKvmTask implements RunnableTask<StopVm.Output> {
48-
@Schema(title = "VM Name")
51+
@Schema(
52+
title = "Domain name",
53+
description = "Name of the libvirt domain to stop."
54+
)
4955
@NotNull
5056
private Property<String> name;
5157

5258
@Builder.Default
53-
@Schema(title = "Force Stop")
59+
@Schema(
60+
title = "Force power off",
61+
description = "If true, calls destroy (hard power off); otherwise uses graceful shutdown. Default false."
62+
)
5463
private Property<Boolean> force = Property.ofValue(false);
5564

5665
@Builder.Default
57-
@Schema(title = "Wait for Stopped state")
66+
@Schema(
67+
title = "Wait for SHUTOFF",
68+
description = "If true, polls until the domain is SHUTOFF or timeout. Default false."
69+
)
5870
private Property<Boolean> waitForStopped = Property.ofValue(false);
5971

6072
@Builder.Default
61-
@Schema(title = "Time to wait")
73+
@Schema(
74+
title = "Max wait duration",
75+
description = "Maximum time to wait for SHUTOFF when waitForStopped is true. Default PT60S."
76+
)
6277
private Property<Duration> timeToWait = Property.ofValue(Duration.ofSeconds(60));
6378

6479
@Override
@@ -151,10 +166,16 @@ public Output run(RunContext runContext) throws Exception {
151166
@Builder
152167
@Getter
153168
public static class Output implements io.kestra.core.models.tasks.Output {
154-
@Schema(title = "VM Name")
169+
@Schema(
170+
title = "VM Name",
171+
description = "Stopped domain name."
172+
)
155173
private String name;
156174

157-
@Schema(title = "VM State")
175+
@Schema(
176+
title = "VM State",
177+
description = "Libvirt domain state after the stop attempt."
178+
)
158179
private String state;
159180
}
160181
}

‎src/main/java/io/kestra/plugin/kvm/UpdateVm.java‎

Lines changed: 29 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -72,16 +72,28 @@
7272
)
7373
}
7474
)
75-
@Schema(title = "Update VM")
75+
@Schema(
76+
title = "Update KVM domain definition",
77+
description = "Redefines a libvirt domain from rendered XML while preserving the existing UUID if missing in the template. Optionally restarts running or paused domains to apply changes when restart is true (default false)."
78+
)
7679
public class UpdateVm extends AbstractKvmTask implements RunnableTask<UpdateVm.Output> {
77-
@Schema(title = "VM Name")
80+
@Schema(
81+
title = "Domain name",
82+
description = "Domain to redefine; should match the <name> in the XML."
83+
)
7884
private Property<String> name;
7985

80-
@Schema(title = "XML Definition")
86+
@Schema(
87+
title = "Domain XML",
88+
description = "Libvirt domain XML template rendered with flow variables before defineXML; UUID is injected when absent."
89+
)
8190
private Property<String> xmlDefinition;
8291

8392
@Builder.Default
84-
@Schema(title = "Restart VM")
93+
@Schema(
94+
title = "Restart after update",
95+
description = "If true, destroys then starts the domain when it is RUNNING or PAUSED to apply changes. Default false."
96+
)
8597
private Property<Boolean> restart = Property.ofValue(false);
8698

8799
@Override
@@ -128,13 +140,22 @@ public Output run(RunContext runContext) throws Exception {
128140
@Builder
129141
@Getter
130142
public static class Output implements io.kestra.core.models.tasks.Output {
131-
@Schema(title = "VM Name")
143+
@Schema(
144+
title = "VM Name",
145+
description = "Redefined domain name."
146+
)
132147
private String name;
133148

134-
@Schema(title = "Indicates whether the VM restart completed successfully.")
149+
@Schema(
150+
title = "Restart performed",
151+
description = "True when the domain was destroyed and started due to restart = true."
152+
)
135153
private Boolean wasRestarted;
136154

137-
@Schema(title = "VM State")
155+
@Schema(
156+
title = "VM State",
157+
description = "Libvirt domain state after the update."
158+
)
138159
private String state;
139160
}
140-
}
161+
}

‎src/main/java/io/kestra/plugin/kvm/VmEventTrigger.java‎

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -54,16 +54,29 @@
5454
)
5555
}
5656
)
57-
@Schema(title = "VM Event Trigger")
57+
@Schema(
58+
title = "Poll KVM domain state",
59+
description = "Polling trigger that connects to libvirt on the given URI, reads a domain's state on each interval, and emits an execution with the name and current state. Logs and skips when lookup fails."
60+
)
5861
public class VmEventTrigger extends AbstractTrigger implements PollingTriggerInterface, TriggerOutput<VmEventTrigger.Output> {
5962

6063
@Builder.Default
64+
@Schema(
65+
title = "Poll interval",
66+
description = "Time between state checks. Default PT1M."
67+
)
6168
private Duration interval = Duration.ofMinutes(1);
6269

63-
@Schema(title = "Libvirt URI")
70+
@Schema(
71+
title = "Libvirt URI",
72+
description = "Connection URI rendered before use; required to reach the hypervisor."
73+
)
6474
protected Property<String> uri;
6575

66-
@Schema(title = "VM Name")
76+
@Schema(
77+
title = "Domain name",
78+
description = "Name of the libvirt domain to monitor."
79+
)
6780
@NotNull
6881
private Property<String> name;
6982

@@ -97,10 +110,16 @@ public Optional<Execution> evaluate(ConditionContext conditionContext, TriggerCo
97110
@Builder
98111
@Getter
99112
public static class Output implements io.kestra.core.models.tasks.Output {
100-
@Schema(title = "VM Name")
113+
@Schema(
114+
title = "VM Name",
115+
description = "Monitored domain name."
116+
)
101117
private String name;
102118

103-
@Schema(title = "VM State")
119+
@Schema(
120+
title = "VM State",
121+
description = "Libvirt domain state at the time of polling."
122+
)
104123
private String state;
105124
}
106-
}
125+
}

0 commit comments

Comments
 (0)