swagger: '2.0' info: title: external/applications/applications.proto ApplicationsService NodesService API version: version not set consumes: - application/json produces: - application/json tags: - name: NodesService paths: /api/v0/nodes: post: summary: Create a Node description: 'Creates a node and adds it to the Chef Automate node manager. Requires a FQDN or IP address, a user-specified name, and a ssh or winrm credential reference. Useful for creating nodes for the purpose of running compliance scan jobs. Example: ``` { "name": "my-vagrant-node", "manager":"automate", "target_config": { "backend":"ssh", "host":"localhost", "secrets":["b75195e5-a173-4502-9f59-d949adfe2c38"], "port": 22 }, "tags": [ { "key":"test-node", "value":"is amazing" } ] } ``` Authorization Action: ``` infra:nodes:create ```' operationId: NodesService_Create responses: '200': description: A successful response. schema: $ref: '#/definitions/chef.automate.api.nodes.v1.Id' 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.nodes.v1.Node' tags: - NodesService /api/v0/nodes/bulk-create: post: summary: Bulk Create Nodes description: 'Creates multiple nodes from a list of node data. `hosts` field is required. Multiple hosts may be defined in this field. Example: ``` { "name_prefix": "000-my-ssh-node", "manager":"automate", "target_config": { "backend":"ssh", "hosts":["localhost","127.0.0.1"], "secrets":["b75195e5-a173-4502-9f59-d949adfe2c38"], "port": 22 }, "tags": [ { "key":"test-node", "value":"is-amazing" }, ] } ``` Authorization Action: ``` infra:nodes:create ```' operationId: NodesService_BulkCreate responses: '200': description: A successful response. schema: $ref: '#/definitions/chef.automate.api.nodes.v1.Ids' 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.nodes.v1.Nodes' tags: - NodesService /api/v0/nodes/delete: post: summary: Bulk Delete Nodes by Filter description: 'Deletes a set of nodes that match a filter. Available filters: account_id, last_contact, manager_id, manager_type, name, platform_name, platform_release, region, source_id, state, statechange_timerange, status, last_run_timerange, last_scan_timerange, last_run_status, last_scan_status, last_run_penultimate_status, last_scan_penultimate_status Example: ``` {"filters": [{"key": "name", "values": ["vj*"]}]}'' ``` Authorization Action: ``` infra:nodes:delete ```' operationId: NodesService_BulkDelete responses: '200': description: A successful response. schema: $ref: '#/definitions/chef.automate.api.nodes.v1.BulkDeleteResponse' 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.nodes.v1.Query' tags: - NodesService /api/v0/nodes/delete/ids: post: summary: Bulk Delete Nodes by ID description: 'Deletes a set of nodes given a list of IDs. Invalid IDs will be ignored. Authorization Action: ``` infra:nodes:delete ```' operationId: NodesService_BulkDeleteById responses: '200': description: A successful response. schema: $ref: '#/definitions/chef.automate.api.nodes.v1.BulkDeleteResponse' 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.nodes.v1.Ids' tags: - NodesService /api/v0/nodes/id/{id}: get: summary: Show Node Details description: 'Returns the details for a node given the node ID. Authorization Action: ``` infra:nodes:get ```' operationId: NodesService_Read responses: '200': description: A successful response. schema: $ref: '#/definitions/chef.automate.api.nodes.v1.Node' default: description: An unexpected error response. schema: $ref: '#/definitions/grpc.gateway.runtime.Error' parameters: - name: id description: Unique node ID (UUID) in: path required: true type: string tags: - NodesService delete: summary: Delete a Node description: 'Deletes the node with the node ID. Authorization Action: ``` infra:nodes:delete ```' operationId: NodesService_Delete responses: '200': description: A successful response. schema: properties: {} default: description: An unexpected error response. schema: $ref: '#/definitions/grpc.gateway.runtime.Error' parameters: - name: id description: Unique node ID (UUID) in: path required: true type: string tags: - NodesService put: summary: Update Node description: 'This PUT operation overwrites ALL node details and requires the complete set of node details, consisting of a FQDN or IP address, a user-specified name, and the ID for an ssh or winrm credential. Substitute the desired values for the existing node details in the PUT message. Authorization Action: ``` infra:nodes:update ```' operationId: NodesService_Update responses: '200': description: A successful response. schema: properties: {} default: description: An unexpected error response. schema: $ref: '#/definitions/grpc.gateway.runtime.Error' parameters: - name: id description: Unique node ID (UUID). in: path required: true type: string - name: body in: body required: true schema: $ref: '#/definitions/chef.automate.api.nodes.v1.Node' tags: - NodesService /api/v0/nodes/rerun/id/{id}: get: summary: List Node Status description: 'Use this to run an `inspec detect` job on the node, which updates the status to reflect that the node is reachable or unreachable. Authorization Action: ``` infra:nodes:rerun ```' operationId: NodesService_Rerun responses: '200': description: A successful response. schema: $ref: '#/definitions/chef.automate.api.nodes.v1.RerunResponse' default: description: An unexpected error response. schema: $ref: '#/definitions/grpc.gateway.runtime.Error' parameters: - name: id description: Unique node ID (UUID) in: path required: true type: string tags: - NodesService /api/v0/nodes/search: post: summary: List and Filter Nodes description: 'Makes a list of nodes. Supports filtering, pagination, and sorting. Adding a filter narrows the list of nodes to only those that match the filter or filters. Supported filters: account_id, last_contact, manager_id, manager_type, name, platform_name, platform_release, region, source_id, state, statechange_timerange, status, last_run_timerange, last_scan_timerange, last_run_status, last_scan_status, last_run_penultimate_status, last_scan_penultimate_status Example: ``` { "filters":[ {"key": "last_scan_status", "values": ["FAILED"]}, {"key": "last_scan_penultimate_status", "values": ["PASSED"]}, {"key": "name", "values": ["MyNode*"]} ], "page":1, "per_page":100, "sort":"status", "order":"ASC" } ``` Authorization Action: ``` infra:nodes:list ```' operationId: NodesService_List responses: '200': description: A successful response. schema: $ref: '#/definitions/chef.automate.api.nodes.v1.Nodes' 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.nodes.v1.Query' tags: - NodesService definitions: chef.automate.api.nodes.v1.TargetConfig: type: object properties: secrets: type: array items: type: string description: List of credential IDs for a node. backend: type: string description: Node backend type (ssh, winrm, aws, ssm, azure, gcp). host: type: string description: Node FQDN or IP address. port: type: integer format: int32 title: ssh or winrm connection port sudo: type: boolean description: Uses `sudo` (boolean). ssl: type: boolean description: Check ssl (boolean). self_signed: type: boolean description: Allow self-signed certificate (boolean). user: type: string description: Username from the credential ID for this node. sudo_options: type: string description: Sudo options to use when accessing the node. hosts: type: array items: type: string description: List of hostnames (FQDN or IP address) for bulk creating nodes. description: Details for ssh/winrm access of the node. chef.automate.api.nodes.v1.Query.OrderType: type: string enum: - ASC - DESC default: ASC description: Return the results in ascending or descending order. chef.automate.api.nodes.v1.LastContactData: type: object properties: id: type: string description: Chef Infra run report ID or InSpec scan report ID. status: $ref: '#/definitions/chef.automate.api.nodes.v1.LastContactData.Status' description: Last node report status. penultimate_status: $ref: '#/definitions/chef.automate.api.nodes.v1.LastContactData.Status' description: Next-to-last node status report. end_time: type: string format: date-time description: Last node report endtime. description: Most recent node data from the latest Chef Infra run and InSpec scan. chef.automate.api.nodes.v1.ResultsRow: type: object properties: node_id: type: string description: Unique node ID. report_id: type: string description: Unique ID of the report generated by the InSpec scan. status: type: string description: Status of the report (failed, success, skipped). result: type: string description: Error message returned after several failed attempts to contact a node. job_id: type: string description: Unique ID of the scan job that generated the report. start_time: type: string format: date-time description: Start time on the report. end_time: type: string format: date-time description: End time on the report. description: Summary of the last Chef InSpec scan job run on the node. chef.automate.api.common.query.Kv: type: object properties: key: type: string description: Tag key. value: type: string description: Tag value. chef.automate.api.nodes.v1.Id: type: object properties: id: type: string title: Unique node ID (UUID) chef.automate.api.nodes.v1.Query: type: object properties: filters: type: array items: $ref: '#/definitions/chef.automate.api.common.query.Filter' description: Use filters to limit the set of nodes to delete. order: $ref: '#/definitions/chef.automate.api.nodes.v1.Query.OrderType' sort: type: string description: Sort the results on a specific field. page: type: integer format: int32 description: Starting page for the results. per_page: type: integer format: int32 description: The number of results on each page. chef.automate.api.nodes.v1.Ids: type: object properties: ids: type: array items: type: string description: List of node UUIDs. chef.automate.api.nodes.v1.LastContactData.Status: type: string enum: - UNKNOWN - PASSED - FAILED - SKIPPED default: UNKNOWN chef.automate.api.nodes.v1.BulkDeleteResponse: type: object properties: names: type: array items: type: string description: List of deleted nodes, by name. google.protobuf.Any: type: object properties: type_url: type: string value: type: string format: byte 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.nodes.v1.Node: type: object properties: id: type: string description: Unique node ID (UUID). name: type: string description: User-specified node name. platform: type: string description: Node platform. platform_version: type: string description: Node platform version. manager: type: string description: Node manager (automate, aws-ec2, aws-api, azure-vm, azure-api, gcp). tags: type: array items: $ref: '#/definitions/chef.automate.api.common.query.Kv' description: Node tags. last_contact: type: string format: date-time description: Timestamp of the last `detect` or `exec` job. status: type: string description: Node status (unreachable, reachable, unknown). last_job: $ref: '#/definitions/chef.automate.api.nodes.v1.ResultsRow' description: Results of the last compliance scan job for this node. target_config: $ref: '#/definitions/chef.automate.api.nodes.v1.TargetConfig' description: Node configuration for ssh or winrm. manager_ids: type: array items: type: string description: List of manager IDs for the node. connection_error: type: string description: Last connection error received when trying to contact the node. state: type: string description: Last known node state (running, stopped, terminated). name_prefix: type: string description: Prefix for node name. The full node name is the prefix + the host. projects: type: array items: type: string description: List of projects associated with the node. run_data: $ref: '#/definitions/chef.automate.api.nodes.v1.LastContactData' description: Most recent node data from the last Chef Infra run results. scan_data: $ref: '#/definitions/chef.automate.api.nodes.v1.LastContactData' description: Most recent compliance scan data for the node from the last InSpec scan. description: Node information. chef.automate.api.common.query.Filter: type: object properties: key: type: string description: Field to filter on. exclude: type: boolean description: "Include matches for this filter.(boolean)\n`true` (default) *includes* all nodes that match this filter. \n`false` *excludes* all nodes that match this filter." values: type: array items: type: string description: Field values to filter on. chef.automate.api.nodes.v1.RerunResponse: type: object chef.automate.api.nodes.v1.Nodes: type: object properties: nodes: type: array items: $ref: '#/definitions/chef.automate.api.nodes.v1.Node' description: List of nodes. total: type: integer format: int32 description: Total number of nodes in the system. total_unreachable: type: integer format: int32 description: Total number of unreachable nodes in the system. total_reachable: type: integer format: int32 description: Total number of reachable nodes in the system. total_unknown: type: integer format: int32 description: Total number of unknown nodes in the system.