Chef Software service_groups API

openapi: 3.2.0
info:
  title: external/applications/applications.proto ApplicationsService Service Groups API
  version: version not set
servers:
- url: https://automate.chef.io/api/v0
tags:
- name: service_groups
paths:
  /api/v0/applications/delete_disconnected_services:
    post:
      summary: Remove Disconnected Services
      description: 'Removes services marked as disconnected based on the `threshold_seconds` setting.

        This function is not used by the API or CLI and is here for testing purposes.

        The functionality is currently covered by a periodically running job that can be configured using `UpdateDeleteDisconnectedServicesConfig`.


        Authorization Action:

        ```

        applications:serviceGroups:delete

        ```'
      operationId: ApplicationsService_DeleteDisconnectedServices
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServicesRes'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      tags:
      - service_groups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/chef.automate.api.applications.DisconnectedServicesReq'
        required: true
  /api/v0/applications/delete_services_by_id:
    post:
      summary: Delete the services with the given IDs
      description: 'Authorization Action:

        ```

        applications:serviceGroups:delete

        ```'
      operationId: ApplicationsService_DeleteServicesByID
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServicesRes'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      tags:
      - service_groups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/chef.automate.api.applications.DeleteServicesByIDReq'
        required: true
  /api/v0/applications/disconnected_services:
    get:
      summary: Mark Services as Disconnected
      description: 'Marks services as disconnected based on the `threshold_seconds` setting.

        This function is not used by the API or CLI and is here for testing purposes.

        The functionality is currently covered by a periodically running job that can be configured

        by utilizing the `UpdateDisconnectedServicesConfig` endpoint.


        Authorization Action:

        ```

        applications:serviceGroups:list

        ```'
      operationId: ApplicationsService_GetDisconnectedServices
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServicesRes'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: threshold_seconds
        description: Threshold for marking services disconnected in seconds.
        in: query
        required: false
        schema:
          type: integer
          format: int32
      tags:
      - service_groups
  /api/v0/applications/service-groups:
    get:
      summary: List Service Groups
      description: 'Lists service groups with name, health information, and application, environment, package, release metadata.

        Accepts pagination, sorting, search, and status filters.


        Example:

        ```

        applications/service-groups?sorting.field=percent_ok&sorting.order=ASC&pagination.page=1&pagination.size=25

        ```


        Authorization Action:

        ```

        applications:serviceGroups:list

        ```'
      operationId: ApplicationsService_GetServiceGroups
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServiceGroups'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: filter
        description: "Applies search and status filters, in the format of `fieldname:value` or `status:value`.\n\nValid filter fieldnames are:\n* `origin`: origin component of the service's package identifier\n* `service`: the name component of the service's package identifier\n* `version`: the version number component of the service's package identifier\n* `buildstamp`: the build timestamp (also called \"release\") of the service's package identifier\n* `channel`: the package channel to which the service subscribes for updates\n* `application`: the application field of the service's event-stream metadata\n* `environment`: the environment field of the service's event-stream metadata\n* `site`: the site field of the service's event-stream metadata\n* `group`: the suffix of the service group name\n\n`status` filters refine the service group results by a service's\n most recent connected/disconnected state or healthcheck result.\n\n Valid status filter parameters are:\n* `status:disconnected`: returns service groups with at least one service in a disconnected state\n* `status:critical`: returns service groups with a with at least one service in a \"critical\" healthcheck result\n* `status:unknown`: returns service groups with at least one service with an \"unknown\" healthcheck result\n* `status:warning`: returns service groups with at least one service with a \"warning\" healthcheck result\n* `status:ok`: returns service groups with at least one service with an \"ok\" health check result"
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: pagination.page
        description: Page number of the results to return.
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: pagination.size
        description: Amount of results to include per page.
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: sorting.field
        description: Field to sort the list results on.
        in: query
        required: false
        schema:
          type: string
      - name: sorting.order
        description: Order the results should be returned in.
        in: query
        required: false
        schema:
          type: string
          enum:
          - ASC
          - DESC
          default: ASC
      tags:
      - service_groups
  /api/v0/applications/service-groups/{service_group_id}:
    get:
      summary: List Services for a Service Group
      description: 'List the services for a service group with health status and service metadata.

        Uses the service group ID generated by Chef Automate instead of the Chef Habitat- provided ID.

        Supports pagination and filtering.


        Example:

        ```

        applications/service-groups/1dfff679054c60a10c51d059b6dbf81a765c46f8d3e8ce0752b22ffe8d4d9716?pagination.page=1&pagination.size=25

        ```


        Authorization Action:

        ```

        applications:serviceGroups:list

        ```'
      operationId: ApplicationsService_GetServicesBySG
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServicesBySGRes'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: service_group_id
        description: Service group ID.
        in: path
        required: true
        schema:
          type: string
      - name: pagination.page
        description: Page number of the results to return.
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: pagination.size
        description: Amount of results to include per page.
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: sorting.field
        description: Field to sort the list results on.
        in: query
        required: false
        schema:
          type: string
      - name: sorting.order
        description: Order the results should be returned in.
        in: query
        required: false
        schema:
          type: string
          enum:
          - ASC
          - DESC
          default: ASC
      - name: filter
        description: 'Applies filters, in the format of `fieldname:value`.

          See documentation for ServicesReq for valid filter parameters.'
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      tags:
      - service_groups
  /api/v0/applications/service_groups_health_counts:
    get:
      summary: List Service Groups Health Counts
      description: 'Lists the total service group health reports by critical, warning, ok and unknown responses. Supports search and status filtering.


        Authorization Action:

        ```

        applications:serviceGroups:list

        ```'
      operationId: ApplicationsService_GetServiceGroupsHealthCounts
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.HealthCounts'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: filter
        description: 'Applies search filters, in the format of `fieldname:value`.

          See the documentation for ServiceGroupsReq for valid filter parameters.'
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      tags:
      - service_groups
  /api/v0/applications/services:
    get:
      summary: List Services
      description: 'Lists service health status and service metadata for services.

        Supports pagination and search and status filtering. For a list of services for a specific service-group see "List Services for a Service Group" (GetServicesBySG endpoint).


        Authorization Action:

        ```

        applications:serviceGroups:list

        ```'
      operationId: ApplicationsService_GetServices
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServicesRes'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: filter
        description: "Applies search filters, in the format of `fieldname:value`.\n\nValid filter fieldnames are:\n* `origin`: origin component of the service's package identifier\n* `service`: the name component of the service's package identifier\n* `version`: the version number component of the service's package identifier\n* `buildstamp`: the build timestamp (also called \"release\") of the service's package identifier\n* `channel`: the package channel to which the service subscribes for updates\n* `application`: the application field of the service's event-stream metadata\n* `environment`: the environment field of the service's event-stream metadata\n* `site`: the site field of the service's event-stream metadata\n* `group`: the suffix of the service group name\n\n`status` filters refine service results by a service's\n current state or most recent healthcheck result.\n Disconnected services keep their last healthcheck result\n until their reports are removed by Chef Automate.\n When you apply a healthcheck filter, the report includes\n all recently disconnected services.\n Valid status filter parameters are:\n* `status:disconnected`: returns services in a disconnected state\n* `status:critical`: returns services with a \"critical\" healthcheck result\n* `status:unknown`: returns services with an \"unknown\" healthcheck result\n* `status:warning`: returns services with a \"warning\" healthcheck result\n* `status:ok`: returns services with an  \"ok\" health check result"
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: pagination.page
        description: Page number of the results to return.
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: pagination.size
        description: Amount of results to include per page.
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: sorting.field
        description: Field to sort the list results on.
        in: query
        required: false
        schema:
          type: string
      - name: sorting.order
        description: Order the results should be returned in.
        in: query
        required: false
        schema:
          type: string
          enum:
          - ASC
          - DESC
          default: ASC
      tags:
      - service_groups
  /api/v0/applications/services-distinct-values:
    get:
      summary: List Filter Values
      description: 'Lists all of the possible filter values for a given valid field.

        Limit the returned values by providing at one or more characters in the `query_fragment` parameter.

        Supports wildcard (* and ?)



        Authorization Action:

        ```

        applications:serviceGroups:list

        ```'
      operationId: ApplicationsService_GetServicesDistinctValues
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServicesDistinctValuesRes'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      parameters:
      - name: field_name
        description: Field name of service values.
        in: query
        required: false
        schema:
          type: string
      - name: query_fragment
        description: Query value, supports wildcards (* and ?).
        in: query
        required: false
        schema:
          type: string
      - name: filter
        description: 'Applies filters, in the format of `fieldname:value`.

          See documentation for ServicesReq for valid filter parameters.'
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      tags:
      - service_groups
  /api/v0/applications/stats:
    get:
      summary: Show Summary
      description: 'Shows a summary of service-groups, services, deployments, and supervisors.

        Used for telemetry.

        Does not support filtering.


        Authorization Action:

        ```

        applications:serviceGroups:list

        ```'
      operationId: ApplicationsService_GetServicesStats
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServicesStatsRes'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      tags:
      - service_groups
components:
  schemas:
    chef.automate.api.applications.ServicesDistinctValuesRes:
      type: object
      properties:
        values:
          type: array
          items:
            type: string
          description: List of distinct values fitting query_fragment and filters.
      description: Response message for GetServicesDistinctValues.
    chef.automate.api.applications.HealthCheckResult:
      type: object
      properties:
        stdout:
          type: string
        stderr:
          type: string
        exit_status:
          type: integer
          format: int32
      title: 'HealthCheckResult aggregates the stdout output, stderr output and process

        exit status of a habitat health check'
    chef.automate.api.applications.DisconnectedServicesReq:
      type: object
      properties:
        threshold_seconds:
          type: integer
          format: int32
          description: Threshold for marking services disconnected in seconds.
      description: Request message for GetDisconnectedServices.
    chef.automate.api.applications.HealthStatus:
      type: string
      enum:
      - OK
      - WARNING
      - CRITICAL
      - UNKNOWN
      - NONE
      default: OK
      description: 'The HealthStatus enumerable matches the Chef Habitat implementation for health-check status:

        => https://www.habitat.sh/docs/reference/#health-check

        For a health status within a service group.

        *critical* means that one or more services are in critical condition.

        *warning* means that one or more services have a warning, but none are in critical condition.

        *unknown* means that one or more services have not responded, but all of the remaining nodes responded to the health check as "OK".

        *OK* means that all of the services are OK and all have responded to the health check.

        *none* means that there is no health check information.'
    chef.automate.api.applications.ServicesStatsRes:
      type: object
      properties:
        total_service_groups:
          type: integer
          format: int32
          description: Total number of service groups reporting to Chef Automate.
        total_services:
          type: integer
          format: int32
          description: Total number of services reporting to Chef Automate, counts both connected and disconnected services.
        total_supervisors:
          type: integer
          format: int32
          description: Total number of supervisors reporting to Chef Automate.
        total_deployments:
          type: integer
          format: int32
          description: Total number of deployments reporting to Chef Automate.
      description: Response message for ServicesStats.
    chef.automate.api.applications.HealthCounts:
      type: object
      properties:
        total:
          type: integer
          format: int32
        ok:
          type: integer
          format: int32
        warning:
          type: integer
          format: int32
        critical:
          type: integer
          format: int32
        unknown:
          type: integer
          format: int32
        disconnected:
          type: integer
          format: int32
      description: Combined count values from the health status and disconnected status reports.
    google.protobuf.Any:
      type: object
      properties:
        type_url:
          type: string
          description: "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n  value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n  URL, or have them precompiled into a binary to avoid any\n  lookup. Therefore, binary compatibility needs to be preserved\n  on changes to types. (Use versioned type names to manage\n  breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics."
        value:
          type: string
          format: byte
          description: Must be a valid serialized protocol buffer of the above specified type.
      description: "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n    Foo foo = ...;\n    Any any;\n    any.PackFrom(foo);\n    ...\n    if (any.UnpackTo(&foo)) {\n      ...\n    }\n\nExample 2: Pack and unpack a message in Java.\n\n    Foo foo = ...;\n    Any any = Any.pack(foo);\n    ...\n    if (any.is(Foo.class)) {\n      foo = any.unpack(Foo.class);\n    }\n\n Example 3: Pack and unpack a message in Python.\n\n    foo = Foo(...)\n    any = Any()\n    any.Pack(foo)\n    ...\n    if any.Is(Foo.DESCRIPTOR):\n      any.Unpack(foo)\n      ...\n\n Example 4: Pack and unpack a message in Go\n\n     foo := &pb.Foo{...}\n     any, err := anypb.New(foo)\n     if err != nil {\n       ...\n     }\n     ...\n     foo := &pb.Foo{}\n     if err := any.UnmarshalTo(foo); err != nil {\n       ...\n     }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n    package google.profile;\n    message Person {\n      string first_name = 1;\n      string last_name = 2;\n    }\n\n    {\n      \"@type\": \"type.googleapis.com/google.profile.Person\",\n      \"firstName\": <string>,\n      \"lastName\": <string>\n    }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n    {\n      \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n      \"value\": \"1.212s\"\n    }"
    chef.automate.api.applications.ServicesRes:
      type: object
      properties:
        services:
          type: array
          items:
            $ref: '#/components/schemas/chef.automate.api.applications.Service'
          description: List of services.
      description: Response message for GetServices.
    chef.automate.api.applications.ServicesBySGRes:
      type: object
      properties:
        group:
          type: string
          description: Service group name.
        services:
          type: array
          items:
            $ref: '#/components/schemas/chef.automate.api.applications.Service'
          description: List of services.
        services_health_counts:
          $ref: '#/components/schemas/chef.automate.api.applications.HealthCounts'
          description: Intentionally blank.
      description: Response message for GetServicesBySG.
    grpc.gateway.runtime.Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/google.protobuf.Any'
    chef.automate.api.applications.Service:
      type: object
      properties:
        supervisor_id:
          type: string
          description: The Chef Habitat Supervisor ID.
        release:
          type: string
          description: 'Combination of the service version and release in a single string.

            Example: 0.1.0/8743278934278923.'
        group:
          type: string
          description: Service group name.
        health_check:
          $ref: '#/components/schemas/chef.automate.api.applications.HealthStatus'
          description: Intentionally blank.
        application:
          type: string
          description: Application name.
        environment:
          type: string
          description: Environment name.
        fqdn:
          type: string
          description: FQDN reported by a Chef Habitat Supervisor.
        channel:
          type: string
          description: Chef Habitat channel that the service is subscribed to.
        update_strategy:
          type: string
          description: Update strategy that the service employs.
        site:
          type: string
          description: Site reported by Chef Habitat service, a user defined flag.
        previous_health_check:
          $ref: '#/components/schemas/chef.automate.api.applications.HealthStatus'
          description: Intentionally blank.
        current_health_since:
          type: string
          description: Time interval of current health status from last status change until now.
        health_updated_at:
          type: string
          format: date-time
          description: Timestamp since health status change.
        disconnected:
          type: boolean
          description: 'Service connection information.

            Based on time since last healthcheck received and disconnected service configuration.'
        last_event_occurred_at:
          type: string
          format: date-time
          description: Timestamp of last received health check message.
        last_event_since:
          type: string
          description: Interval since last event received until now.
        health_check_result:
          $ref: '#/components/schemas/chef.automate.api.applications.HealthCheckResult'
          description: Intentionally blank.
        id:
          type: string
          title: Internal ID
    chef.automate.api.applications.ServiceGroups:
      type: object
      properties:
        service_groups:
          type: array
          items:
            $ref: '#/components/schemas/chef.automate.api.applications.ServiceGroup'
          description: List of service groups.
      description: List of service groups.
    chef.automate.api.applications.ServiceGroup:
      type: object
      properties:
        name:
          type: string
          description: Name of service group.
        release:
          type: string
          description: 'Combination of the version and release in a single string.

            Example: 0.1.0/8743278934278923.'
        status:
          $ref: '#/components/schemas/chef.automate.api.applications.HealthStatus'
          description: Intentionally blank.
        health_percentage:
          type: integer
          format: int32
          description: 'Percentage of services reporting OK status.

            The health_percentage can be a number between 0-100.'
        services_health_counts:
          $ref: '#/components/schemas/chef.automate.api.applications.HealthCounts'
          description: Intentionally blank.
        id:
          type: string
          description: Service group ID. This is a value constructed by Chef Automate and is not reported by Chef Habitat.
        application:
          type: string
          description: Application name for the service group.
        environment:
          type: string
          description: Environment name for the service group.
        package:
          type: string
          description: 'Combination of the origin and package name in a single string.

            Example: core/redis.'
        disconnected_count:
          type: integer
          format: int32
          description: Count of disconnected services within this service group.
      description: 'A service group message is the representation of an individual service group that

        is internally generated by aggregating all of its services.'
    chef.automate.api.applications.DeleteServicesByIDReq:
      type: object
      properties:
        ids:
          type: array
          items:
            type: string
          description: List of the database IDs of the services to be deleted.