swagger: '2.0' info: title: external/applications/applications.proto ApplicationsService service_groups API version: version not set consumes: - application/json produces: - application/json 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. schema: $ref: '#/definitions/chef.automate.api.applications.ServicesRes' default: description: An unexpected error response. schema: $ref: '#/definitions/grpc.gateway.runtime.Error' parameters: - name: body in: body required: true schema: $ref: '#/definitions/chef.automate.api.applications.DisconnectedServicesReq' tags: - service_groups /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. schema: $ref: '#/definitions/chef.automate.api.applications.ServicesRes' default: description: An unexpected error response. schema: $ref: '#/definitions/grpc.gateway.runtime.Error' parameters: - name: body in: body required: true schema: $ref: '#/definitions/chef.automate.api.applications.DeleteServicesByIDReq' tags: - service_groups /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. schema: $ref: '#/definitions/chef.automate.api.applications.ServicesRes' default: description: An unexpected error response. schema: $ref: '#/definitions/grpc.gateway.runtime.Error' parameters: - name: threshold_seconds description: Threshold for marking services disconnected in seconds. in: query required: false 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. schema: $ref: '#/definitions/chef.automate.api.applications.ServiceGroups' default: description: An unexpected error response. schema: $ref: '#/definitions/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 type: array items: type: string collectionFormat: multi - name: pagination.page description: Page number of the results to return. in: query required: false type: integer format: int32 - name: pagination.size description: Amount of results to include per page. in: query required: false type: integer format: int32 - name: sorting.field description: Field to sort the list results on. in: query required: false type: string - name: sorting.order description: Order the results should be returned in. in: query required: false 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. schema: $ref: '#/definitions/chef.automate.api.applications.ServicesBySGRes' default: description: An unexpected error response. schema: $ref: '#/definitions/grpc.gateway.runtime.Error' parameters: - name: service_group_id description: Service group ID. in: path required: true type: string - name: pagination.page description: Page number of the results to return. in: query required: false type: integer format: int32 - name: pagination.size description: Amount of results to include per page. in: query required: false type: integer format: int32 - name: sorting.field description: Field to sort the list results on. in: query required: false type: string - name: sorting.order description: Order the results should be returned in. in: query required: false 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 type: array items: type: string collectionFormat: multi 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. schema: $ref: '#/definitions/chef.automate.api.applications.HealthCounts' default: description: An unexpected error response. schema: $ref: '#/definitions/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 type: array items: type: string collectionFormat: multi 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. schema: $ref: '#/definitions/chef.automate.api.applications.ServicesRes' default: description: An unexpected error response. schema: $ref: '#/definitions/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 type: array items: type: string collectionFormat: multi - name: pagination.page description: Page number of the results to return. in: query required: false type: integer format: int32 - name: pagination.size description: Amount of results to include per page. in: query required: false type: integer format: int32 - name: sorting.field description: Field to sort the list results on. in: query required: false type: string - name: sorting.order description: Order the results should be returned in. in: query required: false 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. schema: $ref: '#/definitions/chef.automate.api.applications.ServicesDistinctValuesRes' default: description: An unexpected error response. schema: $ref: '#/definitions/grpc.gateway.runtime.Error' parameters: - name: field_name description: Field name of service values. in: query required: false type: string - name: query_fragment description: Query value, supports wildcards (* and ?). in: query required: false 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 type: array items: type: string collectionFormat: multi 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. schema: $ref: '#/definitions/chef.automate.api.applications.ServicesStatsRes' default: description: An unexpected error response. schema: $ref: '#/definitions/grpc.gateway.runtime.Error' tags: - service_groups definitions: 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. 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.ServiceGroups: type: object properties: service_groups: type: array items: $ref: '#/definitions/chef.automate.api.applications.ServiceGroup' description: List of service groups. description: List of service groups. 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: '#/definitions/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: '#/definitions/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: '#/definitions/chef.automate.api.applications.HealthCheckResult' description: Intentionally blank. id: type: string title: Internal ID 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.DeleteServicesByIDReq: type: object properties: ids: type: array items: type: string description: List of the database IDs of the services to be deleted. chef.automate.api.applications.ServicesRes: type: object properties: services: type: array items: $ref: '#/definitions/chef.automate.api.applications.Service' description: List of services. description: Response message for GetServices. 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. 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\": ,\n \"lastName\": \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 }" grpc.gateway.runtime.Error: type: object properties: error: type: string code: type: integer format: int32 message: type: string details: type: array items: $ref: '#/definitions/google.protobuf.Any' 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.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: '#/definitions/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: '#/definitions/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.ServicesBySGRes: type: object properties: group: type: string description: Service group name. services: type: array items: $ref: '#/definitions/chef.automate.api.applications.Service' description: List of services. services_health_counts: $ref: '#/definitions/chef.automate.api.applications.HealthCounts' description: Intentionally blank. description: Response message for GetServicesBySG.