Add detail on how to configure the webhook path

Signed-off-by: Jackline Mutua <[email protected]>
vmware-tanzu · Apr 21, 2022 · 1096ace · 1096ace
1 parent a81c519
commit 1096ace
Show file tree

Hide file tree

Showing 2 changed files with 12 additions and 28 deletions.
diff --git a/api/openapi-spec/conventions-server.yaml b/api/openapi-spec/conventions-server.yaml
@@ -2,7 +2,9 @@ openapi: 3.0.0
 info:
   title: Conventions Server API
   description: |
-    This API must be implemented in order to relay conventions to be be applied.
+    This API defines the expected request and response format from the conventions server. The webhook path can be configured in the ClusterPodConvention 
+    on either .spec.webhook.clientConfig.url or .spec.webhook.clientConfig.service.path with the later preferred if the 
+    convention server is to run on the same cluster as workoads.
   version: 1.0.0-alpha.1   
   license:
     name: Apache-2.0
@@ -17,23 +19,16 @@ paths:
                $ref: "#/components/schemas/PodConventionContext"
       responses:
         200:
-          description: Return a succes message once all conventions are applied successfully
+          description: Expected response once all conventions are applied successfully
           content: 
             "application/json":
               schema:
                $ref: "#/components/schemas/PodConventionContext"
         400:
           description: Return an error if unable to decode request body into a PodConventionContext type or if request body is nil. 
-          content:
-            "application/json":
-              schema:
-                $ref: "#/components/schemas/ErrorResponse"
         500:
-          description: Internal server error
-          content:
-            "application/json":
-              schema:
-                $ref: "#/components/schemas/ErrorResponse"
+          description: Return an error if unable to apply conventions.
+
 components:
   schemas:
     PodConventionContext:
@@ -82,12 +77,10 @@ components:
           properties:
             annotations:
               type: object
-              additionalProperties:
-                type: string
+              additionalProperties: true 
             labels:
               type: object
-              additionalProperties:
-                type: string
+              additionalProperties: true
     ImageConfig:
       type: object 
       properties: 
@@ -135,16 +128,4 @@ components:
                 "convention-1", 
                 "convention-2",
                 "convention-4" 
-              ]        
-    Error:
-      type: object
-      properties:
-        message:
-          type: string
-          example: "Some unexpected error"
-
-    ErrorResponse:
-      type: object 
-      properties:
-        error:
-          $ref: "#/components/schemas/Error"
+              ] 
diff --git a/docs/design.md b/docs/design.md
@@ -241,6 +241,9 @@ In the future other mechanisms may be defined to provide conventions other than
 #### Webhook Helper Library  
 
 Extentions author can define convention by creating a webhook server which is registered with the controller via the `ClusterPodConvention` resource. The webhook server can be written in any programming language. See the [Open API Specification](/api/openapi-spec/conventions-server.yaml) that defines how to to create your own conventions server. 
+
+The webhook path can be configured by setting the ClusterPoodConvention's `.spec.webhook.clientConfig.url` or `.spec.webhook.clientConfig.service.path`. If the convention server is to be deployed in the same cluster as your target workloads, then the service path is preferred.
+
 Go developers can use a [helper library](https://pkg.go.dev/github.com/vmware-tanzu/cartographer-conventions/webhook) that streamlines handling the http response for the webhook.
 
 ## Lifecycle