openapi: 3.0.3 info: title: Perfectscale API - OpenAPI 3.0 version: v1 contact: name: Support email: support@perfectscale.io description: | The Perfectscale API provides programmatic access to Perfectscale's resources and services, allowing users to analyze their workloads in a Kubernetes environment. servers: - url: https://api.app.perfectscale.io/public/v1 externalDocs: description: Find more info here url: https://docs.perfectscale.io security: - auth: [ ] paths: /auth/public_auth: post: tags: - Authentication summary: Public authentication for clients description: | This endpoint allows clients to authenticate using their client credentials. requestBody: required: true content: application/json: schema: type: object properties: client_id: type: string description: The client identifier issued to the client during the registration process. client_secret: type: string description: The client secret issued to the client during the registration process. required: [ client_id, client_secret ] responses: '200': description: Authentication successful content: application/json: schema: type: object properties: access_token: type: string description: Access token to be used for subsequent requests. expires_in: type: integer description: The number of seconds the token will be valid. '400': description: Bad request, client credentials are missing or incorrect. '401': description: Unauthorized, client authentication failed. '500': description: Internal server error /clusters/{cluster_uid}/workloads: get: tags: - Workloads summary: List all workloads in a specified cluster parameters: - name: cluster_uid in: path required: true schema: type: string description: The unique identifier for the cluster responses: '200': description: A list of workloads content: application/json: schema: type: object properties: meta: type: object properties: count: type: integer description: The total number of workloads in the specified cluster. example: 10 required: - count data: type: array items: $ref: '#/components/schemas/Workload' required: - meta - data examples: SingleWorkloadExample: value: meta: count: 1 data: - containers: nginx: indicators: - name: "CpuRequestNotSet" severityLevel: 2 type: "risk" - name: "MemRequestNotSet" severityLevel: 2 type: "risk" - name: "MemLimitNotSet" severityLevel: 2 type: "risk" name: "nginx" resources: current: cpuLimitCores: 0 cpuRequestCores: 0 memoryLimitMiB: 0 memoryRequestMiB: 0 recommended: cpuLimitCores: 0 cpuRequestCores: 0.02 memoryLimitMiB: 28.6102294921875 memoryRequestMiB: 14.30511474609375 runningMinutes: 2 usage: cpuCores: p100: 0.00024516326637646197 p90: 0.00022064694785512985 p95: 0.00023290511162485925 memoryMiB: p100: 2.5859375 p90: 2.5859375 p95: 2.5859375 costAnalysis: past30Days: totalCost: 7.953553911574971e-7 wastedCost: -0.000016735894608842506 projected30Days: projectedCost: 0.01797400355109174 projectedWaste: 0 recommendedCost: 0.37867500000000004 firstSeen: "2023-10-21T13:24:51Z" id: "default-deployment-nginx-deployment" indicators: - name: "OverProvisionedWorkload" severityLevel: 0 type: "waste" lastSeen: "2023-10-21T13:25:41.084Z" muteStatus: isMuted: false expires: null name: "nginx-deployment" namespace: "default" replicasCounts: avgCount: 1 maxCount: 1 resilienceLevel: "high" runningMinutes: 2 type: "Deployment" workloadLabels: label_app: "nginx" label_pod_template_hash: "6595874d85" headers: X-RateLimit-Limit-Minute: description: The maximum number of requests allowed per minute. schema: type: integer X-RateLimit-Remaining-Minute: description: The number of requests remaining in the current minute window. schema: type: integer RateLimit-Limit: description: The maximum number of requests allowed in the current rate limit window. schema: type: integer RateLimit-Remaining: description: The number of requests remaining in the current rate limit window. schema: type: integer RateLimit-Reset: description: The time at which the current rate limit window resets in UTC epoch seconds. schema: type: integer '400': description: Bad Request '401': description: Unauthorized '404': description: Cluster not found '500': description: Internal server error security: - auth: [ ] components: securitySchemes: auth: type: http scheme: bearer bearerFormat: JWT schemas: Workload: type: object title: Workload description: A representation of a workload within a Kubernetes cluster. properties: id: type: string description: A unique identifier for the workload, usually following a namespace-type-name convention. example: "examplenamespace-deployment-example-test-workload" name: type: string description: A human-readable name for the workload. example: "example-test-workload" type: type: string description: The type of Kubernetes workload. Common types include Deployment, StatefulSet, and DaemonSet, but other string values can also be used to represent custom or extended workload types. example: "Deployment" namespace: type: string description: The Kubernetes namespace in which the workload resides. example: "examplenamespace" firstSeen: type: string format: date-time description: The timestamp when the workload was first observed, formatted as an ISO 8601 date-time string. example: "2023-04-08T16:51:08Z" lastSeen: type: string format: date-time description: The timestamp when the workload was last observed, formatted as an ISO 8601 date-time string. example: "2023-10-22T15:23:22.9Z" runningMinutes: type: integer description: The total number of minutes the workload has been running. example: 40265 replicasCounts: $ref: '#/components/schemas/ReplicasCounts' resilienceLevel: type: string description: The resilience level of the workload, indicating its tolerance to failures or disruptions (configured on Perfectscale side). enum: [ low, medium, high, highest ] example: "medium" muteStatus: $ref: '#/components/schemas/MuteStatus' costAnalysis: $ref: '#/components/schemas/CostAnalysis' workloadLabels: type: object description: Key-value pairs representing kubernets labels associated with the workload. additionalProperties: type: string description: A label value associated with a particular key. indicators: type: array description: A list of indicators providing insights into the performance and health of the workload. items: $ref: '#/components/schemas/Indicator' containers: type: object description: An object holding detailed information about each container within the workload. additionalProperties: $ref: '#/components/schemas/Container' required: - id - name - type - namespace - firstSeen - lastSeen - runningMinutes - replicasCounts - resilienceLevel - muteStatus - costAnalysis - workloadLabels - indicators - containers ReplicasCounts: type: object title: Replicas Counts description: An object representing the count statistics of replicas for a workload over a month period. properties: maxCount: type: integer description: The maximum count of replicas observed for the workload during the month period. example: 3 avgCount: type: integer description: The average count of replicas observed for the workload during the month period. example: 2 required: [ maxCount, avgCount ] MuteStatus: type: object title: Mute Status description: The mute status of a workload, indicating whether the workload is currently muted and when it will become unmuted. properties: isMuted: type: boolean description: Indicates whether the workload is currently muted. example: false muteExpiry: type: string format: date-time description: The date and time when the workload will automatically become unmuted. If null, the mute status does not expire automatically. example: null required: [ isMuted ] Resources: type: object title: Resources description: Metrics detailing the resource allocation in terms of memory and CPU. properties: memoryRequestMiB: type: number format: double description: The amount of memory requested for the workload in MiB. example: 128 memoryLimitMiB: type: number format: double description: The maximum amount of memory that can be allocated for the workload in MiB. example: 256 cpuRequestCores: type: number format: double description: The amount of CPU resources requested for the workload in cores. example: 128 cpuLimitCores: type: number format: double description: The maximum amount of CPU resources that can be allocated for the workload in cores. example: 256 required: - memoryRequestMiB - memoryLimitMiB - cpuRequestCores - cpuLimitCores Past30DaysCostAnalysis: type: object title: Past 30 Days Cost Analysis description: Metrics detailing the total and wasted costs associated with the workload's resource consumption. properties: totalCost: type: number format: double description: The total cost incurred by the workload's resource consumption. example: 1.2111549136128001 wastedCost: type: number format: double description: The cost attributed to over-provisioned or inefficiently utilized resources. example: 0.370918634267412 required: [ totalCost, wastedCost ] Projected30DaysCostAnalysis: type: object title: Projected 30 Days Cost Analysis description: Metrics detailing the projected costs, recommended costs, and projected waste associated with the workload's resource consumption. properties: projectedCost: type: number format: double description: The projected cost of the workload's resource consumption for the next 30 days. example: 0.9014828577603567 recommendedCost: type: number format: double description: The recommended cost based on optimized resource allocation. example: 0.9014828577603567 projectedWaste: type: number format: double description: The projected cost waste due to over-provisioned or inefficiently utilized resources for the next 30 days. example: 0.3979556687036433 required: [ projectedCost, recommendedCost, projectedWaste ] CostAnalysis: type: object title: Cost Analysis description: Analysis of the costs associated with the workload's resource consumption over the past 30 days and projected for the next 30 days. properties: past30Days: $ref: '#/components/schemas/Past30DaysCostAnalysis' projected30Days: $ref: '#/components/schemas/Projected30DaysCostAnalysis' required: [ past30Days, projected30Days ] Indicator: type: object title: Indicator description: An object representing key performance indicators that provide insights into the performance and health of the workload or container. properties: name: type: string description: The name of the indicator representing a specific aspect of performance or health. enum: - OOM - CpuThrottling - CpuRequestNotSet - MemRequestNotSet - MemLimitNotSet - UnderProvisionedMemRequest - UnderProvisionedMemLimit - UnderProvisionedCpuRequest - UnderProvisionedCpuLimit - OverProvisionedCpuRequest - OverProvisionedMemRequest - RestartsObserved example: "OverProvisionedMemRequest" type: type: string description: The type of indicator, categorizing it as either a risk, waste, or no issue (none). enum: - none - risk - waste example: "waste" severityLevel: type: integer description: The severity level of the indicator, ranging from 0 (no issue) to 3 (critical issue). enum: - 0 - 1 - 2 - 3 example: 1 required: [ name, type, severityLevel ] Container: type: object title: Container description: Detailed information about a specific container within the workload, including its performance indicators and usage statistics. properties: name: type: string description: The name of the container. example: "container-example-name" runningMinutes: type: integer description: The total number of minutes the container has been running. example: 40265 indicators: type: array description: A list of indicators providing insights into the performance and health of the container. items: $ref: '#/components/schemas/Indicator' resources: type: object description: The resource allocation details for the workload, including the current and recommended by PerfectScale allocation. properties: current: $ref: '#/components/schemas/Resources' recommended: $ref: '#/components/schemas/Resources' required: [ current, recommended ] usage: type: object description: An object representing the resource usage statistics of a container, broken down into CPU and memory consumption. properties: cpuCores: $ref: '#/components/schemas/Percentiles' memoryMiB: $ref: '#/components/schemas/Percentiles' required: [ cpuCores, memoryMiB ] required: [ name, runningMinutes, indicators, resources, usage ] Percentiles: type: object title: Container description: An object representing percentile statistics of resource usage, providing insights into the distribution of usage values over a certain period. properties: p90: type: number format: double description: The 90th percentile value of resource usage, indicating that 90% of the usage values are below this value and 10% are above. example: 0.0015262789745040441 p95: type: number format: double description: The 95th percentile value of resource usage, indicating that 95% of the usage values are below this value and 5% are above. example: 0.0015262789745040441 p100: type: number format: double description: The 100th percentile value (or maximum value) of resource usage observed during the specified period. example: 0.07069631706099244 required: [ p90, p95, p100 ]