openapi.yaml

openapi: '3.0.2'
info:
  title: Lieutenant API
  description: Project Syn Management API
  contact:
    name: VSHN AG
    email: info@vshn.ch
    url: https://vshn.ch
  version: 0.0.1
  license:
    name: BSD 3-Clause License
    url: https://choosealicense.com/licenses/bsd-3-clause/
servers:
  - url: https://api.syn.vshn.net/
    description: Project Syn Lieutenant Production API
  - url: https://api-dev.syn.vshn.net/
    description: Project Syn Lieutenant Test API
  - url: /
    description: Local development
security:
  - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Id:
      type: string
      description: >
        A unique object identifier string. Automatically generated by the API on creation (in the form
        "<letter>-<adjective>-<noun>-<digits>" where all letters are lowercase, max 63 characters in total).
      readOnly: true
    TenantProperties:
      type: object
      description: |-
        A tenant defition object.
        It can belong to another tenant to allow for tenant hierarchies.
        The Git repository is usually managed by the API and autogenerated.
        All properties except name are optional on creation.
      properties:
        displayName:
          type: string
          description: Display name of the tenant
          example: Acme Corp.
        tenant:
          type: string
          description: The tenant this tenant belongs to
          example: multicorp
          nullable: true
        gitRepo:
          $ref: '#/components/schemas/GitRepo'
    TenantId:
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/Id'
    Tenant:
      allOf:
        - $ref: '#/components/schemas/TenantId'
        - $ref: '#/components/schemas/TenantProperties'
    ClusterProperties:
      type: object
      required:
        - tenant
      description: |-
        A cluster defition object.
        The Git repository is usually managed by the API and autogenerated.
        The sshDeployKey will be managed by Steward
      properties:
        displayName:
          type: string
          description: Display Name of the cluster
          example: My very important cluster
        facts:
          $ref: '#/components/schemas/ClusterFacts'
        gitRepo:
          $ref: '#/components/schemas/GitRepo'
        tenant:
          type: string
          description: Id of the tenant this cluster belongs to
          example: aezoo6
        installURL:
          type: string
          readOnly: true
          description: URL to fetch install manifests for Steward cluster agent. This will only be set if the cluster's token is still valid.
          example: https://api.syn.vshn.net/install/steward.json?token=<secretToken>
    ClusterId:
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/Id'
    ClusterFacts:
      type: object
      description: Facts about a cluster object. Statically configured key/value pairs.
      example:
        distribution: openshift4
        cloud: aws
        region: eu-west-1
    Cluster:
      allOf:
        - $ref: '#/components/schemas/ClusterId'
        - $ref: '#/components/schemas/ClusterProperties'
    Reason:
      type: object
      required:
        - reason
      description: A reason for responses
      properties:
        reason:
          type: string
          description: The reason message
          example: Because of reasons
    Inventory:
      type: object
      required:
      - cluster
      description: Inventory data of a cluster
      properties:
        cluster:
          type: string
        inventory:
          type: object
    GitRepo:
      type: object
      description: Configuration Git repository, usually generated by the API
      properties:
        url:
          type: string
          description: Full URL of the git repo
          example: ssh://git@github.com/acmecorp/gitops-mycluster.git
        type:
          type: string
          description: Specifies if a repo should be managed by the git controller. A value of 'unmanaged' means it's not manged by the controller
          example: auto
          default: auto
        deployKey:
          type: string
          description: SSH public key / deploy key for clusterconfiguration catalog Git repository. This property is managed by Steward.
          example: |
            ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDG9a5WwLuwcxMRydNqI4ofuzXucrBKpGOvPV9PO4guj
        hostKeys:
          type: string
          description: SSH known hosts of the git server (multiline possible for multiple keys)
          example: |
            gitlab.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf
            gitlab.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFSMqzJeV9rUzU4kWitGjeR4PWSa29SPqJ1fVkhtj3Hw9xjLVXVYrU9QlYWrOLXBpQ6KWjbjTDTdDkoohFzgbEY=
  responses:
    Default:
      description: A default response with a reason.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Reason'
  parameters:
    TenantIdParameter:
      name: tenantId
      in: path
      required: true
      description: Distinct id of the tenant.
      schema:
        $ref: '#/components/schemas/Id'
    ClusterIdParameter:
      name: clusterId
      in: path
      required: true
      description: Distinct id of the cluster.
      schema:
        $ref: '#/components/schemas/Id'
tags:
  - name: tenant
    description: Management of tenants
  - name: cluster
    description: Management of clusters
  - name: bootstrapping
    description: Cluster bootstrapping
  - name: inventory
    description: Cluster inventory time based data
  - name: system
    description: API system
paths:
  /tenants:
    get:
      operationId: listTenants
      summary: Returns a list of tenants
      description: List of all tenants available in the API
      tags:
        - tenant
      responses:
        '200':
          description: Tenant listing. Empty array if no tenants available.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tenant'
                example:
                - id: aezoo6
                  displayName: Big Corp.
                  gitRepo: https://github.com/bigcorp/commodore-config.git
                - id: os3ce3
                  displayName: Acme Corp. (Subtenant of Big Corp)
                  tenant: aezoo6
                  gitRepo: https://github.com/acmecorp/commodore-config.git
        default:
          $ref: '#/components/responses/Default'
    post:
      operationId: createTenant
      summary: Creates a new tenant
      description: |-
        Create a tenant in the API.
        The ID is generated by the API (in the form `t-<adjective>-<noun>-<digits>` where
        all the words are lowercase, max 63 characters in total).
        It generates the `Tenant` object in the configured namespace (usually the same namespace where the API runs).
        The customer config Git repository (the `<GitRepoSpec>`) is automatically
        generated based on default configuration or using the provided values.
        If `gitRepo` is already set on creation, no `<GitRepoSpec>` will be added.
      tags:
        - tenant
      requestBody:
        required: true
        description: Create a new tenant
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantProperties'
      responses:
        '201':
          description: Tenant created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
              example:
                id: aezoo6
                displayName: Acme Corp.
                tenant: multicorp
                gitRepo: https://github.com/acmecorp/commodore-config.git
        '400':
          description: Tenant can't be created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reason'
        '405':
          description: Tenant already exists
        default:
          $ref: '#/components/responses/Default'
  /tenants/{tenantId}:
    get:
      operationId: getTenant
      summary: Returns all values of a tenant
      description: Returns all values of a tenant
      tags:
        - tenant
      parameters:
        - $ref: '#/components/parameters/TenantIdParameter'
      responses:
        '200':
          description: Tenant found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        '404':
          description: A tenant with the specified id wasn't found.
        default:
          $ref: '#/components/responses/Default'
    patch:
      operationId: updateTenant
      summary: Updates a tenant
      description: Updates a tenant
      tags:
        - tenant
      parameters:
        - $ref: '#/components/parameters/TenantIdParameter'
      requestBody:
        description: Update tenant with properties to be changed (RFC 7396)
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/TenantProperties'
      responses:
        '200':
          description: Tenant updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        '403':
          description: Tenant update forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reason'
        default:
          $ref: '#/components/responses/Default'
    delete:
      operationId: deleteTenant
      summary: Deletes a tenant
      description: Deletes a tenant
      tags:
        - tenant
      parameters:
        - $ref: '#/components/parameters/TenantIdParameter'
      responses:
        '204':
          description: Tenant deleted
        '403':
          description: Tenant deletion forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reason'
        default:
          $ref: '#/components/responses/Default'
  /clusters:
    get:
      operationId: listClusters
      summary: Returns a list of clusters
      description: List of clusters available in the API
      tags:
        - cluster
      parameters:
        - in: query
          name: tenant
          schema:
            type: string
          description: Filter clusters by tenant id
          example: aezoo6
      responses:
        '200':
          description: Cluster listing. Empty array if no tenants available.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cluster'
        default:
          $ref: '#/components/responses/Default'
    post:
      operationId: createCluster
      summary: Creates a new cluster
      description: |-
        Create a cluster in the API.
        The ID is generated by the API (in the form `c-<adjective>-<noun>-<digits>` where
        all the words are lowercase, max 63 characters in total).
        It checks if the tenant exists before creating the object, otherwise fails.
        It generates the `Cluster` object and its `<GitRepoSpec>` and `bootstrapToken` values.
      tags:
        - cluster
      requestBody:
        description: Create a new Cluster
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClusterProperties'
      responses:
        '201':
          description: Cluster created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '400':
          description: Cluster can't be created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reason'
        '405':
          description: Cluster already exists
        default:
          $ref: '#/components/responses/Default'
  /clusters/{clusterId}:
    get:
      operationId: getCluster
      summary: Returns all values of a cluster
      description: Returns all values of a cluster
      tags:
        - cluster 
      parameters:
        - $ref: '#/components/parameters/ClusterIdParameter'
      responses:
        '200':
          description: Cluster found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '404':
          description: A cluster with the specified id wasn't found.
        default:
          $ref: '#/components/responses/Default'
    patch:
      operationId: updateCluster
      summary: Updates a cluster
      description: Updates a cluster
      tags:
        - cluster
      parameters:
        - $ref: '#/components/parameters/ClusterIdParameter'
      requestBody:
        description: Update cluster with properties to be changed (RFC 7396)
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/ClusterProperties'
      responses:
        '200':
          description: Cluster updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '403':
          description: Cluster update forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reason'
        default:
          $ref: '#/components/responses/Default'
    delete:
      operationId: deleteCluster
      summary: Deletes a cluster
      description: Deletes a cluster
      tags:
        - cluster
      parameters:
        - $ref: '#/components/parameters/ClusterIdParameter'
      responses:
        '204':
          description: Cluster deleted
        '403':
          description: Cluster deletion forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reason'
        default:
          $ref: '#/components/responses/Default'
  /install/steward.json:
    get:
      operationId: installSteward
      summary: Returns the Steward JSON installation manifest
      description: |-
        Autogenerated JSON containing all the needed parameters for having Steward up and running.
        It Iterates through all available Cluster objects to find the object matching the token in the field `spec.bootstrapToken.token`.
        It checks if the token is valid (fields `spec.bootstrapToken.valid` and field `spec.bootstrapToken.validUntil`).
        If valid delivers the JSON and sets the field `spec.bootstrapToken.valid` to `false`.
      security: []
      tags:
        - bootstrapping
      parameters:
        - in: query
          name: token
          schema:
            type: string
          description: Initial bootstrap token
      responses:
        '200':
          description: Kubernetes manifests to install Steward, the cluster agent
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Token invalid
        '404':
          description: Cluster not found
        default:
          $ref: '#/components/responses/Default'
  /inventory:
    get:
      operationId: queryInventory
      summary: Returns inventory data according to query
      description: Search inventory data
      tags:
        - inventory
      parameters:
        - in: query
          name: q
          schema:
            type: string
          description: InfluxQL query string
          example: SELECT LAST(version,cloud) FROM mycluster
      responses:
        '200':
          description: Query succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Inventory'
        default:
          $ref: '#/components/responses/Default'
    post:
      operationId: updateInventory
      summary: Write inventory data
      description: Write inventory data
      tags:
        - inventory
      requestBody:
        description: Inventory data of a cluster
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Inventory'
      responses:
        '201':
          description: Inventory data stored
        default:
          $ref: '#/components/responses/Default'
  /healthz:
    get:
      operationId: healthz
      summary: API health check
      description: API health check
      security: []
      tags:
       - system
      responses:
        '200':
          description: All is fine
          content:
            text/plain:
              schema:
                type: string
                example: ok
        default:
          $ref: '#/components/responses/Default'