Update kubernetes API spec: cluster status messages (#999)

* Update kubernetes API spec: cluster status messages

* Update specification/resources/kubernetes/responses/status_messages.yml

Co-authored-by: Andrew Starr-Bochicchio <andrewsomething@users.noreply.github.com>

---------

Co-authored-by: Andrew Starr-Bochicchio <andrewsomething@users.noreply.github.com>

Author: kperath

specification/DigitalOcean-public.v2.yaml

@@ -1263,6 +1263,10 @@ paths:
     delete:
       $ref: "resources/kubernetes/kubernetes_remove_registry.yml"
 
+  /v2/kubernetes/clusters/{cluster_id}/status_messages:
+    get:
+      $ref: "resources/kubernetes/kubernetes_get_status_messages.yml"
+
   /v2/load_balancers:
     post:
       $ref: "resources/load_balancers/loadBalancers_create.yml"

specification/resources/kubernetes/examples/curl/kubernetes_get_status_messages.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/status_messages"

specification/resources/kubernetes/examples/go/kubernetes_get_status_messages.yml

@@ -0,0 +1,17 @@
+lang: Go
+source: |-
+  import (
+      "context"
+      "os"
+
+      "github.com/digitalocean/godo"
+  )
+
+  func main() {
+      token := os.Getenv("DIGITALOCEAN_TOKEN")
+
+      client := godo.NewFromToken(token)
+      ctx := context.TODO()
+
+      messages, _, err := client.Kubernetes.GetClusterStatusMessages(ctx, "8d91899c-0739-4a1a-acc5-deadbeefbb8f", nil)
+  }

specification/resources/kubernetes/kubernetes_get_status_messages.yml

@@ -0,0 +1,43 @@
+operationId: kubernetes_get_status_messages
+
+summary: Fetch Status Messages for a Kubernetes Cluster
+
+description: |
+  To retrieve status messages for a Kubernetes cluster, send a GET request to
+  `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/status_messages`. Status messages inform users of any issues that come up during the cluster lifecycle.
+
+tags:
+  - Kubernetes
+
+parameters:
+  - $ref: 'parameters.yml#/kubernetes_cluster_id'
+  - $ref: 'parameters.yml#/kubernetes_status_messages_since'
+
+responses:
+  '200':
+    $ref: 'responses/status_messages.yml'
+
+  '401':
+    $ref: '../../shared/responses/unauthorized.yml'
+
+  '404':
+    $ref: '../../shared/responses/not_found.yml'
+
+  '429':
+    $ref: '../../shared/responses/too_many_requests.yml'
+
+  '500':
+    $ref: '../../shared/responses/server_error.yml'
+
+  default:
+    $ref: '../../shared/responses/unexpected_error.yml'
+
+
+x-codeSamples:
+  - $ref: 'examples/curl/kubernetes_get_status_messages.yml'
+  - $ref: 'examples/go/kubernetes_get_status_messages.yml'
+
+security:
+  - bearer_auth:
+    - 'kubernetes:read'
+

specification/resources/kubernetes/models/status_messages.yml

@@ -0,0 +1,16 @@
+type: object
+
+properties:
+  message:
+    type: string
+    readOnly: true
+    example: Resource provisioning may be delayed while our team resolves an incident
+    description: Status information about the cluster which impacts it's lifecycle.
+
+  timestamp:
+    type: string
+    format: date-time
+    readOnly: true
+    example: "2018-11-15T16:00:11Z"
+    description: A timestamp in ISO8601 format that represents when the status 
+      message was emitted.

specification/resources/kubernetes/parameters.yml

@@ -83,3 +83,14 @@ kubernetes_node_replace:
     maximum: 1
     default: 0
   example: 1
+
+kubernetes_status_messages_since:
+  in: query
+  name: since
+  required: false
+  description: A timestamp used to return status messages emitted since the
+    specified time. The timestamp should be in ISO8601 format.
+  schema:
+    type: string
+    format: date-time
+  example: 2018-11-15T16:00:11Z

specification/resources/kubernetes/responses/status_messages.yml

@@ -0,0 +1,20 @@
+description: |
+  The response is a JSON object which contains status messages for a Kubernetes cluster. Each message object contains a timestamp and an indication of what issue the cluster is experiencing at a given time.
+
+
+headers:
+  ratelimit-limit:
+    $ref: '../../../shared/headers.yml#/ratelimit-limit'
+  ratelimit-remaining:
+    $ref: '../../../shared/headers.yml#/ratelimit-remaining'
+  ratelimit-reset:
+    $ref: '../../../shared/headers.yml#/ratelimit-reset'
+
+content:
+  application/json:
+    schema:
+      properties:
+        messages:
+          type: array
+          items:
+            $ref: "../models/status_messages.yml"