[docs] Convention Server Open API spec

api/openapi-spec/conventions-server.yaml

@@ -0,0 +1,151 @@
+openapi: 3.0.0
+info:
+  title: Conventions server 
+  description: a sample conventions server.
+  version: 1.0.0        
+  license:
+    name: Apache-2.0
+    url: "https://www.apache.org/licenses/LICENSE-2.0.html"
+paths:
+  /webhook:
+    post:  
+      requestBody:
+        content:
+           "application/json":
+              schema: 
+               $ref: "#/components/schemas/PodConventionContext"
+      responses:
+        200:
+          description: Return a succes message 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"
+components:
+  schemas:
+    PodConventionContext:
+      description: | 
+        A wrapper for the PodConventionContextSpec and the PodConventionContextStatus. The PodConventionContext as defined in the API object 
+        webhooks.conventions.carto.run/v1alpha1 API group is the structure used for both request and response from the convention server.
+      type: object
+      properties:
+        apiVersion: 
+          type: string
+        kind: 
+          type: string
+        metadata:
+          type: object 
+          properties:
+            name: 
+              type: string
+        spec:
+          $ref: "#/components/schemas/PodConventionContextSpec"
+        status:
+          $ref: "#/components/schemas/PodConventionContextStatus"
+    PodConventionContextSpec:
+      type: object
+      description: a wrapper of the PodTemplateSpec and the ImageConfig provided in the request body of the server.
+      properties:
+        template:
+          $ref: "#/components/schemas/PodTemplateSpec"
+        imageConfig:
+          type: array 
+          description: |
+            an array of imageConfig objects with each image configuration object holding the name of the image, the BOM, and the OCI image
+            configuration with image metadata from the repository. Each of the image config array entries have a 1:1 mapping to 
+            images referenced in the PodTemplateSpec. 
+          items:
+            $ref: "#/components/schemas/ImageConfig"
+    PodTemplateSpec:
+      type: object 
+      properties:
+        spec: 
+          type: object
+          description: defines the PodTemplateSpec to be enriched by conventions.
+        metadata:
+          type: object
+          properties:
+            annotations:
+              type: object
+              additionalProperties:
+                type: string
+            labels:
+              type: object
+              additionalProperties:
+                type: string
+    ImageConfig:
+      type: object 
+      properties: 
+        image: 
+          type: string 
+          description: a string reference to the image name and tag or associated digest.
+          example: "example.com/repository/nginx:alpine"
+        BOMs:
+          type: array
+          description: | 
+            an array of Bills of Materials (BOMs) describing the software components and their dependencies and may be zero or more per image.
+          items:
+            $ref: "#/components/schemas/BOM"
+          example: | 
+            "boms": [{
+                "name": "bom-name",
+                "raw": "a byte array"
+            }],
+        config: 
+          type: object 
+          description: a ggcrv1 config file object.
+    BOM: 
+      type: object 
+      properties:
+        name: 
+          description: bom-name
+          type: string 
+        raw: 
+          description: a base64 encoded string with the encoded content of the BOM.
+          type: string
+      example: | 
+        {
+          "name": "bom-name",
+          "raw": "some byte array"
+        }
+    PodConventionContextStatus:
+      description: status type used to represent the current status of the context retrieved by the request.
+      type: object 
+      properties:
+        template: 
+          $ref: "#/components/schemas/PodTemplateSpec"
+        appliedConventions:
+          description: list of names of conventions applied
+          type: array 
+          items:
+            type: string
+          example: |
+              "appliedConventions": [ 
+                "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"

docs/design.md

@@ -12,6 +12,7 @@
     - [PodIntent (conventions.carto.run/v1alpha1)](#podintent-conventionscartorunv1alpha1)
     - [ClusterPodConvention (conventions.carto.run/v1alpha1)](#clusterpodconvention-conventionscartorunv1alpha1)
     - [PodConventionContext (webhooks.conventions.carto.run/v1alpha1)](#podconventioncontext-webhooksconventionscartorunv1alpha1)
+  - [Webhook Helper Library](#webhook-helper-library) 
 - [Lifecycle](#lifecycle)
   - [Security](#security)
   - [Supportability](#supportability)
@@ -237,6 +238,18 @@ status: # the response
 
 In the future other mechanisms may be defined to provide conventions other than webhooks. In particular, mechanisms that are safe to execute within the controller process like a YTT overlay or WebAssembly. Each mechanism will define the specifics of its own contract similar in scope to the `PodConventionContext`.
 
+#### Webhook Helper Library  
+
+An extentions author can provide a set of conventions to the conventions controller in various ways. One way to do this, is by creating a webhook which 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. Applied conventions defined in the conventions server implementation created by a extensions author need to be defined as pure functions.
+
+_Go Spring Boot example_
+
+In the`go` [springboot conventions example](/samples/spring-convention-server/) implementation provided in the `/samples` directory, the author has defined a set of conventions to be applied to a spring boot application using a webhook which is registered as follows:-   
+  ```
+  http.HandleFunc("/", webhook.ConventionHandler(ctx, addSpringBootConventions))
+  ```
+  The convention controller handler function expects a `context Context` and applied conventions which are provided as a function called `addSpringBootConventions`. This function defines conventions to be applied to any springboot application.
+
 ## Lifecycle 
 
 Cartographer Conventions lives entirely within the user space of a Kubernetes cluster. It can be installed, upgraded and removed like any other CRDs with a controller. Upgrade instructions will be included with each release.