Asset-Inventory-OpenAPI-0.8.9.yaml

openapi: 3.0.0
info:
  title: Kessel Asset Inventory API 
  description: Kessel Asset Inventory
  version: 0.8.9

servers:
  - url: https://console.redhat.com
tags:
  - name: hosts
    description: Everything about hosts
  - name: k8s_clusters
    description: Everything about kube clusters
  - name: policies
    description: Everything about policies
  - name: relationships
    description: Everything about relationships between resources   
paths:
  /v1beta1/resources/hosts:
    description: Create a RHEL Host in Kessel Asset Inventory
    post:
      tags:
        - hosts
      summary: Create a RHEL Host in Kessel Asset Inventory
      operationId: createRHELHostinKessel
      requestBody:
        description: |-
           The RHEL Host to create in Kessel Asset Inventory
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RHELHost"
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RHELHost"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized (really unauthenticated)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden (really unauthorized)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v1beta1/resources/hosts/{resource}:
    description: Manage a RHEL Host in Kessel Asset Inventory
    parameters:
      - name: resource
        in: path
        schema:
          type: string
        required: true
        description: |-
          A resource instance using the format:
          "<reporter_data.reporter_type>:<reporter_data.reporter_id>::<reporter_data.resourceId_alias>"

    delete:
      summary: Delete a RHEL Host from Kessel Asset Inventory. The {resource} format "<reporter_data.reporter_type>:<reporter_data.reporter_id>::<reporter_data.resourceId_alias>". This delete operation will also delete any resource relationships that include this RHEL Host.
      tags:
        - hosts
      operationId: deleteRHELHost
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized (really unauthenticated)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden (really unauthorized)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    put:
      summary: Update a RHEL Host from Kessel Asset Inventory. The {resource} format "<reporter_data.reporter_type>:<reporter_data.reporter_id>::<reporter_data.resourceId_alias>".
      tags:
        - hosts
      operationId: updateRHELHost
      requestBody:
        description: The RHEL host to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RHELHost"
      responses:
        "204":
          description: No content
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized (really unauthenticated)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden (really unauthorized)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v1beta1/resources/k8s_clusters:
    description: Create a k8s cluster in Kessel Asset Inventory
   
    post:
      summary: Create a k8s cluster in Kessel Asset Inventory
      tags:
        - k8s_clusters
      operationId: createK8sClusterinKessel
      requestBody:
        description: |-
           The k8s cluster to create in Kessel Asset Inventory
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/K8sCluster"
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema:
               $ref: "#/components/schemas/K8sCluster"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized (really unauthenticated)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden (really unauthorized)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v1beta1/resources/k8s_clusters/{resource}:
    description: Manage a k8s cluster in Kessel Asset Inventory
    parameters:
      - name: resource
        in: path
        schema:
          type: string
        required: true
        description: |-
          The {resource} format "<reporter_data.reporter_type>:<reporter_data.reporter_id>::<reporter_data.resourceId_alias>".
    delete:
      summary: Delete a k8s cluster from Kessel Asset Inventory. The {resource} format "<reporter_data.reporter_type>:<reporter_data.reporter_id>::<reporter_data.resourceId_alias>". This will also delete any resource relationships that included this Cluster.
      tags:
        - k8s_clusters
      operationId: deleteK8sCluster
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized (really unauthenticated)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden (really unauthorized)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    put:
      summary: Update a k8s cluster in Kessel Asset Inventory. The {resource} format "<reporter_data.reporter_type>:<reporter_data.reporter_id>::<reporter_data.resourceId_alias>".
      tags:
        - k8s_clusters
      operationId: updateK8sCluster
      requestBody:
        description: The k8s clsuter to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/K8sCluster"
      responses:
        "204":
          description: No content
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized (really unauthenticated)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden (really unauthorized)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"


  /v1beta1/resources/policies:
    description: Create a policy in Kessel Asset Inventory
   
    post:
      summary: Create a policy in Kessel Asset Inventory
      tags:
        - policies
      operationId: createPolicyinKessel
      requestBody:
        description: |-
           The policy to create in Kessel Asset Inventory
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Policy"
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Policy"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized (really unauthenticated)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden (really unauthorized)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v1beta1/resources/policies/{resource}:
    description: Manage a Policy in Kessel Asset Inventory
    parameters:
      - name: resource
        in: path
        schema:
          type: string
        required: true
        description: |-
          The {resource} format "<reporter_data.reporter_type>:<reporter_data.reporter_id>::<reporter_data.resourceId_alias>".
    delete:
      summary: Delete a policy from Kessel Asset Inventory. The {resource} format "<reporter_data.reporter_type>:<reporter_data.reporter_id>::<reporter_data.resourceId_alias>". This will also delete any resource relationships that included this policy.
      tags:
        - policies
      operationId: deletePolicy
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized (really unauthenticated)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden (really unauthorized)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    put:
      summary: Update a policy from Kessel Asset Inventory. The {resource} format "<reporter_data.reporter_type>:<reporter_data.reporter_id>::<reporter_data.resourceId_alias>".
      tags:
        - policies
      operationId: updatePolicy
      requestBody:
        description: The Policy to update in Kessel Asset Inventory
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Policy"
      responses:
        "204":
          description: No content
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized (really unauthenticated)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden (really unauthorized)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"        

 
  /v1beta1/resource_relationships/propagated:
    description: Create a Policy propagation relationship in Kessel Asset Inventory 
   
    post:
      summary: Create a Policy propagation relationship in Kessel Asset Inventory
      tags:
        - relationships
      operationId: createPolicyRelationshipinKessel
      requestBody:
        description: |-
           The resource relationship to create in Kessel Asset Inventory
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PolicyRelationship"
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PolicyRelationship"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized (really unauthenticated)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden (really unauthorized)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"


  /v1beta1/resource_relationships/propagated/{resources}:
    description: Manage Policy propagation relationship in Kessel Asset Inventory by the subject resource and the object resource. A relationship is between a Subject and an Object, e.g. a Policy (subject) has a propagated relationship to an k8s cluster (object).  
    parameters:
      -  name: resources
         in: path
         style: simple
         schema:
          type: object
          properties:
            subject_resource: 
               type: string
            object_resource: 
               type: string
         required: true
         description: |-
          The subject {resource} and the object {resource}. A relationship is between a Subject and an Object, e.g. a Policy (subject) has a propagated relationship to an k8s cluster (object)
    delete:
      summary: Delete a resource relationship from Kessel Asset Inventory by the {subject resource, object resource}. A relationship is between a Subject and an Object, e.g. a Policy (subject) has a propagated relationship to an k8s cluster (object).. The {resource} format "<reporter_data.reporter_type>:<reporter_data.reporter_id>::<reporter_data.resourceId_alias>". 
      tags:
        - relationships
      operationId: deleteResourceRelationshipByURN
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized (really unauthenticated)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden (really unauthorized)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    put:
      summary: Update a resource relationship from Kessel Asset Inventory by the subject URN and the object URN. A relationship is between a Subject and an Object, e.g. a Policy (subject) has a propagated relationship to an k8s cluster (object).. The {resource} format "<reporter_data.reporter_type>:<reporter_data.reporter_id>::<reporter_data.resourceId_alias>".
      tags:
        - relationships
      operationId: updateResourceRelationshipByURNHs
      requestBody:
        description: Update a resource relationship in Kessel Asset Inventory by the {subject resource, object resource}. A relationship is between a Subject and an Object, e.g. a Policy (subject) has a propagated relationship to an k8s cluster (object).. The {resource} format "<reporter_data.reporter_type>:<reporter_data.reporter_id>::<reporter_data.resourceId_alias>".  
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PolicyRelationship"
      responses:
        "204":
          description: No content
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized (really unauthenticated)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden (really unauthorized)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"    

components:
  schemas:
    ResourceTags:
      type: object
      description: |-
        Map of string keys and string values that can be used to organize and categorize
        (scope and select) resources
      properties:
        tags:
         type: array
         items:
           $ref: '#/components/schemas/ResourceTag'  
    ResourceTag:
       type: object
       properties:
          key:
            type: string
          value:
            type: string        
    ReporterData:
      type: object
      required:
        - reporter_type
        - reporter_alias
        - resourceid_alias
      properties:
        reporter_type:
          type: string
          enum:
            - ACM
            - HBI
            - OCM
            - Other
            - Unknown
        reporter_is:
          type: string
          # read only because this can be inferred from the path
          readOnly: true
          description: |-
            The ID of the instance of the reporter. This is derived from the authentication mechanism, i.e. authentication token. 
        console_href:
          type: string
          format: uri
          example: https://console-openshift-console.apps.bu-demo.bu.red-chesterfield.com/
          description: |-
            The URL for this resource in the reporter's management UI console. For example
            this would be the cluster URL in the HCC Console for an OCM reported cluster.
        api_href:
          type: string
          format: uri
          example: https://api.bu-demo.bu.red-chesterfield.com:6443
          description: |- 
             Reporter specific API link to the resource.
        resourceid_alias:
          type: string
          example: namctixyz36f
          description: |- 
             The ID assigned to this resource by the reporter, for example OCM cluster ID, HBI's host id, or ACM managed cluster name etc.
        reporter_version:
          type: string
          example: 2.12
          description: |- 
             version of the reporter
             
    CommonAttributes:
      type: object
      description: |-
         Attributes shared by all items in Kessel Asset Inventory
      required:
        - ReporterData
      properties:
        id:
          type: string
          readOnly: true
          description: |- 
             Kessel Asset Inventory generated identifier.
        resource_type:
          type: string
          # read only because this can be inferred from the path
          readOnly: true
          description: |-
            The type of the Resource.  This should match the segment of the URL path that is used to manage individual resources of the type; e.g., "k8s-cluster"
        first_reported:
          type: string
          readOnly: true
          format: date-time
          description: |- 
             Date and time when the inventory item was first reported.
        first_reported_by:
          type: string
          readOnly: true
          description: |- 
             Identification of the reporter that first reported this item.
        latest_reported:
          type: string
          readOnly: true
          format: date-time
          description: |- 
             Date and time when the inventory item was last updated.
        latest_reported_by:
          type: string
          readOnly: true
          description: |- 
             Id of the reporter that last reported on this item.
        workspace:
          type: string
          description: |-
            The workspace in which this resource is a member for access control.  A resource can only be a member of one workspace.
        reporter_data:
          type: object
          writeOnly: true
          description: Write only reporter specific data
          allOf:
            - $ref: '#/components/schemas/ReporterData'
        reporters:
          type: array
          readOnly: true
          description: |-
             The entities that registered this item in the Kessel Asset Inventory. The same resource may be registered by multiple reporters
          items:
            type: object
            properties:
              Type:
                type: string
                description: |-
                  The reporter type, for example, Satellite, ACM, OCM
                  The reporter type is authenticated during resource registration/update.
              reporter_instance_id:
                type: string
                description: |-
                  Identifies the reporter. This is meant to uniquely identify reporters that can have multiple instances running, such as ACM. The instance ID is authenticated during resource registration/update.
              created:
                type: string
                readOnly: true
                format: date-time
                description: |-
                   The time when this reporter record was created
              last_updated:
                type: string
                readOnly: true
                format: date-time
                description: |-
                   The time when this reporter record was updated

    RHELHost:
      allOf:
        - $ref: '#/components/schemas/CommonAttributes'
        - $ref: '#/components/schemas/ResourceTags'

    K8sCluster:
      allOf:
        - $ref: '#/components/schemas/CommonAttributes'
        - $ref: '#/components/schemas/ResourceTags'
        - type: object
          description: Definition of k8s cluster resource type
          properties:
            Data:
              allOf:
                - $ref: "#/components/schemas/K8sClusterDetail"

    K8sClusterDetail:
      type: object
      description: Definition of k8s cluster resource type details
      required:
        - external_cluster_id
        - cluster_status
        - kube_vendor
        - vendor_version
        - cloud_platform
      properties:
        external_cluster_id:
          type: string
          description: The OCP cluster ID or ARN etc for *KS
          example: e201ea20-87fb-4b93-a464-05f95cb3099d
        cluster_status:
          type: string
          description: the aggregate status of the cluster
          enum:
            - Ready 
            - Failed
            - Offline
            - Unknown
        kube_version:
          type: string
          description: The version of kubernetes
        kube_vendor:
          type: string
          description: The kubernetes vendor
          example: OpenShift
          enum:
            - AKS
            - EKS
            - IKS
            - OpenShift
            - GKE
            - Other
            - Unknown
        vendor_version:
          type: string
          example: 4.15.19
          description: The version of the productized kubernetes distribution
        cloud_platform:
          description: The platform on which this cluster is hosted
          type: string
          enum:
            - BareMetal (IPI)
            - BareMetal (UPI)
            - AWS (IPI)
            - AWS (UPI)
            - Azure (IPI)
            - Azure (UPI)
            - IBMCloud (IPI)
            - IBMCloud (UPI)
            - KubeVirt (IPI)
            - OpenStack (IPI)
            - OpenStack (UPI)
            - GCP (IPI)
            - GCP (UPI)
            - Nutanix (IPI)
            - Nutanix (UPI)
            - VSphere (IPI)
            - VSphere (UPI)
            - oVirt (IPI)
            - Unknown (IPI)
            - None (UPI)
        Nodes:
          type: array
          items:
            type: object
            properties:
               name:
                 type: string
                 description: The name of the node (this can contain private info)
                 example: 10.2.3.41
               cpu:
                 type: string
                 description: CPU Capacity of the node defined in CPU units, e.g. "0.5"
                 example: 4
               memory:
                 type: string
                 description: Memory Capacity of the node defined as MiB, e.g. "50Mi"
                 example: 13437648Ki
               labels:
                 description: |-
                     Map of string keys and string values that can be used to organize and categorize
                     (scope and select) resources
                 type: array
                 items:
                    $ref: '#/components/schemas/ResourceTag'
    Policy:
      allOf:
        - $ref: '#/components/schemas/CommonAttributes'
        - type: object
          description: Definition of k8s cluster resource type
          properties:
            Data:
              allOf:
                - $ref: "#/components/schemas/PolicyDetail"

    PolicyDetail:
      type: object
      description: Definition of k8s cluster resource type details
      required:
        - policy_type
        - disabled
      properties:
        disabled:
          type: boolean
          description: Defines if the policy is currently enabled or disabled across all targets
        severity:
          type: string
          description: The kind of policy
          enum:
            - Low
            - Medium
            - High
            - Critical
            - Other
            
    PolicyRelationship:
      type: object
      description: Definition of Policy->Cluster relationship
      required:
        - policy_id
        - cluster_id
        - status
      properties:
        relationship_type:
          type: string
          # read only because this can be inferred from the path
          readOnly: true
          description: |-
            The type of Resource relationship
        policy_id:
          type: string
          description: |-
           The resource ID assigned to the resource by Kessel Asset Inventory.
           A reporter alias may also be used as a resource ID using the format:
           "hcrn:<reporter_data.reporter_type>:<reporter_data.reporter_id>::<reporter_data.resourceId_alias>"
        cluster_id:
          type: string
          description: |-
            The resource ID assigned to the resource by Kessel Asset Inventory.
            A reporter alias may also be used as a resource ID using the format:
            "hcrn:<reporter_data.reporter_type>:<reporter_data.reporter_id>::<reporter_data.resourceId_alias>"
        status:
          type: string
          description: the aggregate status of the cluster
          enum:
            - Compliant 
            - Non-Compliant
            - Other
            - Unknown
    Error:
      type: object
      required:
        - status
        - type
      properties:
        # https://datatracker.ietf.org/doc/html/rfc7807#section-3.1
        type:
          type: string
          description: |-
             A URI reference [RFC3986] that identifies the problem type.
        title:
          type: string
          description: |-
             A short, human-readable summary of the problem type.
        status:
          type: integer
          description: |- 
             The HTTP status code ([RFC7231], Section (6) generated by the origin server for this occurrence of the problem.
          format: int32
          minimum: 400
          maximum: 599
        detail:
          type: string
          description: |-
             A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: |- 
            A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.