DOC-425 Debug bundle API endpoint (#820)

modules/ROOT/attachments/admin-api.yaml

@@ -1632,6 +1632,341 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/uuid'
+  /v1/debug/bundle:
+    post:
+      tags:
+        - Debugging
+      summary: Start a debug bundle collection
+      description: Start a debug bundle collection.
+      operationId: post_debug_bundle
+      requestBody:
+        description: Request to start a debug bundle collection.
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                job_id:
+                  type: string
+                  description: UUID for the debug bundle job.
+                  example: "123e4567-e89b-12d3-a456-426614174000"
+                config:
+                  type: object
+                  description: Optional configuration for debug bundle collection.
+                  properties:
+                    authentication:
+                      type: object
+                      description: Authentication object
+                      properties:
+                        mechanism:
+                          type: string
+                          description: SCRAM mechanism
+                        username:
+                          type: string
+                          description: username used by RPK to authenticate against Kafka and Admin API
+                        password:
+                          type: string
+                          description: password used by RPK to authenticate against Kafka and Admin API
+                    controller_logs_size_limit_bytes:
+                      type: integer
+                      description: Size limit for controller logs in bytes
+                    cpu_profiler_wait_seconds:
+                      type: integer
+                      description: Time to wait for CPU profiling in seconds
+                    logs_since:
+                      type: string
+                      description: Include logs dated from the specified date onward (journalctl date format YYYY-MM-DD, 'yesterday', or 'today')
+                    logs_size_limit_bytes:
+                      type: integer
+                      description: Size limit for logs in bytes
+                    logs_until:
+                      type: string
+                      description: Include logs older than the specified date (journalctl date format YYYY-MM-DD, 'yesterday', or 'today')
+                    metrics_interval_seconds:
+                      type: integer
+                      description: Interval for metrics collection in seconds
+                    metrics_samples:
+                      type: integer
+                      description: Number of metric samples to collect
+                    partition:
+                      type: string
+                      description: Partition identifier for which logs are collected
+                    tls_enabled:
+                      type: boolean
+                      description: Enables TLS for the connection
+                    tls_insecure_skip_verify:
+                      type: boolean
+                      description: Skip verification of the server's certificate chain and hostname
+                    namespace:
+                      type: string
+                      description: Kubernetes namespace for filtering Kubernetes resources
+                    label_selector:
+                      type: array
+                      description: Label selection to filter Kubernetes resources in the debug bundle response
+                      items:
+                        type: object
+                        properties:
+                          key:
+                            type: string
+                            description: The resource label key
+                          value:
+                            type: string
+                            description: The resource label value
+      responses:
+        '200':
+          description: Successfully started the debug bundle collection.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  job_id:
+                    type: string
+                    description: UUID of the job started.
+                    example: "123e4567-e89b-12d3-a456-426614174000"
+        '401':
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '403':
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '409':
+          description: Debug bundle process already running.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '422':
+          description: Invalid input, could not start the debug bundle collection.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+    get:
+      tags:
+        - Debugging
+      summary: Get status of debug bundle collection
+      description: Get the status of a debug bundle collection process.
+      operationId: get_debug_bundle_status
+      responses:
+        '200':
+          description: Successfully retrieved the status of the debug bundle collection.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  job_id:
+                    type: string
+                    description: UUID of the current debug bundle job.
+                    example: "123e4567-e89b-12d3-a456-426614174000"
+                  status:
+                    type: string
+                    description: Status of the debug bundle process.
+                    enum:
+                      - running
+                      - success
+                      - error
+                    example: "running"
+                  created:
+                    type: string
+                    format: int64
+                    description: Timestamp of when the debug bundle process started.
+                  filename:
+                    type: string
+                    description: The name of the output file if the process succeeded.
+                  stdout:
+                    type: array
+                    items:
+                      type: string
+                    description: Output from the stdout stream of the process.
+                  stderr:
+                    type: array
+                    items:
+                      type: string
+                    description: Output from the stderr stream of the process.
+        '401':
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '403':
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '409':
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+
+  /v1/debug/bundle/{jobid}:
+    delete:
+      tags:
+        - Debugging
+      summary: Cancel a debug bundle process
+      description: Cancel the debug bundle process with a given job ID.
+      operationId: delete_debug_bundle
+      parameters:
+        - name: jobid
+          in: path
+          required: true
+          description: UUID of the debug bundle job to cancel.
+          schema:
+            type: string
+            example: "123e4567-e89b-12d3-a456-426614174000"
+      responses:
+        '204':
+          description: Debug bundle process cancelled successfully.
+        '401':
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '403':
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '409':
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '422':
+          description: Format error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '500':
+          description: Internal error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+
+  /v1/debug/bundle/file/{filename}:
+    get:
+      tags:
+        - Debugging
+      summary: Download a debug bundle file
+      description: Download a debug bundle file.
+      operationId: get_debug_bundle_file
+      parameters:
+        - name: filename
+          in: path
+          required: true
+          description: The name of the file to download.
+          schema:
+            type: string
+            example: "debug-bundle-123e4567-e89b-12d3-a456-426614174000.zip"
+      responses:
+        '200':
+          description: Debug bundle file successfully downloaded.
+          content:
+            application/zip:
+              schema:
+                type: string
+                format: binary
+        '401':
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '403':
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '404':
+          description: Debug bundle file not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '409':
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '500':
+          description: Internal error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+
+    delete:
+      tags:
+        - Debugging
+      summary: Delete a debug bundle file
+      description: Delete the debug bundle file with a given filename.
+      operationId: delete_debug_bundle_file
+      parameters:
+        - name: filename
+          in: path
+          required: true
+          description: The name of the file to delete.
+          schema:
+            type: string
+            example: "debug-bundle-123e4567-e89b-12d3-a456-426614174000.zip"
+      responses:
+        '204':
+          description: OK
+        '401':
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '403':
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '404':
+          description: Debug bundle file not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '409':
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
+        '500':
+          description: Internal error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error_body'
   /v1/debug/self_test/start:
     post:
       tags:
@@ -1954,6 +2289,15 @@ components:
           description: A list of Enterprise features in use.
           items:
             $ref: '#/components/schemas/enterprise_feature'
+    error_body:
+      type: object
+      properties:
+        code:
+          type: integer
+          description: The error code.
+        message:
+          type: string
+          description: Error message describing what went wrong.
     node_config_properties:
       type: object
       properties: