conventions-server.yaml

openapi: 3.0.0
info:
  title: Pod convention webhook
  description: |
    This API defines the expected request and response format from the conventions server. 
  version: 1.0.0-alpha.1   
  license:
    name: Apache-2.0
    url: "https://www.apache.org/licenses/LICENSE-2.0.html"
paths:
  /webhook:
    post:  
      description: |
        The path defined above is arbitrary and can be overridden to any value by the ClusterPodConvention resource. 
        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. 
        The webhook request and response both use the PodConventionContext with the request defining 
        the .spec and the response defining the status.
        status 
      requestBody:
        content:
           "application/json":
              schema: 
               $ref: "#/components/schemas/PodConventionContext"
      responses:
        200:
          description: expected response once all conventions are applied successfully. 
          content: 
            "application/json":
              schema:
               $ref: "#/components/schemas/PodConventionContext"
        400:
          description: | 
            return code 400 if the request body is nil or if unable to to decode request body into a PodConventionContext. 
        500:
          description: |
           return code 500 if unable to apply conventions at all. 

components:
  schemas:
    PodConventionContext:
      description: | 
        A wrapper for the PodConventionContextSpec and the PodConventionContextStatus which is the structure used for both requests 
        and responses from the convention server.
      type: object
      properties:
        apiVersion: 
          type: string
        kind: 
          type: string
        metadata:
          type: object 
          additionalProperties: true 
          properties:
            name: 
              type: string
        spec:
          $ref: "#/components/schemas/PodConventionContextSpec"
        status:
          $ref: "#/components/schemas/PodConventionContextStatus"
    PodConventionContextSpec:
      type: object
      description: a wrapper of the PodTemplateSpec and list of ImageConfigs provided in the request body of the server.
      properties:
        template:
          $ref: "#/components/schemas/PodTemplateSpec"
        imageConfig:
          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. 
          type: array 
          items:
            $ref: "#/components/schemas/ImageConfig"
    PodTemplateSpec:
      type: object 
      properties:
        spec: 
          type: object
          additionalProperties: true
          description: defines the PodTemplateSpec to be enriched by conventions.
        metadata:
          type: object
          additionalProperties: true
          properties:
            name:
              type: string 
            additionalProperties: true 
    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"
        config: 
          type: object 
          description: OCI image metadata
          additionalProperties: true
    BOM: 
      type: object 
      properties:
        name: 
          description: bom-name
          type: string 
        raw: 
          description: base64 encoded bytes with the encoded content of the BOM.
          type: string
      example: | 
        {
          "name": "bom-name",
          "raw": "c29tZSBieXRlIGFycmF5"
        }
    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: a list of string with names of conventions to be applied
          type: array 
          items:
            type: string 
          example: |
              "appliedConventions": [ 
                "convention-1", 
                "convention-2",
                "convention-4" 
              ]