Add documentation for /monitoring/sinks/** (#933)

* add tailfinapi

* whitespace + resource_id query param

* fix issues in make lint

* edits to obj descriptions

* updates to examples + OpenSearch casing

* update path on update_destination

* update path on update_destination

* Use enum in destination create request.

---------

Co-authored-by: Anna Lushnikova <loosla@users.noreply.github.com>
Co-authored-by: Andrew Starr-Bochicchio <a.starr.b@gmail.com>

specification/DigitalOcean-public.v2.yaml

@@ -1402,6 +1402,32 @@ paths:
     get:
       $ref: 'resources/monitoring/monitoring_get_lb_droplets_downtime.yml'
 
+  /v2/monitoring/sinks/destinations:
+    post:
+      $ref: 'resources/monitoring/monitoring_create_destination.yml'
+    get:
+      $ref: 'resources/monitoring/monitoring_list_destinations.yml'
+
+  /v2/monitoring/sinks/destinations/{destination_uuid}:
+    get:
+      $ref: 'resources/monitoring/monitoring_get_destination.yml'
+    post:
+      $ref: 'resources/monitoring/monitoring_update_destination.yml'
+    delete:
+      $ref: 'resources/monitoring/monitoring_delete_destination.yml'
+
+  /v2/monitoring/sinks:
+    post:
+      $ref: 'resources/monitoring/monitoring_create_sink.yml'
+    get:
+      $ref: 'resources/monitoring/monitoring_list_sinks.yml'
+
+  /v2/monitoring/sinks/{sink_uuid}:
+    get:
+      $ref: 'resources/monitoring/monitoring_get_sink.yml'
+    delete:
+      $ref: 'resources/monitoring/monitoring_delete_sink.yml'
+
   /v2/projects:
     get:
       $ref: 'resources/projects/projects_list.yml'

specification/resources/monitoring/examples/curl/monitoring_create_destination.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X POST \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/monitoring/sinks/destinations" \
+    --data '{"name":"cluster", "type":"opensearch_dbaas", "config": {"endpoint": "example.com", "credentials": {"username": "username", "password": "password"}}}'

specification/resources/monitoring/examples/curl/monitoring_create_sink.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X POST \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/monitoring/sinks" \
+    --data '{"destination_uuid": "f2fcd5d9-f410-4f3a-8015-130ada94b1fe",  "resources": [{"name": "fra_kubernetes_cluster", "urn":"do:kubernetes:8463c9db-150c-4b44-830c-fca7f68d005b"}]}'

specification/resources/monitoring/examples/curl/monitoring_delete_destination.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X DELETE \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/monitoring/sinks/destinations/01f30bfa-319a-4769-ba95-9d43971fb514"

specification/resources/monitoring/examples/curl/monitoring_delete_sink.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X DELETE \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/monitoring/sinks/aef7ff4a-f1be-4d9e-b886-650fcb5bdfe3"

specification/resources/monitoring/examples/curl/monitoring_get_destination.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/monitoring/sinks/destinations/01f30bfa-319a-4769-ba95-9d43971fb514"

specification/resources/monitoring/examples/curl/monitoring_get_sink.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/monitoring/sinks/f945d774-86e8-4dc8-8f60-cfc76dd3d098"

specification/resources/monitoring/examples/curl/monitoring_list_destinations.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/monitoring/sinks/destinations"

specification/resources/monitoring/examples/curl/monitoring_list_sinks.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/monitoring/sinks?resource_id=do:kubernetes:f2fcd5d9-f410-4f3a-8015-130ada94b1fe"

specification/resources/monitoring/examples/curl/monitoring_update_destination.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X PATCH \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/monitoring/sinks/destinations/01f30bfa-319a-4769-ba95-9d43971fb514" \
+    --data '{"index_name": "logs", "retention_days": 30}'

specification/resources/monitoring/models/destination.yml

@@ -0,0 +1,22 @@
+type: object
+required:
+  - config
+properties:
+  id:
+    type: string
+    description: "A unique identifier for a destination."
+    example: "01f30bfa-319a-4769-ba95-9d43971fb514"
+  name:
+    type: string
+    description: "destination name"
+    example: "managed_opensearch_cluster"    
+  type:
+    enum:
+      - opensearch_dbaas
+      - opensearch_ext
+    description: |
+      The destination type. `opensearch_dbaas` for a DigitalOcean managed OpenSearch
+      cluster or `opensearch_ext` for an externally managed one.
+    example: "opensearch_dbaas"
+  config:
+    $ref: 'opensearch_config.yml'

specification/resources/monitoring/models/destination_omit_credentials.yml

@@ -0,0 +1,20 @@
+type: object
+properties:
+  id:
+    type: string
+    description: "A unique identifier for a destination."
+    example: "01f30bfa-319a-4769-ba95-9d43971fb514"
+  name:
+    type: string
+    description: "destination name"
+    example: "managed_opensearch_cluster"    
+  type:
+    enum:
+      - opensearch_dbaas
+      - opensearch_ext
+    description: |
+      The destination type. `opensearch_dbaas` for a DigitalOcean managed OpenSearch
+      cluster or `opensearch_ext` for an externally managed one.
+    example: opensearch_dbaas
+  config:
+    $ref: 'opensearch_config_omit_credentials.yml'

specification/resources/monitoring/models/destination_request.yml

@@ -0,0 +1,18 @@
+type: object
+required:
+  - config
+  - type
+properties:
+  name:
+    type: string
+    description: "destination name"
+    example: "managed_opensearch_cluster"
+  type:
+    enum:
+      - opensearch_dbaas
+      - opensearch_ext
+    description: |
+      The destination type. `opensearch_dbaas` for a DigitalOcean managed OpenSearch
+      cluster or `opensearch_ext` for an externally managed one.
+  config:
+    $ref: 'opensearch_config_request.yml'

specification/resources/monitoring/models/opensearch_config.yml

@@ -0,0 +1,38 @@
+type: object
+required:
+  - endpoint
+properties:
+  id:
+    type: string
+    description: "A unique identifier for a configuration."
+    example: "41078d41-165c-4cff-9f0a-19536e3e3d49"
+  credentials:
+    type: object
+    description: "Credentials for an OpenSearch cluster user. Optional if `cluster_uuid` is passed."
+    properties:
+      username:
+        type: string
+        example: "username"
+      password:
+        type: string
+        example: "password"
+  endpoint:
+    type: string
+    example: "example.com"
+    description: "host of the OpenSearch cluster"
+  cluster_uuid:
+    type: string
+    example: "85148069-7e35-4999-80bd-6fa1637ca385"
+    description: "A unique identifier for a managed OpenSearch cluster."
+  cluster_name:
+    type: string
+    example: "managed_dbaas_cluster"
+    description: "Name of a managed OpenSearch cluster."
+  index_name:
+    type: string
+    description: "OpenSearch index to send logs to."
+    example: "logs"
+  retention_days:
+    type: integer
+    description: "Number of days to retain logs in OpenSearch (default: 14)"
+    example: 14

specification/resources/monitoring/models/opensearch_config_omit_credentials.yml

@@ -0,0 +1,28 @@
+type: object  
+description: "OpenSearch destination configuration with `credentials` omitted."
+properties:
+  id:
+    type: string
+    description: "A unique identifier for a configuration."
+    example: "41078d41-165c-4cff-9f0a-19536e3e3d49"
+  endpoint:
+    type: string
+    example: "example.com"
+    description: "host of the OpenSearch cluster"
+  cluster_uuid:
+    type: string
+    example: "85148069-7e35-4999-80bd-6fa1637ca385"
+    description: "A unique identifier for a managed OpenSearch cluster."
+  cluster_name:
+    type: string
+    example: "managed_dbaas_cluster"
+    description: "Name of a managed OpenSearch cluster."
+  index_name:
+    type: string
+    description: "OpenSearch index to send logs to."
+    example: "logs"
+  retention_days:
+    type: integer
+    description: "Number of days to retain logs in OpenSearch."
+    example: 14
+    default: 14

specification/resources/monitoring/models/opensearch_config_request.yml

@@ -0,0 +1,37 @@
+type: object
+required:
+  - endpoint
+properties:
+  credentials:
+    type: object
+    description: "Credentials for an OpenSearch cluster user. Optional if `cluster_uuid` is passed."
+    properties:
+      username:
+        type: string
+        example: "username"
+      password:
+        type: string
+        example: "password"
+  endpoint:
+    type: string
+    example: "example.com"
+    description: "host of the OpenSearch cluster"
+  cluster_uuid:
+    type: string
+    example: "85148069-7e35-4999-80bd-6fa1637ca385"
+    description: "A unique identifier for a managed OpenSearch cluster."
+  cluster_name:
+    type: string
+    example: "managed_dbaas_cluster"
+    description: "Name of a managed OpenSearch cluster."
+  index_name:
+    type: string
+    description: "OpenSearch index to send logs to."
+    example: "logs"
+  retention_days:
+    type: integer
+    description: "Number of days to retain logs in an OpenSearch cluster."
+    example: 14
+    default: 14
+
+

specification/resources/monitoring/models/sink_resource.yml

@@ -0,0 +1,14 @@
+type: object
+required:
+  - urn
+properties:
+  urn:
+    type: string
+    pattern: ^do:kubernetes:.*
+    example: do:kubernetes:f453aa14-646e-4cf8-8c62-75a19fb24ec2
+    description: The uniform resource name (URN) for the resource in the format 
+      do:resource_type:resource_id.
+  name:
+    type: string
+    description: "resource name"
+    example: "managed_kubernetes_cluster"

specification/resources/monitoring/models/sinks_response.yml

@@ -0,0 +1,11 @@
+type: object
+required:
+  - urn
+properties:
+  destination:
+    $ref: '../models/destination.yml'
+  resources:
+    type: array
+    description: "List of resources identified by their URNs."
+    items:
+      $ref: '../models/sink_resource.yml'

specification/resources/monitoring/monitoring_create_destination.yml

@@ -0,0 +1,64 @@
+operationId: monitoring_create_destination
+
+summary: Create Logging Destination
+
+description: To create a new destination, send a POST request to `/v2/monitoring/sinks/destinations`.
+
+tags:
+  - Monitoring
+
+requestBody:
+  required: true
+  content:
+    application/json:
+      schema:
+        $ref: 'models/destination_request.yml'
+
+      examples:
+        Managed OpenSearch Cluster:
+          value:
+            name: managed_opensearch_cluster
+            type: opensearch_dbaas
+            config:
+              endpoint: db-opensearch-nyc3-123456-do-user-123456-0.g.db.ondigitalocean.com
+              cluster_uuid: 85148069-7e35-4999-80bd-6fa1637ca385
+              cluster_name: managed_dbaas_cluster
+              index_name: logs
+              retention_days: 14
+        External OpenSearch Cluster:
+          value:
+            name: external_opensearch
+            type: opensearch_ext
+            config:
+              endpoint: example.com
+              credentials:
+                username: username
+                password: password
+              index_name: logs
+              retention_days: 14
+
+responses:
+  '200':
+    $ref: 'responses/destination.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/monitoring_create_destination.yml'
+
+security:
+  - bearer_auth:
+    - 'monitoring:create'