Skip to content

Commit 29495a2

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #6878 from fabriziopandini/improve-open-api-docs
🌱 Improve open API docs
2 parents 881b175 + be103c1 commit 29495a2

File tree

4 files changed

+98
-34
lines changed

4 files changed

+98
-34
lines changed

‎exp/runtime/catalog/openapi.go

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,15 @@ func (c *Catalog) OpenAPI(version string) (*spec3.OpenAPI, error) {
3737
Version: "3.0.0",
3838
Info: &spec.Info{
3939
InfoProps: spec.InfoProps{
40-
Description: "Open API specification for Cluster API Runtime SDK",
41-
Title: "Cluster API - Runtime SDK",
40+
Description: "This document defines the Open API specification of the services that Cluster API runtime is going " +
41+
"to call while managing the Cluster's lifecycle.\n" +
42+
"\n" +
43+
"Services described in this specification are also referred to as Runtime Hooks, given that they allow " +
44+
"external components to hook-in the cluster's lifecycle. The corresponding components implementing handlers " +
45+
"for Runtime Hooks calls are referred to as Runtime Extensions.\n" +
46+
"\n" +
47+
"More information is available in the [Cluster API book](https://cluster-api.sigs.k8s.io/).",
48+
Title: "Cluster API - Runtime SDK",
4249
License: &spec.License{
4350
Name: "Apache 2.0",
4451
URL: "http://www.apache.org/licenses/LICENSE-2.0.html",
@@ -88,9 +95,10 @@ func addHookAndTypesToOpenAPI(openAPI *spec3.OpenAPI, c *Catalog, gvh GroupVersi
8895
path = GVHToPath(gvh, "{name}")
8996
operation.Parameters = append(operation.Parameters, &spec3.Parameter{
9097
ParameterProps: spec3.ParameterProps{
91-
Name: "name",
92-
In: "path",
93-
Required: true,
98+
Name: "name",
99+
In: "path",
100+
Description: "The handler name. Handlers for the same hook within a single external component implementing Runtime Extensions must have different names",
101+
Required: true,
94102
Schema: &spec.Schema{
95103
SchemaProps: spec.SchemaProps{
96104
Type: []string{"string"},
@@ -131,7 +139,7 @@ func addHookAndTypesToOpenAPI(openAPI *spec3.OpenAPI, c *Catalog, gvh GroupVersi
131139
responseTypeName := typeName(responseType, responseGVK)
132140
operation.Responses.StatusCodeResponses[http.StatusOK] = &spec3.Response{
133141
ResponseProps: spec3.ResponseProps{
134-
Description: "OK",
142+
Description: "Status code 200 indicates that the request has been processed successfully. Runtime Extension authors must use fields in the response like e.g. status and message to return processing outcomes.",
135143
Content: createContent(responseTypeName),
136144
},
137145
}

‎exp/runtime/hooks/api/v1alpha1/discovery_types.go

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -91,9 +91,14 @@ func Discovery(*DiscoveryRequest, *DiscoveryResponse) {}
9191

9292
func init() {
9393
catalogBuilder.RegisterHook(Discovery, &runtimecatalog.HookMeta{
94-
Tags: []string{"Discovery"},
95-
Summary: "Discovery hook",
96-
Description: "Discovery hook discovers the supported hooks of a RuntimeExtension",
97-
Singleton: true,
94+
Tags: []string{"Discovery"},
95+
Summary: "Cluster API Runtime will call this hook when an ExtensionConfig is reconciled",
96+
Description: "Cluster API Runtime will call this hook when an ExtensionConfig is reconciled. " +
97+
"Runtime Extension implementers must use this hook to inform the Cluster API runtime about all the handlers " +
98+
"that are defined in an external component implementing Runtime Extensions.\n" +
99+
"\n" +
100+
"Notes:\n" +
101+
"- When using Runtime SDK utils, a handler for this hook is automatically generated",
102+
Singleton: true,
98103
})
99104
}

‎exp/runtime/hooks/api/v1alpha1/lifecyclehooks_types.go

Lines changed: 57 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -180,38 +180,77 @@ func BeforeClusterDelete(*BeforeClusterDeleteRequest, *BeforeClusterDeleteRespon
180180

181181
func init() {
182182
catalogBuilder.RegisterHook(BeforeClusterCreate, &runtimecatalog.HookMeta{
183-
Tags: []string{"Lifecycle Hooks"},
184-
Summary: "Called before Cluster topology is created.",
185-
Description: "This blocking hook is called after the Cluster is created by the user and immediately before all the objects which are part of a Cluster topology are going to be created.",
183+
Tags: []string{"Lifecycle Hooks"},
184+
Summary: "Cluster API Runtime will call this hook before a Cluster's topology is created",
185+
Description: "Cluster API Runtime will call this hook after the Cluster is created by the user and immediately before " +
186+
"all the objects which are part of a Cluster's topology are going to be created.\n" +
187+
"\n" +
188+
"Notes:\n" +
189+
"- This hook will be called only for Clusters with a managed topology\n" +
190+
"- The call's request contains the Cluster object\n" +
191+
"- This is a blocking hook; Runtime Extension implementers can use this hook to execute\n" +
192+
"tasks before the objects which are part of a Cluster's topology are created",
186193
})
187194

188195
catalogBuilder.RegisterHook(AfterControlPlaneInitialized, &runtimecatalog.HookMeta{
189-
Tags: []string{"Lifecycle Hooks"},
190-
Summary: "Called after the Control Plane is initialized for the first time.",
191-
Description: "This non-blocking hook is called after the Control Plane for the Cluster is reachable for the first time.",
196+
Tags: []string{"Lifecycle Hooks"},
197+
Summary: "Cluster API Runtime will call this hook after the control plane is reachable for the first time",
198+
Description: "Cluster API Runtime will call this hook after the control plane for the Cluster is reachable for the first time.\n" +
199+
"\n" +
200+
"Notes:\n" +
201+
"- This hook will be called only for Clusters with a managed topology\n" +
202+
"- This is a non-blocking hook",
192203
})
193204

194205
catalogBuilder.RegisterHook(BeforeClusterUpgrade, &runtimecatalog.HookMeta{
195-
Tags: []string{"Lifecycle Hooks"},
196-
Summary: "Called before the Cluster is upgraded.",
197-
Description: "This blocking hook is called after the Cluster object has been updated with a new spec.topology.version by the user, and immediately before the new version is propagated to the Control Plane.",
206+
Tags: []string{"Lifecycle Hooks"},
207+
Summary: "Cluster API Runtime will call this hook before the Cluster is upgraded",
208+
Description: "Cluster API Runtime will call this hook after the Cluster object has been updated with a new spec.topology.version by the user, " +
209+
"and immediately before the new version is propagated to the control plane.\n" +
210+
"\n" +
211+
"Notes:\n" +
212+
"- This hook will be called only for Clusters with a managed topology\n" +
213+
"- The call's request contains the Cluster object, the current Kubernetes version and the Kubernetes version we are upgrading to\n" +
214+
"- This is a blocking hook; Runtime Extension implementers can use this hook to execute " +
215+
"tasks before the new version is propagated to the control plane",
198216
})
199217

200218
catalogBuilder.RegisterHook(AfterControlPlaneUpgrade, &runtimecatalog.HookMeta{
201-
Tags: []string{"Lifecycle Hooks"},
202-
Summary: "Called after the Control Plane is upgraded.",
203-
Description: "This blocking hook is called after the Control Plane has been upgraded to the version specified in spec.topology.version, and immediately before the new version is propagated to the MachineDeployments.",
219+
Tags: []string{"Lifecycle Hooks"},
220+
Summary: "Cluster API Runtime will call this hook after the control plane is upgraded",
221+
Description: "Cluster API Runtime will call this hook after the a cluster's control plane has been upgraded to the version specified " +
222+
"in spec.topology.version, and immediately before the new version is going to be propagated to the MachineDeployments. " +
223+
"A control plane upgrade is completed when all the machines in the control plane have been upgraded.\n" +
224+
"\n" +
225+
"Notes:\n" +
226+
"- This hook will be called only for Clusters with a managed topology\n" +
227+
"- The call's request contains the Cluster object and the Kubernetes version we upgraded to\n" +
228+
"- This is a blocking hook; Runtime Extension implementers can use this hook to execute " +
229+
"tasks before the new version is propagated to the MachineDeployments",
204230
})
205231

206232
catalogBuilder.RegisterHook(AfterClusterUpgrade, &runtimecatalog.HookMeta{
207-
Tags: []string{"Lifecycle Hooks"},
208-
Summary: "Called after the Cluster is upgraded.",
209-
Description: "This non-blocking hook is called after the Cluster, Control Plane and MachineDeployments have been upgraded to the version specified in spec.topology.version.",
233+
Tags: []string{"Lifecycle Hooks"},
234+
Summary: "Cluster API Runtime will call this hook after a Cluster is upgraded",
235+
Description: "Cluster API Runtime will call this hook after a Cluster has been upgraded to the version specified " +
236+
"in spec.topology.version. An upgrade is completed when all control plane and MachineDeployment's Machines have been upgraded.\n" +
237+
"\n" +
238+
"Notes:\n" +
239+
"- This hook will be called only for Clusters with a managed topology\n" +
240+
"- The call's request contains the Cluster object and the Kubernetes version we upgraded to \n" +
241+
"- This is a non-blocking hook",
210242
})
211243

212244
catalogBuilder.RegisterHook(BeforeClusterDelete, &runtimecatalog.HookMeta{
213-
Tags: []string{"Lifecycle Hooks"},
214-
Summary: "Called before the Cluster is deleted.",
215-
Description: "This blocking hook is called after the Cluster deletion has been triggered by the user, and immediately before objects of the Cluster are going to be deleted.",
245+
Tags: []string{"Lifecycle Hooks"},
246+
Summary: "Cluster API Runtime will call this hook before the Cluster is deleted",
247+
Description: "Cluster API Runtime will call this hook after the Cluster deletion has been triggered by the user, " +
248+
"and immediately before objects of the Cluster are going to be deleted.\n" +
249+
"\n" +
250+
"Notes:\n" +
251+
"- This hook will be called only for Clusters with a managed topology\n" +
252+
"- The call's request contains the Cluster object \n" +
253+
"- This is a blocking hook; Runtime Extension implementers can use this hook to execute " +
254+
"tasks before objects of the Cluster are deleted",
216255
})
217256
}

‎exp/runtime/hooks/api/v1alpha1/topologymutation_types.go

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -175,14 +175,26 @@ func ValidateTopology(*ValidateTopologyRequest, *ValidateTopologyResponse) {}
175175

176176
func init() {
177177
catalogBuilder.RegisterHook(GeneratePatches, &runtimecatalog.HookMeta{
178-
Tags: []string{"Topology Mutation Hook"},
179-
Summary: "GeneratePatches generates patches during topology reconciliation for the entire Cluster topology.",
180-
Description: "A GeneratePatches call generates patches for the entire Cluster topology. Accordingly the request contains all templates, the global variables and the template-specific variables. The response contains generated patches.",
178+
Tags: []string{"Topology Mutation Hook"},
179+
Summary: "Cluster API Runtime will call this hook when a Cluster's topology is being computed",
180+
Description: "Cluster API Runtime will call this hook when a Cluster's topology is being computed " +
181+
"during each topology controller reconcile loop. More specifically, this hook will be called " +
182+
"while computing patches to be applied on top of templates derived from the Cluster's ClusterClass.\n" +
183+
"\n" +
184+
"Notes:\n" +
185+
"- The call's request contains all templates, the global variables and the template-specific variables required to compute patches\n" +
186+
"- The response must contain generated patches",
181187
})
182188

183189
catalogBuilder.RegisterHook(ValidateTopology, &runtimecatalog.HookMeta{
184-
Tags: []string{"Topology Mutation Hook"},
185-
Summary: "ValidateTopology validates the Cluster topology after all patches have been applied.",
186-
Description: "A ValidateTopology call validates the Cluster topology after all patches have been applied. The request contains all templates of the Cluster topology, the global variables and the template-specific variables. The response contains the result of the validation.",
190+
Tags: []string{"Topology Mutation Hook"},
191+
Summary: "Cluster API Runtime will call this hook after a Cluster's topology has been computed",
192+
Description: "Cluster API Runtime will call this hook after a Cluster's topology has been computed " +
193+
"during each topology controller reconcile loop. More specifically, this hook will be called " +
194+
"after all patches have been applied to the templates derived from the Cluster's ClusterClass.\n" +
195+
"\n" +
196+
"Notes:\n" +
197+
"- The call's request contains all templates, the global variables and the template-specific variables used while computing patches\n" +
198+
"- The response must contain the result of the validation",
187199
})
188200
}

0 commit comments

Comments
 (0)